Use Shell ContextMenu in your applications

Roman Engels, 15 May 2003

   4.94 (40 votes)

Rate this:

A class that makes it easy to use the Shell Context Menu (aka Explorer Contextmenu) in your own applications

• Download source files - 5 Kb
• Download Demo files - 59 Kb

<!-- Article image -->

<!-- Add the rest of your HTML here -->

Introduction

This article explains how to use my self-written CShellContextMenu class which makes it possible to use the shell contextmenu in your own application (the one that shows if you right-click on an object in the Windows Explorer).

Why CShellContextMenu

I have a lot of projects in which i work with files/folders. So I wanted to use the common shell contextmenu for those. Microsoft put a wonderful example on how to achieve this in their Platform SDK, called EnumDesk. But since not all people understand Shell interfaces and the code should be reusable, I wrapped things up in a C++ class. I also did some google-searching to get some good ways of implementing this. The class hides all the interface-related stuff; you can either use normal file system paths (f. ex. c:\windows) or PIDLs to obtain the shell contextmenu. So here it this, the CShellContextMenu class which makes it easy as hell to use the shell contextmenu.

CShellContextMenu scm;        // instantiate class objectscm.SetObjects (TEXT ("<A href="file:///c://">c:\\</A>"));    // we whant shellcontext menu for drive c:\ scm.ShowContextMenu (this, point);    // point is a CPoint objects which indicates where the contextmenu should // be shown this refers to a MFC-window class (showcontextmenu needs that // to set the owner window)

There's just one other importing thing you have to do. In your InitInstance () function of your CWinAppderived class insert the following lines of code, that's neccessary otherwise not all shell contextmenu items would be shown.

// Initialize OLE 2.0 librariesif (!AfxOleInit ()){    AfxMessageBox (TEXT ("Unable to load OLE 2.0 libraries!"));    return (FALSE);}

and put the following #include statement in your project's stdafx.h file.

#include <afxole.h>    // for OLE

That's all you need to pop-up the shell contextmenu for drive C. CShellContextMenu also supports multiple files/folders. Just pass an CStringArray to CShellContextMenu::SetObjects () and you'll get a contextmenu which refers to all the items specified in that array. That corresponds to selecting multiple objects in Windows Explorer and than right-click on the selection. Keep in mind that if you pass multiple files/folder/shell objects, they have to be all in the same folder. This is no limitation of CShellContextMenu, rather then how theIContextMenu interface is implemented in the Windows Shell. CShellContextMenu also works with PIDLs. If you don't know what PIDLs are then it won't matter, cause CShellContextMenu handles the stuff for you. I would also suggest that you have a look at SetObjects (...) and the other functions to get a better grab to shell interfaces. The source code is also heavily commented, so with MSDN at hand there shouldn't be any problems.

How CShellContextMenu works

Let's have an inside look in CShellContextMenu and see what it really does under the hood to obtain that handy shell contextmenu.

First take a look at those SetObjects (...) methods.

void SetObjects (CString strObject);// one file system path (file/folder)void SetObjects (CStringArray &strArray);// array of multiple file system paths (files/folders)void SetObjects (LPITEMIDLIST pidl);// full qualified PIDL of shell objectvoid SetObjects (IShellFolder * psfFolder, LPITEMIDLIST pidlItem);// relative PIDL and its parent IShellFolder interfacevoid SetObjects (IShellFolder * psfFolder, LPITEMIDLIST * pidlArray,                  int nItemCount);// array of multiple relative PIDLs and their parent IShellFolder interface

With the SetObjects (...) you tell CShellContextMenu for which objects (file/folder/shell object) you wish to have the contextmenu. For people who don't know how to handle PIDLs or if your program just works with usual file system paths I implemented two overriden methods of SetObjects (...) that accept a CString or a CStringArray as argument and CShellContextMenu converts the given file system path(s) into PIDLs and retrieves its IShellFolder interface. That's neccessary because the IContextMenu interface is only accessable via the IShellFolder interface which only takes PIDLs as an argument. Now we take some in-depths look atShowContextMenu which actually does the work.

