Partager via

Creating Icon Overlay Handlers

  • Article

Icon overlays are small images placed at the lower-left corner of the icon that represents a Shell object. They are normally added to an object's icon to provide some extra information. For instance, a commonly used icon overlay is the small arrow that indicates that the icon represents a link, rather than the actual file or folder. In addition to the standard icon overlays that are provided by the system, you can request custom icon overlays for specified Shell objects by implementing and registering an icon overlay handler.

Note   The number of different icon overlay handlers that the system can support is limited by the amount of space available for icon overlays in the system image list. There are currently fifteen slots allotted for icon overlays, some of which are reserved by the system. For this reason, icon overlay handlers should be implemented only if there are no satisfactory alternatives.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to icon overlay handlers.

  • How Icon Overlay Handlers Work
  • Registering Icon Overlay Handlers
  • Implementing Icon Overlay Handlers

How Icon Overlay Handlers Work

Icon overlay handlers are Component Object Model (COM) objects that are associated with a particular icon overlay. All communication between the Shell and the handler takes place through the handler's IShellIconOverlayIdentifier interface.

When the Shell starts up, it initializes all icon overlay handlers by calling two of their IShellIconOverlayIdentifier methods:

  • The Shell calls GetOverlayInfo to request the location of the handler's icon overlay. The icon overlay handler returns the name of the file containing the overlay image, and its index within that file. The Shell then adds the icon overlay to the system image list.
  • The Shell calls GetPriority to determine the icon overlay's priority. The priority value is a number from zero to 100, with 100 indicating the lowest priority. If more than one icon overlay is requested for a particular file, the Shell uses this value to help it determine which icon overlay to display.

Before painting an object's icon, the Shell passes the object's name to each icon overlay handler's IsMemberOf method. An icon overlay handler is normally associated with a particular group of files. For example, the icon overlay handler might request an overlay for all members of a file class, such as all files with an .myp file name extension. If a handler wants to have its icon overlay displayed, it returns S_OK. The Shell then calls the handler's GetOverlayInfo method to determine which icon to display.

Note   Once the image has been loaded into the system image list during initialization, it cannot be changed. After initialization, the file name and index are used only to identify the icon overlay. The system will not load a new icon overlay. When GetOverlayInfo is called, your handler must return the same file name and index that was specified when the function was first called.

Although only one icon overlay can be displayed, it is possible for an object to have icon overlays requested by more than one handler. In that case, the Shell resolves the conflict by displaying the highest priority icon overlay. The Shell resolves many such conflicts with an internal set of rules. If these rules are not sufficient, the Shell compares the priority values that were specified by the handlers' GetPriority method during initialization.

Registering Icon Overlay Handlers

In addition to normal COM registration, you must also create a subkey named for the handler under this key.

HKEY_LOCAL_MACHINE

Software

Microsoft

Windows

CurrentVersion

Explorer

  • ShellIconOverlayIdentifiers

Set the default value of the subkey to the string form of the object's class identifier (CLSID) GUID. The following example illustrates how to register an icon overlay handler named MyOverlay.

HKEY_LOCAL_MACHINE

Software

Microsoft

Windows

CurrentVersion

Explorer

ShellIconOverlayIdentifiers

  • MyOverlay

Implementing Icon Overlay Handlers

Icon overlay handlers are in-process COM objects, implemented as DLLs. They export one interface in addition to IUnknown: IShellIconOverlayIdentifier. This interface has three methods: GetOverlayInfo, GetPriority, and IsMemberOf.

Implementing GetOverlayInfo

This method is first called during initialization. The method returns the fully qualified path of the file containing the icon overlay image, and its zero-based index within the file. The Shell then adds the image to the system image list. Icon overlays can be contained in any of the standard file types, including .exe, .dll, and .ico.

After initialization is complete, the Shell calls GetOverlayInfo when it needs to display the handler's icon overlay. The method should return the same file name and index that it did during initialization. Although the Shell uses the image that is cached in the system image list rather than loading the image from the file, an icon overlay is still identified by its file name and index.

Implementing GetPriority

This method is called only during initialization. It assigns a priority value to the handler's icon overlay. The value can range from zero to 100, where 100 is the lowest priority. The purpose of this priority value is to help the Shell resolve the conflict that arises when multiple icon overlays are specified for a single object. The Shell first uses an internal set of rules to determine the highest priority icon overlay. If these rules do not resolve the conflict, the values assigned to the icon overlays by GetPriority determine priority.

The priority value set by GetPriority is not a reliable way to resolve conflicts between unrelated icon overlay handlers. There is no way for your handler to determine what priority values other handlers are using. Normally, you should set the value to zero. However, the priority value is useful when you have implemented two or more icon overlay handlers that can request icon overlay icons for the same object. By setting the priority values appropriately, you can specify which of the requested icon overlays will be displayed.

Implementing IsMemberOf

The Shell calls this method to determine whether it should display a handler's icon overlay for a particular object. It specifies the object by passing its name to the method. If a handler wants to have its icon overlay displayed, IsMemberOf returns S_OK. If not, it returns S_FALSE.

Icon overlay handlers are normally intended to work with a particular group of files. A typical example is a file class, identified by a specific file name extension. An icon overlay handler can request an icon overlay for all members of the file class. Some handlers request an icon overlay only if a member of the file class is in a particular state. However, icon overlay handlers are free to request their icon overlay for any object that they want.