Class: UI::Command

Relationships
Inherits:	Object

Overview

The Command class is used to create toolbar buttons and menu entries for invoking your extension.

Examples:

file_extension = Sketchup.platform == :platform_win ? "svg" : "pdf"

menu = UI.menu("Extensions").add_submenu("My Extension")
toolbar = UI::Toolbar.new("My Extension")

command = UI::Command.new("My Action") do
  UI.messagebox("Hello World!")
end
command.menu_text = "My Action"
command.tooltip = "My Action"
command.status_bar_text = "One sentence explaining what the action does."
command.large_icon = "icons/my_action.#{file_extension}"

# More commands here...

menu.add_item(command)
toolbar.add_item(command)
toolbar.show

Version:

SketchUp 6.0

Class Method Summary

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

The new method is used to create a new command.

Instance Attribute Summary

#extension ⇒ SketchupExtension^? rw

The #extension method returns the command's associated extension.
#extension=(extension) rw

The #extension= method explicitly sets the command's associated extension.
#large_icon ⇒ String rw

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

The large_icon= method is used to set the icon file for the command's large icon.
#menu_text ⇒ String rw

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

The menu_text= method is used to set the menu item name for the command.
#small_icon ⇒ String rw

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

The small_icon= method is used to set the icon file for the command's small icon.
#status_bar_text ⇒ String rw

The status_bar_text method returns the description of the command.
#status_bar_text=(text) ⇒ String rw

The status_bar_text= method is used to set the description for the command.
#tooltip ⇒ String rw

The tooltip method returns command item's tooltip's header text.
#tooltip=(text) ⇒ String rw

The #tooltip= method is used to define a command item's tooltip header.

Instance Method Summary

#get_validation_proc ⇒ Proc^?

The #get_validation_proc method returns the command's validation proc.
#proc ⇒ Proc

The #proc method returns the command's proc that is called when the command is invoked.
#set_validation_proc { ... } ⇒ UI::Command

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

Constructor Details

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

The new method is used to create a new command.

Examples:

command = UI::Command.new("Example Command") { UI.messagebox("Hello World!") }
UI.menu("Extensions").add_item(command)

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.

Version:

SketchUp 6.0

Instance Attribute Details

#extension ⇒ SketchupExtension^? (rw)

The #extension method returns the command's associated extension.

Examples:

extension = Sketchup.extensions['Sandbox Tools']
command = UI::Command.new("Test") {}
command.extension = extension
command.extension == extension

Version:

SketchUp 2022.0

#extension=(extension) (rw)

Note:

This is an advanced feature that extension developers normally won't have to deal with. It's purpose is to address scenarios when SketchUp isn't able to automatically infer which extension the command belongs to. These scenarios are for example an extension using a library to add its commands or command manager extensions.

The #extension= method explicitly sets the command's associated extension.

Examples:

extension = Sketchup.extensions['Sandbox Tools']
cmd = UI::Command.new("Test") {}
cmd.extension = extension

Parameters:

extension (SketchupExtension, nil)

Version:

SketchUp 2022.0

#large_icon ⇒ String (rw)

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

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.large_icon = "icons/my_action.svg"
toolbar = toolbar.add_item(command)
toolbar.show
command.large_icon

Version:

SketchUp 8.0 M1

#large_icon=(path) ⇒ String (rw)

The large_icon= method is used to set the icon file for the command's large icon. large icons should be 32x32 pixel images for best display quality. Along the edge there should be a 4 px empty margin for the icon to match those of native SketchUp commands.

Starting in SketchUp 2016 it is possible to use vector images for better display at varying ::UI scaling. SVG format for Windows and PDF format for Mac. Since the vector images scale for both small and large icon sizes, you only need to use one.

Starting in SketchUp 2027 it is possible to use SVG on both Windows and Mac.

Examples:

file_extension = Sketchup.platform == :platform_win ? "svg" : "pdf"
toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.large_icon = "icons/my_action.#{file_extension}"
toolbar = toolbar.add_item(command)
toolbar.show

Parameters:

path (String) —
The path to the large icon.

Version:

SketchUp 6.0

#menu_text ⇒ String (rw)

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

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.menu_text = "My Action"
toolbar = toolbar.add_item(command)
toolbar.show
command.menu_text

Version:

SketchUp 8.0 M1

#menu_text=(menuitem) ⇒ String (rw)

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

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.menu_text = "My Action"
toolbar = toolbar.add_item(command)
toolbar.show

