CONTEXTMENUITEM

[This is preliminary documentation and subject to change.]

The CONTEXTMENUITEM structure is passed to IContextMenuCallback::AddItem or IContextMenuProvider::AddItem 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.

typedef struct _CONTEXTMENUITEM
{
    LPWSTR    strName;
    LPWSTR    strStatusBarText;
    LONG      lCommandID;
    LONG      lInsertionPointID;
    LONG      fFlags;
    LONG      fSpecialFlags;
} CONTEXTMENUITEM;
typedef CONTEXTMENUITEM* LPCONTEXTMENUITEM;

Members

strName

Pointer to a zero-terminated string containing the name of the menu item or of the submenu. This member may not be NULL except for a separator or insertion point.

strStatusBarText

Pointer to a zero-terminated string containing the text that will be displayed in the status bar when this item is highlighted. This member may be NULL.

lCommandID

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 will be passed back to IExtendContextMenu::Command.

If this menu item is added by IContextMenuProvider and then selected, this is the command ID that will be 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), you can use lCommandID in subsequent calls as lInsertionPoint (see the following table). Read the following discussion carefully 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.

Value Meaning

CCM_COMMANDID_MASK_
RESERVED = 0xFFFF0000 Items other than insertion points and submenus may not be added with these bits set.

Value	Meaning
CCM_COMMANDID_MASK_ RESERVED = 0xFFFF0000	Items other than insertion points and submenus may not be added with these bits 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).

Value Meaning

CCM_INSERTIONPOINTID_
MASK_SPECIAL = 0xFFFF0000 Special behavior. Snap-ins may use the other bits as they see fit.

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. Any of these entities adding items to a shared insertion point or submenu add them to the same insertion point or submenu.
If this bit is not set, IContextMenuProvider and each extension may use the same ID and each refers to a different insertion point or submenu.

Only IContextMenuProvider may create insertion points or submenus with this bit set, unless CCM_INSERTIONPOINTID_MASK_CREATE_PRIMARY is also set in the insertion point ID. If it is, only the primary extension may create them.

CCM_INSERTIONPOINTID_
MASK_CREATE_PRIMARY = 0x40000000 Only the system may add insertion points or submenus for which CCM_INSERTIONPOINTID_MASK_SHARED is set and this bit is not set. Only the primary extension may add insertion points or submenus for which both bits are set. This prevents insertion point ID conflicts between insertion points and submenus created by IContextMenuProvider and those created by the primary extension.

CCM_INSERTIONPOINTID_
MASK_ADD_PRIMARY = 0x20000000 If CCM_INSERTIONPOINT_SHARED is set and this bit is not set, the primary extension may not add to this insertion point or submenu.

CCM_INSERTIONPOINTID_
MASK_ADD_3^RDPARTY = 0x10000000 If CCM_INSERTIONPOINT_SHARED is set and this bit is not set, the third-party extensions may not add to this insertion point or submenu.

CCM_INSERTIONPOINTID_
MASK_RESERVED = 0x0FFF0000 Insertion points or submenus may not be added with any of these bits set.

lInsertionPointID

Value	Meaning
CCM_INSERTIONPOINTID_ MASK_SPECIAL = 0xFFFF0000	Special behavior. Snap-ins may use the other bits as they see fit.
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. Any of these entities adding items to a shared insertion point or submenu add them to the same insertion point or submenu. If this bit is not set, IContextMenuProvider and each extension may use the same ID and each refers to a different insertion point or submenu. Only IContextMenuProvider may create insertion points or submenus with this bit set, unless CCM_INSERTIONPOINTID_MASK_CREATE_PRIMARY is also set in the insertion point ID. If it is, only the primary extension may create them.
CCM_INSERTIONPOINTID_ MASK_CREATE_PRIMARY = 0x40000000	Only the system may add insertion points or submenus for which CCM_INSERTIONPOINTID_MASK_SHARED is set and this bit is not set. Only the primary extension may add insertion points or submenus for which both bits are set. This prevents insertion point ID conflicts between insertion points and submenus created by IContextMenuProvider and those created by the primary extension.
CCM_INSERTIONPOINTID_ MASK_ADD_PRIMARY = 0x20000000	If CCM_INSERTIONPOINT_SHARED is set and this bit is not set, the primary extension may not add to this insertion point or submenu.
CCM_INSERTIONPOINTID_ MASK_ADD_3^RDPARTY = 0x10000000	If CCM_INSERTIONPOINT_SHARED is set and this bit is not set, the third-party extensions may not add to this insertion point or submenu.
CCM_INSERTIONPOINTID_ MASK_RESERVED = 0x0FFF0000	Insertion points or submenus may not be added with any of these bits set.

