How to: Add Menu Controllers to Toolbars or Menus
注意
Beginning with Visual Studio 2008 SDK, use XML Command Table (.vsct) files instead of command table configuration (.ctc) files to define how menus and commands appear in your VSPackages. For more information, see XML-Based Command Table Configuration (.vsct) Files.
A menu controller may be placed on a menu or a toolbar. A menu controller on a menu appears as a drop-down menu or submenu that can be selected along with any members of that submenu. A menu controller on a toolbar appears as a button with a drop-down arrow beside it. When clicked, the menu controller displays a menu that is built by combining all of the groups that call this menu controller their parent.
A menu controller is typically used on toolbars and provides a way to change a toolbar button on the fly. Selecting a command from the drop-down list attached to the menu controller causes the menu controller to display that command while at the same time executing the command. To execute the command again, just click on the menu controller itself. To change the command that appears on the menu controller, select another command from the drop-down list. This same functionality occurs for a menu controller added to a normal menu.
Menu controllers have the following features:
Displays the icon and text of the first visible command in the drop-down list.
If a command is selected from the drop-down list, the menu controller displays the icon and text for that command.
Can display just the icon or the text or both of the command.
Can be set up to always execute the same command when the menu controller is clicked, regardless of the last command selected and executed from the drop-down list.
The above features can be modified by flags that are applied to the definition of the menu controller in the command table (.ctc) file.
The following procedure describes how to create and add a menu controller to a toolbar or menu.
The following walkthrough shows how to add a menu controller to a toolbar in both managed (Visual C#) and unmanaged (Visual C++) code:
To create and add a menu controller
Select a GUID:ID pair to represent the new menu controller. The ctc.exe compiler expects a GUID data type in the following format:
#define guidCmd { 0xBC8DA515, 0x5743, 0x4FEB, { 0xA9, 0x29, 0x29, 0x38, 0x24, 0x9C, 0xBA, 0x26 } }The pair definition continues with a colon and finally a unique number. The GUID:ID pair must be unique and used to identify the menu controller.
Create a new line in the MENUS_BEGIN – MENUS_END section of the Command Table Configuration (.Ctc) Files.
Set the Menu ID field to the GUID:ID of the new menu.
Set the Group ID field to the GUID:ID of the group that is to contain the menu controller.
The specified group should have the GUID:ID of the menu or toolbar in which the menu controller is to be placed as its Menu ID field.
Alternative (or in addition) to specifying a group's GUID:ID in the Group ID field, you can place the menu controller in a group using an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section. If the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section is used exclusively to place the menu controller, set the Group ID field for the menu controller, by convention, to the same GUID:ID used in the Menu ID field.
Set the Priority field to an appropriate value.
The value of the Priority field determines the location of the menu controller relative to the other elements in the same group.
Elements with low priority values are displayed before elements with high priority values. Duplicate priority values are permitted, but the relative position of the elements with equal priority is determined by the order in which VSPackages are processed for menus and that order cannot be predetermined.
Set the Type field to MenuController or MenuControllerLatched.
MenuController - the menu controller uses the first visible command as the initial command displayed.
MenuControllerLatched - the menu controller uses the first visible command that is latched or checked as the initial command displayed. If no such command is checked, then the first visible command is used.
Add the following flags to the Type field, using the | (logical OR) operator as appropriate:
TextIsAnchorCommand - if you want the menu controller to change to the last command selected. This should be combined with the TextChanges flag.
IconAndText - if you want the menu controller to display both icon and text for the initial or last used command.
AlwaysCreate – if you want to create the menu controller even if it contains no commands.
TextChanges – if you want the menu to have dynamic text.
Set the Menu Name field to the name of the menu controller, enclosed in quotes.
Set the Menu Text field to the name of the menu controller.
If the Menu Text field is not specified, then the Menu Name field is used.
注意
The value of the Menu Text field appears as a ToolTip when the menu controller is placed in a toolbar. It is also used when generating keyboard shortcuts.
Create a new group to contain the commands that are to appear on your menu controller.
See the NEWGROUPS_BEGIN – NEWGROUPS_END section for details on creating new groups.
Set the parent for this new group to be the GUID:ID of the menu controller you created in step 2. This places the group of commands on the menu controller.
Add commands to the menu controller by creating command entries in the BUTTONS_BEGIN – BUTTONS_END section of the .ctc file and setting the Group ID field for each command to the GUID:ID of the group created in step 3.
Use the Priority field of each command entry to specify the order in which the commands appear in the group.
注意
To force the menu controller to always display the same command, mark the command that is to be used with the FixMenuController flag.
Using the command table compiler (ctc.exe), convert your .ctc file to a binary resource that can be included in your VSPackage satellite dll file. For information on the Command Table Compiler, see How to: Create Menu Commands for a VSPackage By Using the Binary Command Table Compiler.