Command element

Article
08/20/2021

Represents a Command definition.

Usage

<Command
  Name = "xs:string"
  Symbol = "xs:string"
  Id = "xs:positiveInteger union xs:string"
  Comment = "xs:string"
  LabelTitle = "xs:string"
  LabelDescription = "xs:string"
  TooltipTitle = "xs:string"
  TooltipDescription = "xs:string"
  Keytip = "xs:string">
  child elements
</Command>

Attributes

Attribute	Type	Required	Description
Comment	xs:string	No	Used to annotate the command element. (xs:string) A string composed of any sequence of characters, including white space and line-break characters. Maximum length: 250 characters.
Id	xs:positiveInteger union xs:string	No	The unique resource ID. (The union of xs:positiveInteger and xs:string) An integer value between 2 and 59999, inclusive, or 0x2 and 0xea5f in hexadecimal, inclusive. Maximum length is 10 characters, including optional leading zeros.
Keytip	xs:string	No	A string that represents the keyboard shortcut of a command element. (xs:string) A string composed of any sequence of characters, including white space.
LabelDescription	xs:string	No	A string that represents the text displayed on a command element. (xs:string) A string composed of any sequence of characters, including white space and line-break characters.
LabelTitle	xs:string	No	A string that represents the text displayed on a command element. (xs:string) A string composed of any sequence of characters, including white space and line-break characters.
Name	xs:string	No	(xs:string) A string that consists of a letter or underscore followed by any sequence of digits, letters, or underscores. Maximum length: 100 characters.
Symbol	xs:string	No	(xs:string) A string that consists of a letter or underscore followed by any sequence of digits, letters, or underscores. Maximum length: 100 characters.
TooltipDescription	xs:string	No	A string that represents the text displayed on a command element. (xs:string) A string composed of any sequence of characters, including white space and line-break characters.
TooltipTitle	xs:string	No	A string that represents the text displayed on a command element. (xs:string) A string composed of any sequence of characters, including white space and line-break characters.

Child elements

Element	Description
Command.Comment	May occur at most once
Command.Id	May occur at most once
Command.Keytip	May occur at most once
Command.LabelDescription	May occur at most once
Command.LabelTitle	May occur at most once
Command.LargeHighContrastImages	May occur at most once
Command.LargeImages	May occur at most once
Command.Name	May occur at most once
Command.SmallHighContrastImages	May occur at most once
Command.SmallImages	May occur at most once
Command.Symbol	May occur at most once
Command.TooltipDescription	May occur at most once
Command.TooltipTitle	May occur at most once

Parent elements

Element
Application.Commands

Remarks

Required.

May occur one or more times for each Application.Commands element.

The child elements of the Command element may occur in any order.

Typically, Command resources are declared in Ribbon markup, but they can also be set at run time with a call to SetUICommandProperty. For example, it is possible to set the UI_PKEY_Keytip property for a Command instead of declaring a value in markup with the Command.Keytip element.

In cases where Command properties, such as labels and images, cannot be set with SetUICommandProperty they can be invalidated with a call to InvalidateUICommand. After invalidation, the framework queries the host application for the resource details.

Note

A resource cannot be reinstated from the markup resource table after it has been invalidated.

A Command definition is added to the Ribbon markup header file for each Command declared in markup.

The value of Keytip acts as the keyboard accelerator for a Command unless that Command is exposed through a menu item. In this case, the framework ignores the Keytip value and instead uses a character preceded by an ampersand as specified by LabelTitle or UI_PKEY_Label. If no ampersand is specified by LabelTitle or UI_PKEY_Label, no keytip or keyboard accelerator is exposed.

Examples

The following example shows a manifest of Command elements for a Home tab.

<Application.Commands>

<Command Name="cmdHomeTab"
         LabelTitle="Home"
         Keytip="H" />
<Command Name="cmdClipboardGroup"
         Symbol="IDR_CMD_CLIPBOARD"
         Id="10000"
         Comment="Command definition for clipboard group"
         LabelTitle="Clipboard"
         Keytip="CB" />
<Command Name="cmdCopy"
         Symbol="IDR_CMD_COPY"
         LabelTitle="Copy"
         LabelDescription="Copy"
         Keytip="C"
         TooltipTitle="Copy"
         TooltipDescription="Click to copy">
  <Command.SmallImages>
    <Image>res/copyS_16.bmp</Image>
  </Command.SmallImages>
  <Command.LargeImages>
    <Image>res/copyL_32.bmp</Image>
  </Command.LargeImages>
</Command>
<Command Name="cmdPaste"
         Symbol="IDR_CMD_PASTE" >
  <Command.LabelTitle>Paste</Command.LabelTitle>
  <Command.LabelDescription>
    <String Content="Paste contents of clipboard"
            Id="10001"
            Symbol="IDR_RES_LABELDESC_PASTE" />
  </Command.LabelDescription>
  <Command.Keytip>P</Command.Keytip>
  <Command.TooltipTitle>
    <String Content="Paste contents of clipboard"
            Id="10002"
            Symbol="IDR_RES_TOOLTIP_PASTE"/>
  </Command.TooltipTitle>
  <Command.TooltipDescription>
    <String Content="Click to paste contents of clipboard"/>
  </Command.TooltipDescription>
  <Command.SmallImages>
    <Image
      Id="10010"
      MinDPI="96"
      Symbol="IDR_RES_SMALL_IMAGE96">
      <Image.Source>res/pasteS_96bpp.bmp</Image.Source>
    </Image>
    <Image Source="res/pasteS_120bpp.bmp"
           Id="10011"
           MinDPI="120"
           Symbol="IDR_RES_SMALL_IMAGE120" />
  </Command.SmallImages>
  <Command.LargeImages>
    <Image>res/pasteL_32.bmp</Image>
  </Command.LargeImages>
</Command>
<Command Name="cmdMinimize"
         Symbol="IDR_CMD_MINIMIZE"
         Id="10001"
         LabelTitle="Minimize" />

</Application.Commands>

Element information

Minimum supported system: Windows 7
Can be empty: No