Use Shell ContextMenu in your applications

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

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 object

scm.SetObjects (TEXT ("file:///c://">c:\\"));    

// 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 CWinApp derived class insert the following lines of code, that's neccessary otherwise not all shell contextmenu items would be shown.

// Initialize OLE 2.0 libraries

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

#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 the IContextMenu 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 object

void SetObjects (IShellFolder * psfFolder, LPITEMIDLIST pidlItem);
// relative PIDL and its parent IShellFolder interface

void 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 at ShowContextMenu 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. The CWnd 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 via ScreenToClient (...) before passing them to ShowContextMenu. So, what is ShowContextMenu doing? First it calls the GetContextMenu (...) to retrieve the IContextMenu interface (which is then stored in pContextMenu) 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 by pWnd 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 to HookWndProc (...) 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 with IContextMenu'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 the IContextMenu 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 its IContextMenu interface. nItems is the number of object that were passed in SetObjects (...) and m_pidlArray is an array of PIDLs that are relative to m_psfFolder (IShellFolder interface). Those PIDLs were 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 valid IContextMenu 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. HookWndProc checks for menu reletad messages and calls the IContextMenu's HandleMenuMsg. g_IContext2 and g_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 an CMINVOKECOMMANDINFO, 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

1. Added GetMenu () method which returns a CMenu pointer, so it is possible to freely customize the contextmenu before it is shown.
2. Added example project which demonstrates the use of CShellContextMenu, and also shows how to add those custom menu items and imitating a Windows Explorer-like listview.
3. Replaced the SHBindToParent function with a workaround implemention that is called SHBindToParentEx which does the same thing. That was neccessary because SHBindToParent isn't available on Windows 95/98 systems.
4. ANSI compiling supported. Before it only worked in UNICODE mode.
5. Fixed a bug, where CShellContextMenu caused an error when SetObjects (...) was called with a CStringArray that contained more then one file/folder.

April 10th, 2003

• April 10th, 2003 - Initial release.