NEWGROUPS_BEGIN – NEWGROUPS_END

Article
10/15/2009

[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_FILTER
```
Menu 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_FILESYSFOLDER
```
To 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
0x0040
```
When 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.

NEWGROUPS_BEGIN – NEWGROUPS_END

The Group Entry

Groups Example

The Group Entry Fields

See Also

Concepts

Other Resources

Additional resources