IShellIconOverlay interface (shlobj_core.h)

Exposes methods that are used by a namespace extension to specify icon overlays for the objects it contains.

Inheritance

The IShellIconOverlay interface inherits from the IUnknown interface. IShellIconOverlay also has these types of members:

Methods

The IShellIconOverlay interface has these methods.

Remarks

Icon overlays are small images placed at the lower-left corner of the icon that represents a Shell object. They are typically used to add some extra information to the icon. A commonly used icon overlay is the small arrow that indicates that a file or folder icon represents a shortcut.

Icon overlays are part of the system image list. They have two identifiers. One is a one-based overlay index that identifies the overlay relative to other overlays in the image list. The other is an image index that identifies the actual image. These two indexes are equivalent to the values that you assign to the iOverlay and iImage parameters, respectively, when you add an icon overlay to a private image list with ImageList::SetOverlayImage.

Before displaying the icon for an object, the Shell calls the associated folder's IShellIconOverlay interface to query whether the object's icon should have an overlay. Typically it calls IShellIconOverlay::GetOverlayIndex to request the overlay's overlay index. In some cases, the Shell might call IShellIconOverlay::GetOverlayIconIndex to request the overlay's image index. To specify an icon overlay, the methods must return the requested index. Otherwise, they return S_FALSE.

To specify an icon overlay, both methods must first retrieve the overlay's overlay index in the system image list by calling SHGetIconOverlayIndex. When SHGetIconOverlayIndex is called for the first time, the Shell uses the overlay's file name and index within the file to add the image to the system image list. Once an overlay is in the system image list, the Shell simply uses the file name and index as an identifier. You can also use SHGetIconOverlayIndex to retrieve the overlay index of several standard system overlays. IShellIconOverlay::GetOverlayIndex simply returns the overlay index to the Shell. IShellIconOverlay::GetOverlayIconIndex must use the INDEXTOOVERLAYMASK macro to convert the overlay index to the equivalent image index.

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 overlays should be specified only if there are no satisfactory alternatives.

This interface is implemented by namespace extensions that need to specify icon overlays for their objects.

This interface is not typically used by applications.

Requirements