Specifies where in the context menu the new item should be added. Extensions are limited in where they can place menu items. The following are the insertion points created by Microsoft Management Console in the default context menus for items in the scope pane and list view result pane:

Value	Meaning
0 (zero)	An IInsertionPointID of zero refers to the root menu for this context menu. Zero may be used interchangeably with CCM_INSERTIONPOINTID_ROOT_MENU. Note that only IContextMenuProvider is permitted to add items directly to the root menu. Extensions may only add items to insertion points and submenus added to the root menu by IContextMenuProvider or by Microsoft Management Console.
CCM_INSERTIONPOINTID_ PRIMARY_TOP = 0xA0000000	The primary extension may use this insertion point to add items to the top of the main context menu.
CCM_INSERTIONPOINTID_ PRIMARY_NEW = 0xA0000001	The primary extension may use this insertion point to add items to the top of the Create New submenu. The Create New submenu is only present for context menus in the scope pane and not for context menus in the result pane.
CCM_INSERTIONPOINTID_ PRIMARY_TASK = 0xA0000002	The primary extension may use this insertion point to add items to the top of the Task submenu.
CCM_INSERTIONPOINTID_ PRIMARY_VIEW	If the user clicks the View dropdown menu in the toolbar, this insertion point will be present but the New and Task insertion points will be absent.
CCM_INSERTIONPOINTID_ 3RDPARTY_NEW = 0x90000001	Third-party extensions may use this insertion point to add items to the bottom of the Create New submenu. The Create 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	Third-party extensions may use this insertion point to add items to the bottom of the Task submenu.
CCM_INSERTIONPOINTID_ ROOT_MENU = 0x80000000	IContextMenuProvider may use this insertion point to add items to the root menu. Neither primary extensions nor third-party extensions may add items to the root menu except through insertion points added by IContextMenuProvider.

fFlags

Specifies one or more of the following style flags:

Value	Meaning
MF_POPUP	Specifies that this is a submenu within the context menu. Menu items, insertion points, and further submenus may be added to this submenu using its lCommandID as their lInsertionPointID.
MF_BITMAP MF_OWNERDRAW	These flags are not permitted and will result in IContextMenuCallback::AddItem returning E_INVALIDARG.
MF_SEPARATOR	Draws a horizontal dividing line. Only IContextMenuProvider is allowed to add menu items with MF_SEPARATOR set.

The following flags all operate the same as in the Win32 API:

Value Meaning

MF_CHECKED Places a check mark next to 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 its 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 place a check mark next to the item (default).

Value	Meaning
MF_CHECKED	Places a check mark next to 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 its 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 place a check mark next to 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

Specifies one or more of the following flags:

Flag	Meaning
CCM_SPECIAL_SEPARATOR = 0x0001	Ignore all other parameters except lInsertionPointID. Add a separator to the end of the menu or the specified insertion point, except that CCM_SPECIAL_SEPARATOR will never add a separator as the first or last item in a menu or submenu. If two or more consecutive CCM_SPECIAL_SEPARATORs are added, only one appears in the menu. Only IContextMenuProvider is permitted to add separators, either 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	This should be the default menu item. If more than one menu item specifies this flag, the last one 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 may use the lCommandID from this call as their lInsertionPointID, and insert their own menu items, submenus, or insertion points at this point in this menu.

CONTEXTMENUITEM

Members

See Also