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
  • IPersist
  • IPersistFolder
  • IShellFolder
  • IContextMenu
  • IExtractIcon
  • IPreviewHandler
• Additional Resources
• Related topics

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:

• Either IPersistFile Interface
• Or IShellExtInit Interface

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

• IInitializeWithStream Interface
• IInitializeWithItem Interface
• IInitializeWithFile Interface

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.

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

IPersist

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.

IPersistFolder

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.

IShellFolder

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.

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.

IContextMenu

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

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.

IPreviewHandler

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:

   HKEY_CLASSES_ROOT\<Your_Object_Type>
   

   HKEY_CLASSES_ROOT\<Your_Object_Type>\ShellEx
   

   HKEY_CLASSES_ROOT\<Your_Object_Type>\ShellEx\{8895b1c6-b41f-4c1c-a562-0d564250836f}
      @ = {<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

• For an overview of the indexing process, see The Indexing Process.
• For information about creating handlers, see Registering Shell Extensions, Creating Shell Extension Handlers, Context Menu, Shell Namespace Extensions and Preview Handlers.

Related topics

Conceptual

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