Thumbnail Providers

Windows Vista makes greater use of file-specific thumbnail images than earlier versions of Microsoft Windows. Windows Vista uses them in all views, in dialogs, and for any file type that provides them. Other applications can consume your thumbnail as well. Thumbnail display has also changed. Now, a continuous spectrum of user-selectable sizes is available rather than the discrete sizes such as Icons and Thumbnails provided in Windows XP.

Note  You might hear these thumbnails refered to as Live Icons.

Thumbnails of 32-bit resolution and as large as 256x256 pixels are often used in Windows Vista user interface (UI). File format owners should be prepared to display their thumbnails at that size. They should also provide non-static images for their thumbnails that reflect the particular file's contents. For example, a text file's thumbnail should show a miniature version of the document, including its text.

The IThumbnailProvider interface has been introduced to make providing a thumbnail easier and more straightforward than in the past, when IExtractImage would have been used instead. Note, that existing code that uses IExtractImage is still valid under Windows Vista. However, IExtractImage is not supported in the Details pane.

This topic discusses the following:

• Thumbnail Processes
• Thumbnail Cache and Sizing
• Thumbnail Overlays
• Thumbnail Adornments
• Registering Your Thumbnail Provider
• Related Topics

Handlers, including thumbnail providers, run by default in a separate process. You can force the handler to run in-process by passing a NULL value as the bind context in a call to IShellItem::BindToHandler as shown here:

IShellItem::BindToHandler(NULL, BHID_ThumbnailHandler,..)

You can also opt out of running in-process by default by setting the DisableProcessIsolation entry in the registry as shown in this example. The class identifier (CLSID) {66742402-F9B9-11D1-A202-0000F81FEDEE} is the CLSID for IThumbnailProvider implementations.

HKEY_CLASSES_ROOT

CLSID

• {66742402-F9B9-11D1-A202-0000F81FEDEE}

When a thumbnail is needed, Windows first checks the thumbnail cache for the image. The thumbnail extractor is called if the image is not found in the cache. It is also called when the last modified time of the image is later than that of the copy in the cache.

The thumbnail images in this cache are stored in a set of discrete sizes. All sizes are given in pixels.

• 32x32
• 96x96
• 256x256
• 1024x1024

Note  These values are subject to change. You code should not assume that any particular size will always be used.

If an image is not square, you should not pad it yourself. Windows is responsible for respecting the original aspect ratio and padding the image to a square size.

When an image of a particular size is asked for, unless an exact match is found, Windows Vista always retrieves the next largest image and scales it down to the requested size. An image is never scaled up in size as was the case in previous versions of Windows.

The following table gives some examples of the relationship between requested size and available size.

You can declare a cutoff point as part of the file association entry in the registry. Below this size, thumbnails are not used.

HKEY_CLASSES_ROOT

• .fileextension

The ThumbnailCutoff entry is one of these REG_DWORD values.

High dots per inch (dpi) sensitivity means that the pixel dimensions of the thumbnail automatically adjust for the greater dpi. For instance, a 32x32 image at 96 dpi would be a 40x40 image at 120 dpi.

If the ThumbnailCutoff entry is not specified, the default cutoff is 20x20 (not dpi-sensitive).

Thumbnail overlays, a small image displayed over the lower right corner of the thumbnail, provide an opportunity for developers to apply brand identification to their thumbnails. Overlays are declared in the registry as part of the file association entry as shown here:

HKEY_CLASSES_ROOT

• .fileextension

The TypeOverlay entry contains a REG_SZ value interpreted as follows:

• If the value is a resource reference, such as ISVComponent.dll@,-155, that image is used as the overlay for files with that file name extension.
• If the value is an empty string, no overlay is applied to the image.
• If the value is not present, the default icon of the associated application is used.

Overlays for your thumbnails should only be provided through this mechanism and applied by Windows. Do not apply overlays yourself.

Adornments such as drop shadows are applied to thumbnails based on the user's currently selected theme. Adornments are provided by Windows; do not create them yourself. Windows could change the look of particular adornments at any time, so if you provided you own you would risk falling out of synch with the system. Your thumbnails could wind up looking dated or out of place.

Potential adornments are declared in the registry as part of the file association entry as shown here:

HKEY_CLASSES_ROOT

• .fileextension

The Treatment entry contains one of these REG_DWORD values:

A drop shadow is applied to images by default.

Registration of a thumbnail provider is based on standard file associations.

The GUID for the thumbnail handler Shell extension is E357FCCD-A995-4576-B01F-234630154E96.

• IThumbnailProvider
• Building Thumbnail Providers
• Thumbnail Provider Guidelines