IContextMenu3::QueryContextMenu Method

  • Article

Adds commands to a shortcut menu.

Syntax

HRESULT QueryContextMenu(      
    HMENU hmenu,
    UINT indexMenu,
    UINT idCmdFirst,
    UINT idCmdLast,
    UINT uFlags
);

Parameters

  • hmenu
    A handle to the shortcut menu. The handler should specify this handle when adding menu items.
  • indexMenu
    The zero-based position at which to insert the first new menu item.
  • idCmdFirst
    The minimum value that the handler can specify for a menu item identifier.
  • idCmdLast
    The maximum value that the handler can specify for a menu item identifier.
  • uFlags
    Optional flags that specify how the shortcut menu can be changed. This parameter can be set to a combination of the following values. The remaining bits of the low-order word are reserved by the system. The high-order word can be used for context-specific communications. The CMF_RESERVED value can be used to mask the low-order word.
    • CMF_NORMAL
      0x00000000. Indicates normal operation. A shortcut menu extension, namespace extension, or drag-and-drop handler can add all menu items.
    • CMF_DEFAULTONLY
      0x00000001. The user is activating the default action, typically by double-clicking. This flag provides a hint for the shortcut menu extension to add nothing if it does not modify the default item in the menu. A shortcut menu extension or drag-and-drop handler should not add any menu items if this value is specified. A namespace extension should at most add only the default item.
    • CMF_VERBSONLY
      0x00000002. The shortcut menu is that of a shortcut file (normally, a .lnk file). Shortcut menu handlers should ignore this value.
    • CMF_EXPLORE
      0x00000004. The Windows Explorer tree window is present.
    • CMF_NOVERBS
      0x00000008. This flag is set for items displayed in the Send To menu. Shortcut menu handlers should ignore this value.
    • CMF_CANRENAME
      0x00000010. The calling application supports renaming of items. A shortcut menu or drag-and-drop handler should ignore this flag. A namespace extension should add a Rename item to the menu if applicable.
    • CMF_NODEFAULT
      0x00000020. No item in the menu has been set as the default. A drag-and-drop handler should ignore this flag. A namespace extension should not set any of the menu items as the default.
    • CMF_INCLUDESTATIC
      0x00000040. Not supported under Windows Vista and later. A static menu is being constructed. Only the browser should use this flag; all other shortcut menu extensions should ignore it.
    • CMF_ITEMMENU
      0x00000080. Windows Vista and later. The calling application is invoking a shortcut menu on an item in the view (as opposed to the background of the view).
    • CMF_EXTENDEDVERBS
      0x00000100. The calling application wants extended verbs. Normal verbs are displayed when the user right-clicks an object. To display extended verbs, the user must right-click while pressing the SHIFT key.
    • CMF_DISABLEDVERBS
      0x00000200. Windows Vista and later. The calling application intends to invoke verbs that are disabled, such as legacy menus.
    • CMF_ASYNCVERBSTATE
      0x00000400. Windows 7 and later. The verb state can be evaluated asynchronously.
    • CMF_OPTIMIZEFORINVOKE
      0x00000800. Windows 7 and later. Informs context menu handlers that do not support the invocation of a verb through a canonical verb name to bypass IContextMenu3::QueryContextMenu in their implementation.
    • CMF_SYNCCASCADEMENU
      0x00001000. Windows 7 and later. Populate submenus synchronously.
    • CMF_DONOTPICKDEFAULT
      0x00001000. Windows 7 and later. When no verb is explicitly specified, do not use a default verb in its place.
    • CMF_RESERVED
      0xffff0000. This flag is a bitmask that specifies all bits that should not be used. This is to be used only as a mask. Do not pass this as a parameter value.

Return Value

If successful, returns an HRESULT value that has its severity value set to SEVERITY_SUCCESS and its code value set to the offset of the largest command identifier that was assigned, plus one. For example, if idCmdFirst is set to 5 and you add three items to the menu with command identifiers of 5, 7, and 8, the return value should be MAKE_HRESULT(SEVERITY_SUCCESS, 0, 8 - 5 + 1). Otherwise, it returns a COM error value.

Remarks

This method should call either InsertMenu or InsertMenuItem to insert its menu items into the menu specified by hmenu. The indexMenu parameter holds the index to be used for the first menu item. The identifier of each menu item must fall within the range defined by idCmdFirst and idCmdLast.

A common practice is to set the first command identifier to idCmdFirst (an offset of zero) and increment the offset for each additional command by one. This practice ensures that you do not exceed idCmdLast and preserves the range of identifiers that are available for use by other handlers. Store the offsets for reference because they can be used to identify the command in subsequent calls to IContextMenu::GetCommandString and IContextMenu::InvokeCommand.

If the Shell subsequently calls another shortcut menu handler, it will use the code value of the returned HRESULT to set idCmdFirst when it calls that handler's QueryContextMenu method.

When a context menu handler adds a pop-up menu item, it must use IContextMenu::QueryContextMenu to add at least one item to that menu for the WM_INITMENUPOPUP message to be forwarded.