My favorites | English | Sign in

Faster apps faster - GWT 2.0 with Speed Tracer New!

Google SketchUp Ruby API

Command

class

Parent: Object

Introduction

SketchUp 6.0+

The Command class is the preferred class for adding tools to the menus and Ruby toolbars. For example, you could add a menu item and pass it a code block directly, or you could first create a Command.

Using Commands gives you greater control over how the item works in the UI, and it allows multiple spots in the UI to call the same code. For example, You might want a tollbar button and a context-click menu item to both point to the same command, and to control the tooltip and its "graying" from a single spot in your code.

     # You can add menu items as procedure blocks, as shown here, but
     # you have no control over whether it is grayed out, for example.
     UI.menu("Draw").add_item("My Procedure") {
       UI.messagebox("My Procedure")
     }

     # Better to create a command object.
     cmd = UI::Command.new("Tester") {
       UI.messagebox("My Command") 
     }
     cmd.menu_text = "My Command"
     cmd.set_validation_proc {
       if Sketchup.active_model.selection.length == 0
         MF_GRAYED
       else
         MF_ENABLED
       end
     }
     UI.menu("Draw").add_item cmd

Methods

Command.large_icon=SketchUp 6.0+

The large_icon= method is used to identify the icon file for the command's large icon. large icons should be 24x24 pixel images for best display quality.

Arguments:

path
The path to the large icon.

Returns:

command
the Command object
 toolbar = UI::Toolbar.new "Test"
 # This command displays Hello World on the screen when clicked
 cmd = UI::Command.new("Test") { UI.messagebox("Hello World") }
 cmd.small_icon = "ToolPencilSmall.png"
 cmd.large_icon = "ToolPencilLarge.png"
 toolbar = toolbar.add_item cmd
 toolbar.show

The menu_text= method is used to set the menu item name for the command.

Arguments:

menuitem
A string representing the menu item for the command.

Returns:

command
a Command object
 add_separator_to_menu("Draw")
 # Adds a Test submenu to the Draw menu where the Tester menu item appears
 testmenu = UI.menu("Draw").add_submenu("Test")
 cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") }
 cmd.menu_text = "New String"
 testmenu.add_item cmd

Command.newSketchUp 6.0+

The new method is used to create a new command.

Arguments:

menutext
The text that will appear for this command's menu item if it appears on a menu.
Code
that executes the command when the menu item or toolbar item is selected.

Returns:

command
the new Command object
 add_separator_to_menu("Draw")

 # Adds a Test submenu to the Draw menu where the Tester menu item appears
 testmenu = UI.menu("Draw").add_submenu("Test")

 # This menu item simply displays Hello World on the screen when clicked.
 cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") }
 testmenu.add_item cmd

Command.set_validation_procSketchUp 6.0+

The set_validation_proc method allows you to change whether the command is enabled, checked, etc. based on the user state. For example, you might want your command to be disabled unless the user has a current selection.

Your procedure should return either MF_ENABLED, MF_DISABLED, MF_CHECKED, MF_UNCHECKED, or MF_GRAYED.

Arguments:

Returns:

command
a Command object
 # Create a command object.
 cmd = UI::Command.new("Tester") {
   UI.messagebox("My Command") 
 }
 cmd.menu_text = "My Command"
 cmd.set_validation_proc {
   if Sketchup.active_model.selection.length == 0
     MF_GRAYED
   else
     MF_ENABLED
   end
 }
 UI.menu("Draw").add_item cmd

Command.small_icon=SketchUp 6.0+

The small_icon= method is used to identify the icon file for the command's small icon. Small icons should be 16x16 pixel images for best display quality.

Arguments:

path
A path to the small icon.

Returns:

command
the Command object
 toolbar = UI::Toolbar.new "Test"
 # This toolbar command displays Hello World on the screen when clicked.
 cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") }    
 cmd.small_icon = "ToolPencilSmall.png"
 cmd.large_icon = "ToolPencilLarge.png"
 toolbar = toolbar.add_item cmd
 toolbar.show

Command.status_bar_text=SketchUp 6.0+

The status_bar_text= method is used to set the status bar text for the command.

Arguments:

text
The text that will appear on the status bar when the cursor is over the command's menu item.

Returns:

command
the Command object
 toolbar = UI::Toolbar.new "Test"
 # This toolbar tool simply displays Hello World on the screen when clicked
 cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") }    
 cmd.small_icon = "ToolPencilSmall.png"
 cmd.large_icon = "ToolPencilLarge.png"
 cmd.status_bar_text = $tStrings.GetString("Testing the toolbars class")
 toolbar = toolbar.add_item cmd
 toolbar.show

Command.tooltip=SketchUp 6.0+

The tooltip= method is used to define a command item's tooltip text. Tooltips will appear when the command is attached to a tool bar and the user hovers their cursor over the icon.

Arguments:

text
The text of the tooltip.

Returns:

command
the Command object
 toolbar = UI::Toolbar.new "Test"
 # This command displays Hello World on the screen when clicked
 cmd = UI::Command.new("Test") { UI.messagebox("Hello World") }
 cmd.tooltip = "Hello World Tool"
 toolbar = toolbar.add_item cmd
 toolbar.show