How to: Add Menu Controllers to Toolbars

Article
11/16/2012

A menu controller appears on a toolbar as a button that has a drop-down arrow next to it. When a user clicks the menu controller, a menu is displayed that contains the groups that have the menu controller as parent. Two examples of menu controllers in Visual Studio are the Find box on the main toolbar and the object selector at the top of the Properties window.
When a user clicks a command on the drop-down list that is attached to a menu controller, the command is executed and the command name is displayed on the menu controller button. To run the command again, the user can just click the button.

Note

Although you can put a menu controller on a menu, we recommend that you use a submenu instead because it is easier to implement and is more consistent with typical user interfaces.

Menu controllers have the following characteristics:
The icon and text of the first visible command in the drop-down list is displayed on the menu controller button.
When a command on the drop-down list is clicked, the icon and text for that command is displayed on the button.
Either the icon or the text of a command, or both, can be displayed.
The button can be configured to execute the same command every time it is clicked. In this case, when a user clicks a command on the drop-down list, it is executed but its name is not displayed on the button.

To modify these characteristics, apply flags in the .vsct file where the menu controller is defined. For more information, see Visual Studio Command Table (.Vsct) Files.

To complete the following procedure, you must have a VSPackage project that has a .vsct file. To create a package, run the Visual Studio Integration Package Wizard. In the wizard, select the Menu Command option so that a .vsct file that contains a default command will be included in the package project.

Open the .vsct file in the editor.
In the section that is formed by the Symbols Element, find the GuidSymbol Element that contains your menus, groups, and commands. By default, it is named guid<ProjectName>CmdSet.

As shown in the following example, add an IDSymbol Element for your menu controller, each command that it will host, and one or more groups to hold the commands.

<IDSymbol name="TestMenuController" value="0x1300"/>
<IDSymbol name="TestMenuControllerGroup" value="0x1060"/>
<IDSymbol name="cmdidMCItem1" value="0x0130"/>
<IDSymbol name="cmdidMCItem2" value="0x0131"/>
<IDSymbol name="cmdidMCItem3" value="0x0132"/>

In the section that is formed by the Commands Element, create a section by using the Menus Element.
In the Menus section, define the menu controller as a menu, as follows.
1. Set the guid and id attributes to the GUID:ID of the new menu controller.
  
  The GUID:ID pair is formed by the name attributes of the GuidSymbol and IDSymbol elements in the menu controller definition in the Symbols section.
2. Set the priority attribute to determine the position of the menu controller in its parent group.
3. Set the type attribute toMenuController or MenuControllerLatched.
  
  The MenuController value means that the menu controller initially displays the first visible command.
  
  The MenuControllerLatched value means that the menu controller uses the first visible command that is selected as the initially displayed command. If no command is selected, then the first visible command is displayed.
4. In the Menu element, create a Parent Element and set its guid and id attributes to the GUID:ID of the group that will host the menu controller. This can be an existing Visual Studio group, such as guidStdEditor:IDG_VS_EDITTOOLBAR_COMMENT, which contains the Comment and Remove Comment buttons on the editor toolbar, or it can be a user-defined group.
  
  The Parent element may be omitted if the menu controller will be placed by using command placement. To enable this, before the Symbols section, use the CommandPlacements Element to create a section. Add a CommandPlacement Element that has the GUID:ID of the menu controller, a priority, and a parent.
  
  Multiple command placements that have the same GUID:ID but have different parents causes a menu controller to appear in multiple locations. For more information, see CommandPlacements Element and How to: Create Reusable Groups of Buttons.
5. After the parent, use the Strings Element to create a section that contains a ButtonText Element and a CommandName Element. The ButtonText element is used to set the name of the toolbar as it appears in the IDE. The CommandName element is used to set the command name that can be typed in the Command window to access the toolbar.
The following example defines a menu controller.
```
<Menu guid="guidTWToolbarCmdSet" id="TestMenuController"
priority="0x0100" type="MenuController">
  <Parent guid="guidTWToolbarCmdSet" id="TWToolbarGroup"/>
  <CommandFlag>IconAndText</CommandFlag>
  <CommandFlag>TextChanges</CommandFlag>
  <CommandFlag>TextIsAnchorCommand</CommandFlag>
  <Strings>
    <ButtonText>Test Menu Controller</ButtonText>
    <CommandName>Test Menu Controller</CommandName>
  </Strings>
</Menu>
```
In the section that is formed by the Groups Element, create a Group Element to contain the commands that you want to appear on your menu controller.
1. Set the priority of the group to determine where it will appear on your menu controller if there are multiple groups.
2. Set the parent of the group to the GUID:ID of the menu controller.
The following group appears on the menu controller from the previous example.
```
<Group guid="guidTWToolbarCmdSet" id="TestMenuControllerGroup"
priority="0x000">
  <Parent guid="guidTWToolbarCmdSet" id="TestMenuController"/>
</Group>
```

In the section that is formed by the Buttons Element, add a Button Element for every command that you want to add to the menu controller. Every command must specify as its parent a group on the menu controller, as shown in the following example.

<Button guid="guidTWToolbarCmdSet" id="cmdidMCItem1"
priority="0x0000" type="Button">
  <Parent guid="guidTWToolbarCmdSet" id="TestMenuControllerGroup"/>
  <Icon guid="guidTWToolbarCmdSet" id="bmpPic1"/>
  <CommandFlag>IconAndText</CommandFlag>
  <Strings>
    <ButtonText>MC Item 1</ButtonText>
    <CommandName>MC Item 1</CommandName>
  </Strings>
</Button>
<Button guid="guidTWToolbarCmdSet" id="cmdidMCItem2"
      priority="0x0100" type="Button">
  <Parent guid="guidTWToolbarCmdSet" id="TestMenuControllerGroup"/>
  <Icon guid="guidTWToolbarCmdSet" id="bmpPic2"/>
  <CommandFlag>IconAndText</CommandFlag>
  <Strings>
    <ButtonText>MC Item 2</ButtonText>
    <CommandName>MC Item 2</CommandName>
  </Strings>
</Button>
<Button guid="guidTWToolbarCmdSet" id="cmdidMCItem3"
      priority="0x0200" type="Button">
  <Parent guid="guidTWToolbarCmdSet" id="TestMenuControllerGroup"/>
  <Icon guid="guidTWToolbarCmdSet" id="bmpPicSmile"/>
  <CommandFlag>IconAndText</CommandFlag>
  <Strings>
    <ButtonText>MC Item 3</ButtonText>
    <CommandName>MC Item 3</CommandName>
  </Strings>
</Button>

To force the menu controller button to display the same command every time it is clicked, set the FixMenuController flag on the command.

The Parent element may be omitted for commands that will be placed by using command placement.

How to: Add Menu Controllers to Toolbars

Creating a Menu Controller

To create and add a menu controller

See Also

Tasks

Concepts

Other Resources

Additional resources