New API doc - typos and questions

Dan Rathbun

Geom::Point3d.+
http://code.google.com/apis/sketchup/docs/ourdoc/point3d.html#+

The '+' operator is a fast way to add to the current x, y and z values of a point, or to set the values of a point by adding to other points together.
The end of the sentence should read, "...by adding **two** other points together."

@unknownuser said:

Returns:
vector a Vector object
There is no defined object named 'vector'. If we follow the example the class of the result is given as Geom::Point3d.

pt2 = Geom;;Point3d.new(100,200,300)
pt3 = pt2 + [1,1,1]
>> Point3d(101, 201, 301)
pt3.class
>> Geom;;Point3d

@unknownuser said:

Arguments:
point2 A Point3d object.
An ArugemtError exception is raised if point2 is a Point3d object.
Valid argument classes are: Array or Vector3d. This means to use a Point3d as an argument, you must convert to Array. Example:

pt3 = pt1 + pt2.to_a

This method needs to be fixed to take a Point3d object and internally convert it to an Array...

# internal to + method
if arg[0].is_a? Point3d { arg[0]=arg[0].to_a }

...or a Vector3d:

# internal to + method
if arg[0].is_a? Point3d { arg[0]=[0,0,0].vector_to(arg[0]) }

either way. The current implementation is clumsy.

Dan Rathbun

**Geom::Point3d.-**
http://code.google.com/apis/sketchup/docs/ourdoc/point3d.html#-

@unknownuser said:

Returns:
vector a Vector object
There is no defined object named 'vector', but there IS one named ' Vector3d'. If we follow the example the class of the result is given as Geom::Vector3d.

pt2 = Geom;;Point3d.new(100,200,300)
pt3 = pt2 - [1,1,1]
>> Vector3d(99, 199, 299)
pt3.class
>> Geom;;Vector3d

It seems a bit strange that + returns Point3d, but - returns Vector3d.

Dan Rathbun

Geom::Point3d.offset
Code example has errors:
[line1]replace"point ="with"point1 ="
[line1]use parameter delimiters both lines
[line3]replace".offset**!**"with".offset"
add comments
Corrected code:


point1 = Geom;;Point3d.new(10,10,10)
vector = Geom;;Vector3d.new(0,0,1)
point2 = point1.offset vector
# point1 is unchanged
# point2 is Point3d(10, 10, 11)

Geom::Point3d.offset!
Code example has errors:
[line1]replace"point ="with"point1 ="
[line1]use parameter delimiters both lines
add comments


point1 = Geom;;Point3d.new(10,10,10)
vector = Geom;;Vector3d.new(0,0,1)
point2 = point1.offset! vector
# point1 now equals point2
# point2 is Point3d(10, 10, 11)

Dan Rathbun

Geom::Vector3d.x=
http://code.google.com/apis/sketchup/docs/ourdoc/vector3d.html#x=
Geom::Vector3d.y=
http://code.google.com/apis/sketchup/docs/ourdoc/vector3d.html#y=
Geom::Vector3d.z=
http://code.google.com/apis/sketchup/docs/ourdoc/vector3d.html#z=

#Anchors: '=' char should be replaced with 'equals' in links.

All 3 methods suffer from the same return class anomoly as the Vector3d.[]= method, in that they return the class of the argument (which may not always be Float.) In contrast, the .x, .y and .z methods always return class Float.
Propose that the .x=, .y= and .z= methods should be modified to return Float as the .x, .y and .z methods do.

Propose to add note: "See the **.set!** method to set all three coordinates in one statement." ( .. to the description sections, of each of the three methods.)

Dan Rathbun

Geom::Vector3d.set!
http://code.google.com/apis/sketchup/docs/ourdoc/vector3d.html#set!

@unknownuser said:

This is a shortcut for writing:
Clarify: "This is a shortcut for setting all coordinates of the vector, instead of setting them individually in three statements."

@unknownuser said:

