Thoughts on Class: Sketchup :: Page (mostly docs issues)

Developers Ruby API
1

Based on my most recent self-education, I would like to share the following findings.
(As you may know, I don’t have GitHub account, and I’m not planning to have one lately :blush: … but I’m still reading.)

Preconditions:
Empty modell opened.
Sketchup.version: 21.1.299 (Windows)

console:

model = Sketchup.active_model
pages = model.pages
page = pages.add "My Page"
#<Sketchup::Page:0x000001fe14dcd5c0>

#1
#camera ⇒ Object

The documentation incorrectly states:

image
image717×65 5.9 KB

Actually, it always returns a Camera object, regardless of that the page does or does not save camera information.

console:

page.use_camera?
true
page.camera
#<Sketchup::Camera:0x000001fe15028978>
page.use_camera = false
false
page.use_camera?
false
page.camera
#<Sketchup::Camera:0x000001fe1445a998>

#2
#label ⇒ Object
#name ⇒ Object
Could be good to mention in documentation, that the two objects are returning same string if #include_in_animation? returns true.
Otherwise the label differs from the name in that the label is similar as the name string but in parentheses. E.g.:
Name: ______ Label:
‘My page’ __ ‘(My Page)’

#3
#include_in_animation? ⇒ Boolean
The example in the documentation does not toggle inclusion. It is collecting the pages which are included in animation.
image

#4
#layer_folders ⇒ Array<Sketchup::LayerFolder>?
#layers ⇒ Array<Sketchup::Layer>?

It is incorrectly stated in the documentation which method the returned value depends on.
image
image

Correctly: the #use_hidden_layers? method must be mentioned.

( Perhaps could be good to mention in the example (Test layer visibility) that the visible_in_scene? method will return error if #use_hidden_layers? returns false. )

#5
#set_visibility (layer, visible_for_page) ⇒ Object
#set_visibility (layer_folder, visible_for_page) ⇒ Sketchup::Page

The documentation text should be rearranged and typo has to be corrected. Perhaps the Returns needs to be more consistently described.

image
image501×640 23.4 KB

#6
#shadow_info ⇒ Object

The documentation incorrectly states:

image
image711×54 7.49 KB

Actually, it always returns a ShadowInfo object, regardless of that the page does or does not save Shadow information.

console:

page.shadow_info
#<Sketchup::ShadowInfo:0x000002685b9c23c0>
page.use_shadow_info?
true
page.use_shadow_info = false
false
page.use_shadow_info?
false
page.shadow_info
#<Sketchup::ShadowInfo:0x000002685b9c23c0>

#7
#use_rendering_options= (setting) ⇒ Object
#use_rendering_options? ⇒ Boolean

#use_style= (style) ⇒ Object
#use_style? ⇒ Boolean

Perhaps could be good to mention in the documentation:
If you are setting the #use_rendering_optoins= it will also toggle the page to use the style.
And and vice versa:
If you are applying a style to the page it will force the rendering options to use.

It is interesting to see that all other setters use a Boolean (TrueClass or FalseClass) to set, but the #use_style= is using the style object.

console:

page.use_rendering_options?
true
page.use_style?
true
style = page.style
#<Sketchup::Style:0x000002685c6b9010>
page.use_rendering_options = false
false
page.use_style?
false
page.use_style = style
#<Sketchup::Style:0x000002685c6b9010>
page.use_style?
true
page.use_rendering_options?
true
2

Also note that there is another topic thread on Scene Page documentation quirkiness:

#1 getting a Sketchup::Camera instance.

Cameras are “virtual” objects that describe how the view looks at the model.
Meaning that, manipulating a camera object does not directly change the view.
You must use the Sketchup::View#camera= method assign the properties of a camera object, to the view’s (and therefor a page’s) internal properties. (In the case of a scene page, the page must also be updated.)

Also, because there is a separation between the view properties and a Ruby API camera, weirdly each time you call the camera getter (for the main view or any page) you get a brand spankin’ new instance object.

I agree the doc errs with regard to nil being returned. That phrase should be removed.
We can entertain the idea that getting the page’s current camera might be beneficial regardless of whether the page saves it. So the current implementation is harmless and likely should remain as is.

3

Well, I’ve logged Page class issues (some even bugs) that are going on 2 years old or more and not yet fixed. The sooner these get logged the sooner they can be considered for work.

(Ie, The Trimble team tends to collect work up into “sets” that apply to localized areas of the codebase. So if and when they are into that part for the Page code, we would want these issues to be on the list, so they get fixed.
Also, this list is quite extensive and could tip the balance and cause the fixing of these and other previously logged API issues regarding scene pages.)

4

Yes, Dan, I got your explanation about the we are “always” calling the camera getter. Thanks!

But still, a docu made me think differently. Actually I was trying to compare what is written and what I got, then I posted the “difference” here without judging or explanation :wink:

Luckily lately, it’s like I’ve seen more effort to improve the documentation.
For example, what was mentioned in #4 has been included in it “these days”, but unfortunately incorrectly.

Then I thought I would put “everything” on one page ( related to Page :slight_smile: ), so the person(s) who willing to edit the documentation, will find it…
If it will be useful to them, that’s good. If it is not … then it was useful to me.

5

On the one hand it might be easy for those wanting to see all the issues for an entire class.

On the other, if each error / bug has it’s own issue number, then they can be referenced separately and fixed individually. (Sometimes within 1 update cycle there is not time to fix all issues. So separate issues allow them to be fixed and closed as time permits.)
Separate issues for each method also allows coders to do a narrower search in the GitHub tracker, if they are concerned only with a certain method.

6

I think I’ve seen that topic opener somewhere… :slight_smile: :slight_smile:

…and yes, that mistake has been corrected in the docu, however the correction have other mistake again. Then the new layer_folders metod description is “inherited” the same mistake.