module Sketchup

 

Parent: N/A

Class Index

Methods: active_model, find_support_files, format_angle, format_area, format_degrees, format_length, get_locale, get_shortcuts, load, open_file,  parse_length, read_default, register_extension, require, send_action, set_status_text, undo, version, version_number, write_default

 

Sample Code: SketchupTests.rb

 

The Sketchup module contains number of important utility methods for use in your Ruby scripts.  
 

Module Methods

 

active_model

model = Sketchup.active_model

Syntax:

model = Sketchup.active_model

Arguments:

 

Return Value:

model – active model object if successful, false if unsuccessful

Comments:

 

Example:

model = Sketchup.active_model

if (! model)

     UI.messagebox “Failure”

else

     # code acting on the model

 
 

find_support_files

The find_support_file method is used to retrieve the relative path and name of a file within the SketchUp installation directory.

Syntax:

path = Sketchup.find_support_file “filename”, “directory”

Arguments:

“filename” – name of the filename you want to find

“directory” – (optional) directory relative to the SketchUp installation directory.

Return Value:

path - the entire path if successful. If unsuccessful, the method returns false.

Comments:

Forward slashes must be used to delimit between directory names.

Example:

help_file = Sketchup.find_support_file “index.html”, “Ruby/Docs/”

if (help_file)

     # Print out the help_file full path
UI.messagebox help_file

     # Open the help_file in a web browser
UI.openURL file:// + help_file
else
UI.messagebox “Failure”

end

 

format_angle

The format_angle method formats a number as an angle (in radians) using the current units settings. For example, 10 becomes 573 or 10 x 180/pi.

Syntax:

radians = Sketchup.format_angle number

Arguments:

number – a number to be formatted

Return Value:

radians – an angle in radians if successful, false if unsuccessful

Comments:

 

Example:

radians = Sketchup.format_angle 10

if (radians)
UI.messagebox radians

end

 

format_area

The format_area method formats a number as an area using the current units settings.

Syntax:

area = Sketchup.format_area number

Arguments:

number – a number to be formatted

Return Value:

area – an area if successful, false if unsuccessful.

Comments:

The default unit setting is inches. For example, 10 becomes 10 inches squared.

Example:

area = Sketchup.format_area 10

if (area)
UI.messagebox area

end

 

format_degrees

The format_degrees method formats a number as an angle given in degrees. For example, 10 becomes 10.0 degrees.

Syntax:

degrees = Sketchup.format_degrees number

Arguments:

number – a number to be formatted.

Return Value:

degrees – degrees if successful, false if unsuccessful.

Comments:

 

Example:

degrees = Sketchup.format_area 10

if (degrees)

    UI.messagebox degrees

end

 

format_length

The format_length method formats a number as a length using the current units settings.

Syntax:

length = Sketchup.format_length number

Arguments:

number – a number to be formatted

Return Value:

length – length if successful, false if unsuccessful

Comments:

The default unit setting is inches. For example, 10 becomes 10”.

Example:

length = Sketchup.format_area 10

if (length)

     UI.messagebox length

end

 

get_locale

The get_locale method returns the locale for the machine where SketchUp is installed.

Syntax:

locale = Sketchup.getlocale

Arguments:

 

Return Value:

locale - a two character locale (see comments)

Comments:

Valid return values are: EN, QE, DE, FR, JP, ES, and IT

Example:

locale = Sketchup.get_locale

if (locale)

     UI.messagebox locale

end

 

get_shortcuts

The get_shortcuts method retrieves an array of all shortcuts currently registered with SketchUp.

Syntax:

shortcuts = sketchup.get_shortcuts

Arguments:

 

Return Value:

shortcuts - an array of shortcut strings

Comments:

 

Example:

shortcuts = Sketchup.get_shortcuts

if (shortcuts)

     UI.messagebox shortcuts

end

 

load

The load method is used to include encrypted and nonencrypted ruby files.

Syntax:

status = sketchup.load path

Arguments:

path - the path, including the filename, to the file you want to require.

Return Value:

status - True if the file is included. False if the file is not included.

Comments:

You do not need to include the file extension on the path. This method will look for .rb first (unencrypted) and then .rbs (encrypted). The scrambler application used to encrypt SketchUp ruby scripts is available in the SketchUp SDK. Send a request to sdk@sketchup.com to obtain the SDK.

Example:

 

 

open_file

The open_file method is used to open a file.

Syntax:

file = sketchup.open_file filename

Arguments:

filename - the path and filename to open

Return Value:

file - a file

Comments:

 

Example:

 

 

 

 

parse_length

The parse_length method parses a string as a length.

Syntax:

length = Sketchup.parse_length “stringnumber”

Arguments:

“stringnumber” – the string number representation to be parsed as a number

Return Value:

length – the numerical representation of the string if successful, or false if unsuccessful.

Comments:

For example, “200” becomes 200.0.

Example:

length = Sketchup.parse_length “200”

if (length)

     UI.messagebox length

end

 

read_default

The read_defaults method is used to retrieve the string associated with a value within the specified sub-section section of a .INI file or registry (within the Software > @Last Software > SketchUp section).

Syntax:

result = Sketchup.read_default “section”, “variable”, “default”

Arguments:

“section” – A section in an .INI or registry

“variable” – A variable within the section

“default” – (optional) A default value if the value is not found