You may also call this method with an array or another vector:
Confusing. (I first took this mean that the SU extended Array class had an Array.set! method; which is NOT the case.)
Clarify: "You may also call this method with an Array or a Vector3d object as the first argument,(and any other arguments will then be ignored.)"

Add: "If only one Numeric argument is supplied, or if a one element Array is supplied, then only the x value will be changed. IF only 2 values are supplied, in the same way, then the z value will remain unchanged.
All coordinate values must be implicitly convertable to Float class.(If you pass a nil value, a TypeError exception is raised.)"

@unknownuser said:

Arguments:
x ____ The x value for the vector.
y ____ The y value for the vector.
z ____ The z value for the vector.
vector2 ____ A Vector3d object.
Remove 4th argument. (There is no valid fourth argument for this method. All args beyond 3 are ignored.)
Clarify: (suggested Argument list)
Arguments:
x ____ The x value for the vector, a Vector3d object, or an Array.
y ____ The y value for the vector. (optional)
z ____ The z value for the vector. (optional)

Better Code Example:


vector = Geom;;Vector3d.new 0,0,1
vector.set! 1,0,0  # three Numeric arguments
vector2 = Geom;;Vector3d.new 1,2,3
vector.set! vector2  # one Vector3d argument
# vector now is (1,2,3)
array1 = Array.new(4,5,6)
vector.set! array1[2]  # one Numeric argument
# vector now is (6,2,3)
vector2.set! array1  # one Array argument
# vector2 now is (4,5,6)
vector.set! [5,4]  # one Array with 2 values
# vector now is (5,4,3)
# change x and z in one statement, this way;
vector.set! 9, vector.y, 8
# vector now is (9,4,8)

Dan Rathbun

Geom::Vector3d.[=]
[="]http://code.google.com/apis/sketchup/docs/ourdoc/vector3d.html#[]=[/url]
Again the HTML anchor may cause problems in some browsers, suggest '#subscriptEquals'

Obviously the #[]= anchor tag in the url cannot even be displayed properly in this forum.All of the #anchor links to methods using special chars need to be changed to comply with the HTML spec, as ThomThom noted:
@unknownuser said:

ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). [url:nfjuel6m]http://www.w3.org/TR/html4/types.html#type-name]("http)

@unknownuser said:

Returns:
value _______ the newly set coordinate value

the Geom::Vector3d.[] method returns class Float
BUT, the Geom::Vector3d.[]= method returns the class of the argument.

The code example may be misleading to the unwary,
@unknownuser said:

value = vector[i] = coordinate

..if the class of the coordinate variable is Integer then the class of the value variable will also be Integer.
This causes a coder to do a two-step expression if they want a Float, ie:


coordinate = 2
vector[i] = coordinate # returns Integer 2
value = vector[i]  # value.class >> Float

%(#FF4000)[Two Issues:

Is 'coordinate' the correct term, or would 'component' be a better term when refering to vectors?1. If all the rest of the methods that return subscript values from a Vector3d object are Float, then perhaps this method should as well, regardless of the class of the argument.]

Dan Rathbun

Geom::Point3d.<
http://code.google.com/apis/sketchup/docs/ourdoc/point3d.html#%3C

@unknownuser said:

Returns:
true if the point2 is closer to the origin.

Following the example, I get the opposite result.

TheReturns:should probably read,
" *true* if the point2 is **farther** from the origin; *false* if the point2 is closer to the origin (than the receiver.)

TIG

@thomthom said:

Group.move!
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/group.html#move!

.move! moves to an absolute point. Worth noting in the manual.

It doesn't seem to though - we've been testing it in another thread this afternoon and it seem that it moves relative to the transformation-origin NOT the model's ORIGIN - you first have to do a transformation by vector from where it is to the ORIGIN and then off again to the absolute point ?

TIG

@dan rathbun said:

