ContextMenu Reference

Reference for the object that handles the shell context menu (IContextMenu).

Related: te Reference, api Reference, FolderView (ShellBrowser) Reference, FolderItems Reference

Notation: P = property, M = method.

How to Obtain
Methods
Properties
Related Events
Constants
Examples

1. How to Obtain

Way	Description
`api.ContextMenu(Items [, FV])`	Creates the context menu for the specified FolderItems / FolderItem. `Items` can be a FolderItem, a FolderItems, a path string, an IDataObject, and so on. If you pass `FV` (a FolderView), the behavior of the menu (the IShellBrowser site) is associated with that view. Returns empty on failure
`FV.ViewMenu([flags])`	Returns the context menu of the view (the background or the selected items). If `flags` is omitted, it is the background menu
`api.ContextMenu(dllPath/CLSID, ..., Item, Items, hKey, subKey, FV)`	Loads a shell extension (`IShellExtInit`) directly and creates a menu object (7 arguments): the pair of `dllPath` and `CLSID`, an IDList (`Item`), the target (`Items`), a registry key (`hKey` and `subKey`), and the view that serves as the site

The 7-argument form is an advanced form for extracting the menu of one particular shell extension only.

2. Methods

Name	Description
`QueryContextMenu(hMenu, indexMenu, idCmdFirst, idCmdLast, uFlags)`	Adds the menu items to `hMenu`. All 5 arguments are required. On success it returns the return value of `IContextMenu::QueryContextMenu` (an HRESULT that holds the maximum command ID + 1). It runs only once per object (from the second call on, it does nothing and returns no value)
`InvokeCommand(fMask, hwnd, Verb, Parameters, Directory, nShow, dwHotKey, hIcon)`	Executes a command. All 8 arguments are required. Returns an HRESULT (see below)
`GetCommandString(idCmd, uFlags)`	Returns the verb or help string of a command. `idCmd` is the 0-based number obtained by subtracting the `idCmdFirst` passed to `QueryContextMenu`. `uFlags` is `GCS_`. If `idCmd` is greater than 65535, it returns an empty string. If called with no arguments, it returns `true`*
`HandleMenuMsg(uMsg, wParam, lParam)`	Message handling for `IContextMenu2` / `IContextMenu3`. Pass `WM_INITMENUPOPUP` / `WM_DRAWITEM` / `WM_MEASUREITEM` / `WM_MENUCHAR` for owner-drawn submenus (such as "Send to"). The return value is an LRESULT
`Items()`	Returns the target of this menu as a `FolderItems`

2.1 Arguments of InvokeCommand

Argument	Content
`fMask`	`CMIC_MASK_*` (`CMINVOKECOMMANDINFOEX.fMask`). If a string parameter cannot be represented in ANSI, `CMIC_MASK_UNICODE` is added internally
`hwnd`	The parent window (normally `te.hwnd`)
`Verb`	If it is a number, the command number in the menu (`idCmd - idCmdFirst`); if it is a string, a verb name (`"open"`, `"delete"`, `"properties"`, etc.)
`Parameters`	The parameter string (normally `null`)
`Directory`	The working directory. If it is `null` (or equivalent to omitted), the path of the current folder of the associated view is used. However, if that is not a folder on the file system, it is treated as if it had not been specified
`nShow`	`SW_*` (normally `SW_SHOWNORMAL`)
`dwHotKey`	The hot key (normally `0`)
`hIcon`	The icon handle (normally `0`)

Return value: when the command is executed, the HRESULT of IContextMenu::InvokeCommand (S_OK = 0 is success); on an exception, E_UNEXPECTED.
If the verb number is a number greater than 65535, the command is not executed and the return value is 0.
When a command whose verb name is mount is executed, the mount time is recorded internally (to refresh the drive display).
If te.OnInvokeCommand is set, OnInvokeCommand(ContextMenu, fMask, hwnd, Verb, Parameters, Directory, nShow, dwHotKey, hIcon) is called before execution. If its return value is S_OK (0), the default execution is not performed and InvokeCommand returns S_OK.

3. Properties

