Menu Element

  • Article

Defines one menu item. These are the six kinds of menus: Context, Menu, MenuController, MenuControllerLatched, Toolbar, and ToolWindowToolbar.

<Menu guid=”guidMyCommandSet” id=”MyCommand” priority=”0x100” type=”button”>
  <Parent>... </Parent>
  <CommandFlag>... </CommandFlag>
  <Strings>... </Strings>
</Menu>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

guid

Required. GUID of the GUID/ID command identifier.

id

Required. ID of the GUID/ID command identifier.

priority

Optional. A numeric value that specifies the relative position of a menu in a group of menus.

ToolbarPriorityInBand

Optional. A numeric value that specifies the relative position of a toolbar in a band when the window is docked.

type

Optional. An enumerated value that specifies the kind of element.

If not present, the default type is Menu.

Context

A shortcut menu that is shown when a user right-clicks a window. A shortcut menu has the following characteristics:

  • Does not use the Parent and Priority fields when the menu is to be displayed as a shortcut menu.

  • Can be used as a submenu and also as a shortcut menu. In this case, both Group ID and Priority fields are respected.

  • Is not always available.

A shortcut menu is displayed only when the following conditions are true:

  • The window that hosts it is displayed.

  • A mouse handler in the VSPackage detects a right-click on the window and then calls a method that handles the command.

  • The shortcut menu is displayed by calling the ShowContextMenu method (the recommended approach) or the ShowContextMenu method.

Menu

Provides a drop-down menu. A drop-down menu has the following characteristics:

  • Respects the Parent in its definition.

  • Must have a Parent group, or a CommandPlacement to a group.

  • Can be a submenu in any other kind of menu.

  • Is automatically displayed whenever its parent menu is displayed.

  • Does not require the implementation of any VSPackage code to make it displayed.

MenuController

Provides a split-button drop-down menu, which is typically used in toolbars. A MenuController menu has the following characteristics:

  • Must be contained in another menu through Parent or CommandPlacement.

  • Respects the Parent in its definition.

  • Can have any kind of menu as its parent.

  • Is automatically made available whenever its parent menu is displayed.

  • Does not require programmatic support to make the menu displayed.

A command from the split-button menu is displayed on the menu button. The command displayed has one of the following characteristics:

  • It is the last command that was used if the command is still displayed and enabled.

  • It is the first displayed command.

MenuControllerLatched

Provides a split-button drop-down menu for which a command can be specified as the default selection by marking the command as latched.

A latched command is a command that is marked in the menu as selected, typically by displaying a check mark. A command can be marked as latched if it has the OLECMDF_LATCHED flag set on it in an implementation of the QueryStatus method of the IOleCommandTarget interface. A MenuControllerLatched menu has the following characteristics:

  • Must be contained in another menu through a Parent group or CommandPlacement.

  • Respects the Parent in its definition.

  • Can have any kind of menu as its parent.

  • Is made available whenever its parent menu is displayed.

  • Does not require programmatic support to make the menu displayed.

A command from the split-button menu is displayed on the menu button. The command displayed has one of the following characteristics:

  • It is the first displayed command that is latched.

  • It is the first displayed command.

Toolbar

Provides a toolbar. A toolbar has the following characteristics:

  • Ignores the Parent in its definition.

  • Cannot be made a submenu of any group, not even by using CommandPlacement.

  • Can always be displayed by clicking Toolbars on the View menu.

  • Can be displayed by using a VisibilityItem.

  • Does not require any code to create it. For an example about how to create a toolbar, see Walkthrough: Adding a Toolbar to the IDE.

ToolWindowToolbar

Provides a toolbar that is attached to a specific tool window, just as a toolbar is attached to the development environment.

  • Ignores the Parent in its definition.

  • Cannot be made a submenu of any group, not even by using CommandPlacement.

  • Is displayed only when the tool window that hosts the toolbar is displayed and the VSPackage explicitly adds the toolbar to the tool window. This is typically done when the tool window is created by obtaining the toolbar host property (as represented by the IVsToolWindowToolbarHost interface) from the tool window frame and then calling the AddToolbar method.

Condition

Optional. See VSCT XML Schema Conditional Attributes.

Child Elements

Element

Description

Parent

Optional. The parent element of the menu item.

CommandFlag

Required. See Command Flag Element. The valid CommandFlag values for a Menu are as follows:

AlwaysCreate

DefaultDocked

DefaultInvisible. This flag does not affect the display of toolbars.

DontCache

DynamicVisibility. This flag does not affect the display of toolbars.

IconAndText

NoCustomize

NotInTBList

NoToolbarClose

TextChanges

TextIsAnchorCommand

Strings

Required. See Strings Element. The child ButtonText element must be defined.

Annotation

Optional comment.

Parent Elements

Element

Description

Menus Element

Defines all the menus that a VSPackage implements.

Example

<Menu guid="cmdGuidWidgetCommands" id="menuIDEditWidget"
  priority="0x0002" type="Menu">
  <Parent guid="cmdSetGuidWidgetCommands" id="groupIDFileEdit">
    <CommandFlag>AlwaysCreate</CommandFlag>
    <Strings>
      <ButtonText>Edit Widget</ButtonText>
    </Strings>
    </Parent>
</Menu>

See Also

Other Resources

Visual Studio Command Table (.Vsct) Files