New API doc - typos and questions

[Dan Rathbun]

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

The following methods need to be documented:

%(#BF0000)[last_height
last_height=
last_width
last_width=]

We are also still wishing to know what the extra Mac parameter for WebDialog.new is for, ie:
:mac_only_use_nswindow = boolean
What's the difference? ... and what's the default?

[Dan Rathbun]

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

@unknownuser said:

The write_image method is used to grab a portion of the screen and save the image to the given file path.
Arguments: **> %(#000000)[*image_path*]%(#E0E0E0)[______]%(#000000)[The destination path of the saved image. *top_left_x*]%(#E0E0E0)[______]%(#000000)[The x coordinate of the upper left] %(#E0E0E0)[__________________]%(#000000)[corner of the region to grab. *top_left_y*]%(#E0E0E0)[______]%(#000000)[The]%(#EF4000)[**x**]%(#000000)[coordinate of the upper left] %(#E0E0E0)[__________________]%(#000000)[corner of the region to grab. *bottom_right_x*]%(#E0E0E0)[__]%(#000000)[The x coordinate of the lower right] %(#E0E0E0)[__________________]%(#000000)[corner of the region to grab. *bottom_right_y*]%(#E0E0E0)[__]%(#000000)[The]%(#EF4000)[**x**]%(#000000)[coordinate of the lower right corner] %(#E0E0E0)[__________________]%(#000000)[of the region to grab.] **
%(#EF4000)[(1) The y coordinate arguments should read 'y' and not 'x'.

(2) The coordinates are relative (in the curent implementation,) to the origin of the webdialog's client area, not the screen origin.

(3) The top_left_x and top_left_y arguments APPEAR to work (and also default to 0,0 of the client area.)
BUG: The bottom_right_x and bottom_right_y arguments SEEM to always get set to top_left_x**+clientareawidth and top_right_y+**clientareaheight. Changing (specifying) these 4th and 5th arguments SEEMS to have no effect (at least on PC.)

(4) So.. although omitted from the API, only the 1st argument is necessary. Simply specifying a file (of the imagetype desired,) produces an image of the WebDialog client area, by default.]

FUTURE:

(a) It is more intuitive, if the 4th and 5th arguments are just widthand heightoffsets from the top_x and top_y (respectively.)

(b) I would like a 6th argument origin which would need to default to 'client', with the optional setting 'screen' so we can grab an image of the entire WebDialog (including frame and captionbar, etc.)

• The top_x and top_y arguments should then default to the WebDialog's topleft xy screen position.* The 4th and 5th arguments should be width and height offsets, from the 2nd and 3rd arguments; and should default to the WebDialogs entire window width and height.* Coders should be able to increase the grabarea to perhaps include portions of other windows on the screen (which may be other dialogs or part of the Sketchup viewport. This may be for tutorial use or to show a result in SU, given a setting in a webdialog (such as when reporting a bug to a plugin developer.)
  (c) Because WebDialogs, are movable, and often resizable, it would be good to have WebDialog instance methods to get the current screen position, current total size, current client size as two-element arrays, which can be used to pass arguments into write_image or any other method.

UPDATE: Just noticed that there are two undocumented methods that can satisfy the need for current total webdialog size. [url=http://forums.sketchucation.com/viewtopic.php?f=180&t=17047&p=230668#p230668:8pzn7g4t]See my next post...[/url:8pzn7g4t]
_

[Dan Rathbun]

API - Release Notes webpage error
http://code.google.com/apis/sketchup/docs/releases.html

The H2 Heading "What's new in SketchUp 7" is not displayed as a H2 heading.

The error is caused by a missing '>' (greaterthan character) on the end of the preceeding <P> element closing tag, which is now: '</P'
ie, snippit from current HTML source (line 378):

` %(#804000)[<p class="post"> </p

<h2>What's new in SketchUp 7</h2>]`

[thomthom]

whoa! we can post comments to the API doc now?!? whoppie!

[scottlininger]

Yes, you can finally comment directly in the API docs (scroll to the bottom of most of the pages). Hopefully this will help the community share their insights into the API.

We are still working through the list of comments from this thread, so don't feel as if you must copy and paste your (excellent) feedback into the site. But you can if you want to.

Cheers,

[thomthom]

Thanks Scott.
Is it better that we post new comments in the actual APi docs now?

@unknownuser said:

so don't feel as if you must copy and paste your (excellent) feedback into the site. But you can if you want to.
I expect I'll put down a couple of notes on some of the key issues/gotchas,

[scottlininger]

New notes should be posted directly to the api site. That way folks visiting the docs can see them immediately and can vote on the most helpful ones. As soon as we close out the issues in this thread, I will remove it from the forums.

[thomthom]

Eeexcellent!

[Dan Rathbun]

@unknownuser said:

As soon as we close out the issues in this thread, I will remove it from the forums.

Don't you dare! This thread was started by ThomThom.

(1) It is more than just Errors to fix in the API docs.

• It has ideas about making the API Docs themselves better.* It has some sample code postings.* It has some Example code (incl. one posted by you yourself Scott regarding Materials Observer,) that would be lost if the entire thread was to be deleted.* It has some suggestions for new API features (new methods, etc.) [that need to be moved to some other thread first; I think there's a hard to find API WishList somewhere.]* It has some Questions posed (some of which have never been answered,) whose answers are not really content that actually will go into the API Programmer's Reference, but are of interest.
  (2) The Error postings are(to"we the customers",) a record of date and time, that an error or omission was logged.

• As it was supposed to work, you were given Moderator rights, on the promise that you would MARK the Error posts, when they were fixed (bold Green with date.)* This would then give "we" the idea of the responce time the GSUPT in attending to these errors. Any customer, in any business sector should expect no less. Any Company or Business should expect to be judged on the basis of their past performance. (Unless of course, if your Toyota.) * I can see only a couple, of 'fixed marks' in the whole thread. YES, we understand your busy, etc., but Jim and others had offered to do the 'marking' for you. You, however, insisted that it would be easier for you to mark them yourself.* I feel the record should stand, and I don't care who marks them; but those fixed should be marked as such.
  (3)I understand wanting to start fresh for the next API Revision, BUT...

• If there was a Revision / Issue number on the API documents page(s) we would be able to correlate the Error threads HERE (on SCF,) with the doc pages over on code.google.com

• THEN whenever you push an update, we can retire a thread here and start a new one for the next Revision.
  (4) In order to help make this work better in the future:

• We need to stop being lazy, and post ONLYErrors to the API Error threads.* Post API Suggestions to the API WishList (me guilty!) * Post API Docs Discussions to the API Comments thread Remus just started.* We need to discuss the issue of whether a feature or method behavior is or is not an error, in a separate thread (it's own or the Discussion thread,) and then only when the issue is identified as a error, post a 'action item' in the current API Error thread.* The current API Error thread's title needs to be marked [current].* Retired API Error threads should be re-labeled [closed].* (Each API Error thread start post should have a standardized list similar to the 6 bullet items above, along with the current API Docs Revision / Issue number at the top.)

@ThomThom: So, of course this means this whole post should be moved to the Discussion thread. (Everything from ThomThom's "whoa!" post on down.)

[thomthom]

How about - when the issues from this thread has been addressed we lock and unstick it?

(I can move some posts around later on.)

[tobiaskordts]

TextureWriter.write_all
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/texturewriter.html#write_all

@unknownuser said:

Arguments:
entity: A face, image, component instance, group, or layer to write.
dirname: The directory to write to.
side: If the entity is a face, the side is used to indicate the side of the face being written (true if front, false if back.)
Returns:

The third parameter is wrong. True activates the 8.3 file naming convention, false for extended filenames.

[Dan Rathbun]

@thomthom said:

How about - when the issues from this thread has been addressed we lock and unstick it?

(I can move some posts around later on.)

I can move my suggestions over to the 'API WishList' thread. It seemed easier to voice them at the time I noticed the errors (I always added them after stating the errors in a different color.)

But I can understand how all the extra 'noise' makes using the thread as a checklist difficult for the GSUPT (Google Sketchup Product Team.)

[cjthompson]

The "View" documentation page is almost completely blocked by the user comments section:

EDIT: Fixed.

[scottlininger]

@dan rathbun said:

@unknownuser said:

As soon as we close out the issues in this thread, I will remove it from the forums.

Don't you dare!

All great points, Dan. There is a valuable historical record here, and there are a lot of posts that aren't simple docs corrections. No reason to remove it. More what I'm getting at is to make it clear where different kind of posts are best shared, as you said. This is the community's site, not mine, so ultimately it's the community's decision!

Cheers,

[tomasz]

@unknownuser said:

Model.select_tool
.....
Arguments:
tool - The Tool object you want to select.

**Returns:**
tool  - **A Tool object.** %(#FF0000)[False! It returns **Sketchup::Model**]

[cjthompson]

http://code.google.com/apis/sketchup/docs/ourdoc/face.html#classify_point

@unknownuser said:

The classify_point method is used to determine if a given Point3d is on your face. The return value will be from this list:

0: PointUnknown,
1: PointInside,
2: PointOnVertex,
4: PointOnEdge,
8: PointOnFace,
16: PointOutside

the list should be:
0: PointUnknown,
1: PointInside,
2: PointOnEdge,
4: PointOnVertex,
8: PointOnPlane,
16: PointOutside

[thomthom]

@cjthompson said:

http://code.google.com/apis/sketchup/docs/ourdoc/face.html#classify_point
the list should be:
0: PointUnknown,
1: PointInside,
2: PointOnEdge,
4: PointOnVertex,
8: PointOnPlane,
16: PointOutside

What?? ... I need to check some of my plugins...

[Dan Rathbun]

Model.get_product_family
http://code.google.com/apis/sketchup/docs/ourdoc/model.html#get_product_family

[url=http://forums.sketchucation.com/viewtopic.php?f=180&t=5868&p=236483#p35213:1wad19kf]This thread[/url:1wad19kf] gives a second-hand indication that Model.get_product_family is deprecated and "might be removed from the API at any time."

So the question(s) I have is:

Is it ( Model.get_product_family ) really to be considered as deprecated ??

And if so, should not the API doc (link above,) mention this ( and perhaps direct coders to use Sketchup.is_pro? instead ) ??

[tomasz]

@unknownuser said:

WebDialog.set_full_security=
The set_full_security= method is used to place the WebDialog into a higher security mode where remote URLs and plugins (such as Flash) are not allowed inside the browser. This defaults to false when a new WebDialog is created.

This method does not exist. There is set_full_security BUT It doesn't take arguments!! Also I am not sure if it defaults to false on MAC since it doesn't display Flash while under Windows it does.

[Dan Rathbun]

WebDialog.set_full_security
@unknownuser said:

@unknownuser said:

WebDialog.set_full_security=
The set_full_security= method is used to place the WebDialog into a higher security mode where remote URLs and plugins (such as Flash) are not allowed inside the browser. This defaults to false when a new WebDialog is created.

This method does not exist. There is set_full_security BUT It doesn't take arguments!! Also I am not sure if it defaults to false on MAC since it doesn't display Flash while under Windows it does.

Also the API code example has nothing to do with this method.