module UI

Parent: N/A |
Methods: add_context_menu_handler, beep, create_cursor, inputbox, menu, messagebox, openURL, openpanel, play_sound, savepanel, set_cursor, start_timer, stop_timer, toolbar |
Sample Code: UITests.rb | Class Index

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

Module Methods

add_context_menu_handler
The add_context_menu_handler method is used to
Syntax:
Arguments:
Return Value:
Comments:
Example:

beep
The beep method plays a system beep sound.
Syntax:
UI.beep
Arguments:
Return Value:
Comments:
The beep method does not accept any arguments nor return any values.
Example:
UI.beep

create_cursor
The create_cursor method is used to create a cursor from an image file at the specified location.
Syntax:
ID = UI.create_cursor filename, x, y
Arguments:
filename - filename for an image x - an x coordinate y - a y coordinate
Return Value:
ID - ID associated with the cursor
Comments:
Example:
def GetCursorID(filename, hotx, hoty) cursorPath = Sketchup.find_support_file(filename, "Tools/Sandbox/Images") if cursorPath id = UI.create_cursor(cursorPath, hotx, hoty) else id=0 end return id end

inputbox
Creates a dialog box for inputting user information. The dialog box contains input fields with static text prompts, optional default values, and optional name.
Syntax:
results = UI.inputbox prompts[], defaultvalues[], “inputboxtitle”
Arguments:
prompts[] – An array of prompt names appearing in the input box adjacent to input fields defaultvalues[] – (optional) An array of default values for the input fields “inputboxtitle” – (optional) The name for the input box
Return Value:
result - true if successful; false if unsuccessful
Comments:
You will have to pass specific units (such as feet in the following examples) if you want your box to conform to a certain scale. Also note, you cannot pass just prompts and a name, you must either pass no arguments or all arguments.
Example:
prompts = ["Width", "Height", "Depth"] values = [6.feet, 5.feet, 4.feet] results = inputbox prompts, values, "Box Dimensions" if (!results) #failure return else #success: you can extract values from the results array end

menu
The menu method retrieves a SketchUp’s menu object with a given name.
Syntax:
menu = UI.menu “menuname”
Arguments:
“menuname” – the name of an existing menu
Return Value:
menu – a menu object.
Comments:
Valid menu names are: "File", "Edit", "View", "Camera", "Create", "Tools", "Page", "Window", "Plugins" and "Help".
Example:
Draw_menu = UI.menu “Draw” if (!draw_menu) #failure return else #success: you can use the menu object now. end

messagebox
Creates a dialog box containing static text.
Syntax:
UI.messagebox "message", mbtype, “messageboxtitle”
Arguments:
“message” – The message that you want to appear in the message box mbtype – (optional) message box type “messageboxtitle” – (optional) title for the message box
Return Value:
Comments:
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) button MB_OKCANCEL – Contains OK (1) and CANCEL (2) buttons MB_ABORTRETRYCANCEL – Contains ABORT (3), RETRY (4), and CANCEL (2) buttons MB_YESNOCANCEL – Contains YES (6), NO (7), and CANCEL (2) buttons MB_YESNO – Contains YES (6) and NO (7) buttons MB_RETRYCANCEL – Contains RETRY (4) and CANCEL (2) buttons MB_MULTILINE – Contains and OK (1) button. 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)
Example:
Keypress = UI.messagebox “Error, incorrect length. Try Again?” , MB_YESNO, “Error” If (keypress == 6) # code to respond to YES else # must be a NO; code to respond to NO end

openURL
The openURL method is used to open the default Web browser to a URL.
Syntax:
status = UI.openURL "URL"
Arguments:
"URL" - a string URL
Return Value:
status - true if successful
Comments:
Example:
status = UI.openURL("http://www.sketchup.com") if (status) UI.messagebox status else UI.messagebox "Failure" end

openpanel
The openpanel method is used to display the Open dialog box.
Syntax:
UI.openpanel "Title", "Directory", "Filename"
Arguments:
"Title" - The tile to apply to the open dialog box "Directory" - the default directory for the open panel "Filename" - the default filename for the open panel
Return Value:
Comments:
Example:
UI.openpanel "Open Image File", "c:\\Program Files\\@Last Software\\Sketchup 5\\Plugins\\", "Shapes.jpg"

play_sound
The play_sound method is used to play a sound file.
Syntax:
UI.play_sound "Filename"
Arguments:
"Filename" - the relative path to the filename from the Plugins directory.
Return Value:
Comments:
Example:
UI.play_sound "mediadiscussion.wav"

savepanel
The savepanel method is used to display the Save dialog box.
Syntax:
UI.savepanel "Title", "Directory", "Filename"
Arguments:
"Title" - The tile to apply to the open dialog box "Directory" - the default directory for the open panel "Filename" - the default filename for the open panel
Return Value:
Comments:
Example:
UI.openpanel "Open Image File", "c:\\Program Files\\@Last Software\\Sketchup 5\\Plugins\\", "Shapes.jpg"

set_cursor
The set_cursor method is used to change the cursor to a new cursor with a new ID
Syntax:
UI.set_cursor ID
Arguments:
ID - a new cursor ID
Return Value:
Comments:
Example:
def onSetCursor if (@activeEntity==true and @state==0) or @state>0 or @activeSel==false UI.set_cursor(@@cursorID) end end

start_timer
The start_timer method is used to start a timer.
Syntax:
timer = UI.start_timer(seconds, repeat) {...}
Arguments:
seconds - the timer in seconds repeat - true if you want the timer to repeat, false if you do not want it to repeat {...} - the procedure you want to execute after seconds has expired
Return Value:
timer - a timer ID
Comments:
Example:
id = UI.start_timer(10) {UI.beep} if (id) UI.messagebox id else UI.messagebox "Failure" end

stop_timer
The stop_timer method is used to stop a timer.
Syntax:
UI.stop_timer id
Arguments:
id - the timer idea for the timer that you want to stop
Return Value:
Comments:
Example:
id = UI.start_timer(10) {UI.beep} if (id) UI.messagebox id else UI.messagebox "Failure" end UI.stop_timer id UI.messagebox "Stopped"

toolbar
The toobar method is used to get a Ruby toolbar by name.
Syntax:
toolbar = UI.toolbar "Name"
Arguments:
"Name" - the name of the Ruby toolbar
Return Value:
toolbar - a Toolbar object
Comments:
Example:
toolbar = UI::Toolbar.new "Test" toolbar = UI.toolbar "Test" if (toolbar) UI.messagebox toolbar else UI.messagebox "Failure" end