Ruby code can no longer use the nil return value in a conditional boolean statement.
There is also no way now to determine how many Dictionary objects, there are within an AttributeDictionaries collection (No Methods: .size, .length, .count, or .empty?)
There are no methods but several easy combos to do it...
You make an array of it and than get its length ?
len = AttributeDictionaries.to_a.length
or use 'each' ?
len = 0;AttributeDictionaries.each{|d|len += 1}
Where len is the AttributeDictionaries length ?

thomthom

AttributeDictionaries.to_a.length works.

thomthom

ComponentInstance.explode
http://code.google.com/apis/sketchup/docs/ourdoc/componentinstance.html#explode

Code example is irrelevant - doesn't show the use of .explode.

thomthom

RenderingOptions
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/renderingoptions.html

@unknownuser said:

FogColor

# FogDensity

FogEnd

FogStart

# FogType

FogUseBkColor

Bold entries returns nil.

The RenderingOptions I get when I iterate the collection is:

BackgroundColor
BandColor
ConstructionColor
DepthQueWidth
DisplayColorByLayer
DisplayDims
DisplayFog
DisplayInstanceAxes
DisplaySketchAxes
DisplayText
DisplayWatermarks
DrawDepthQue
DrawGround
DrawHidden
DrawHorizon
DrawLineEnds
DrawProfilesOnly
DrawSilhouettes
DrawUnderground
EdgeColorMode
EdgeDisplayMode
EdgeType
ExtendLines
FaceBackColor
FaceColorMode
FaceFrontColor
FogColor
FogEndDist
FogStartDist
FogUseBkColor
ForegroundColor
GroundColor
GroundTransparency
HideConstructionGeometry
HighlightColor
HorizonColor
InactiveHidden
InstanceHidden
JitterEdges
LineEndWidth
LineExtension
LockedColor
MaterialTransparency
ModelTransparency
RenderMode
SectionActiveColor
SectionCutWidth
SectionDefaultCutColor
SectionInactiveColor
ShowViewName
SilhouetteWidth
SkyColor
Texture
TransparencySort

If the differences is due to changes between SU version I hope the docs will say when they where removed instead of removing them from the manual. Good to know the history.

chrisglasier

Probably picked up before but I just noticed it. So just in case ...

@unknownuser said:

Drawingelement.visible=SketchUp 6.0+
The visible= method is used to set the visible status for an element. This method performs an opposite function to the hidden= method.
Arguments:
visibility true if you want to hide the element, false if not
Returns:
status true if the element has been hidden, false if the element has not been hidden.

Dan Rathbun

My previous post onSketchup::AttributeDictionarieshas been REVISED See the original post:
http://forums.sketchucation.com/posting.php?mode=reply&f=180&t=17047#pr218516

Dan Rathbun

@unknownuser said:

AttributeDictionaries (Introduction )
http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionaries.html
You access this class not by performing an AttributeDictionaries.new but by grabbing a handle from an existing entity.
... which is refering to Sketchup::Entity.attribute_dictionaries
http://code.google.com/apis/sketchup/docs/ourdoc/entity.html#attribute_dictionaries

@dan rathbun said:

http://forums.sketchucation.com/viewtopic.php?f=180&t=17047&p=208352#p208352
This only works for model objects (seems the model has an empty dictionary list by default.) Other entities will return nil (as they do not have an AttributeDictionaries object created until after an AttributeDictionary has been attached.); the API should note that first a script needs to create an AttributeDictionary object, before the AttributeDictionaries object can be 'grabbed' (because it does not yet exist.)

UPDATE (2010JAN23-DanRathbun) PC ver 7.1.6860:
REVISED (2010JAN28-DanRathbun):In, SU ver 7.1, IF the Dynamic Components extension is turned OFF, the entity.attribute_dictionariesmethod will appear to always return aSketchup::AttributeDictionariesobject for the entity, regardless of whether there are any memberSketchup::AttributeDictionary%(#4040BF)[objects.

In addition, (if DCs are OFF,) all of the methods of the]Sketchup::AttributeDictionaryclass (except.name,) will no longer work!

