Google SketchUp Ruby API

Introduction
- Getting Started
- Tutorials

Quick Reference

Object Reference
- App Level Classes
  - SketchUp
  - Model
  - AttributeDictionary
  - Animation
  - Camera
  - Color
  - Extension
  - Importer
  - OptionsManager
  - OptionsProvider
  - Set
  - TextureWriter
  - View
  - UVHelper
- Entity Classes
  - Entity
  - Drawingelement
  - ArcCurve
  - Behavior
  - ComponentDefinition
  - ComponentInstance
  - ConstructionLine
  - ConstructionPoint
  - Curve
  - Edge
  - EdgeUse
  - Face
  - Group
  - Image
  - Material
  - Layer
  - Loop
  - Page
  - SectionPlane
  - ShadowInfo
  - Style
  - Text
  - Texture
- Collection Classes
  - AttributeDictionaries
  - DefinitionList
  - Entities
  - Layers
  - Materials
  - Pages
  - RenderingOptions
  - Selection
  - Styles
  - Tools
- Geom Classes
  - Geom
  - BoundingBox
  - LatLong
  - Point3d
  - PolygonMesh
  - Vector3d
  - Vertex
  - Transformation
- UI Classes
  - UI
  - Command
  - InputPoint
  - PickHelper
  - Menu
  - Tool
  - Toolbar
  - WebDialog
- Observer Classes
- Core Ruby Classes
  - Array
  - Length
  - Numeric
  - String

UI

module

Parent: N/A

Introduction

SketchUp 6.0+

The UI module contains a number of methods for creating simple UI elements from a SketchUp Ruby script.

Methods

UI.add_context_menu_handlerSketchUp 6.0+

The add_context_menu_handler method is used to register a block of code with SketchUp that will be called when a context menu is to be displayed. The context menu handler can then display the context menu with the items that you have added.

See the contextmenu.rb script in the Plugins/examples directory for an example.

Arguments:

menu: A block of code that takes a menu as its only as its only argument.

Returns:

count: the number of context handlers that are registered

 # Right click on anything to see a Hello World item.
 UI.add_context_menu_handler do |context_menu|
   context_menu.add_separator
   context_menu.add_item("Hello World") { 
     UI.messagebox("Hello world")
   }
 end

UI.beepSketchUp 6.0+

The beep method plays a system beep sound.

The beep method does not accept any arguments nor return any values.

Returns:

nil

 UI.beep

UI.create_cursorSketchUp 6.0+

The create_cursor method is used to create a cursor from an image file at the specified location. This must be called from within a custom Tool. See the Tool class for a complete example.

Arguments:

filename: Filename for an image.

hot_x: An x coordinate that is the "hotpoint" for the cursor. For example, a value of 5 here would identify the hotpoint of the cursor as 5 pixels from the left edge of your cursor image.

hot_y: A y coordinate that is the "hotpoint" for the cursor.

Returns:

ID: ID associated with the cursor

 cursor_path = Sketchup.find_support_file("Pointer.png", "Plugins/")
 if cursor_path
   id = UI.create_cursor(cursor_path, 0, 0)
   UI.set_cursor(id)
 else
   id=0
 end

UI.inputboxSketchUp 6.0+

Creates a dialog box for inputting user information. The dialog box contains input fields with static text prompts, optional default values, optional drop down selections, and optional title.

You can also use this method to display drop down lists of options, by passing an optional param.

Arguments:

prompts: An array of prompt names appearing in the input box adjacent to input fields.

defaults: (optional) An array of default values for the input fields.

title_or_list: (optional) If 3 params are passed, then this value is a string containing the title of the input box. If a total of 4 params are passed, then this is an array containing pipe-separated strings of options.

title: (optional) The title for the input box.

Returns:

results: An array of returned values if the user did not cancel the dialog. If the user canceled the dialog, nil is returned. The returned values in the array will be in the same order as the input fields.

 # With three params, it shows all text boxes:
 prompts = ["What is your Name?", "What is your Age?", "Gender"]
 defaults = ["Enter name", "", "Male"]
 input = UI.inputbox prompts, defaults, "Tell me about yourself."

 # With four params, it shows a drop down box for prompts that have 
 # pipe-delimited lists of options. In this case, the Gender prompt
 # is a drop down instead of a text box.
 prompts = ["What is your Name?", "What is your Age?", "Gender"]
 defaults = ["Enter name", "", "Male"]
 list = ["", "", "Male|Female"]
 input = UI.inputbox prompts, defaults, list, "Tell me about yourself."

UI.inspector_namesSketchUp 6.0+

