New API doc - typos and questions

Jim

Just a general request for the API docs. When viewing a method which references another class, would it be possible to link to that class? For example, you are the viewing Model.bounds description - it would be nice to be able to jump right to the BoundingBox class.

Thanks.

Jim

I wonder if we should lock this list and start a new one for 7.1?

thomthom

@jim said:

I wonder if we should lock this list and start a new one for 7.1?

Maybe once Scott has updated the docs first?

thomthom

Entity.typename
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/entity.html#typename

I think it's worth noting here that .typename comparison is slow and should be avoided if possible. Ref: http://forums.sketchucation.com/viewtopic.php?f=180&t=19576&st=0&sk=t&sd=a#p166340
.typename is required if you need to identify entity types that don't have ruby API classes, such as DimensionLinear, DimensionRadial and Polyline3d. And if you scan for these that you check for entities of class DrawingElement before you do a .typename comaprison.

tomasz

"DisplayColorbyLayer" key of RenderinOptions should read "DisplayColorByLayer"

NewOne

@unknownuser said:

"DisplayColorbyLayer" key of RenderinOptions should read "DisplayColorByLayer"

What's wrong with Colorby Layer ?

tomasz

@newone said:

What's wrong with Colorby Layer ?

Try read the value of it. Such a key does not exist.

thomthom

Did I miss a joke..?

NewOne

@unknownuser said:

@newone said:

What's wrong with Colorby Layer ?

Try read the value of it. Such a key does not exist.

hey, that was a joke I got your point and you are right...

cjthompson

@newone said:

@unknownuser said:

@newone said:

What's wrong with Colorby Layer ?

Try read the value of it. Such a key does not exist.

hey, that was a joke I got your point and you are right...

I'm afraid you are much too easily amused

thomthom

Sketchup.register_importer
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/sketchup.html#register_importer

The docs says SU6.0+, but isn't it SU7.0+ ?

thomthom

Sketchup.read_default
http://code.google.com/apis/sketchup/docs/ourdoc/sketchup.html#read_default

@unknownuser said:

True if successful, false if unsuccessful.

Surely it would return the value being accessed?

Dan Rathbun

@thomthom said:

Sketchup.read_default
http://code.google.com/apis/sketchup/docs/ourdoc/sketchup.html#read_default

True if successful, false if unsuccessful.
Surely it would return the value being accessed?

Verified!
Sketchup.read_default('Preferences','SnapAngle') returns 15.0
[My current setting; which happens in this case to be class Float.]

The API doc is vague about the default argument. The definition should read (as things work now):
"(optional) A value to return, if the variable is not found or empty."
[The way it is written, I read it as being a value to write into the registry.]

The lack of error checking in this method, can easily create false Resistry Keys.
Example: if you misspell the key (section on the Mac,)... ie:
[note misspelled 'Preferences']:
Sketchup.read_default('Prefer ances','SnapAngle')
... the method creates a new 'Preferances' key, with nothing under this new WORTHLESS key. (No Valuename, no value.) The method then just returns nil. [On Win32, we must manually use the Registry Editor to get rid of this junk!]

If the key is correct, but the Valuename is wrong (or does not exist,) the method just returns nil, [again,] or the default ReturnValue.

If the the Key is correct, AND the Valuname is correct, but the Value is empty, the method returns nil, [once again,] or the default ReturnValue.

So we have 3 situations in which the method can return nil, and no way thru the SU API to tell what the situation is. [yes we can use one of the full ruby Win32 Registry modules, and I may begin doing this.]

A fourth situation, is if the value is an empty string, (ie '' or "" are stored in the registry value the method just returns the empty string (and NOT nil.) The return class of the method is string in this case.
This can happen if you use Sketchup.write_default( key, valuename, ""), but its not necessary as each value in the registry has a type, and strings don't need delimiters.
We should use instead Sketchup.write_default( key, valuename, nil) to clear a string value in the registry.

I would propose a change to this method...

(1 as is.) IF everything exists, it works OK, and the value is returned.

(2 as is.) If (the Key exists, AND the Valuename exists,) AND the value is empty, then the method should return NIL without a default Return Value (3rd parameter,) OR the 3rd parameter if given.

(3) If the EITHER the Key OR the Valuename do NOT exist, then the method should raise an exception similar to a hash index error, viz:
Error in myprog.rb:22:in `Sketchup.read_default': key not found (IndexError) ...

Then (reference methods for Hash class):
CREATEseveral new boolean methods similar to Hash.has_key?, Hash.has_value? and Hash.empty? so the programmer can decide in their RESCUE block what action to perform;

I'd envision these boolean methods to be named similar to:
Sketchup.default_empty?
Sketchup.default_has_key? (perhaps with a Mac alias .default_has_section? for plist files)
Sketchup.default_has_valuename? (perhaps a Mac alias .default_has_variable? for plist files)

.
Thoughts?

Dan Rathbun

Face.mesh
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/face.html#mesh

@unknownuser said:

Valid flags are:

[condensed: 0, 1, 2, 4 ]

Add these numbers together to combine flags. A value of **5** will include all flags, for example.

I seem to get 7 (as shown in the example,) when I add all the flags.

thomthom

Some of the methods to access toolbars needs clarification.

UI.set_toolbar_visible UI.toolbar_names UI.toolbar_visible?
These only works on the native Sketchup toolbars. And UI.toolbar_names doesn't list all native toolbars.

UI.toolbar is used to return Ruby toolbars. But (!) it will never fail if you try to refer to a non-existent toolbar - it will create a new one. Have not found a way to detect if a Ruby toolbar exists or not.

http://forums.sketchucation.com/viewtopic.php?f=180&t=21156

thomthom

View.draw2d
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/view.html#draw2d

In order to draw lines with an odd number thicksness without looking "fuzzy" - then you need to specify .5 to all numbers. This is because the points makes up the centre line so the points for odd numbered thickness must then lie in the middle of the pixel.

thomthom

UI.inputbox
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/ui.html#inputbox

It should be noted that the default value types you pass to the input box controls the return types.
http://forums.sketchucation.com/viewtopic.php?f=180&t=23288&p=197300#p197298

thomthom

http://code.google.com/intl/nb/apis/sketchup/docs/releases.html
The release notes says:

@unknownuser said:

Cleaner, hash-based syntax for initializing

But there's nowhere any example of what the hash should look like, keys etc.

Jim

Thom, you are right it needs to be documented.

This is from the webtextures_loader.rb. The constants are defined a little earlier in the code, but this gives some idea about the keys:


 # Create our dialog.
    keys = {
      ;dialog_title => title,
      ;scrollable => false,
      ;preferences_key => WT_DIALOG_REGISTRY_KEY,
      ;height => WT_DIALOG_HEIGHT,
      ;width => WT_DIALOG_WIDTH,
      ;left => WT_DIALOG_X,
      ;top => WT_DIALOG_Y,
      ;resizable => true,
      ;mac_only_use_nswindow => true}
    @dialog = UI;;WebDialog.new(keys)

thomthom

Thanks Jim. Would probably be able to guess most - but...

What's unexpected there is :mac_only_use_nswindow - Same as WebDialog.navigation_buttons_enabled?