CONTEXTMENUITEM structure (mmc.h)
The CONTEXTMENUITEM structure is passed to the IContextMenuCallback::AddItem method or the IContextMenuProvider::AddItem method (inherited from IContextMenuCallback) to define a new menu item, submenu, or insertion point. The context menu is built from the root down, with each new item going to the end of the submenu or insertion point where it is inserted.
Syntax
typedef struct _CONTEXTMENUITEM {
LPWSTR strName;
LPWSTR strStatusBarText;
LONG lCommandID;
LONG lInsertionPointID;
LONG fFlags;
LONG fSpecialFlags;
} CONTEXTMENUITEM;
Members
strName
A pointer to a null-terminated string that contains the name of the menu item or of the submenu. This member cannot be NULL except for a separator or insertion point.
strStatusBarText
A pointer to a null-terminated string that contains the text that is displayed in the status bar when this item is highlighted. This member can be NULL.
lCommandID
A value that specifies the command identifier for menu items. If this menu item is added by IExtendContextMenu::AddMenuItems and then selected, this is the command ID that is passed back to IExtendContextMenu::Command. If this menu item is added by the IContextMenuProvider interface and then selected, this is the command ID that is passed back to pISelected by IContextMenuProvider::ShowContextMenu. If this is an insertion point (CCM_SPECIAL_INSERTION_POINT is set in fSpecialFlags) or a submenu (MF_POPUP is set in fFlags), use lCommandID in subsequent calls as lInsertionPointID (for more information, see the following list). Carefully read the following discussion because specific bits in the new insertion point ID must be on and others must be off.
Some bits in the command ID require special handling for items that are not insertion points or submenus.
CCM_COMMANDID_MASK_RESERVED = 0xFFFF0000
Items other than insertion points and submenus cannot be added when these bits are set.
Some bits in the insertion point ID require special handling for items that are insertion points (fSpecialFlags and CCM_SPECIAL_INSERTION_POINT) or submenus (fFlags and MF_POPUP).
CCM_INSERTIONPOINTID_MASK_SPECIAL = 0xFFFF0000
Special behavior. Snap-ins can use the other bits as required.
CCM_INSERTIONPOINTID_MASK_SHARED = 0x80000000
These insertion points and submenus are shared between the creator of the context menu, the primary extension, and the third-party extension. Items added to a shared insertion point or submenu are available to the creator of the context menu, the primary extension, and the third-party extension.
If this bit is not set, the IContextMenuProvider interface and each extension can use the same ID. Each ID refers to a different insertion point or submenu.
Only the context menu creator and the primary snap-in can create shared insertion points or submenus.
CCM_INSERTIONPOINTID_MASK_CREATE_PRIMARY = 0x40000000
This bit must be set for shared insertion points and submenus created by the primary snap-in and not set for those created by the context menu creator. This prevents ID conflicts between the two sources of shared insertion points and submenus.
CCM_INSERTIONPOINTID_MASK_ADD_PRIMARY = 0x20000000
Allow the primary snap-in to add items to a shared insertion point or submenu.
CCM_INSERTIONPOINTID_MASK_ADD_3RDPARTY = 0x10000000
Allow extension snap-ins to add items to a shared insertion point or submenu.
CCM_INSERTIONPOINTID_MASK_RESERVED = 0x0FFF0000
Insertion points or submenus cannot be added with any of these bits set.
lInsertionPointID
A value that specifies where in the context menu the new item should be added. Snap-ins can only add items to insertion points created by the menu creator or the primary snap-in. The following are the insertion points created by MMC in the default context menus for items in the scope pane and list view result pane:
0 (zero)
An lInsertionPointID of zero refers to the root menu for this context menu. Zero can be used interchangeably with CCM_INSERTIONPOINTID_ROOT_MENU. Be aware that only the IContextMenuProvider interface can add items directly to the root menu. Extensions can only add items to insertion points and submenus added to the root menu by IContextMenuProvider or by MMC.
CCM_INSERTIONPOINTID_PRIMARY_TOP = 0xA0000000
The primary snap-in can use this insertion point to add items to the top of the main context menu.
CCM_INSERTIONPOINTID_PRIMARY_NEW = 0xA0000001
The primary snap-in can use this insertion point to add items to the top of the New submenu. The New submenu is available in context menus in both the scope pane and the result pane.
CCM_INSERTIONPOINTID_PRIMARY_TASK = 0xA0000002
The primary snap-in can use this insertion point to add items to the top of the All Tasks submenu. The All Tasks submenu is available in context menus in both the scope pane and the result pane.
CCM_INSERTIONPOINTID_PRIMARY_VIEW = 0xA0000003
The primary snap-in can use this insertion point to add items to the View drop-down menu. If the user clicks the View menu in the toolbar, this insertion point will be present, but the New and All Tasks insertion points will not appear.
CCM_INSERTIONPOINTID_3RDPARTY_NEW = 0x90000001
Extension snap-ins can use this insertion point to add items to the bottom of the New submenu. The New submenu is only present for context menus in the scope pane and not for context menus in the result pane.
CCM_INSERTIONPOINTID_3RDPARTY_TASK = 0x90000002
Extension snap-ins can use this insertion point to add items to the bottom of the All Tasks submenu.
CCM_INSERTIONPOINTID_ROOT_MENU = 0x80000000
The IContextMenuProvider interface can use this insertion point to add items to the root menu.
Neither primary extensions nor third-party extensions can add items to the root menu except through insertion points added by IContextMenuProvider.
fFlags
A value that specifies one or more of the following style flags:
MF_POPUP
A value that specifies that this is a submenu within the context menu. Menu items, insertion points, and further submenus can be added to this submenu using its lCommandID as their lInsertionPointID.
MF_BITMAP
MF_OWNERDRAW
These flags are not supported and will result in IContextMenuCallback::AddItem returning E_INVALIDARG.
MF_SEPARATOR
Draws a horizontal separator line.
Only the IContextMenuProvider interface can add menu items with MF_SEPARATOR set.
The following flags function in the same way that they do in the Windows API:
MF_CHECKED
Selects the menu item.
MF_DISABLED
Disables the menu item so it cannot be selected, but the flag does not gray it.
MF_ENABLED
Enables the menu item so it can be selected, restoring it from a grayed state.
MF_GRAYED
Disables the menu item, graying it so it cannot be selected.
MF_MENUBARBREAK
Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.
MF_MENUBREAK
Places the item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.
MF_UNCHECKED
Does not select the item (default).
The following groups of flags cannot be used together:
- MF_DISABLED, MF_ENABLED, and MF_GRAYED
- MF_MENUBARBREAK and MF_MENUBREAK
- MF_CHECKED and MF_UNCHECKED
fSpecialFlags
A value that specifies one or more of the following flags:
CCM_SPECIAL_SEPARATOR = 0x0001
Ignore all other parameters except lInsertionPointID. Add a separator to the end of the menu or at the specified insertion point. Separators placed at the top or bottom of a menu or submenu will not be displayed. Separators with no menu items between them will be collapsed into a single separator.
Only the IContextMenuProvider interface can add separators, special or otherwise.
CCM_SPECIAL_SUBMENU = 0x0002
If this submenu is empty, it will be grayed and disabled. This is only valid for MF_POPUP items.
CCM_SPECIAL_DEFAULT_ITEM = 0x0004
The default menu item. If more than one menu item specifies this flag, the last item in each submenu takes precedence.
CCM_SPECIAL_INSERTION_POINT = 0x0008
Ignore all other parameters except lCommandID and lInsertionPointID. This creates a new insertion point at the end of the insertion point or submenu identified by lInsertionPointID.
Subsequent calls can use the lCommandID parameter from this call as their lInsertionPointID, and insert their own menu items, submenus, or insertion points at this point in the menu.
CCM_SPECIAL_TESTONLY = 0x0010
Validate the item parameters, but do not add the menu item. Return result code that indicates whether add would have been successful.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista |
| Minimum supported server | Windows Server 2008 |
| Header | mmc.h |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for