New API doc - typos and questions

MarkBergaas

Behavior.snapto

I see two problems with the documentation of this method (I would like to call it a property, but that is probably my C# habit talking):

The "Returns:" section says it returns true or false, but it actually returns one of the 4 values listed in the description above "Returns:" (the default seems to be SnapTo_Arbitrary). The first sentence of the description ("The snapto method is used to verify the status of a component's "snap to" behavior.") also implies that the return value is a status, not the actual "snap to" selection.

It would be very helpful if the documentation of this method would make it clear that the value of Behavior.snapto works in conjunction with the value of Behavior.is2d to set the "glue to" behavior. If is2d equals false, the component will not glue to anything, no matter what value snapto returns. If is2d equals true, the component will glue to faces matching the snapto value.

I don’t think it is at all clear that these two (snapto and is2d) are related. It would be helpful to include a reference to snapto in the description of is2d, also.

This second issue applies equally, if not more, to the snapto= and is2d= methods.

Jim

Pages.add should contain some of this information about the meaning of the flags argument.

[ and also, Pages.add returns a Page object, not nil. ]


# The Page Constants
Object.constants.grep /^pag/i
["PAGE_USE_SECTION_PLANES", "PAGE_USE_ALL", "PAGE_NO_CAMERA", "PAGE_USE_CAMERA", "PAGE_USE_RENDERING_OPTIONS", "PAGE_USE_SHADOWINFO", "PAGE_USE_SKETCHCS", "PAGE_USE_HIDDEN", "PAGE_USE_LAYER_VISIBILITY"]


model = Sketchup.active_model
pages = model.pages
index = 0
page = pages.add("New Page", PAGE_USE_ALL, index)

If you want to pick and choose which options, bitwise OR ( | ) the options together:


model = Sketchup.active_model
pages = model.pages
index = 0
page = pages.add("New Page", (PAGE_USE_HIDDEN|PAGE_USE_CAMERA), index)

Jim

View.write_image

From my tests, write_image will accept several common image formats - .jpg, .bmp, .png at least. There is no mention of this in the docu. Just include the extension in the filename - as in "path/to/my_image.png"

If you do not provide the optional width or height, the image uses the View Size for the written image.

write_image returns true on success or false on failure, not nil (from my experience.)

thomthom

Entities.add_arc
http://code.google.com/apis/sketchup/docs/ourdoc/entities.html#add_arc

@unknownuser said:

Returns:
arccurve
an ArcCurve object if successful

It returns an array of edges instead.

avariant

PolygonMesh.uv_at

Arguments;  
index    The index for the texture coordinate.

Doesn't include the second argument, which is true for front face coordinates, false for back face.

PolygonMesh.uvs
Doesn't include the required argument, true for front face coordinates, false for back face.

thomthom

Camera.set
http://code.google.com/apis/sketchup/docs/ourdoc/camera.html#set

@unknownuser said:

The initialize method is deprecated. It essentially does the same thing as Camera.set.

Camera.set does what Camera.set does? ... "Spider Pig! Spider Pig! Does whatever piderpigs does."

thomthom

View.pickray
http://code.google.com/apis/sketchup/docs/ourdoc/view.html#pickray

@unknownuser said:

The pickray method is used to retrieve a ray passing through a given screen position in the viewing direction.

Returns:
ray
a ray

The "ray" is a Line; Array [Point3D, Vector3D] and the Point3D is the camera.eye.

Chris Fullmer

I hope Scott stops by soon. He's got a lot of stuff here to pick up

Chris

thomthom

Looking back at this thread I can trail the subjects I was looking into while making plugins. Like breadcrumbs.

TIG

UI.menu lists the valid menus titles, one is 'Create' isn't it 'Draw' ?

RunnerPack

@unknownuser said:

Point3d.offset (http://code.google.com/apis/sketchup/docs/ourdoc/point3d.html#offset) Description of the length parameter:

(optional) the distance to offset. If not provided, the offset is my a distance equal to the vector length.

Suggestion:

The (optional) offset distance. If not provided, the point is offset a distance equal to the vector's length.

thomthom

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

@unknownuser said:

The mesh method creates a polygon mesh that represents the face. See the PolygonMesh class for more information.

Valid flags are:
* 0: Include PolygonMeshPoints,
* 1: Include PolygonMeshUVQFront,
* 2: Include PolygonMeshUVQBack,
* 4: Include PolygonMeshNormals.
Add these numbers together to combine flags. A value of 5 will include all flags, for example.

The example uses 7. Typo or undocumented feature?

avariant

@thomthom said:

The example uses 7. Typo or undocumented feature?

You can bit-wise OR the options together. 7 means 4 + 2 + 1, so normals, front UV, and back UV.

remus

@unknownuser said:

For acolor it's always = 255 [100% opaque]... there is a color.alpha= method but it's never ever worked, you must set alpha [transparency] for a material itself not material.color e.g. material.alpha=0.4 for 40% opacity will work but the material.color.alpha still reports 255 [100%], if you try to change it, it just does nothing !

So to recap - the fourth item in a SUp material.color array is its alpha [r,g,b,a] but it's not used ! The alpha of the material itself works as a 0 to 1.0, equivalent to % setting of opacity...
http://code.google.com/apis/sketchup/do ... color.html

thomthom

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

Returns false, not nil when user cancels.

thomthom

WebDialog.new
http://code.google.com/apis/sketchup/docs/ourdoc/webdialog.html#new

Two last parameters isn't explained.

remus

BoundingBox.min

@unknownuser said:

returns: a Point3d object representing the point where x, y, and z are the maximum in the bounding box.

Im guessing it should say minimum.

thomthom

WebDialog.get_element_value
http://code.google.com/apis/sketchup/docs/ourdoc/webdialog.html#get_element_value

The example hasn't escaped the HTML tags - so the HTML sample text is instead interpreted by the browser..

thomthom

Curve.move_vertices
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/curve.html#move_vertices

Description says:

@unknownuser said:

The vertices method retrieves a collection of all vertices in a curve.

thomthom

Tool.enableVCB?
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/tool.html#enableVCB?

@unknownuser said:

The enableVCB? method is used to tell SketchUp whether to allow the user to enter text into the VCB (value control box, aka the "measurements" panel). If you do not implement this method, then the vcb is disabled by default.

I've never used this method for my Tools. But the VCB has still worked.