Module: UI

Relationships
Namespace Children
Classes: `Command`, `HtmlDialog`, `Notification`, `Toolbar`, `WebDialog`

Overview

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

Version:

SketchUp 6.0

Class Method Summary

.add_context_menu_handler {|menu| ... } ⇒ Integer

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.
.beep ⇒ nil

The beep method plays a system beep sound.
.create_cursor(path, hot_x, hot_y) ⇒ Integer

The .create_cursor method is used to create a cursor from an image file at the specified location.
.get_clipboard_data ⇒ String^?

Returns the plain text available on the clipboard, if there is any.
.inputbox(prompts, defaults, title) ⇒ Array<String>, false

Creates a dialog box for inputting user information.
.inspector_names ⇒ Array<String>

The .inspector_names method is used to returns the names of all the inspectors.
.menu(menu_name = "Extensions") ⇒ Sketchup::Menu

The .menu method retrieves a SketchUp’s menu object with a given name.
.messagebox(message, type = MB_OK) ⇒ Integer

Creates a dialog box containing static text with a series of buttons for the user to choose from.
.model_info_pages ⇒ Array<String>

The model_info_pages method is used to returns the names of all the available model info pages.
.openpanel(title, directory, filename) ⇒ String

The .openpanel method is used to display the Open dialog box.
.openURL(url) ⇒ Boolean

The .openURL method is used to open the default browser to a URL.
.play_sound(filename) ⇒ nil

The play_sound method is used to play a sound file.
.preferences_pages ⇒ Array<String>

The preferences_pages method is used to returns the names of all the preferences pages.
.refresh_inspectors ⇒ nil

Tells SketchUp to refresh all inspectors such as the Component Browser and the Outliner.
.refresh_toolbars ⇒ nil

Tells SketchUp to refresh all floating toolbars.
.savepanel(title, directory, filename) ⇒ String

The .savepanel method is used to display the Save dialog box.
.scale_factor ⇒ Float

Returns the scaling factor SketchUp uses on high DPI monitors.
.select_directory(options = {}) ⇒ String, ...

The .select_directory method is used to display the OS dialog for selecting one or several directories from the file system.
.set_clipboard_data(data) ⇒ Boolean

Copies plain text to the clipboard.
.set_cursor(cursor_id) ⇒ Boolean

The .set_cursor method is used to change the cursor to a new cursor with a given cursor id.
.set_toolbar_visible(name, visible) ⇒ Boolean

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

The show_extension_manager method is used to display the Extension Manager dialog.
.show_inspector(name) ⇒ Boolean

The .show_inspector method is used to display the inspector with the given name.
.show_model_info(page_name) ⇒ Boolean

The .show_model_info method is used to display the model info dialog for a specific page.
.show_preferences(page_name) ⇒ Boolean

The show_preferences method is used to display a SketchUp preferences dialog.
.start_timer(seconds, repeat = false) {|procedure| ... } ⇒ Integer

The start_timer method is used to start a timer.
.stop_timer(id) ⇒ nil

The stop_timer method is used to stop a timer based on its id.
.toolbar(name) ⇒ UI::Toolbar

The toolbar method is used to get a Ruby toolbar by name.
.toolbar_names ⇒ Array<String>

The toolbar_names method is used to return the name of all the available native toolbars (this differs between PC and Mac).
.toolbar_visible?(name) ⇒ Boolean

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

Class Method Details

.add_context_menu_handler {|menu| ... } ⇒ `Integer`

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.

Be careful with what you do in a context menu handler. If you perform an operation takes take a long time, such as traversing the model or selection in a large model it will delay the menu.

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

Examples:

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

Yields:

(menu) —

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

Returns:

(Integer) —

the number of context handlers that are registered

Version:

SketchUp 6.0

.beep ⇒ `nil`

The beep method plays a system beep sound.

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

Examples:

UI.beep

Version:

SketchUp 6.0

.create_cursor(path, hot_x, hot_y) ⇒ `Integer`

Note:

Since SketchUp 2016 it is possible to provide vector images for the cursors. SVG format for Windows and PDF format for macOS. This is the recommended format to use since it will scale well with different DPI scaling.

Note:

Because the image is never released, avoid creating new cursors for the same image for any given tool. Cache it and reuse it.

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 ::Sketchup::Tool documentation for a complete example.

The size of the cursor images should be 32x32 pixels.

The coordinates for the cursor’s hotspot is based from it’s top left corner. For example, a value of (hot_x, hot_y) = (5, 10) would identify the hotpoint of the cursor at 6 pixels from the left edge of your cursor image and 11 pixels from the top edge of your cursor image.

Examples:

class ExampleTool
  def initialize
    @cursor_id = nil
    # Load vector cursor format depending on platform.
    ext = Sketchup.platform == :platform_win ? 'svg' : 'pdf'
    cursor_path = File.join(__dir__, "cursor.#{ext}")
    @cursor_id = UI.create_cursor(cursor_path, 4, 6)
  end

  def onSetCursor
    UI.set_cursor(@cursor_id)
  end
end

Parameters:

path (String) —

File path to an image.
hot_x (Integer) —

An x coordinate that is the “hotpoint” for the cursor computed from the left edge of your cursor image.
hot_y (Integer) —

A y coordinate that is the “hotpoint” for the cursor computed from the top edge of the of your cursor image.

Returns:

(Integer) —

Id associated with the cursor. Use this with .set_cursor in Sketchup::Tool#onSetCursor.

.get_clipboard_data ⇒ String^?

Returns the plain text available on the clipboard, if there is any.

Examples:

text = UI.get_clipboard_data

Version:

SketchUp 2023.1

.inputbox(prompts, defaults, title) ⇒ Array<String>, `false` .inputbox(prompts, defaults, list, title) ⇒ Array<String>, `false`

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.

Examples:

# 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.")

Overloads:

.inputbox(prompts, defaults, title) ⇒ Array<String>, false
Parameters:
- prompts (Array<String>) —
  
  An array of prompt names appearing in the input box adjacent to input fields.
- defaults (Array<String>) —
  
  An array of default values for the input fields.
- title (String) —
  
  The title for the input box.
.inputbox(prompts, defaults, list, title) ⇒ Array<String>, false
Parameters:
- prompts (Array<String>) —
  
  An array of prompt names appearing in the input box adjacent to input fields.
- defaults (Array<String>) —
  
  An array of default values for the input fields.
- list (String, Array<String>) —
  
  An array containing pipe-separated strings of options.
- title (String) —
  
  The title for the input box.

Returns:

(Array<String>, false) —

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

Version:

SketchUp 6.0

.inspector_names ⇒ Array<String>

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.

Examples:

inspectors = UI.inspector_names

Returns:

(Array<String>) —

an array of strings containing the names of inspectors.

Version:

SketchUp 6.0

.menu(menu_name = "Extensions") ⇒ Sketchup::Menu

Note:

The ‘Extensions’ menu was named ‘Plugins’ prior to SketchUp 2015. For backward compatibility ‘Plugins’ still works.

Note:

‘Developer’ menu was added with SketchUp 2021.1.

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’, ‘Draw’, ‘Tools’, ‘Window’, ‘Extensions’, ‘Help’ and ‘Developer’.

Examples:

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

Parameters:

menu_name (String) (defaults to: "Extensions") —

The name of a supported menu.

Version:

SketchUp 6.0

.messagebox(message, type = MB_OK) ⇒ `Integer`

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

Valid message box types are:

MB_OK - Contains an OK button.
MB_OKCANCEL - Contains OK and Cancel buttons.
MB_ABORTRETRYIGNORE - Contains Abort, Retry, and Ignore buttons.
MB_YESNOCANCEL - Contains Yes, No, and Cancel buttons.
MB_YESNO - Contains Yes and No buttons.
MB_RETRYCANCEL - Contains Retry and Cancel buttons.
MB_MULTILINE - Contains and OK button.

Return values can be any of following:

IDOK
IDCANCEL
IDABORT
IDRETRY
IDIGNORE
IDYES
IDNO

