Ruby API Pages.add bug(s)

[tim]

Couldn't find any prior references to this matter -
Pages.add has two issues that I consider bugs.
a) when you add a page it returns nil, according to the official API doc pages. This would be a really daft thing to do but actually the code appears to do the right thing and returns the created page. So far as I can tell from testing, anyway. The API doc needs correcting.
b) If you add a page to a document that has only there default first page (i.e. no set scene name) then you do not end up with two pages as one might expect. No, a single page - the one you added - is your lot. It seems that the default state for a new document is that sketchup.active_model.pages is empty. That isn't very logical to my way of thinking. At the very least a mention of that in the doc relating to Pages might be nice. I discovered this when my plugin code 'added' a page, set everything to hidden and inserted a new component. I was left with a model that only had my new page with the component visible. Workaround would seem to be adding a new page with some default name if the pages count is 0 before doing whatever else one was about to do.

[Dan Rathbun]

a) when you add a page it returns nil, according to the official API doc pages. ... but actually ... returns the created page. ... The API doc needs correcting.

This is common for the API. It comes comes from embedded comments in the C++ API core. Looks like the coders copy and pasted blocks of comments and forgot, in more places than I can count, to change the return value text, and modify the following code sample, so that it actually pertains to the method above it.
We have posted many corrections (that used to appear on the old API site.) But the new developers.google.com site did not have that functionality. So you cannot read all those postings. One of the team members posted a chronological list of all the postings. (They still have them.) I cannot find the posting tho ...

b) It seems that the default state for a new document is that Sketchup.active_model.pages is empty. That isn't very logical to my way of thinking.

MOST of the collection objects are empty?==true and size==0 when they are empty as first created. With 3 exceptions, there is always a default "Layer0" in Layers, a default Style in Styles, and the LineTool is set for Tools on startup. (also, RenderingOptions, but that is really a Hash wrapper.)

If a Page was always there.. it might have the same language naming bugs that was eliminated in the most recent release (for "Layer0".)

I think you may not realize that the View is a separate object and class, than a Page. The active_view is really a singleton instance object, that has it's own instance of a Camera object, when SketchUp starts up. Later it (the active_view,) can be made to change it's camera to use the camera of any pages, or animate between any or all of them. (See the Animation class.)

I was left with a model that only had my new page with the component visible.

You cannot hide the active layer. And if the component was inserted on the active layer, then it would perhaps be visible ??

[Dan Rathbun]

Now.. if this still bothers you, why not modify one of the supplied templates with a default page. (I actually created a template for myself, that had Iso, Top, Left, Right, Bottom, Front, and Back pages.)

[tim]

Doc and code drifting is quite possibly one of the biggest issues affecting code maintainability. I've never quite got over the idiocy of a few people I've worked with that really took to heart the attitude of "documents and comments? Why do you think it's called 'code'?" Certainly when I was managing a team I didn't let anyone get away with that - at least where I could detect it…
An old colleague came up with a pithy way to describe what ought to happen - "don't document the code, code the document!"

I didn't know that there is a separation between Page and View; now I do, so thanks for that. The specific problem I had with my code was that with no named page in a fresh drawing simply adding a page, hiding everything, adding my new layer, adding the copy of the selected component and updating the page left an apparently mangled drawing because there was still only one page visible and it no longer had the main model visible. I can see that going down well with anyone trying out a new plugin! As a workaround I've made it add a default new page before adding my 'real' new page so that at least there is no nasty surprise.