How to: Create Reusable Groups of Buttons
Nota
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 command group is a collection of commands that always appear together in a menu or on a toolbar. For example, the commands Cut, Copy, and Paste belong to the command group guidSHLMainMenu:IDG_VS_TOOLSB_CUTCOPY, which is defined in the ShellCmdPlace.ctc file. The commands Cut, Copy, and Paste are defined as guidVSStd97:cmdidCut, guidVSStd97:cmdidCopy, and guidVSStd97:cmdidPaste respectively. The ShellCmdPlace.ctc file and other files described in Command Table Configuration (.Ctc) Files as well as .h files that contain predefined commands, groups, and menus are all located in <Visual Studio SDK installation path>\VisualStudioIntegration\Common\Inc\.
The ctc.exe compiler makes use of a C preprocessor so it is possible to #include these or any additional .h or .ctc files. The items in a command group are usually buttons, but they can also be other menus or combo boxes.
Note:Visual Studio uses the following naming convention:
Predefined menus always begin with IDM_
Predefined groups always begin with IDG_.
Predefined commands always begin with cmdid.
When you define your own menus, groups, or commands, follow this naming convention or a similar one. See Guidelines for Small Command Sets and Guidelines for Large Command Sets.
The two parts that make up a single item's definition look like this:
#define guidCmdSet { 0xBC8DA515, 0x5743, 0x4FEB, { 0xA9, 0x29, 0x29, 0x38, 0x24, 0x9C, 0xBA, 0x26 } }
#define IDG_MyNewReusableGroup 1
// This is a valid value for the first parameter of the definition.
guidCmdSet:IDG_MyNewReusableGroup
Note Create your own unique GUID in the Visual Studio SDK using the Create GUID tool available by selecting Create GUID from the Tools menu.
To create a reusable group of buttons
Use the notation guidCmdSet:IDG_MyNewReusableGroup described above to define a new reusable group. As a rule, do not use the Visual Studio defined command sets, guidVSStd97 or guidVSStd2K, because the guidCmdSet:IDG_MyNewReusableGroup pair must be unique and it would require a great deal of investigation to ensure the uniqueness of the ID (the right-hand part of the GUID:ID pair). You are free to define your own group and then populate it with predefined components. The pair guidCmdSet:IDG_MyNewReusableGroup is used internally to tie components together. It is never treated as a command so you can create a GUID just for this group, if desired.
Create a line in the NEWGROUPS_BEGIN – NEWGROUPS_END section of the Command Table Configuration (.Ctc) Files.
Set the Group ID field to the GUID:ID pair of the new command group.
Set the Menu ID field to the same GUID:ID used in the Group ID field (guidCmdSet:IDG_MyNewReusableGroup). This group can later be placed on a menu or toolbar by adding entries to the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.
Set the Priority field to zero. The entries in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section determine the group's priority relative to other groups in the menu.
A command group that is not a parent to any other group, menu, or command is ignored.
To populate a group of buttons for reuse
There are two ways in which a command or menu can be placed in a group: either by making the definition of the command or menu use the group as a parent or by placing the command or menu in the group through the command placement section.
If the definition for the command or menu appears in the .ctc file and command or menu is to appear only in a single group, then modify or add a definition for the command or menu in the appropriate section and set the Group ID field to the GUID:ID of the desired group. This means that predefined commands or menus cannot be modified and must be placed using an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.
For adding or modifying command entries, see the BUTTONS_BEGIN – BUTTONS_END section.
For adding or modifying menu entries, see the MENUS_BEGIN – MENUS_END section.
For commands or menus that are not defined in the .ctc or that are to appear in multiple groups, create an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section of the command table. A command or menu can be placed in multiple groups using the CMDPLACEMENT_SECTION - CMDPLACEMENT_END section. For each entry:
Set the Item ID field to the GUID:ID of the command or menu.
Set the Parent IDfield to the GUID:ID of the command group you have just created (for example, guidCmdSet:IDG_MyNewReusableGroup).
Set the value of the Priority field. The value of the Priority field determines the location of the button or other command among the other objects in the command group.
Note The value of the Priority field determines the position of the command within the new command group. Commands with low priority values are displayed before commands with high priority values. Duplicate priority values are permitted, but the relative position of commands with equal priority values cannot be guaranteed. This is because the order that devenv.exe /setup reads and merges resources from the registry to create the final interface is not guaranteed to be consistent.
To place a group of buttons for reuse
To place the reusable command group in a menu, create an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section. Note that a command group can be placed in multiple menus. The parent menu can be one you have created or one supplied by Visual Studio, as described in the ShellCmdDef.ctc or SharedCmdDef.ctc files located in the \EnvSDK\common\inc\ folder (for example, C:\Program Files\VSIP 8.0\EnvSDK\common\inc\), or even a menu defined in another VSPackage. The layers of parenting may be arbitrarily deep as long as the parent menu is eventually connected to Visual Studio or a context menu displayed by a VSPackage.
Set the Item ID field to the GUID:ID of the new group (in this example, guidCmdSet:IDG_MyNewReusableGroup).
Set the Parent ID field to the GUID:ID of the menu or command group that is to contain the new group.
Set the value of the Priority field. The value of the Priority field determines the location of the command group relative to the other objects in the parent menu.