An application implements a context menu handler interface, IContextMenu, to add menu items to the context menu for a file object. The shell displays the object's context menu when the user clicks the object with mouse button 2. The menu items can be either class-specific (that is, applicable to all files of a particular type) or instance-specific (that is, applicable to an individual file).
When the user clicks a file object by using mouse button 2, the system passes the address of the object's context menu to the context menu handler, which should use the handle only to add items to the menu. The handler should not delete or modify existing menu items, because other handlers may add items either before or after it does. In addition, the shell adds items to the menu after all context menu handlers have been called.
Context menu handlers are entered in the registry under the shellex key within an application's information area. The ContextMenuHandlers key lists the names of subkeys that contain the CLSID of each context menu handler. An example showing the ContextMenuHandlers key follows.
ContextMenuHandlers
{00000000-1111-2222-3333-00000000000001}
You can register multiple context menu handlers for a file type.
In addition to the standard IUnknown member functions, the context menu handler interface uses the QueryContextMenu, InvokeCommand, and GetCommandString member functions.
When the user selects one of the menu items added by a context menu handler, the shell calls the handler's IContextMenu::InvokeCommand member function to let the handler process the command. If multiple context menu handlers are registered for a file type, the value of the ContextMenuHandlers key determines the order of the commands.
When the system is about to display a context menu (or the File menu on the menu bar) for a file object, the system calls the context menu handler's QueryContextMenu member function. The context menu handler inserts menu items by position (MF_POSITION) directly into the context menu by calling the InsertMenu function. The following example shows that menu items must be string items (MF_STRING).
STDMETHODIMP CShellExt::QueryContextMenu(HMENU hMenu,
UINT indexMenu, UINT idCmdFirst, UINT idCmdLast, UINT uFlags)
{
UINT idCmd = idCmdFirst;
char szMenuText[64];
char szMenuText2[64];
char szMenuText3[64];
char szMenuText4[64];
BOOL bAppendItems=TRUE;
if ((uFlags & 0x000F) == CMF_NORMAL) {
lstrcpy(szMenuText, "&New .GAK menu 1, Normal File");
lstrcpy(szMenuText2, "&New .GAK menu 2, Normal File");
lstrcpy(szMenuText3, "&New .GAK menu 3, Normal File");
lstrcpy(szMenuText4, "&New .GAK menu 4, Normal File");
} else if (uFlags & CMF_VERBSONLY) {
lstrcpy(szMenuText, "&New .GAK menu 1, Shortcut File");
lstrcpy(szMenuText2, "N&ew .GAK menu 2, Shortcut File");
lstrcpy(szMenuText3, "&New .GAK menu 3, Shortcut File");
lstrcpy(szMenuText4, "&New .GAK menu 4, Shortcut File");
} else if (uFlags & CMF_EXPLORE) {
lstrcpy(szMenuText, "&New .GAK menu 1,
Normal File right click in Explorer");
lstrcpy(szMenuText2, "N&ew .GAK menu 2,
Normal File right click in Explorer");
lstrcpy(szMenuText3, "&New .GAK menu 3,
Normal File right click in Explorer");
lstrcpy(szMenuText4, "&New .GAK menu 4,
Normal File right click in Explorer");
} else if (uFlags & CMF_DEFAULTONLY) {
bAppendItems = FALSE;
} else {
char szTemp[32];
bAppendItems = FALSE;
}
if (bAppendItems) {
InsertMenu(hMenu, indexMenu++, MF_SEPARATOR | MF_BYPOSITION,
0, NULL);
InsertMenu(hMenu, indexMenu++, MF_STRING | MF_BYPOSITION,
idCmd++, szMenuText);
InsertMenu(hMenu, indexMenu++, MF_SEPARATOR | MF_BYPOSITION,
0, NULL);
InsertMenu(hMenu, indexMenu++, MF_STRING | MF_BYPOSITION,
idCmd++, szMenuText2);
InsertMenu(hMenu, indexMenu++, MF_SEPARATOR | MF_BYPOSITION,
0, NULL);
InsertMenu(hMenu, indexMenu++, MF_STRING | MF_BYPOSITION,
idCmd++, szMenuText3);
InsertMenu(hMenu, indexMenu++, MF_STRING | MF_BYPOSITION,
idCmd++, szMenuText4);
// Must return the number of menu items added.
return ResultFromShort(idCmd-idCmdFirst);
}
return NOERROR;
}
The system calls the InvokeCommand member function when the user selects a menu item that the context menu handler added to the context menu. The InvokeCommand function in the following example handles the commands associated with the menu items added by the previous example.
STDMETHODIMP CShellExt::InvokeCommand(LPCMINVOKECOMMANDINFO lpcmi)
{
HRESULT hr = E_INVALIDARG;
// If the high-order word of lpcmi->lpVerb is not NULL, this
// function was called by an application and lpVerb is a command
// that should be activated. Otherwise, the shell has called this
// function, and the low-order word of lpcmi->lpVerb is the
// identifier of the menu item that the user selected.
if (!HIWORD(lpcmi->lpVerb)) {
UINT idCmd = LOWORD(lpcmi->lpVerb);
switch (idCmd) {
case 0:
hr = DoGAKMenu1(lpcmi->hwnd, lpcmi->lpDirectory,
lpcmi->lpVerb, lpcmi->lpParameters, lpcmi->nShow);
break;
case 1:
hr = DoGAKMenu2(lpcmi->hwnd, lpcmi->lpDirectory,
lpcmi->lpVerb, lpcmi->lpParameters, lpcmi->nShow);
break;
case 2:
hr = DoGAKMenu3(lpcmi->hwnd, lpcmi->lpDirectory,
lpcmi->lpVerb, lpcmi->lpParameters, lpcmi->nShow);
break;
case 3:
hr = DoGAKMenu4(lpcmi->hwnd, lpcmi->lpDirectory,
lpcmi->lpVerb, lpcmi->lpParameters, lpcmi->nShow);
break;
}
}
return hr;
}
Windows calls the GetCommandString member function to get a language-independent command string or the help text for a context menu item.