The inspector_names method is used to returns the names of all the inspectors. Inspectors are another name for the various floating dialog windows that you can activate from withing SketchUp, such as the Materials window.

Returns:

inspectors: a vector of strings containing the names of inspectors.

 inspectors = UI.inspector_names

UI.menuSketchUp 6.0+

The menu method retrieves a SketchUp's menu object with a given name. This is the first step toward adding your own custom items to the bottom of SketchUp's menus.

Valid menu names are: "File", "Edit", "View", "Camera", "Create", "Tools", "Page", "Window", "Plugins" and "Help".

Arguments:

menuname: The name of an existing menu.

Returns:

menu: a menu object.

 tool_menu = UI.menu "Tools"
 tool_menu.add_item("Cheese Tool") {
   UI.messagebox("Cheese activated.")
 }

UI.messageboxSketchUp 6.0+

Creates a dialog box containing static text with a series of buttons for the user to choose from.

The default message box type is MB_OK and the default title for the message box is "Validity Check." Valid message box types are:

MB_OK - Contains an OK (1)
MB_OKCANCEL - Contains OK (1) and CANCEL (2)
MB_ABORTRETRYCANCEL - Contains ABORT (3), RETRY (4), and CANCEL (2)
MB_YESNOCANCEL - Contains YES (6), NO (7), and CANCEL (2)
MB_YESNO - Contains YES (6) and NO (7)
MB_RETRYCANCEL - Contains RETRY (4) and CANCEL (2)
MB_MULTILINE - Contains and OK (1)

In a MB_MULTILINE message box, the message is displayed as a multi-line message with scrollbars (as needed).

The messagebox method returns a number corresponding to the button pressed (in parentheses above.)

Arguments:

message: The message that you want to appear in the message box.

type: (optional) message box type, which will be a constant from the list in the method comments. Default to MB_OK.

Returns:

: A number corresponding to what the user selected. This number will be an integer from the values listed in parenthesis inside the method comments.

 result = UI.messagebox "Do you like cheese?", MB_YESNO
 if result == 6 # Yes
   UI.messagebox("Sketchup likes cheese, too.")
 end

UI.model_info_pagesSketchUp 6.0+

The model_info_pages method is used to returns the names of all the available model info pages. These include UI windows such as Components, Credits, and Units.

Returns:

mipages: an array of strings containing the names of model info pages.

 mipages = UI.model_info_pages

UI.openURLSketchUp 6.0+

The openURL method is used to open the default Web browser to a URL.

Arguments:

URL: A string URL.

Returns:

status: true if successful

 status = UI.openURL "http://www.google.com"

UI.openpanelSketchUp 6.0+

The openpanel method is used to display the Open dialog box. The path that is returned can then be used inside code to open a text or image file. See the standard Ruby class File for examples of reading and writing from disk.

SU7 Bug: The wildcards are not working properly if more than one is entered (e.g. "*.jpg;*.png") or if a directory is included. The '*' gets converted to a '_'.

Arguments:

title: The title to apply to the open dialog box.

directory: The default directory for the open panel.

filename: The default filename for the open panel. On Windows, you can alternatively pass a mask, like "*.txt", to have all the .txt files display. If you want multiple file types to display, you can supply multiple masks for the filename and separate them with a semicolon, like this: "*.txt;*.zip".

Returns:

string: the full path and name of the file selected, or nil if the dialog was canceled.

 chosen_image = UI.openpanel "Open Image File", "c:\\", "*.jpg"

UI.play_soundSketchUp 6.0+

The play_sound method is used to play a sound file. Valid sound files include .wav and .mp3 files on the Mac and .wav files on the PC.

Arguments:

filename: the relative path to the filename from the Sketchup install directory, or an absolute path to the file. (See Sketchup.find_support_file for a way to search for a specific file.)

Returns:

nil

 UI.play_sound "Plugins/mediadiscussion.wav"

UI.preferences_pagesSketchUp 6.0+

The preferences_pages method is used to returns the names of all the preferences pages. These include windows like Extensions.

Returns:

prefspages: an array of strings containing the names of prefspages.

 prefs = UI.preferences_pages

UI.refresh_inspectorsSketchUp 7.0+

Tells SketchUp to refresh all inspectors such as the Component Browser and the Outliner. This is useful when you need to manually force a refresh after you've made a change to the document via Ruby. Generally, SketchUp will keep these in sync for you, but occasionally it does not, such as when model.start_operation has disabled UI updates.

Returns:

nil

 UI.refresh_inspectors

UI.savepanelSketchUp 6.0+