Theentity.attribute_dictionariesmethod was NOT changed in the previous release, as I thought. The method works as the API says it does, returning "nil if there are none." BUT the Dynamic Components extension must be enabled."
http://code.google.com/apis/sketchup/docs/ourdoc/entity.html#attribute_dictionaries

There is also no way to determine how many Dictionary objects, there are within an AttributeDictionaries collection (NoMethods: .size, .length, .count, or .empty?)

Dan Rathbun

Re: General

@richmorin said:

Class and method names could be turned into links
to the appropriate API page, for ease of navigation.

Rich, note the left Nav column. The second box labeled "Quick Reference" has exactly these Class index and Method index links.

Re: Array class Introduction
@richmorin said:

Specific
http://code.google.com/apis/sketchup/docs/ourdoc/array.html


> The SketchUp Array class adds ...
> ---
> SketchUp adds ...
>

The correct ruby term is **extends** (as in extending a base class.) The way it is currently worded, a reader might misconstrue that the class is a custom class within the Sketchup namespace (ie, Sketchup::Array ), which is NOT the case. My version would read " Sketchup extends the standard Ruby Array class with additional methods.."

@richmorin said:

(same subject... Array class Introduction)


> Specifically, it contains methods ...
> ---
> Specifically, it adds methods ...
>

The word ***add*** is better here, because it's more specific (as to the manner in which the base Array class was extended.)

Re: AttributeDictionaries.each
@richmorin said:

http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionaries.html


> ... all of the attributes dictionaries.
>                attribute
>

For clarity I would suggest rewording the method description as: " *The each method is used to iterate through the entire list of attribute dictionary objects*."

@unknownuser said:

Throws an exception if there are no keys.
(1) What specific exception is thrown? KeyError or IndexError or a custom SU error class? (the API should state what it is we may need to trap with a rescue clause.)
(2) Error conditions are not documented in a uniform manner throughout the API. Sometimes they are noted in the method description paragraph; sometimes (as in this case,) as a separate paragraph of the description section; other times in the ***Returns:*** section. Perhaps it's time to add a third ***Exceptions:*** section list, where the list labels would be exception class names and the defintion text would be the reason why the exception is raised.
(3) Why does this method raise an exception, and the *.[]* method returns *nil* when there are no keys (or matches)? IMHO, the proper ruby way is to raise the correct exception in both cases, AND provide the *.empty?*, *.has_key?* and *.length* (or similar named) methods so scripts can use them in conditional statements when checking the Dictionary lists. Example:

 model = Sketchup.active_model
 attrdicts = model.attribute_dictionaries
 if not attrdicts.empty?
   attrdicts.each {|key,value| puts key.to_s+" is "+value.to_s }
 else
   puts "Dictionary List is Empty!"
 end

It just seems strange, as these are Array or Hash type classes, and they didn't inherit some of the basic funtionality, that they should have. Which brings us to...
**(4) AttributeDictionaries.member?** is undocumented. Not that it does us any good, as it only takes an object, not a string name (returns false even for vaild dictionary names.) This means you need to know it exists in the first place, so why would we need to test it's membership? *.member?* is normally an alias for *.has_key?*, so if this method could be updated to ALSO take the dictionary string name, it would serve us well.

Re: AttributeDictionaries Introduction

@unknownuser said:

