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”