Class: UI::Command

Inherits:

Object

Object
UI::Command

Defined in:: lib/sketchup-api-stubs/stubs/UI/Command.rb

Overview

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 toolbar 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.

Examples:

# 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

Version:

SketchUp 6.0

Class Method Summary collapse

.new(menutext) { ... } ⇒ UI::Command

The new method is used to create a new command.

Instance Method Summary collapse

#large_icon ⇒ String

The large_icon method returns the icon file for the command’s large icon.
#large_icon=(path) ⇒ String

The large_icon= method is used to identify the icon file for the command’s large icon.
#menu_text ⇒ String

The menu_text method returns the menu item name for the command.
#menu_text=(menuitem) ⇒ String

The menu_text= method is used to set the menu item name for the command.
#set_validation_proc { ... } ⇒ UI::Command

The #set_validation_proc method allows you to change whether the command is enabled, checked, etc.
#small_icon ⇒ String

The small_icon method returns the icon file for the command’s small icon.
#small_icon=(path) ⇒ String

The small_icon= method is used to identify the icon file for the command’s small icon.
#status_bar_text ⇒ String

The status_bar_text method returns the status bar text for the command.
#status_bar_text=(text) ⇒ String

The status_bar_text= method is used to set the status bar text for the command.
#tooltip ⇒ String

The tooltip method returns command item’s tooltip text.
#tooltip=(text) ⇒ String

The tooltip= method is used to define a command item’s tooltip text.

Class Method Details

.new(menutext) { ... } ⇒ `UI::Command`

Note:

Prior to SketchUp 2019 it was not possible to sub-class UI::Command due to a bug in how SketchUp initialized the class.

The new method is used to create a new command.

Examples:

UI.menu("Draw").add_separator

# 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

Parameters:

menutext (String) —

The text that will appear for this command’s menu item if it appears on a menu.

Yields:

Code that executes the command when the menu item or toolbar item is selected.

Returns:

(UI::Command) —

the new Command object

Version:

SketchUp 6.0



65
66

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 65

def self.new(menutext)
end

Instance Method Details

#large_icon ⇒ `String`

The large_icon method returns the icon file for the command’s large icon.

Examples:

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
puts cmd.large_icon

Returns:

(String) —

the path to the large icon.

Version:

SketchUp 8.0 M1



86
87

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 86

def large_icon
end

#large_icon=(path) ⇒ `String`

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

Since SketchUp 2016 it is possible to provide vector images for the command. SVG format for Windows and PDF format for OS X. Since the vector images scale for both small and large icon sizes, you may choose to use only one vector image for both variants.

Examples:

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

Parameters:

path (String) —

The path to the large icon.

Returns:

(String)

Version:

SketchUp 6.0



113
114

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 113

def large_icon=(path)
end

#menu_text ⇒ `String`

The menu_text method returns the menu item name for the command.

Examples:

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
puts cmd.menu_text

Returns:

(String)

Version:

SketchUp 8.0 M1



130
131

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 130

def menu_text
end

#menu_text=(menuitem) ⇒ `String`

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

Examples:

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

Parameters:

menuitem (String) —

A string representing the menu item for the command.

Returns:

(String)

Version:

SketchUp 6.0



149
150

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 149

def menu_text=(menuitem)
end

#set_validation_proc { ... } ⇒ `UI::Command`

Note:

Avoid disabling an command as it often isn’t obvious to the user why it is disabled. Prefer keeping the command enabled but show an error message if pressed when it cannot be used.

The #set_validation_proc method allows you to change whether the command is enabled, checked, etc. For instance, the command toggling a dialog window may be displayed as checked while the dialog is open.

Examples:

# 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)

Yields:

Yield Returns:

(Integer) —

MF_ENABLED, MF_DISABLED, MF_CHECKED, MF_UNCHECKED, or MF_GRAYED

Returns:

(UI::Command)

Version:

SketchUp 6.0



186
187

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 186

def set_validation_proc
end

#small_icon ⇒ `String`

The small_icon method returns the icon file for the command’s small icon.

Examples:

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
puts cmd.small_icon

Returns:

(String) —

the path to the small_icon

Version:

SketchUp 8.0 M1



205
206

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 205

def small_icon
end

#small_icon=(path) ⇒ `String`

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

Since SketchUp 2016 it is possible to provide vector images for the cursors. SVG format for Windows and PDF format for OS X. Since the vector images scale for both small and large icon sizes, you may choose to use only one vector image for both variants.

Examples:

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

Parameters:

path (String) —

A path to the small icon.

Returns:

(String)

Version:

SketchUp 6.0



232
233

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 232

def small_icon=(path)
end

#status_bar_text ⇒ `String`

The status_bar_text method returns the status bar text for the command.

Examples:

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
puts cmd.status_bar_text

Returns:

(String) —

the status bar text.

Version:

SketchUp 8.0 M1



253
254

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 253

def status_bar_text
end

#status_bar_text=(text) ⇒ `String`

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

Examples:

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

Parameters:

text (String) —

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

Returns:

(String)

Version:

SketchUp 6.0



276
277

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 276

def status_bar_text=(text)
end

The tooltip method returns command item’s tooltip text.

Examples:

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
puts cmd.tooltip

Returns:

(String) —

the tooltip text

Version:

SketchUp 8.0 M1



293
294

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 293

def tooltip
end

#tooltip=(text) ⇒ `String`

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.

Examples:

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

Parameters:

text (String) —

The text of the tooltip.

Returns:

(String)

Version:

SketchUp 6.0



314
315

# File 'lib/sketchup-api-stubs/stubs/UI/Command.rb', line 314

def tooltip=(text)
end

Class: UI::Command

Overview

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(menutext) { ... } ⇒ UI::Command

Instance Method Details

#large_icon ⇒ String

#large_icon=(path) ⇒ String

#menu_text ⇒ String

#menu_text=(menuitem) ⇒ String

#set_validation_proc { ... } ⇒ UI::Command

#small_icon ⇒ String

#small_icon=(path) ⇒ String

#status_bar_text ⇒ String

#status_bar_text=(text) ⇒ String

#tooltip ⇒ String

#tooltip=(text) ⇒ String

.new(menutext) { ... } ⇒ `UI::Command`

#large_icon ⇒ `String`

#large_icon=(path) ⇒ `String`

#menu_text ⇒ `String`

#menu_text=(menuitem) ⇒ `String`

#set_validation_proc { ... } ⇒ `UI::Command`

#small_icon ⇒ `String`

#small_icon=(path) ⇒ `String`

#status_bar_text ⇒ `String`

#status_bar_text=(text) ⇒ `String`

#tooltip ⇒ `String`

#tooltip=(text) ⇒ `String`