NEWGROUPS_BEGIN – NEWGROUPS_END
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
The NEWGROUPS_BEGIN – NEWGROUPS_END section contains entries that define the command groups of a VSPackage.
The Group Entry
A group is a container for commands and menus. Groups are located on menus or toolbars, and a separator is automatically inserted between groups. A group entry specifies a primary menu where the group will be added. A group can be included on more than one menu or toolbar by using additional entries in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.
A group entry is defined in the NEWGROUPS_BEGIN - NEWGROUPS_END section. A group entry has three fields that are separated by commas. The group entry ends with a semicolon. The following example shows the syntax:Group ID, Menu ID, Priority;
These fields are described in the following table. In a group entry, they must appear in the order shown. The last field must end with a semicolon. For more information, see "Group Entry Fields" in this topic.
Field |
Description |
|---|---|
Group ID |
A GUID:ID pair that identifies this group. |
Menu ID |
A GUID:ID pair that identifies the primary menu in which this group appears. |
Priority |
A value that is used to position this group relative to other groups on the same menu. |
Groups Example
The following example shows the NEWGROUPS_BEGIN – NEWGROUPS_END section from the File Explorer sample. The container of a group is a menu. The menu section format is described in MENUS_BEGIN – MENUS_END. Groups can contain menus and buttons. The button section format is described in BUTTONS_BEGIN – BUTTONS_END.
NEWGROUPS_BEGIN
// File Pane Toolbar Groups
guidEUGrp:IDG_FILEPANE_COMMANDS , guidEUGrp:IDM_TLB_FILESYSFILE , 0x0010;
guidEUGrp:IDG_FILEPANE_REFRESH , guidEUGrp:IDM_TLB_FILESYSFILE , 0x0020;
guidEUGrp:IDG_FILEPANE_PROPS , guidEUGrp:IDM_TLB_FILESYSFILE , 0x0030;
guidEUGrp:IDG_FILEPANE_FILTER , guidEUGrp:IDM_TLB_FILESYSFILE , 0x0040;
// File Pane Context Menu Groups
guidEUGrp:IDG_FILEPANECTX_COMMANDS, guidEUGrp:IDM_CTX_FILESYSFILE , 0x0010;
guidEUGrp:IDG_FILEPANECTX_ARRANGE , guidEUGrp:IDM_CTX_FILESYSFILE , 0x0020;
// File Pane Context Menu Arrange Cascading Menu Groups
guidEUGrp:IDG_FILEPANE_SORT , guidEUGrp:IDM_MNU_FILESYSFILE_SORT, 0x0010;
// Folder Pane Toolbar Groups
guidEUGrp:IDG_FOLDERPANE_VIEW , guidEUGrp:IDM_TLB_FILESYSFOLDER , 0x0010;
// Folder Pane Context Menu Groups
guidEUGrp:IDG_FOLDERCTX_SHORTCUT , guidEUGrp:IDM_CTX_FILESYSFOLDER , 0x0010;
guidEUGrp:IDG_FOLDERCTX_PROPS , guidEUGrp:IDM_CTX_FILESYSFOLDER , 0xFF00;
// Shared Commands Group
guidEUGrp:IDG_FILESYSCTX_COMMANDS , guidEUGrp:IDM_CTX_FILESYSFILE , 0x0030;
// Shared Commands Cascading Menu Groups
guidEUGrp:IDG_COMMANDS_LIST , guidEUGrp:IDM_MNU_FILESYS_COMMANDS, 0x0010;
// Command Macro Context Menu Groups
guidEUGrp:IDG_CMDCTX_FOLDER , guidEUGrp:IDM_CTX_CMDMACRO , 0x0010;
NEWGROUPS_END
The Group Entry Fields
Every entry in the NEWGROUPS_BEGIN – NEWGROUPS_END section must contain three fields. A comma separates the fields in an entry and a semicolon indicates the end of the entry. The fields, in order, are as follows:
Group ID
The Group ID field identifies the new group that you want to create. The Group ID is always a GUID:ID pair and uniquely identifies the group. Some of the Group ID fields in the "File Pane Toolbar Groups" code example are the following.
guidEUGrp:IDG_FILEPANE_COMMANDS guidEUGrp:IDG_FILEPANE_REFRESH guidEUGrp:IDG_FILEPANE_PROPS guidEUGrp:IDG_FILEPANE_FILTERMenu ID
The Menu ID field identifies the primary menu on which the group is added. The Menu ID is always a GUID:ID pair that uniquely identifies the primary menu. Some of the Menu ID fields in the "File Pane Toolbar Groups" code example are the following.
guidEUGrp:IDM_TLB_FILESYSFILE guidEUGrp:IDM_CTX_FILESYSFILE guidEUGrp:IDM_MNU_FILESYSFILE_SORT guidEUGrp:IDM_TLB_FILESYSFOLDER guidEUGrp:IDM_CTX_FILESYSFOLDERTo create a group without specifying the primary menu to host it, you should either make the group self-hosted, or use the GUID of the group and an ID of 0 (zero). Self-hosted means that the group uses its own Group ID in the Menu ID field, for example, as follows.
guidEUGrp:IDG_FILEPANE_COMMANDS, guidEUGrp:IDG_FILEPANE_COMMANDS, 0x0010;
The following example shows how to use the GUID of the group and an ID of 0 (zero).
guidEUGrp:IDG_FILEPANE_COMMANDS, guidEUGrp:0, 0x0010;
If a group does not have a primary menu, it must be included on a menu with an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section or it will not appear in the integrated development environment (IDE).
Priority
The Priority field specifies the placement of the group in the specified menu relative to the other groups in the menu. Items that have a lower priority number appear before items that have a higher priority number. The Priority fields in the "File Pane Toolbar Groups" code example are as follows.
0x0010 0x0020 0x0030 0x0040When the hosting of a group is defined by command placement, the Priority field that is specified in the group entry is ignored in favor of the Priority field that is specified by the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.
See Also
Concepts
How VSPackages Add User Interface Elements to the IDE