|
SketchUp Ruby API Reference |
The UI module contains a number of methods for creating simple UI elements from a SketchUp Ruby script.
Parent: N/A
Methods: add_context_menu_handler, beep, create_cursor, inputbox, inspector_names, menu, messagebox, model_info_pages, openURL, openpanel, play_sound, preferences_pages, savepanel, set_cursor, show_inspector, show_model_info, show_preferences, start_timer, stop_timer, toolbar, toolbar_names, toolbar_visible?, toolbar_visible=
Example Code: uitests.rb,
contextmenu.rb
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.
count = UI.add_context_menu_handler menu
menu - a block of code that takes a menu as its only as its only argument
count - the number of context handlers that are registered
See the contextmenu.rb script in the Plugins\examples directory for an example.
UI.add_context_menu_handler do |menu|
The beep method plays a system beep sound.
UI.beep
The beep method does not accept any arguments nor return any values.
The create_cursor method is used to create a cursor from an image file at the specified location.
ID = UI.create_cursor filename, x, yfilename - filename for an image
x - an x coordinate
y - a y coordinate
ID - ID associated with the cursor
def GetCursorID(filename, hotx, hoty)cursorPath = Sketchup.find_support_file(filename, "Tools/Sandbox/Images")if cursorPathid = UI.create_cursor(cursorPath, hotx, hoty)elseid=0endreturn idend
Creates a dialog box for inputting user information. The dialog box contains input fields with static text prompts, optional default values, and optional name.
results = UI.inputbox prompts[], defaultvalues[], “inputboxtitle”
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
result - true if successful; false if unsuccessful
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.
prompts = ["Width", "Height", "Depth"]
values = [6.feet, 5.feet, 4.feet]
results = inputbox prompts, values, "Box Dimensions"
if (!results)
#failure
returnelse#success: you can extract values from the results arrayend
The inspector_names method is used to returns the names of all the inspectors.
inspectors = UI.inspector_names
inspectors - a vector of strings containing the names of inspectors.
The menu method retrieves a SketchUp’s menu object with a given name.
menu = UI.menu “menuname”
“menuname” – the name of an existing menu
menu – a menu object.
Valid menu names are: "File", "Edit", "View", "Camera", "Create", "Tools", "Page", "Window", "Plugins" and "Help".
Draw_menu = UI.menu “Draw” if (!draw_menu)
#failure
return
else
#success: you can use the menu object now.
end
Creates a dialog box containing static text.
UI.messagebox "message", mbtype, “messageboxtitle”
“message” – The message that you want to appear in the message box
mbtype – (optional) message box type
“messageboxtitle” – (optional) title for the message box
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)
The model_info_pages method is used to returns the names of all the available model info pages.
mipages = UI.model_info_pages
mipages - a vector of strings containing the names of model info pages.
The openURL method is used to open the default Web browser to a URL.
status = UI.openURL "URL"
"URL" - a string URL
status - true if successful
status = UI.openURL("http://www.sketchup.com")
if (status)
UI.messagebox status
else
UI.messagebox "Failure"
end
The openpanel method is used to display the Open dialog box.
UI.openpanel "Title", "Directory", "Filename"
"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
UI.openpanel "Open Image File", "c:\\Program Files\\@Last Software\\Sketchup 5\\Plugins\\", "Shapes.jpg"
The play_sound method is used to play a sound file.
UI.play_sound "Filename"
"Filename" - the relative path to the filename from the Plugins directory.
UI.play_sound "mediadiscussion.wav"
The preferences_pages method is used to returns the names of all the preferences pages.
prefspages = UI.preferences_pages
prefspages - a vector of strings containing the names of prefspages.
The savepanel method is used to display the Save dialog box.
UI.savepanel "Title", "Directory", "Filename"
"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
UI.openpanel "Open Image File", "c:\\Program Files\\@Last Software\\Sketchup 5\\Plugins\\", "Shapes.jpg"
The set_cursor method is used to change the cursor to a new cursor with a new ID
UI.set_cursor ID
ID - a new cursor ID
def onSetCursor
if (@activeEntity==true and @state==0) or @state>0 or @activeSel==false
UI.set_cursor(@@cursorID)
end
end
The show_inspector method is used to display the inspector with the given name.
status = UI.show_inspector inspector_name
inspector_name - the name of inspector that you want to display.
status - true if successful, false if unsuccessful
The show_model_info method is used to displays the ModelInfo dialog for a specific page.
status = UI.show_model_info page_name
page_name - the name of page_name whose model_info dialog you want to display.
status - true if successful, false if unsuccessful
The show_preferences method is used to return the names of all the preferences pages.
prefs= UI.show_preferences
prefs - vector of strings representing preferences pages.
The start_timer method is used to start a timer.
timer = UI.start_timer(seconds, repeat) {...}
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
timer - a timer ID
id = UI.start_timer(10) {UI.beep}
if (id)
UI.messagebox id
else
UI.messagebox "Failure"
end
The stop_timer method is used to stop a timer.
UI.stop_timer id
id - the timer idea for the timer that you want to stop
id = UI.start_timer(10) {UI.beep}
if (id)
UI.messagebox id
else
UI.messagebox "Failure"
end
UI.stop_timer id
UI.messagebox "Stopped"
The toobar method is used to get a Ruby toolbar by name.
toolbar = UI.toolbar "Name"
"Name" - the name of the Ruby toolbar
toolbar - a Toolbar object
toolbar = UI::Toolbar.new "Test"
toolbar = UI.toolbar "Test"
if (toolbar)
UI.messagebox toolbar
else
UI.messagebox "Failure"
end
The toolbar_names method is used to returns the name of all the available toolbars (this differs between PC and Mac).
names = UI.toolbar_names
names - vector of strings representing toolbar names.
The toolbar_visible? method is used to determine whether a toolbar is visible.
status = UI.toolbar_visible?
status - true if successful, false if unsuccessful
The toolbar_visible= method is used to make a specific toolbar visible.
status = UI.toolbar_visible= name
name - the name of the toolbar to display
status - true if successful, false if unsuccessful