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