The savepanel method is used to display the Save dialog box. The path that is returned can then be used inside code to save out a text or image file. See the standard Ruby class File for examples of reading and writing from disk.

Arguments:

title: The title to apply to the open dialog box.

directory: The default directory for the open panel.

filename: The default filename for the open panel .

Returns:

string: the full path and name of the file selected or nil if the dialog was canceled.

 path_to_save_to = UI.savepanel "Save Image File", "c:\\", "Shapes.jpg"

UI.set_cursorSketchUp 6.0+

The set_cursor method is used to change the cursor to a new cursor with a given cursor id. See UI.create_cursor and the Tool class for details on creating your own tools with arbitrary cursors.

If you call this while a standard SketchUp tool is active, you will not see your custom cursor, as these tools are constantly setting their own cursors to indicate SketchUp's state.

Arguments:

cursor_id: The id of the cursor you want to display.

Returns:

nil

 def onSetCursor
   UI.set_cursor(@@my_custom_cursor_id)
 end

UI.set_toolbar_visibleSketchUp 6.0+

The set_toolbar_visible method is used to set whether a given toolbar is visible.

Arguments:

name: The name of a Ruby toolbar.

visible: True to make the toolbar visible, false to hide it.

Returns:

visibility: the newly set visibility state.

 status = UI.set_toolbar_visible("Camera", true)

UI.show_inspectorSketchUp 6.0+

The show_inspector method is used to display the inspector with the given name. You can get the list of valid inspectors with UI.inspector_names.

Arguments:

name: The name of inspector that you want to display.

Returns:

status: true if successful, false if unsuccessful

 status = UI.show_inspector "Components"

UI.show_model_infoSketchUp 6.0+

The show_model_info method is used to display the model info dialog for a specific page. You can get the list of valid dialogs with UI.model_info_pages.

Arguments:

page_name: The name of the model info dialog you want to display.

Returns:

status: true if successful, false if unsuccessful

 status = UI.show_model_info "Credits"

UI.show_preferencesSketchUp 6.0+

The show_preferences method is used to display a SketchUp preferences dialog. You can get the list of valid dialogs with UI.preferences_pages.

Arguments:

page_name: The name of the preferences dialog you want to display.

Returns:

status: true if successful, false if unsuccessful

 status = UI.show_preferences "GraphicsCard"

UI.start_timerSketchUp 6.0+

The start_timer method is used to start a timer. This is an effective method to create a repeating snippet of code for arbitrary animation.

See this blog post for an detailed example of custom animation using timers: http://sketchupapi.blogspot.com/2008/10/animate-yo-cheese.html

Arguments:

seconds: The time in seconds before your code should be called.

repeat: true if you want the timer to repeat, false if you do not want it to repeat.

procedure: The procedure you want to execute after seconds has expired.

Returns:

timer: a timer ID

 # Beep after 10 seconds.
 id = UI.start_timer(10, false) { UI.beep }
 if (id)
   UI.messagebox id
 else
   UI.messagebox "Failure"
 end

UI.stop_timerSketchUp 6.0+

The stop_timer method is used to stop a timer based on its id.

Arguments:

id: The timer idea for the timer that you want to stop.

Returns:

nil

 # Beep after 10 seconds.
 id = UI.start_timer(10) { UI.beep }
 if (id)
   UI.messagebox id
 else
   UI.messagebox "Failure"
 end
 UI.stop_timer id
 UI.messagebox "Stopped"

UI.toolbarSketchUp 6.0+

The toolbar method is used to get a Ruby toolbar by name.

Arguments:

name: The name of the Ruby toolbar.

Returns:

toolbar: a Toolbar object

 toolbar = UI::Toolbar.new "Test"
 toolbar = UI.toolbar "Test"
 if (toolbar)
   UI.messagebox toolbar
 else
   UI.messagebox "Failure"
 end

UI.toolbar_namesSketchUp 6.0+

The toolbar_names method is used to returns the name of all the available toolbars (this differs between PC and Mac).

Returns:

names: Array of strings representing toolbar names.

 names = UI.toolbar_names

UI.toolbar_visible?SketchUp 6.0+

The toolbar_visible? method is used to determine whether a given toolbar is visible.

Arguments:

name: The name of a Ruby toolbar.

Returns:

status: true if successful, false if unsuccessful

 status = UI.toolbar_visible? "Camera"

Faster apps faster - GWT 2.0 with Speed Tracer New!

Google SketchUp Ruby API

Introduction

Quick Reference

Object Reference

UI

module

Introduction

Methods

Faster apps faster - GWT 2.0 with Speed Tracer ^New!