In an MB_MULTILINE message box, the message is displayed as a multi-line message with scrollbars (as needed). MB_MULTILNE also allows a third string argument that will be used as the title for the messagebox.

Examples:

result = UI.messagebox('Do you like cheese?', MB_YESNO)
if result == IDYES
  UI.messagebox('SketchUp likes cheese too!')
end

Parameters:

message (String) —

The message that you want to display.
type (Integer) (defaults to: MB_OK) —

The message box type, which will be a constant from the list in the method comments.

Returns:

(Integer) —

A number corresponding to what the user selected.

Version:

SketchUp 6.0

.model_info_pages ⇒ Array<String>

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.

Examples:

mypages = UI.model_info_pages

Returns:

(Array<String>) —

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

Version:

SketchUp 6.0

.openpanel(title, directory, filename) ⇒ String

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.

Examples:

chosen_image = UI.openpanel("Open SKP File", "c:/", "model.skp")
chosen_image = UI.openpanel("Open Image File", "c:/", "Image Files|*.jpg;*.png;||")
chosen_image = UI.openpanel("Open CAD File", "c:/", "DXF|*.dxf|DWG|*.dwg||")

Parameters:

title (String) —

The title to apply to the open dialog box.
directory (String) —

The default directory for the open panel.
filename (String) —

The default filename for the open panel. On Windows, you can alternatively pass a wildcard filter using this format: UIname|wildcard||. Additional filter dropdown list items can be added by adding additional pairs of filter name and filter like this: UIname1|wildcard1|UIname2|wildcard2||. Also multiple wildcard filters can be combined into a single line using a semicolon-separated list in the filter field: ui_name|wildcard1;wildcard2||.

Returns:

(String) —

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

.openURL(url) ⇒ `Boolean`

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

Examples:

status = UI.openURL("http://www.sketchup.com")

Parameters:

url (String)

Version:

SketchUp 6.0

.play_sound(filename) ⇒ `nil`

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.

Examples:

UI.play_sound "Plugins/mediadiscussion.wav"

Parameters:

filename (String) —

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.)

Version:

SketchUp 6.0

.preferences_pages ⇒ Array<String>

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

SketchUp 2017: "Extensions" page was removed.

Examples:

prefs = UI.preferences_pages

Returns:

(Array<String>) —

an array of strings containing the names of preference pages.

Version:

SketchUp 6.0

.refresh_inspectors ⇒ `nil`

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.

Examples:

UI.refresh_inspectors

Version:

SketchUp 7.0

.refresh_toolbars ⇒ `nil`

Tells SketchUp to refresh all floating toolbars. 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 Sketchup::Model#start_operation has disabled UI updates. This only affects macOS, on Windows the toolbars are always refreshing.

Examples:

UI.refresh_toolbars

Version:

SketchUp 2018

.savepanel(title, directory, filename) ⇒ String

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.

Examples:

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

Parameters:

title (String) —

The title to apply to the save dialog box.
directory (String) —

The default directory for the save panel.
filename (String) —

The default filename for the save 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;.doc”.

Returns:

(String) —

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

.scale_factor ⇒ `Float`

Note:

SU2017M0 will automatically scale up line width and text size, but will not scale up the points provided to Sketchup::View#draw2d.

Returns the scaling factor SketchUp uses on high DPI monitors. Useful for things like Sketchup::View#draw2d.

Examples:

# Scale a set of points representing 2d screen points to account for high
# DPI monitors.
points2d = [
  Geom::Point3d.new(0, 0, 0),
  Geom::Point3d.new(8, 0, 0),
  Geom::Point3d.new(8, 4, 0),
  Geom::Point3d.new(0, 4, 0)
]
tr = Geom::Transformation.scaling(UI.scale_factor)
points2d.each { |point| point.transform!(tr)

Version:

SketchUp 2017

.select_directory(options = {}) ⇒ String, ...

The .select_directory method is used to display the OS dialog for selecting one or several directories from the file system.

Examples:

# Default title and folder:
chosen_folder = UI.select_directory

# Custom dialog title:
chosen_folder = UI.select_directory(title: "Select Image Directory")

# Force a start folder:
chosen_folder = UI.select_directory(directory: "C:/images")

# Allow multiple items to the selected:
chosen_folder = UI.select_directory(select_multiple: true)

# Custom dialog title and force a start folder:
chosen_folder = UI.select_directory(
  title: "Select Image Directory",
  directory: "C:/images"
)

Parameters:

options (Hash) (defaults to: {}) —

The dialog can be customized by providing a hash or named arguments of options.

Options Hash (options):

:title (String) — default: nil —

The title for the dialog.
:directory (String) — default: nil —

Force the starting directory for the dialog. If not specified the last chosen directory will be used.
:select_multiple (Boolean) — default: false —

Set to true to allow multiple items to be selected.

Returns:

(String, Array<String>, nil) —

A string with the full path of the directory selected when :select_multiple option is set to false otherwise an array of strings or nil if the user cancelled.

Version:

SketchUp 2015

.set_clipboard_data(data) ⇒ `Boolean`

Copies plain text to the clipboard.

Examples:

UI.set_clipboard_data('Hello World')

Version:

SketchUp 2023.1

.set_cursor(cursor_id) ⇒ `Boolean`

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.

Examples:

def onSetCursor
  UI.set_cursor(cursor_id)
end

Parameters:

cursor_id (Integer) —

The id of the cursor you want to display.

Version:

SketchUp 6.0

.set_toolbar_visible(name, visible) ⇒ `Boolean`

The set_toolbar_visible method is used to set whether a given toolbar is visible. Note that the toolbars and their names are different on the Mac vs. PC, so be careful and be sure to test when using this method in a cross-platform script.

Examples:

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

Parameters:

name (String) —

The name of a Ruby toolbar.
visible (Boolean) —

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

Returns:

(Boolean) —

true if successful, false if not.

Version:

SketchUp 6.0

.show_extension_manager ⇒ `nil`

The show_extension_manager method is used to display the Extension Manager dialog.

Examples:

UI.show_extension_manager

Version:

SketchUp 2017

.show_inspector(name) ⇒ `Boolean`

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.

Examples:

status = UI.show_inspector("Components")

Parameters:

name (String) —

The name of inspector that you want to display.

Returns:

(Boolean) —

true if successful, false if unsuccessful

Version:

SketchUp 6.0

.show_model_info(page_name) ⇒ `Boolean`

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

SketchUp 2014: "Classifications" page was added.

Examples:

UI.show_model_info('Credits')

Parameters:

page_name (String) —

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

Version:

SketchUp 6.0

.show_preferences(page_name) ⇒ `Boolean`

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

Examples:

status = UI.show_preferences('GraphicsCard')

Parameters:

page_name (String) —

The name of the preferences dialog you want to display.

Returns:

(Boolean) —

true

Version:

SketchUp 6.0

.start_timer(seconds, repeat = false) {|procedure| ... } ⇒ `Integer`

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: sketchupapi.blogspot.com/2008/10/animate-yo-cheese.html

Note that there is a bug that if you open a modal window in a non-repeating timer the timer will repeat until the window is closed.

Examples:

# Beep once after 10 seconds.
id = UI.start_timer(10, false) { UI.beep }

Parameters:

seconds (Numeric) —

The time in seconds before your code should be called.
repeat (Boolean) (defaults to: false) —

true if you want the timer to repeat, false (or omit) if you do not want it to repeat.

Yields:

(procedure) —

The procedure you want to execute after seconds has expired.

Returns:

(Integer) —

a timer ID

Version:

SketchUp 6.0

.stop_timer(id) ⇒ `nil`

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

Examples:

# Stop timer before it triggers.
id = UI.start_timer(10) { UI.beep }
UI.stop_timer(id)

Parameters:

id (Integer) —

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

Version:

SketchUp 6.0

.toolbar(name) ⇒ UI::Toolbar

The toolbar method is used to get a Ruby toolbar by name. If the toolbar doesn’t exist a new one will be created.

Examples:

toolbar = UI.toolbar('Test')

Parameters:

name (String) —

The name of the Ruby toolbar.

Returns:

(UI::Toolbar) —

a ::UI::Toolbar object

Version:

SketchUp 6.0

.toolbar_names ⇒ Array<String>

The toolbar_names method is used to return the name of all the available native toolbars (this differs between PC and Mac). These toolbar names do not include Ruby toolbars.

Examples:

names = UI.toolbar_names

Returns:

(Array<String>) —

::Array of strings representing toolbar names.

Version:

SketchUp 6.0

.toolbar_visible?(name) ⇒ `Boolean`

The toolbar_visible? method is used to determine whether a given toolbar is visible. Note that the toolbars and their names are different on the Mac vs. PC, so be careful and be sure to test when using this method in a cross-platform script.

Examples:

status = UI.toolbar_visible?("Camera")

Parameters:

name (String) —

The name of a native toolbar.

Version:

SketchUp 6.0

Module: UI

Overview

Class Method Summary

Class Method Details

.add_context_menu_handler {|menu| ... } ⇒ Integer

.beep ⇒ nil

.create_cursor(path, hot_x, hot_y) ⇒ Integer

.get_clipboard_data ⇒ String?

.inputbox(prompts, defaults, title) ⇒ Array<String>, false .inputbox(prompts, defaults, list, title) ⇒ Array<String>, false

.inspector_names ⇒ Array<String>

.menu(menu_name = "Extensions") ⇒ Sketchup::Menu

.messagebox(message, type = MB_OK) ⇒ Integer

.model_info_pages ⇒ Array<String>

.openpanel(title, directory, filename) ⇒ String

.openURL(url) ⇒ Boolean

.play_sound(filename) ⇒ nil

.preferences_pages ⇒ Array<String>

.refresh_inspectors ⇒ nil

.refresh_toolbars ⇒ nil

.savepanel(title, directory, filename) ⇒ String

.scale_factor ⇒ Float

.select_directory(options = {}) ⇒ String, ...

.set_clipboard_data(data) ⇒ Boolean

.set_cursor(cursor_id) ⇒ Boolean

.set_toolbar_visible(name, visible) ⇒ Boolean

.show_extension_manager ⇒ nil

.show_inspector(name) ⇒ Boolean

.show_model_info(page_name) ⇒ Boolean

.show_preferences(page_name) ⇒ Boolean

.start_timer(seconds, repeat = false) {|procedure| ... } ⇒ Integer

.stop_timer(id) ⇒ nil

.toolbar(name) ⇒ UI::Toolbar

.toolbar_names ⇒ Array<String>

.toolbar_visible?(name) ⇒ Boolean

.add_context_menu_handler {|menu| ... } ⇒ `Integer`

.beep ⇒ `nil`

.create_cursor(path, hot_x, hot_y) ⇒ `Integer`

.get_clipboard_data ⇒ String^?

.inputbox(prompts, defaults, title) ⇒ Array<String>, `false` .inputbox(prompts, defaults, list, title) ⇒ Array<String>, `false`

.messagebox(message, type = MB_OK) ⇒ `Integer`

.openURL(url) ⇒ `Boolean`

.play_sound(filename) ⇒ `nil`

.refresh_inspectors ⇒ `nil`

.refresh_toolbars ⇒ `nil`

.scale_factor ⇒ `Float`

.set_clipboard_data(data) ⇒ `Boolean`

.set_cursor(cursor_id) ⇒ `Boolean`

.set_toolbar_visible(name, visible) ⇒ `Boolean`

.show_extension_manager ⇒ `nil`

.show_inspector(name) ⇒ `Boolean`

.show_model_info(page_name) ⇒ `Boolean`

.show_preferences(page_name) ⇒ `Boolean`

.start_timer(seconds, repeat = false) {|procedure| ... } ⇒ `Integer`

.stop_timer(id) ⇒ `nil`

.toolbar_visible?(name) ⇒ `Boolean`