This tutorial demonstrates how to create a useful namespace extension using the set of classes in Objective Toolkit and Stingray namespace extension wizard. Every namespace must implement at least the IEnumIDList, IShellFolder and IShellView interfaces. Most namespaces also implement IContextMenu and IExtractIcon. Objective Toolkit has implementations for all of these classes, while the Stingray namespace extension wizard lays out the basic framework for how all these interfaces work together. Combining these two makes namespace development much easier.

To develop a namespace extension, we must deal with pointers to item ID list, such as PIDL, which involves dealing with the raw memory. This is the hard part of namespace extension development. To ease this, Stingray developers created the SECPidlMgr<T> template class, which encapsulates the complication.

In this tutorial, we use Objective Toolkit classes and the namespace extension wizard to create a light version of the WinView namespace extension, which was developed by Dino Esposito in his book Visual C++ Window Shell Programming. For serious shell and namespace extension development, this book is a must. As you will see, the framework created by our namespace wizard makes the development much easier.

The first step is to create a skeleton namespace extension project as follows:

Now you can compile and register the namespace extension we just created. After the compilation is done, you can open Explorer and your namespace extension NSExtComp will show up under the Desktop node. Figure 167 demonstrates what it looks like.

The Wizard generates five classes for our namespace extension: CNSExtComp, CNSExtCompEnum, CNSExtCompIcon, CNSExtCompMenu, and CNSExtCompView.

As we mentioned before, only CNSExtComp, CNSExtCompEnum and CNSExtCompView are required for a namespace extension. As documented in the shell SDK, the Explorer starts to interact with our namespace extension COM object through the IShellFolder interface. Through this interface, Explorer obtains IEnumIDList and IShellView interfaces. The relationship of IEnumIDList to IShellView in the namespace extension is very similar to that of CDocument to CView in standard doc/view application, with IEnumIDList behaving as a kind of document and IShellView behaving as a view.

The CNSExtCompEnum class extends the SECIEnumIDListImpl template class and implements the CreateEnumIDList() method. The first step in extending the skeleton namespace extension is to add a meaningful implementation for this virtual function. The base class has a variable, m_pPidlMgr, that is a pointer to our PIDL manager class. The PIDL manager is derived from SECPidlMgr template class. All the PIDL should be created and freed using the PIDL manager; the PIDL manager in turn uses the IMallc interface from the shell to manage the memory. This class is responsible for creating the PIDL list for the namespace extension. The framework requires that our CNSExtCompEnum class have a default constructor. When Explorer asks IShellFolder for IEnumIDList interface, the framework creates a new instance of IEnumIDList implementation class, and immediately calls CreateEnumIDList() once, passing the PIDL and some flags to this functions, and then returns the interface IEnumIDList to Explorer if the CreateEnumIDList() has succeeded.

The CNSExtCompView class extends the SECIShellViewImpl template class. This class must have a constructor with two arguments; the first argument is a pointer to the IShellFolder interface and the second argument is a pointer to PIDL. When Explorer calls the CreateViewObject() method of IShellFolder interface, the framework creates a new instance of our IShellView implementation class with the IShellFolder pointer and the PIDL, then returns the interface to Explorer if everything is all right. CNSExtCompView is responsible for providing a view window to the Explorer shell, so it is derived from CWindowImpl class as well. Generally, we should handle the WM_CREATE() and WM_SIZE() messages to create a child window, such as a list view to display our folder contents, and resize the child window. Then we can pass all other messages to the base class for further processing. The example CNSExtCompView class uses a CListView as child window; this window is held in the m_listView member. You can use any other kind of child window. The base class SECIShellViewImpl saves the argument IShellFolder into a smart pointer and makes a copy of the argument PIDL.

The CNSExtComp class simplifies registration by extending the SECIShellFolderImpl class and using the ATL COM object implementation. Our SECIShellFolderImpl class takes four template arguments. The first one is our final implementation class, the second is our IShellView implementation class, the third is our IEnumIDList implementation class, and the last one is our PIDL manager class. Since we chose to support IExtractIcon and IContextMenu when we run the namespace extension wizard, the wizard added some code into the GetUIObject() method to inform the caller(i.e. Explorer) that we support these optional interfaces.

Since we have chosen to support two optional interfaces, IContextMenu and IExtractIcon, the wizard also generated classes for each of these two interface implementations. CNSExtCompIcon basically just initializes its base class; CNSExtCompMenu contains the command map definition and some sample code demonstrating adding menu items to the context menu and adding a menu command. The command map cannot be removed, even you don’t have any command items inside.

If we had chosen to support other optional interfaces, the wizard would have generated the corresponding implementation classes.

