\nYou might wonder why\n\nthe \nThe reason is to support something which I will call “compositing”.\n<\/P>\n \nYou may have multiple context menu extensions that you want to\ncombine into one giant context menu extension. The shell does this\nall over the place. For example, the context menu we have been\nplaying with all this time is really a composite of several\nindividual context menu extensions: the static registry verbs\nplus all the COM-based extensions like “Send To”, “Open With”,\nand anything else that may have been added by a program you installed\n(like a virus checker).\n<\/P>\n \nSo before we can write a compositor, we need to \nhave a second context menu to composite. Here’s a quickie that\nimplements two commands, let’s call them “Top” and “Next” for lack\nof anything interesting to do.\n<\/P>\n \/\/ *** IContextMenu ***\n STDMETHODIMP QueryContextMenu(HMENU hmenu,\n UINT indexMenu, UINT idCmdFirst,\n UINT idCmdLast, UINT uFlags);\n STDMETHODIMP InvokeCommand(\n LPCMINVOKECOMMANDINFO lpici);\n STDMETHODIMP GetCommandString(\n UINT_PTR idCmd,\n UINT uType,\n UINT * pwReserved,\n LPSTR pszName,\n UINT cchMax);<\/p>\n static HRESULT Create(REFIID riid, void **ppv);<\/p>\n private:\n CTopContextMenu() : m_cRef(1), m_cids(0) { }<\/p>\n private:\n HRESULT ValidateCommand(UINT_PTR idCmd, BOOL fUnicode,\n UINT *puOffset);\n HRESULT Top(LPCMINVOKECOMMANDINFO lpici);\n HRESULT Next(LPCMINVOKECOMMANDINFO lpici);<\/p>\n private:\n ULONG m_cRef;\n UINT m_cids;\n};\n<\/PRE>\n \nThe class declaration isn’t particularly interesting. We\nare not owner-draw so we don’t bother implementing\n \nFirst, some basic paperwork for getting off the ground.\n \nWe have two commands. Instead of hard-coding the numbers\n \nAnd here’s a table that we’re going to use to help us manage\nthese two commands.\n<\/P>\n \nOur \nNext come the boring parts of a COM object:\n<\/P>\n *ppv = punk;\n if (punk) {\n punk->AddRef();\n return S_OK;\n } else {\n return E_NOINTERFACE;\n }\n}<\/p>\n ULONG CTopContextMenu::AddRef()\n{\n return ++m_cRef;\n}<\/p>\n ULONG CTopContextMenu::Release()\n{\n ULONG cRef = –m_cRef;\n if (cRef == 0) delete this;\n return cRef;\n}\n<\/PRE>\n \nFinally, we get to something interesting:\n if ((int)(idCmdLast – idCmdFirst + 1) >= TOPCMD_MAX &&\n !(uFlags & CMF_DEFAULTONLY)) {\n InsertMenu(hmenu, indexMenu + TOPCMD_TOP, MF_BYPOSITION,\n idCmdFirst + TOPCMD_TOP, TEXT(“Top”));\n InsertMenu(hmenu, indexMenu + TOPCMD_NEXT, MF_BYPOSITION,\n idCmdFirst + TOPCMD_NEXT, TEXT(“Next”));\n m_cids = TOPCMD_MAX;\n }<\/p>\n return MAKE_HRESULT(SEVERITY_SUCCESS, 0, m_cids);\n}\n<\/PRE>\n \nIn order to implement the next few methods, we need to have\nsome culture-invariant comparison functions.\n<\/P>\n int strcmpiW_invariant(LPCWSTR psz1, LPCWSTR psz2)\n{\n return CompareStringW(LOCALE_INVARIANT, NORM_IGNORECASE,\n psz1, -1, psz2, -1) – CSTR_EQUAL;\n}\n<\/PRE>\n \nThese are like the strcmpi functions except that they\nuse the invariant locale since they will be used to compare\ncanonical strings rather than strings that are meaningful to\nan end user.\n(More discussion here in MSDN<\/A>.)\n<\/P>\n \nNow we have enough to write a helper function which is\ncentral to the context menu: Figuring out which command\nsomebody is talking about.\n<\/P>\n \nCommands can be passed to the if (idCmd < m_cids) {\n *puOffset = (UINT)idCmd;\n return S_OK;\n }<\/p>\n return E_INVALIDARG;\n}\n<\/PRE>\n \nThis helper function takes a “something” parameter in the\nform of a \nAfter the (possibly failed) conversion to an ordinal, the\nordinal is checked for validity; if valid, then the ordinal\nis returned back for further processing.\n<\/P>\n \nWith this helper function the implementation of the other methods\nof the \nWe continue with the CMINVOKECOMMANDINFOEX* lpicix = (CMINVOKECOMMANDINFOEX*)lpici;\n BOOL fUnicode = lpici->cbSize >= sizeof(CMINVOKECOMMANDINFOEX) &&\n (lpici->fMask & CMIC_MASK_UNICODE);\n UINT idCmd;\n HRESULT hr = ValidateCommand(fUnicode ? (UINT_PTR)lpicix->lpVerbW\n : (UINT_PTR)lpici->lpVerb,\n fUnicode, &idCmd);\n if (SUCCEEDED(hr)) {\n switch (idCmd) {\n case TOPCMD_TOP: hr = Top(lpici); break;\n case TOPCMD_NEXT: hr = Next(lpici); break;\n default: hr = E_INVALIDARG; break;\n }\n }\n return hr;\n}\n<\/PRE>\n \nHere is a case where the “Are there three cases or four?” question\nlands squarely on the side of “four”. There are two forms of the\n \nIf the structure is \nThis means that there are indeed four scenarios:\n<\/P>\n \nAfter figuring out whether the parameter is ANSI or Unicode,\nwe ask \nFailing to implement string-based command invocation is an\nextremely common oversight in context menu implementations.\nDoing so prevents people from invoking\nyour verbs programmatically.\n<\/P>\n \n“Why should I bother to let\npeople invoke my verbs programmatically?”\n<\/P>\n \nBecause if you don’t,\nthen people won’t be able to write programs like the one we are\ndeveloping in this series of articles! For example, suppose\nyour context menu extension lets people “Frob” a file. If you\ndon’t expose this verb programmability, then it is impossible to write\na program that, say, takes all the files modified in the last\ntwenty-four hours and Frobs them.\n<\/P>\n \n(I’m always amused by the people who complain\nthat Explorer doesn’t expose enough customizability\nprogrammatically,\nwhile simultaneously not providing the same degree of\nprogrammatic customizability\nin their own programs.)\n<\/P>\n \nOh wait, I guess I should implement those two operations.\nThey don’t do anything particularly interesting.\n<\/P>\n HRESULT CTopContextMenu::Next(LPCMINVOKECOMMANDINFO lpici)\n{\n MessageBox(lpici->hwnd, TEXT(“Next”), TEXT(“Title”), MB_OK);\n return S_OK;\n}\n<\/PRE>\n \nThe remaining method is\n switch (uType) {\n case GCS_VERBA:\n lstrcpynA(pszName, c_rgciTop[id].pszNameA, cchMax);\n return S_OK;<\/p>\n case GCS_VERBW:\n lstrcpynW((LPWSTR)pszName, c_rgciTop[id].pszNameW, cchMax);\n return S_OK;<\/p>\n case GCS_HELPTEXTA:\n lstrcpynA(pszName, c_rgciTop[id].pszHelpA, cchMax);\n return S_OK;<\/p>\n case GCS_HELPTEXTW:\n lstrcpynW((LPWSTR)pszName, c_rgciTop[id].pszHelpW, cchMax);\n return S_OK;<\/p>\n case GCS_VALIDATEA:\n case GCS_VALIDATEW:\n return S_OK; \/\/ all they wanted was validation\n }<\/p>\n return E_NOTIMPL;\n}\n<\/PRE>\n \nHere again we use the\n \nIf the command is not valid, then we propagate the error code,\nexcept in the \nIf the command is valid, we return the requested\ninformation, which is handled by a simple \nOkay, now that we have this context menu, we can even test it\nout a little bit. Throw out the changes from\n\npart 9<\/A>\nand return to the program as it was in\n\npart 6<\/A>, making the following change to the\n IContextMenu *pcm;\n if (SUCCEEDED(CTopContextMenu::Create(<\/FONT>\n IID_IContextMenu, (void**)&pcm))) {\n …\n<\/PRE>\n \nWe now obtain our context menu not by calling\nthe \nWhen you run this program, observe that even the help text works.\n<\/P>\n \nAh, one of the powers of operating with interfaces rather than\nobjects: You can swap out the object and the rest of the code\ndoesn’t even realize what happened, so long as the interface stays\nthe same.\n<\/P>\n \nOkay, today was a long day spent just laying groundwork,\njust writing what has to be written. No breakthroughs,\nno “aha” moments, just typing. Read the method, understand\nwhat you have to do, and do it.\n<\/P>\nIContextMenu<\/CODE> interface<\/A>\noperates on menu identifier offsets so much\nrather than with the menu identifiers themselves.\n<\/P>\n\nclass CTopContextMenu : public IContextMenu\n{\npublic:\n \/\/ *** IUnknown ***\n STDMETHODIMP QueryInterface(REFIID riid, void **ppv);\n STDMETHODIMP_(ULONG) AddRef();\n STDMETHODIMP_(ULONG) Release();<\/p>\nIContextMenu2<\/A><\/CODE> or\nIContextMenu3<\/A><\/CODE>.\n<\/P>\n\nHRESULT CTopContextMenu::Create(REFIID riid, void **ppv)\n{\n *ppv = NULL;\n HRESULT hr;\n CTopContextMenu *self = new CTopContextMenu();\n if (self) {\n hr = self->QueryInterface(riid, ppv);\n self->Release();\n } else {\n hr = E_OUTOFMEMORY;\n }\n return hr;\n}\n<\/PRE>\n0<\/CODE> and 1<\/CODE>,\nlet’s give them nice names.\n<\/P>\n\n#define TOPCMD_TOP 0\n#define TOPCMD_NEXT 1\n#define TOPCMD_MAX 2\n<\/PRE>\n
\nconst struct COMMANDINFO {\n LPCSTR pszNameA;\n LPCWSTR pszNameW;\n LPCSTR pszHelpA;\n LPCWSTR pszHelpW;\n} c_rgciTop[] = {\n { “top”, L”top”,\n “The top command”, L”The top command”, }, \/\/ TOPCMD_TOP\n { “next”, L”next”,\n “The next command”, L”The next command”, },\/\/ TOPCMD_NEXT\n};\n<\/PRE>\nTOPCMD_*<\/CODE>\nvalues conveniently double as indices into the\nc_rgciTop<\/CODE> array.\n<\/P>\n\nHRESULT CTopContextMenu::QueryInterface(REFIID riid, void **ppv)\n{\n IUnknown *punk = NULL;\n if (riid == IID_IUnknown) {\n punk = static_cast<IUnknown*>(this);\n } else if (riid == IID_IContextMenu) {\n punk = static_cast<IContextMenu*>(this);\n }<\/p>\nIContextMenu::QueryContextMenu<\/A><\/CODE>.\nThings to watch out for in the code below:\n<\/P>\n\n
idCmdFirst<\/CODE> and\n idCmdLast<\/CODE> is complicated by the fact that\n idCmdLast<\/CODE> is\n endpoint-inclusive<\/STRONG>, which forces a strange +1<\/CODE>.\n Another reason to\n \n prefer endpoint-exclusive ranges<\/A>.\nCMF_DEFAULTONLY<\/CODE> flag is set, then we don’t bother\n adding our menu items since none of our options is the default\n menu item.\n<\/UL>\n\nHRESULT CTopContextMenu::QueryContextMenu(\n HMENU hmenu, UINT indexMenu, UINT idCmdFirst,\n UINT idCmdLast, UINT uFlags)\n{\n m_cids = 0;<\/p>\n\nint strcmpiA_invariant(LPCSTR psz1, LPCSTR psz2)\n{\n return CompareStringA(LOCALE_INVARIANT, NORM_IGNORECASE,\n psz1, -1, psz2, -1) – CSTR_EQUAL;\n}<\/p>\nIContextMenu<\/CODE> interface either\n(a) by ordinal or by name, and either (b) as ANSI or\nas Unicode. This counts as either three ways or four ways,\ndepending on whether you treat “ANSI as ordinal” and “Unicode\nas ordinal” as the same thing or not.\n<\/P>\n\nHRESULT CTopContextMenu::ValidateCommand(UINT_PTR idCmd,\n BOOL fUnicode, UINT *puOffset)\n{\n if (!IS_INTRESOURCE(idCmd)) {\n if (fUnicode) {\n LPCWSTR pszMatch = (LPCWSTR)idCmd;\n for (idCmd = 0; idCmd < TOPCMD_MAX; idCmd++) {\n if (strcmpiW_invariant(pszMatch,\n c_rgciTop[idCmd].pszNameW) == 0) {\n break;\n }\n }\n } else {\n LPCSTR pszMatch = (LPCSTR)idCmd;\n for (idCmd = 0; idCmd < TOPCMD_MAX; idCmd++) {\n if (strcmpiA_invariant(pszMatch,\n c_rgciTop[idCmd].pszNameA) == 0) {\n break;\n }\n }\n }\n }<\/p>\nUINT_PTR<\/CODE> and a flag that indicates whether that\n“something” is ANSI or Unicode. The function itself checks\nwhether the “something” is a string or an ordinal. If a string,\nthen it converts that string into an ordinal by looking for\nit in the table of commands in the appropriate character set\nand using a locale-insensitive comparison.\nNotice that if the string is not found, then\nidCmd<\/CODE> is left equal to TOPCMD_MAX<\/CODE>,\nwhich is an invalid value (and therefore is neatly handled\nby the fall-through).\n<\/P>\nIContextMenu<\/CODE> interface are a lot easier.\n<\/P>\nIContextMenu::InvokeCommand<\/CODE> method:\n\nHRESULT CTopContextMenu::InvokeCommand(\n LPCMINVOKECOMMANDINFO lpici) {<\/p>\nCMINVOKECOMMANDINFO<\/CODE> structure, the base structure (which is\nANSI-only) and the extended structure\nCMINVOKECOMMANDINFOEX<\/CODE> which adds Unicode support.\n<\/P>\nCMINVOKECOMMANDINFOEX<\/CODE> and the\nCMIC_MASK_UNICODE<\/CODE> flag is set, then the Unicode fields\nof the CMINVOKECOMMANDINFOEX<\/CODE> structure should be used\nin preference to the ANSI ones.\n<\/P>\n\n
lpVerb<\/CODE> member.\nlpVerb<\/CODE> member.\nlpVerbW<\/CODE> member.\nlpVerbW<\/CODE> member.\n<\/OL>\nValidateCommand<\/CODE> to do the work of validating\nthe verb and converting it to an ordinal, at which point we use\nthe ordinal in a switch<\/CODE> statement to dispatch the\nactual operation.\n<\/P>\n\nHRESULT CTopContextMenu::Top(LPCMINVOKECOMMANDINFO lpici)\n{\n MessageBox(lpici->hwnd, TEXT(“Top”), TEXT(“Title”), MB_OK);\n return S_OK;\n}<\/p>\nIContextMenu::GetCommandString<\/CODE>, which is probably\nthe one people most frequently get wrong since the consequences of\ngetting it wrong are not immediately visible to the implementor.\nIt is the people who are trying to access the context menu\nprogrammatically who most likely to notice that the method isn’t\nworking properly.\n<\/P>\n\nHRESULT CTopContextMenu::GetCommandString(\n UINT_PTR idCmd,\n UINT uType,\n UINT * pwReserved,\n LPSTR pszName,\n UINT cchMax)\n{\n UINT id;\n HRESULT hr = ValidateCommand(idCmd, uType & GCS_UNICODE, &id);\n if (FAILED(hr)) {\n if (uType == GCS_VALIDATEA || uType == GCS_VALIDATEW) {\n hr = S_FALSE;\n }\n return hr;\n }<\/p>\nValidateCommand<\/CODE> method to do the hard work\nof validating the command, which is passed in the\nidCmd<\/CODE> parameter, with interpretive assistance\nin the GCS_UNICODE<\/CODE> flag of the uType<\/CODE>\nparameter.\n<\/P>\nGCS_VALIDATE<\/CODE> cases, where the documentation\nsays that we should return S_FALSE<\/CODE> to indicate that\nthe command is not valid.\n<\/P>\nswitch<\/CODE>\nstatement.\n<\/P>\nOnContextMenu<\/CODE> function:\n<\/P>\n\nvoid OnContextMenu(HWND hwnd, HWND hwndContext, int xPos, int yPos)\n{\n POINT pt = { xPos, yPos };\n if (pt.x == -1 && pt.y == -1) {\n pt.x = pt.y = 0;\n ClientToScreen(hwnd, &pt);\n }<\/p>\nGetUIObjectOfFile<\/CODE> function but rather\nby constructing a CTopContextMenu<\/CODE> object.\nSince our CTopContextMenu<\/CODE> implements\nIContextMenu<\/CODE>, all the remaining code can be\nleft unchanged.\n<\/P>\n