Return Value:

result – True if successful, false if unsuccessful.

Comments:

 

Example:

# Write to the Windows registry
Sketchup.write_default “Test”, “TesterName”, “Jon Bradley”

# Read from the Windows registry
value = Sketchup.read_default “Test”, “TesterName,” “Default”

if(value)

    UI.messagebox value

end

 

register_extension

The register_extension method is used to register an extension with SketchUp's extension manager (in SketchUp preferences).

Syntax:

status = Sketchup.register_extension extension, registered?

Arguments:

extension - a SketchupExtension object

registered? - true if extension should be automatically loaded the first time it is registered

Return Value:

status - true if extension registered properly

Comments:

 

Example:

utilitiesExtension = SketchupExtension.new $uStrings.GetString("Utilities Tools"), "Utilities/utilitiesTools.rb"               

utilitiesExtension.description=$uStrings.GetString("Adds Tools->Utilities to the SketchUp inteface.  The Utilities submenu contains two tools: Create Face and Query Tool.")                       

Sketchup.register_extension utilitiesExtension, false

 

require

The require method is used to include encrypted and nonencrypted ruby files.

Syntax:

status = sketchup.require path

Arguments:

path - the path, including the filename, to the file you want to require.

Return Value:

status - True if the file is included. False if the file is not included.

Comments:

You do not need to include the file extension on the path. This method will look for .rb first (unencrypted) and then .rbs (encrypted). The scrambler application used to encrypt SketchUp ruby scripts is available in the SketchUp SDK. Send a request to sdk@sketchup.com to obtain the SDK.

Example:

 

 

send_action

The send_action method sends a message to the message queue to perform some action asynchronously.

Syntax:

result = Sketchup.send_action “action”

Arguments:

“action” – the action to be performed

Return Value:

result – true if successful; false if unsuccessful

Comments:

Valid actions are:

showRubyPanel:
viewBack:
viewBottom:              
viewFront:                
viewIso:
viewLeft:
viewRight:
viewTop:
viewPerspective:
viewShowAxes:
viewShowHidden:
viewZoomExtents:
viewZoomToSelection:
viewUndo:
selectOrbitTool:
selectPositionCameraTool:
selectDollyTool:
selectTurnTool:
selectWalkTool:
selectZoomTool:
selectFieldOfViewTool:
selectZoomWindowTool:
pageAdd:
pageDelete:
pageUpdate:
pageNext:
pagePrevious:
renderWireframe:
renderHiddenLine:
renderMonochrome:
renderShaded:
renderTextures:
selectArcTool:
selectAxisTool:
selectCircleTool:
selectEraseTool:
selectFreehandTool:
selectLineTool:
selectMeasureTool:
selectMoveTool:
selectOffsetTool:
selectPaintTool:
selectPolygonTool:
selectProtractorTool:
selectPushPullTool:
selectRectangleTool:
selectRotateTool:
selectScaleTool:
selectSectionPlaneTool:
selectTextTool:
selectDimensionTool:
selectExtrudeTool:
selectSelectionTool:
editUndo:
editRedo:
editHide:
editUnhide:
fixNonPlanarFaces:

Example:

result = Sketchup.send_action “selectMoveTool:”

if (result)

    UI.messagebox “Move Tool Selected.”

else

   UI.messagebox “Error: Could not select the Move Tool”

end

 

set_status_text

The set_status_text method is used to set the text appearing on the status bar within the drawing window.

Syntax:

result = Sketchup.set_status_text “status text”  position

Arguments:

“status text” – (optional) the status text that will appear on the left-side of the status bar

position – (optional) the position where the text will appear.

Return Value:

“result” -  true if successful; false if unsuccessful

Comments:

If no arguments are passed, the status bar content is cleared. Valid POSITIONs are:

SB_PROMPT- the status text will appear at the left-side of the status bar
SB_VCB_LABEL – the status text will appear in place of the VCB label
SB_VCB_VALUE – the status text will appear in the VCB

Example:

result = Sketchup.set_status_text “This is a Test”

if (result)

    #code to do something if set_status_text is successful

end

 

undo

The undo method is used undo the last transaction on the undo stack.

Syntax:

sketchup.undo

Arguments:

 

Return Value:

 

Comments:

Returns nil.

Example:

 

 

version

Gets the current version of sketchup in decimal form.

Syntax:

version = Sketchup.version

Arguments:

 

Return Value:

version – the decimal form of the version

Comments:

 

Example:

version = Sketchup.version

if (version)

    UI.messagebox version

else

     return

end

 

version_number

Get the current version of sketchup as a whole number for comparisons.

Syntax:

version = Sketchup.version

Arguments:

 

Return Value:

version – the whole number form of the version

Comments:

 

Example:

version = Sketchup.version_number

if (version)

     UI.messagebox version

else

     return

end

 

write_defaults

The write_defaults method is used to write an entry to the specified sub-section section of a .INI file or registry (within the Software > @Last Software > SketchUp section).

Syntax:

result = Sketchup.write_defults “section”, “variable”, “value”

Arguments:

“section” – a section in an .INI or registry

“variable” – the variable to be written within the section

“value” – the value to be written

Return Value:

result – true if successful, false if unsuccessful.

Comments:

 

Example:

# Write to the Windows registry

Sketchup.write_default “Test”, “TesterName”, “Jon Bradley”