Now let us begin to make our skeleton namespace extension functional. First, we have to decide what data to put into the PIDL. Since Explorer doesn’t know anything of our data, it just passes the data around as PIDL. We must therefore package our data completely into a PIDL. The data in the PIDL cannot be pointers that point to some other data outside the PIDL. For this tutorial, we will use the following structure.

Go to NSExtComp.h and change the following structure into our new data structure.

After changing the data structure, you must also make two other changes. One of them is the #define immediately following the structure.

You should change the above line to the following:

The second change is in the CreateEnumIDList() function of CNSExtCompEnum class. You should remove the code that uses the old data structure.

Since we are going to enumerate windows, we need a helper data structure for the enumeration. Let’s add the following global data structure at the top of NSExtComp.h.

After that, we need to change the implementation of CreateEnumIDList(). The new implementation should be similar to the following.

One important point to notice is that when you use the CreateItem() function of SECPidlMgr class, you need to package the data into an SECPidlData structure and pass the structure to CreateItem() function together with the actual size of the data. If you look at the implementation of CreateItem(), you will see that it copies the block of data passed into it. To complete the implementation of CreateEnumIDList()), we need another static member function for the EnumChildWindow() method. The implementation of CreateEnumIDListHelper() follows.

The last change we need to make is in the InitList() method of CNSExtCompView class. The old data structure is used in this method.

Let’s first make the simplest change to this method by changing one line of code to use our new data structure instead of the old one. The change is in bold text.

After we recompile and register the namespace, it will look something like Figure 168 in the Explorer.

Notice that a context menu for the node appears in the left pane of Explorer, because we chose to support context menus when we ran the wizard. The wizard generated two sample context menu items for us. The default handler displays the menu item ID in a message box.

If you want the menu command to do meaningful things, you can override the CommandHandler() method of SECIContextMenuImpl class in the CNSExtCompMenu class; see the sample code shown inside the comment of this class. As you can see, the SECIContextMenuImpl class hides all the complications of context menu implementation. All you have to do is to add the menu item into the existing command map. You give the menu item text, help string, and the menu item ID, and then override the CommandHandler() method to look for your menu ID to decide what to do. It is really simple and easy. Please note that the context menu on the right pane is the responsibility of CNSExtCompView. You have to handle the WM_CONTEXTMENU() message and draw the context menu.

To make it more interesting, perform the following modification to the InitList() method.

Now if we recompile and register the namespace extension, it looks something similar to the following image in the Explorer.

The node name in the left pane of Explorer should be more informative. To correct this, we need to override the GetPidlName() method of SECIShellFolderImpl() method in the CNSExtComp class. The default implementation of this function displays the first byte data of the PIDL corresponding to the node as a binary. Let’s override GetPidlName() in CNSExtComp and change the code to the following.

Since we know the data in each item is a window handle, we should display the window’s class name, or, if it has a title, the combination of class name and title. If the handle is NULL, it means we are at the top node, which we know it is the desktop window. After we recompile, the namespace looks like Figure 171.

As we saw before, the context menu didn’t do anything other than display the corresponding menu item ID. In order to make the context menu useful, we have to override the CommandHandler() function. Let’s uncomment the CommandHandler() method in the CNSExtCompMenu class generated by our wizard. Assume we want to display the information about the node the mouse right-clicked on. For this tutorial, we want to display the Windows class name and the window handle as binary data. In order for our context menu to display information about the clicked node, we need to save the PIDL for the node passed to us by Explorer when it requested the IContextMenu interface in the GetUIObject() method of IShellFolder. The PIDL is available from our class CNSExtCompMenu in the GetUIObject() method. GetUIObject() also saves the owner window handle into our class. This window handle can be used when we want to display a dialog box or message box inside our CNSExtCompMenu implementation code. The implementation of CommandHandler() is listed below.

This function makes uses the GetPidlName() method, which we can copy from CNSExtComp. The m_pPidlmember is in our base class. Now when you right-click any node and select one of the two menu items, the message box will display the relevant information for this node. The context menu is shown in Figure 172.

The last thing we are going to do is to give the node our own icon. The default implementation of SECIExtractIconImpl gives every node a small Windows logo icon. To provide a different icon for the node on the left pane, we have to override the Extract() function of IExtractIcon interface. First, add a small icon into our project and name the icon ID to IDI_ICONNODE, as shown in Figure 173.

Then we change the default implementation of Extract() method in CNSExtCompIcon class to the following:

The completed namespace is shown in Figure 174.

That’s all for this tutorial. You can add more features to the namespace extension, such as modifying the menu of Explorer, adding toolbars into Explorer, and displaying status text. We strongly recommend the excellent reference Visual C++ Windows Shell Programming by Dino Esposito, published by Wrox Press, as well as the MSDN.