Name	Kind	Description
`hmenu`	P (read-only)	The `hMenu` passed to `QueryContextMenu`
`indexMenu`	P (read-only)	The `indexMenu` passed to `QueryContextMenu`
`idCmdFirst`	P (read-only)	The first command ID passed to `QueryContextMenu`
`idCmdLast`	P (read-only)	The last command ID passed to `QueryContextMenu`
`uFlags`	P (read-only)	The `CMF_*` flags passed to `QueryContextMenu`
`FolderView`	P (read-only)	The associated FolderView (the one set with the second argument of `api.ContextMenu` or with `FV.ViewMenu()`). Empty if there is none

Before QueryContextMenu is called, the five properties above (hmenu and the others) return 0.

Event	Description
`te.OnInvokeCommand`	Called before `InvokeCommand` is executed. As described above, returning `0` (`S_OK`) cancels the default execution
`te.OnShowContextMenu`	The event for when a context menu is shown. In the implementation in `sync1.js`, the arguments are `(Ctrl, hwnd, msg, wParam, pt, ContextMenu)`
`te.OnMenuMessage`	The event that receives menu messages. In the implementation in `sync1.js`, the arguments are `(Ctrl, hwnd, msg, wParam, lParam)` (it is used to update the status display and so on)

5. Constants

Defined in consts.js.

CMF_* (uFlags of QueryContextMenu) CMF_NORMAL = 0 / CMF_DEFAULTONLY = 1 / CMF_VERBSONLY = 2 / CMF_EXPLORE = 4 / CMF_NOVERBS = 8 / CMF_CANRENAME = 0x10 / CMF_NODEFAULT = 0x20 / CMF_INCLUDESTATIC = 0x40 / CMF_ITEMMENU = 0x80 / CMF_EXTENDEDVERBS = 0x100 / CMF_DISABLEDVERBS = 0x200 / CMF_ASYNCVERBSTATE = 0x400 / CMF_OPTIMIZEFORINVOKE = 0x800 / CMF_SYNCCASCADEMENU = 0x1000 / CMF_DONOTPICKDEFAULT = 0x2000

GCS_* (uFlags of GetCommandString) GCS_VERB = 4 / GCS_HELPTEXT = 5 / GCS_VALIDATE = 6 / GCS_VERBICON = 0x14

Others CMIC_MASK_HOTKEY / CMIC_MASK_ICON / CMIC_MASK_FLAG_NO_UI / CMIC_MASK_UNICODE / CMIC_MASK_NO_CONSOLE (fMask of InvokeCommand), SW_SHOWNORMAL = 1, TPM_RIGHTBUTTON = 2, TPM_RETURNCMD = 0x100 (pass to api.TrackPopupMenuEx to receive the selected command as the return value)

6. Examples

const FV = te.Ctrl(CTRL_FV);
const Items = FV.SelectedItems();

// 1. Create the menu for the selected items, show it, and execute
const ContextMenu = api.ContextMenu(Items, FV);
if (ContextMenu) {
    const hMenu = api.CreatePopupMenu();
    ContextMenu.QueryContextMenu(hMenu, 0, 1, 0x7FFF, CMF_NORMAL | CMF_CANRENAME);
    const pt = api.Memory("POINT");
    api.GetCursorPos(pt);
    const nVerb = api.TrackPopupMenuEx(hMenu, TPM_RIGHTBUTTON | TPM_RETURNCMD, pt.x, pt.y, te.hwnd, null, ContextMenu);
    if (nVerb) {
        ContextMenu.InvokeCommand(0, te.hwnd, nVerb - ContextMenu.idCmdFirst, null, null, SW_SHOWNORMAL, 0, 0);
    }
    api.DestroyMenu(hMenu);
}

// 2. Execute directly by verb name (without showing the menu)
const cm = api.ContextMenu(Items, FV);
const hm = api.CreatePopupMenu();
cm.QueryContextMenu(hm, 0, 1, 0x7FFF, CMF_NORMAL);   // QueryContextMenu is needed once before executing
cm.InvokeCommand(0, te.hwnd, "properties", null, null, SW_SHOWNORMAL, 0, 0);
api.DestroyMenu(hm);

// 3. Look up the verb name of a command
const verb = cm.GetCommandString(nVerb - cm.idCmdFirst, GCS_VERB);

HandleMenuMsg is used by script/sync1.js to initialize a submenu (such as "Send to") of the menu built with QueryContextMenu, by calling ContextMenu.HandleMenuMsg(WM_INITMENUPOPUP, hMenu, 0) before reading it.