UI

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