Parameters:

menuitem (String) —
A string representing the menu item for the command.

Version:

SketchUp 6.0

#small_icon ⇒ String (rw)

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

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.small_icon = "icons/my_action.svg"
toolbar = toolbar.add_item(command)
toolbar.show
command.small_icon

Version:

SketchUp 8.0 M1

#small_icon=(path) ⇒ String (rw)

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

Starting in SketchUp 2027 it is possible to use SVG on both Windows and Mac.

Examples:

file_extension = Sketchup.platform == :platform_win ? "svg" : "pdf"
toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.small_icon = "icons/my_action.#{file_extension}"
toolbar = toolbar.add_item(command)
toolbar.show

Parameters:

path (String) —
A path to the small icon.

Version:

SketchUp 6.0

#status_bar_text ⇒ String (rw)

The status_bar_text method returns the description of the command.

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.status_bar_text = "Show a message that says hello world."
toolbar = toolbar.add_item(command)
toolbar.show
command.status_bar_text

Version:

SketchUp 8.0 M1

#status_bar_text=(text) ⇒ String (rw)

The status_bar_text= method is used to set the description for the command. This should typically be a one sentence paragraph with a trailing point.

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.status_bar_text = "Show a message that says hello world."
toolbar = toolbar.add_item(command)
toolbar.show

Parameters:

text (String)

Version:

SketchUp 6.0

#tooltip ⇒ String (rw)

The tooltip method returns command item's tooltip's header text.

Examples:

toolbar = UI::Toolbar.new("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.tooltip = "My Action"
toolbar = toolbar.add_item(command)
toolbar.show
command.tooltip

Version:

SketchUp 8.0 M1

#tooltip=(text) ⇒ String (rw)

Note:

The tooltip text should repeat the commands' title text. For the command description, use #status_bar_text.

The #tooltip= method is used to define a command item's tooltip header. 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("My Toolbar")
command = UI::Command.new("My Action") { UI.messagebox("Hello World!") }
command.tooltip = "My Action"
toolbar = toolbar.add_item(command)
toolbar.show

Parameters:

text (String) —
The text of the tooltip.

Version:

SketchUp 6.0

Instance Method Details

#get_validation_proc ⇒ `Proc`^?

The #get_validation_proc method returns the command's validation proc.

Examples:

command = UI::Command.new("My Action") {}
command.set_validation_proc { MF_CHECKED }
proc = command.get_validation_proc

#proc ⇒ `Proc`

The #proc method returns the command's proc that is called when the command is invoked.

Examples:

command = UI::Command.new("Test") { UI.messagebox("Hello World!") }
proc = command.proc
proc.call

Version:

SketchUp 2022.0

#set_validation_proc { ... } ⇒ `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:

menu = UI.menu("Extensions")
command = UI::Command.new("Display Color by Layer") do
  rendering_options = Sketchup.active_model.rendering_options
  rendering_options["DisplayColorByLayer"] = ! rendering_options["DisplayColorByLayer"]
end
command.set_validation_proc do
  rendering_options = Sketchup.active_model.rendering_options
  if rendering_options["DisplayColorByLayer"]
    MF_CHECKED
  else
    MF_UNCHECKED
  end
end
menu.add_item(command)

Yields:

[]

Yield Returns:

(Integer) —
MF_ENABLED, MF_DISABLED, MF_CHECKED, MF_UNCHECKED, or MF_GRAYED

Class: UI::Command

Overview

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

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

Instance Attribute Details

#extension ⇒ SketchupExtension? (rw)

#extension=(extension) (rw)

#large_icon ⇒ String (rw)

#large_icon=(path) ⇒ String (rw)

#menu_text ⇒ String (rw)

#menu_text=(menuitem) ⇒ String (rw)

#small_icon ⇒ String (rw)

#small_icon=(path) ⇒ String (rw)

#status_bar_text ⇒ String (rw)

#status_bar_text=(text) ⇒ String (rw)

#tooltip ⇒ String (rw)

#tooltip=(text) ⇒ String (rw)

Instance Method Details

#get_validation_proc ⇒ Proc?

#proc ⇒ Proc

#set_validation_proc { ... } ⇒ Command

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

#extension ⇒ SketchupExtension^? (rw)

#get_validation_proc ⇒ `Proc`^?

#proc ⇒ `Proc`

#set_validation_proc { ... } ⇒ `Command`