Menu Element

  • Article

Defines a single menu item. There are six kinds of menus, as follows: Context, Menu, MenuController, MenuControllerLatched, Toolbar, and ToolWindowToolbar.

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 priority.

type

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

If not given, uses Button.

Context

Provides a menu that can be shown when a user right-clicks a window.

A Context menu has the following characteristics:

  • Does not use the Parent and Priority fields when the menu is being displayed as a context menu.

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

  • Is not automatically made available by the integrated development environment (IDE) as a context menu.

A Context menu is only visible when the following are true:

  • The window that hosts it is visible.

  • A mouse handler in the VSPackage detects a right-click on the window and then calls an implementing method.

  • The context menu is displayed by using a call to the ShowContextMenu method in the IOleComponentUIManager interface (the preferred approach) or the ShowContextMenu method in the IVsUIShell interface.

Menu

Provides a typical drop-down menu list.

A menu has the following characteristics:

  • Is specified by leaving the type argument blank in a menu declaration.

  • Respects the Parent in its definition.

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

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

  • Is automatically made visible by the IDE whenever its parent menu is visible.

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

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 by the IDE whenever its parent menu is visible.

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

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

  • The last command that was used if the command is still visible and enabled.

  • The first visible 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 automatically made available by the IDE whenever its parent menu is visible.

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

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

  • The first visible command that is latched.

  • The first visible command.

Toolbar

Provides a standard toolbar that is attached to the IDE.

A Toolbar menu has the following characteristics:

  • Ignores the Parent in its definition.

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

  • Is always available by clicking Toolbars on the View menu in the IDE.

  • Can be made visible and also be made a default part of the user's IDE by using flags (see CommandFlag).

  • Is automatically made available by the IDE.

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

ToolWindowToolbar

Provides a toolbar that is attached to a specific tool window, just as a Toolbar menu is attached to the IDE.

A ToolWindowToolbar menu has the following characteristics:

  • Ignores the Parent in its definition.

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

  • Is not automatically made available by the IDE.

  • Is only visible when the tool window that hosts the toolbar is visible 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

DontCache

DynamicVisibility

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>
</Menu>

See Also

Other Resources

Visual Studio Command Table (.Vsct) Files