You access this class not by performing an AttributeDictionaries.new but by grabbing a handle from an existing entity.
http://code.google.com/apis/sketchup/docs/ourdoc/entity.html#attribute_dictionaries
This only works for [ruby:2bffgwcd]model[/ruby:2bffgwcd] objects (seems the model has an empty dictionary list by default.) Other entities will return nil (as they do not have an AttributeDictionaries object created until after an AttributeDictionary has been attached.); the API should note that first a script needs to create an AttributeDictionary object, before the AttributeDictionaries object can be 'grabbed' (because it does not yet exist.)
UPDATE (2010JAN23-DanRathbun) PC ver 7.1.6860:
REVISED (2010JAN28-DanRathbun) See later post (this forum):
[url=http://forums.sketchucation.com/viewtopic.php?f=180&t=17047&p=218516#p218516:2bffgwcd]http://forums.sketchucation.com/viewtopic.php?f=180&...p218516[/url:2bffgwcd]

[i:2bffgwcd]Re: AttributeDictionary Introduction[/i:2bffgwcd]

@unknownuser said:

An Entity or Model object can have any number of AttributeDictionaries.
[url:2bffgwcd]http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionary.html[/url:2bffgwcd]
This is confounding the use of the two differnet class names. (The parent should have been named [i:2bffgwcd]DictionaryList[/i:2bffgwcd], or better yet, [i:2bffgwcd]AttributeLibrary[/i:2bffgwcd]. [as in: shelf space for many dictionary volumes.]) Actually each entity can have only 1 [ruby:2bffgwcd]AttributeDictionaries[/ruby:2bffgwcd] object. The sentecnce should read "[ruby:2bffgwcd]An Entity or Model object can have any number of AttributeDictionary objects[/ruby:2bffgwcd]."

Both AttributeDictionaries and AttributeDictionary Introductions should have an 'also see note' directing readers to Entity class methods [ruby:2bffgwcd].attribute_dictionary[/ruby:2bffgwcd] and [ruby:2bffgwcd].attribute_dictionaries[/ruby:2bffgwcd] on how to create them.

It would have been nice to have a [ruby:2bffgwcd]new[/ruby:2bffgwcd] method for the child dictionary objects at least. We could then call something like:


myEntity = Sketchup.active_model.selection[0]
#
# this is more intuitive
attrdict = AttributeDictionary.new("My Dictionary", myEntity)
#
# this is not so
attrdict = myEntity.attribute_dictionary("My Dictionary", true)

thomthom

Layer.page_behavior
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/layer.html#page_behavior

Only lists two flags:

@unknownuser said:

LAYER_VISIBLE_BY_DEFAULT 0x0000,

LAYER_HIDDEN_BY_DEFAULT 0x0001.

But Layer.page_behavior= lists other constants.
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/layer.html#page_behavior=

@unknownuser said:

* LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES: 0x0000,
* LAYER_IS_VISIBLE_ON_NEW_PAGES: 0x0010,
* LAYER_IS_HIDDEN_ON_NEW_PAGES: 0x0020.

Meaning the constants in the getter should be the same for the setter.

LAYER_VISIBLE_BY_DEFAULT: 0x0000 LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES: 0x0000 LAYER_HIDDEN_BY_DEFAULT: 0x0001 LAYER_IS_VISIBLE_ON_NEW_PAGES: 0x0010 LAYER_IS_HIDDEN_ON_NEW_PAGES: 0x0020
And .page_behavior can be any bitwise combination of these.

thomthom

Layer.page_behavior=
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/layer.html#page_behavior=

@unknownuser said:

To create a layer which is only visible on a single page, you can set its page behavior flags to LAYER_HIDDEN_BY_DEFAULT | LAYER_IS_HIDDEN_ON_NEW_PAGES

When I used that to set the behaviour of a layer on a model I get an error message when I save saying that something was messed up and this is the result of SU fixing it:

@unknownuser said:

Results of Validity Check.

The behavior for CLayer (178941) is not valid - fixed

thomthom

Tools.pop_tool
http://code.google.com/apis/sketchup/docs/ourdoc/tools.html#pop_tool

@unknownuser said:

Returns: tool
the last pushed Tool object.

I only get true or false.

Dan Rathbun

Sketchup::ViewObserver
http://code.google.com/apis/sketchup/docs/ourdoc/viewobserver.html
@unknownuser said:

(Introduction Section > Code example:)

# This is an example of an observer that watches tool interactions.

The comment line should read:" # This is an example of an observer that watches **for changes to a view**."