Export (0) Print
Expand All

Adding Icons, Previews and Shortcut Menus

To ensure that your data is indexed and presented correctly to the user during searches, you need to implement Shell data stores (also known as Shell Namespace Extensions), and file type handlers (also known as Shell extensions, extension handlers, or Shell extension handlers).

This topic describes the following interfaces:

Implementing File Type Handlers

These Shell extensions or file type handlers provide your users with the following Shell experiences:

  • The results view displays a specific icon for your item type.
  • The results view displays a preview of the item when the user selects the item.
  • Users can double-click items to initiate events such as opening the file.
  • Users can right-click items to access a shortcut (context) menu.
  • Users can drag-and-drop items.

Like all Component Object Model (COM) objects, file type handlers must implement an IUnknown interface and a class factory.

In Windows XP or earlier, handlers should also implement:

In Windows Vista, IPersistFile Interface and IShellExtInit Interface were replaced by the following three interfaces for Shell to initialize the handler:

To provide a reasonable user experience you must provide a Shell data store with your protocol handler. That data store then serves as the "factory" for icon handlers, shortcut menu handlers, preview handlers, and so forth. Minimal implementations of IPersist Interface and IPersistFolder Interface are required by IShellFolder Interface, and a minimal implementation of IShellFolder Interface is required for the IContextMenu and IExtractIcon.

Note  The same class identifier (CLSID) should be implemented for IPersist, IPersistFolder and IShellFolder.

For more information about creating a Shell data store to support a protocol handler, see Implementing the Basic Folder Object Interfaces.


The IPersist interface defines the single method GetClassID, which is designed to supply the CLSID of an object that can be stored persistently in the system.

GetClassIDReturns the CLSID of the Shell data store object



The IPersistFolder interface is used to initialize Shell folder objects. Implementation of this interface, which is derived from IPersist, is how the folder is told where it is in the Shell namespace. You do not use this interface directly. It is used by the file system implementation of IShellFolder::BindToObject Method when it initializes a Shell folder object.

InitializeInstructs a Shell folder object to initialize itself based on the information passed and returns S_OK



The IShellFolder Interface interface is used to manage folders, and a partial implementation is required so that the icon and context interfaces implemented for a protocol handler will behave correctly in the Windows Search results user interface. Most of the functionality required is exposed through the GetUIObjectOf method. This method enables an add-in to query for the IExtractIcon and IContextMenu interfaces.

The IShellFolder Interface interface uses PIDLs instead of URLs. In contrast to the requirements of a complete Shell data store, add-ins can use a simple IDL structure that contains only the URL.

The following methods of IShellFolder Interface must be implemented. Five of these methods require minimal implementation.

BindToObjectReturns E_NOTIMPL
BindToStorageReturns E_NOTIMPL
CreateViewObjectReturns E_NOTIMPL
SetNameOfReturns E_NOTIMPL
ParseDisplayNameConverts a URL to the PIDL structure
CompareIDsCompares two PIDL values
GetDisplayNameOfReturns the URL for a PIDL
GetUIObjectOfThis method is similar to the IUnknown::QueryInterface Method. If an icon is requested, the caller requests the IID_IExtractIcon; if a shortcut menu is requested, the caller requests the IID_IContextMenu


IShellFolder is not used to enumerate folders. This means that the display name of a folder will be the physical URL. This may change in the future.


When Windows Search displays results to the user, the user can right-click an item and see a shortcut menu defined by your IContextMenu interface. Shortcut menus are also known as context menus.

The default action on the context menu is the same action taken when the item is double-clicked. Without the corresponding IShellFolder or IContextMenu interfaces for the item, the default behavior for a double-click event is to pass the URL as an argument to the ShellExecute Function function.

Refer to Creating Context Menu Handlers for more information on creating shortcut menu handlers, and Sample: Shell Extensions for Protocol Handlers for sample code.


IExtractIcon retrieves an icon for the Windows Search user interface based on the URL in the PIDL provided by your protocol handler.

Refer to Creating Icon Handlers for more information on creating icon handlers and Sample: Shell Extensions for Protocol Handlers for sample code.


The IPreviewHandler renders a rich preview of a selected item in Windows Explorer. Previews are available in Windows Search 4.0, or in Windows Vista with Windows Desktop Search 3.x.

To create a custom preview handler:

  1. Implement an IPreviewHandler that takes an IStream, following the guidelines provided in Preview Handlers.
  2. Register your preview handler:



       @ = {<Your_PreviewHandler_GUID>}
  3. Complete the following two steps to implement a Shell folder for your URL:
    1. In IShellFolder::GetUIObjectOf Method, handle IQueryAssociations and return your association for your Shell items, as shown in the following code sample.

      CComPtr<IQueryAssociations> spqa;
      AssocCreate(CLSID_QueryAssociations, __uuidof(IQueryAssociations), &spqa);
      spqa->Init(0, L"Your_Object_Type", NULL, NULL);
      spqa->QueryInterface(riid, ppvReturn);
    2. After the Shell queries your Shell folder for the data stream to initialize the preview handler, go to your IShellFolder::BindToObject Method method, handle IID_IStream and return an IStream to your URL.

To reuse an existing preview handler for your file type, follow these two steps:

  1. Register that preview handler for your file type using the CLSID of the existing preview handler in place of <Your_PreviewHandler_GUID>.
  2. Implement a Shell folder.

For more information on creating preview handlers, see IPreviewHandler and Preview Handlers.

Additional Resources

Related topics

Developing Protocol Handlers
Understanding Protocol Handlers
Notifying the Index of Changes
Code Sample: Shell Extensions for Protocol Handlers
Installing and Registering Protocol Handlers
Creating a Search Connector for a Protocol Handler
Debugging Protocol Handlers



Community Additions

© 2014 Microsoft