SketchUp  Ruby API Reference 

Class Index

Method Index

Developers Guide

Examples

Sketchup Module

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

Parent:N/A

Methods: active_model, add_observer, app_name, create_texture_writer, display_name_from_action, file_new, find_support_file, find_support_files, format_angle, format_area, format_degrees, format_length, get_datfile_info, get_locale, get_shortcuts, is_online, is_valid_filename?, load, open_file, os_language,  parse_length, read_default, register_extension, register_importer, remove_observer, require, save_thumbnail, send_action, set_status_text=, set_status_text, template, template=, template_dir, undo, vcb_label=, vcb_value=, version, version_number, write_default

Example Code:sketchuptests.rb

Module Methods


active_model

Syntax

model = Sketchup.active_model

Return Value

model – active model object if successful, false if unsuccessful

Example

model = Sketchup.active_model
if (! model)
UI.messagebox “Failure”else
# code acting on the model

 

 


add_observer

The add_observer method is used to add an observer to the current object.

Syntax

status = Sketchup.add_observer observer

Arguments

observer - an observer

Return Value

status - true if successful, false if unsuccessful.

Example

 

 


app_name

The app_name method is used to retrieve the current application name.

Syntax

name = Sketchup.app_name

Return Value

name - the name of the application, either "Google SketchUp Pro" or "Google SketchUp"

Example

 

 

 


create_texture_writer

The create_texture_writer method is used to create a TextureWriter object.

Syntax

texturewriter = Sketchup.create_texture_writer

Return Value

texturewriter - a texturewriter object if successful.

Example

 

 

 


display_name_from_action

The display_ name_from_action method is used to gets a user-friendly name from an action string.

Syntax

friendly_name = Sketchup.display_name_from_action action_name

Arguments

action_name = an action string. See comments for a valid list of action strings.

Return Value

friendly_name = a friendly name.

Comments

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

Sketchup.display_name_from_action("viewRight:")

 

 


file_new 

The file_new method is used to create a new file.

Syntax

Sketchup = Sketchup.file_new

Return Value

Sketchup = a Sketchup object if successful.

 

 


find_support_files  

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

Syntax

array = Sketchup.find_support_files “filename”, “directory”

Arguments

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

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

Return Value

array - an array of files. If unsuccessful, the method returns false.

Comments

Forward slashes must be used to delimit between directory names.

 

 


find_support_file 

The find_support_files 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

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.

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_datfile_info

The get_datfile_info method is used to retrieve the value for the given key from Sketchup.dat.

Syntax

value = Sketchup.get_datfile_info key,default value

Arguments

key - the key whose value you want to retrieve

default value - the default value you want returned if key is not available.

Return Value

value - a string value if successful.

Comments

If the key is not found, default_value is returned.

Example

 

 

 


get_locale 

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

Syntax

locale = Sketchup.getlocale

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

Return Value

shortcuts - an array of shortcut strings

Example 

shortcuts = Sketchup.get_shortcuts
if (shortcuts)
UI.messagebox shortcuts
end

 

 


is_online

The is_online method is used to verify a connection to the Internet.

Syntax

status = Sktechup.is_online

Return Value

status - true if successful, false if unsuccessful.

Example

 

 

 


is_valid_filename?

The is_valid_filename? method is used to determine whether a filename contains illegal characters.

Syntax

status = Sketchup.is_valid_filename? filename

Arguments

filename - a filename string

Return Value

status - true if filename is valid, false if filename is invalid (contains illegal characters).

Example

 

 

 


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.

 

 


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

 

 


os_language

The os_language method is used to retrieve a two character code representing the os language.

Syntax

language = SketchUp.os_language

Return Value

lanuage - a two character code representing the os language. For example, EN represents English.

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.

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

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

 

 


register_importer

The register_importer method is used to register an importer with SketchUp.

Syntax

status = Sketchup.register_importer importer

Arguments

importer - an Importer object representing the importer.

Return Value

status - true if successful, false if unsuccessful.

Example

 

 

 



remove_observer

The remove_observer method is used to remove an observer from the current object.

Syntax

status = object.remove_observer observer

Arguments

observer - an observer

Return Value

true if successful, false if unsuccessful.

Example

 

 


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.

 

 


save_thumbnail

The save_thumbnail method is used to generate a thumbnail for any SKP file - not necessarily the loaded model.

Syntax

status = "skp_filename", "image_filename"

Arguments

"skp_filename" - the name of the SketchUp file whose model you want represented in the thumbnail.

"image_filename" - the name of the file where the thumbnail will be saved.

Return Value

status - true if successful, false if unsuccessful.

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

 

 


template

The template method is used to get the file name of the current template.

Syntax

name = Sketchup.template

Return Value

name - the current template

Example

 

 


template=

The template= method is used to set the file name of the current template.

Syntax

status = Sketchup.template= "filename"

Arguments

"filename" - the name of the template to set.

Return Value

status - true if successful, false if unsuccessful.

Example

 

 


template_dir

The template_dir is used to retrieve the directory where templates are stored by the SketchUp install.

Syntax

directory = Sketchup.template_dir

Return Values

directory - the directory where templates are stored.

Example

 

 

 


undo 

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

Syntax

sketchup.undo

 

 


version 

Gets the current version of sketchup in decimal form.

Syntax

version = Sketchup.version

Return Value

version – the decimal form of the version

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

Return Value

version – the whole number form of the version

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.

Example 

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