<Command>

A single command that is associated to one or more buttons on the ribbon.

Parent Elements

This element can appear as a child of the following elements.

Attributes

This element supports the following attributes:

Caption

The Caption can be any text. When the command is associated to a button, this is the text that will appear on the button. You can omit the caption if you don't want the button to display text, though keep in mind that some buttons do not display a caption depending on where they appear on the ribbon.

Enabled

The Enabled attribute can be set to "true" or "false". This determines the default enabled state of any button associated to this command. You can use the CommandEnabled at runtime to change the enabled states of all associated buttons at once.

Key

The Key attribute is arguably the most important as it defines the unique identifier you will use in other parts of the XML to associate the command to a button. See the <Button> element for details on how to associate a command. Note that this key must be unique to other commands' keys, but you can have the same key as a tab or control. Still, it's usually best to keep everything as unique as possible. For example, you can use "SAVE" as a command key and "BTN_SAVE" as a button key for clarity.

KeyboardTip

The KeyboardTip attribute establishes the sequence of keys that trigger this command when the user is holding down the Alt key. Consider the old menu system. If you want the user to open a file by pressing Alt+F to open the file menu followed by Alt+O, then you needed to set the menu text to "&Open". The ampersand tells OI what letter is to be used, and the letter is called the accelerator. Keyboard tips are very much like accelerators except they can have more than one letter to avoid ambiguity among other controls on the same tab. If you omit this attribute, then the keyboard tip is generated from the caption. If you set this to one or two letters, then that becomes the preferred keyboard tip. The ribbon will attempt to use that keyboard tip as long as it doesn't conflict elsewhere.

LargeIcon

The LargeIcon attribute sets up the icon to be used when the button is large. Omitting this attribute informs the ribbon that any button using this command should be small in size, if possible. If the ribbon renders the button as large anyway, then the small image is scaled to a larger size.

Shortcut

The Shortcut attribute establishes the keyboard shortcut that will execute this command. Unlike the keyboard tip, which is only used when the user presses the Alt key, this attribute defines a full shortcut. For example, you can set the Shortcut attribute of a command called "SAVE" to "Ctrl+S". You can use any of the three command keys in any combination: Ctrl, Shift, or Alt. You can also use any letter, number, or function key. Examples include "Shift+F3", "Alt+F1", or "Shift+Ctrl+F".

SmallIcon

The SmallIcon attribute sets up the icon to be used when the button is small. If you omit this attribute, then the large icon is scaled down.

Tooltip

The Tooltip attribute sets the text to appear when the user hovers over the associated button.

Remarks

The Command element defines a single command. A command can be associated to any number of buttons. This adds a layer of convenience to the developer. All you have to do is interact with the command via properties and events and all the associated buttons are kept up to date automatically. For example, if you have three buttons associated with the SAVE command, then disabling the SAVE command automatically disables all three buttons. Likewise, clicking any of the three buttons fires an event for the same command.

Note: A command key can only be referenced if the command appears earlier in the XML. For example, let's say you define a command called "PASTE". Any button that appears later in the XML can reference "PASTE", but any button earlier in the XML cannot.

Example

<Command Key="NEW" Caption="New" Shortcut="Ctrl+N" KeyboardTip="N"
         LargeIcon="Images\32x32\new.png"
         SmallIcon="Images\16x16\new.png"
         Tooltip="Opens a new document." />
 
<Command Key="OPEN" Caption="Open" KeyboardTip="O"
         LargeIcon="Images\32x32\folder_open.png"
         SmallIcon="Images\16x16\folder_open.png"
         Tooltip="Opens a new document." />
 
<Command Key="SAVE" Caption="Save" Shortcut="Ctrl+S" Enabled="False"
         LargeIcon="Images\32x32\save.png"
         SmallIcon="Images\16x16\save.png"
         Tooltip="Saves the document." />
 
<Command Key="SAVE_AS" Caption="Save As" KeyboardTip="A"
         LargeIcon="Images\32x32\save.png"
         SmallIcon="Images\16x16\save.png"
         Tooltip="Saves the document to the selected file." />
 
<Command Key="CLOSE" Caption="Close" KeyboardTip="X"
         Tooltip="Closes the application." />