UINT CShellContextMenu::ShowContextMenu(CWnd *pWnd, CPoint pt){    int iMenuType = 0;        // to know which version of IContextMenu is supported    LPCONTEXTMENU pContextMenu;        // common pointer to IContextMenu and higher version interface       if (!GetContextMenu ((void**) &pContextMenu, iMenuType))            return;    // something went wrong    if (!m_Menu)    {        delete m_Menu;        m_Menu = NULL;        m_Menu = new CMenu;        m_Menu->CreatePopupMenu ();    }    // lets fill the our popupmenu      pContextMenu->QueryContextMenu (m_Menu->m_hMenu,                   m_Menu->GetMenuItemCount(),0, MIN_ID, MAX_ID, CMF_EXPLORE);     // subclass window to handle menurelated messages in CShellContextMenu     WNDPROC OldWndProc;    if (iMenuType > 1)    // only version 2 and 3 supports menu messages    {        OldWndProc = (WNDPROC) SetWindowLong (pWnd->m_hWnd,                 GWL_WNDPROC, (DWORD) HookWndProc);        if (iMenuType == 2)            g_IContext2 = (LPCONTEXTMENU2) pContextMenu;        else// version 3            g_IContext3 = (LPCONTEXTMENU3) pContextMenu;    }    else        OldWndProc = NULL;    UINT idCommand = Menu.TrackPopupMenu (TPM_RETURNCMD | TPM_LEFTALIGN,                                           pt.x, pt.y, pWnd);        if (OldWndProc) // unsubclass        SetWindowLong (pWnd->m_hWnd, GWL_WNDPROC, (DWORD) OldWndProc);    // see if returned idCommand belongs to shell menu entries    if (idCommand >= MIN_ID && idCommand <= MAX_ID)    {   //executes related command        InvokeCommand (pContextMenu, idCommand - MIN_ID);            idCommand = 0;    }    pContextMenu->Release();    g_IContext2 = NULL;    g_IContext3 = NULL;    return (idCommand);}

As you can see ShowContextMenu takes a pointer to a CWnd object and a CPoint object as arguments. TheCWnd pointer is needed for later subclassing and CPoint is used to determine at which position the contextmenu should be shown. Note that these are screen coordinates. So, if you have client coordinates convert them viaScreenToClient (...) before passing them to ShowContextMenu. So, what is ShowContextMenu doing? First it calls the GetContextMenu (...) to retrieve the IContextMenu interface (which is then stored inpContextMenu) associated with the objects passed in SetObjects (...). The GetContextMenu is explained afterwards. What we now have to do, is to determine which version of IContextMenu we have. That's neccessary because if we have a IContextMenu higher than version 1, we need to handle the WM_DRAWITEM, WM_MEASUREITEM and WM_INITMENUPOPUP messages. These message are send to the window pointed to bypWnd which is passed in ShowContextMenu's argument list. That's the point where window subclassing comes in handy. All we have to do, is to redirect the window's default window procedure (the function which handles all the messages belonging to a window). With SetWindowLong (...) we set the new window procedure toHookWndProc (...) which is a static member function of CShellContextMenu.

Let's again take a look at the code. After we have a pointer to the IContextMenu interface we create a popup menu with CMenu's CreatePopuMenu () method. The next thing is, we let our popup menu fill withIContextMenu's QueryContextMenu (...) method. This method has four parameters. The first is the handle to the popupmenu which should be filled with the shell menu items. The second is the menu position where it starts. This could be useful because before you let the menu be filled you can insert additional menu items which are specific to your program. Therefore the 3rd and 4th parameters. They specify the lowest and highest command ID that QueryContextMenu (...) should use to fill the menu. That means, that command IDs which are below or above that range, are for you own additional menu items. CShellContextMenu has support for adding custom menus. Just call the GetMenu () method to retrieve a CMenu pointer to the popupmenu. With this you can customize the menu as you like. After that, go on as usual and call ShowContextMenu (...). The 5th parameter uses the flag CMF_EXPLORE to indicate that we want the same items that Window Explorer shows in its contextmenu. Then we subclass pWnd and redirect all messages to HookWndProc (...), but only if theIContextMenu is Version 2 or 3. With CMenu's TrackPopupMenu (...) we show the contextmenu, and store the command ID of the selected menu item in idCommand. Then we test idCommand if its between MIN_ID and MAX_ID, if so it means that a shell menu item was clicked and not one we manually inserted (btw. those constants are defined in ShellContextMenu.cpp, change them to your needs if you wish to). If its a shell menu item we call CShellContextMenu::InvokeCommand (...) which executes the appriorate command that belongs to a shell menu item and release the IContextMenu interface with pContextMenu->Release ()

Here's GetContextMenu which retrieves the highest version of IContextMenu available to the given objects.m_psfFolder is an IShellFolder interface, via its GetUIObjectsOf method we get version 1 of itsIContextMenu interface. nItems is the number of object that were passed in SetObjects (...) andm_pidlArray is an array of PIDLs that are relative to m_psfFolder (IShellFolder interface). Those PIDLswere also passed in SetObjects (...) or if you passed a file system paths CShellContextMenu has automatically retrieved the corresponding PIDLs and the IShellFolder interface. If we have a validIContextMenu interface we try to get version 3, if that fails we test for version 2 and if that too fails we stay with version 1. And that's all.

BOOL CShellContextMenu::GetContextMenu (void ** ppContextMenu,int & iMenuType){    *ppContextMenu = NULL;    LPCONTEXTMENU icm1 = NULL;        // first we retrieve the normal IContextMenu     // interface (every object should have it)    m_psfFolder->GetUIObjectOf (NULL, nItems, (LPCITEMIDLIST *) m_pidlArray,                 IID_IContextMenu, NULL, (void**) &icm1);       if (icm1)    {    // since we got an IContextMenu interface we can         // now obtain the higher version interfaces via that        if (icm1->QueryInterface(IID_IContextMenu3, ppContextMenu) == NOERROR)            iMenuType = 3;        else if (icm1->QueryInterface (IID_IContextMenu2,                                        ppContextMenu) == NOERROR)            iMenuType = 2;        if (*ppContextMenu)             icm1->Release();     // we can now release version 1 interface,                     // cause we got a higher one        else         {                iMenuType = 1;            *ppContextMenu = icm1;    // since no higher versions were found        }  // redirect ppContextMenu to version 1 interface    }    else        return (FALSE);    // something went wrong        return (TRUE); // success}

That's the alternative window procedure that is only used while the contextmenu is being showed. HookWndProcchecks for menu reletad messages and calls the IContextMenu's HandleMenuMsg. g_IContext2 andg_IContext3 are global pointers, they are pointing to IContextMenu2 and IContextMenu3 interfaces of the contextmenu that is currently being showed. It's neccessary to have a global variable because HookWndProc is a static member function and static member functions have no this pointer, therefore it cannot access its class member variables and functions. The HookWndProc must be static because a non-static member function has always an additional this pointer, and therefore its argument list wouldn't match that of a window procedure. At the end of HookWndProc we call the original WndProc to avoid undefined behaviour of the associated window. The original WndProc is retrieved via the GetProp () API function. Refer to the MSDN for further informations on this API function.

LRESULT CALLBACK CShellContextMenu::HookWndProc (HWND hWnd, UINT message,                         WPARAM wParam, LPARAM lParam){   switch (message)   {    case WM_MENUCHAR:// only supported by IContextMenu3       if (g_IContext3)       {           LRESULT lResult = 0;           g_IContext3->HandleMenuMsg2 (message, wParam, lParam, &lResult);           return (lResult);       }       break;   case WM_DRAWITEM:   case WM_MEASUREITEM:      if (wParam)           break; // if wParam != 0 then the message is not menu-related     case WM_INITMENUPOPUP:       if (g_IContext2)           g_IContext2->HandleMenuMsg (message, wParam, lParam);       else// version 3           g_IContext3->HandleMenuMsg (message, wParam, lParam);      return (message == WM_INITMENUPOPUP ? 0 : TRUE); // inform caller that                         // we handled WM_INITPOPUPMENU by ourself      break;   default:      break;   }   // call original WndProc of window to prevent undefined bevhaviour   // of window   return ::CallWindowProc ((WNDPROC) GetProp ( hWnd, TEXT ("OldWndProc")),              hWnd, message, wParam, lParam);}

This little function is also very important. Without it the shell context menu would also show correctly with all the expected menu items, but it would do just nothing if you'd click on an item. So, all this function does is fill anCMINVOKECOMMANDINFO, set its lpVerb member to the idCommand (command ID of the clicked menu item) and calls the IContextMenu's InvokeCommand method, which finally executes the command that belongs to the menu item that was clicked.

void CShellContextMenu::InvokeCommand (LPCONTEXTMENU pContextMenu,                                        UINT idCommand){    CMINVOKECOMMANDINFO cmi = {0};    cmi.cbSize = sizeof (CMINVOKECOMMANDINFO);    cmi.lpVerb = (LPSTR) MAKEINTRESOURCE (idCommand);    cmi.nShow = SW_SHOWNORMAL;        pContextMenu->InvokeCommand (&cmi);}

Summary

So, that's the whole thing behind the shell contextmenu. Wasn't that hard was it?  Shell interfaces are not that difficult like they seem to be on the first look. One problem with them is that they are not well documented in the MSDN. So with a little work and some google-searching everything's possible. Before I began working with that shell context menu I didn't know much about the Shell. I did use a lot of shell functions like SHGetFileInfo and such stuff, but no real shell interfaces, PIDLs and such. Now I'm able to produce a full Windows Explorer alternative with the shell interfaces. That's not a very hard thing to do.

I hope the article is good to understand, because English is not my native language. On the other hand, it's my first development related article ever.  So hey, I think it's good enough for that.

What comes next?

I hope the example project covers CShellContextMenu fairly well, so you'll know how to use it. It also demonstrates how to add custom app-specific menu item< to the contextmenu before it is shown and shows how to imitate the right-pane listview of Windows Explorer (in a simple way). The active project configuration is set to ANSI compiling, but everything also works in UNICODE mode, which is also included as a project configuration. I'm also considering providing CListCtrl and CTreeCtrl derived classes which imitate those in Windows Explorer. But this could still be a long way ahead, because while writing this article I noticed that it's really an exhausting task, harder than actually programming  . There is already 2 or 3 article about that on codeproject.com, but I've noticed that those examples/classes are totally overblown, and therefore the source codes of those are almost impossible to follow and understand.

History