Menu Element

Article
11/15/2016

Note

This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

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

Syntax

<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 Adding a Toolbar. 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 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>