Creating Icon Overlay Handlers / 创建图标标记 Handlers (翻译自MSDN) / VC++, Windows, DLL, ATL, COM
创建图标标记 Handlers
Creating Icon Overlay Handlers
图标标记是放在代表着某个 Shell 对象的图标之左下角的小图像。它们通常被加在一个对象的图标的身上来提供一些额外信息。例如，有个常见的图标标记是用来表示图标对应着一个链接而非真正的文件或文件夹的小箭头。除了系统提供的标准图标标记，用户还可以通过实现和注册一个图标标记 handler 来给特殊的 Shell 对象自定义图标标记。
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.
注意 系统能支持的不同图标标记数量受到系统图像列表中图标标记可用空间的限制。目前为图标标记分配了15个插槽，其中一些被系统所保留。因此，图标标记 handlers 应该只在现有选择无法令人满意的情况下采用。
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.
Creating Shell Extension Handlers 里讨论了实现和注册一个 Shell 拓展 handler 的普遍过程。这篇文档重点在于实现图标标记 handler 的方面。
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.
- 图标标记如何工作
- 注册图标标记 handler
- 实现图标标记 handler
- 实现 GetOverlayInfo
- 实现 GetPriority
- 实现 IsMemberOf
- How Icon Overlay Handlers Work
- Registering Icon Overlay Handlers
- Implementing Icon Overlay Handlers
- Implementing GetOverlayInfo
- Implementing GetPriority
- Implementing IsMemberOf
图标标记如何工作
How Icon Overlay Handlers Work
图标标记 handler 是与特定图标标记相关联的组件对象模型(COM)对象。 Shell 和 handler 之间的通信都通过 handler 的 IShellIconOverlayIdentifier 接口。
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.
当 Shell 启动时，所有的图标标记都会被 Shell 通过调用它们的以下两个 IShellIconOverlayIdentifier 方法来完成初始化：
When the Shell starts up, it initializes all icon overlay handlers by calling two of their IShellIconOverlayIdentifier methods:
- Shell 调用 IShellIconOverlayIdentifier::GetOverlayInfo 来获得 handler 的图标标记的位置。图标标记 handler 返回包含标记图像的文件的文件名以及它在文件中的索引。然后 Shell 将图标标记加入到系统图像列表中。
- The Shell calls IShellIconOverlayIdentifier::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.
- Shell 调用 IShellIconOverlayIdentifier::GetPriority 来确定图标标记的优先级。优先级值是从0到100的数字，100代表着最低优先级。如果为特定文件请求的图标标记超过一个，Shell 将根据这个值来帮助它决定显示哪个图标标记。
- The Shell calls IShellIconOverlayIdentifier::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.
在绘制一个对象的图标之前，Shell 将对象的名字传递给每个图标标记 handler 的 IShellIconOverlayIdentifier::IsMemberOf 方法。一个图标标记 handler 通常与特定的一组文件相关联。例如，图标标记 handler 可能会为某一文件类型的所有成员请求一个标记，比如文件拓展名为 .myp 的所有文件。如果一个 handler 想要让它的图标标记显示出来，他将返回 S_OK。然后 Shell 调用 handler 的 IShellIconOverlayIdentifier::GetOverlayInfo 方法来确定显示哪个图标。
Before painting an object's icon, the Shell passes the object's name to each icon overlay handler's IShellIconOverlayIdentifier::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 type, 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 IShellIconOverlayIdentifier::GetOverlayInfo method to determine which icon to display.
注意 图像一旦在初始化期间被载入系统图像列表，就不能被改变了。在初始化后，文件名和索引仅用来识别图标标记。系统不会载入新的图标标记。当 IShellIconOverlayIdentifier::GetOverlayInfo 被第一次调用时，你的 handler 必须返回和之前一样的文件名和索引。
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 IShellIconOverlayIdentifier::GetOverlayInfo is called, your handler must return the same file name and index that was specified when the function was first called.
尽管只能显示一个图标标记，但是一个对象可能会有来自超过一个 handler 的图标标记请求。在这种情况下 Shell 通过显示最高优先级的图标标记来解决冲突。Shell 通过一系列内置的规则解决了许多类似的冲突。如果这些规则不够充分，Shell 会在初始化期间比较 handler 的 IShellIconOverlayIdentifier::GetPriority 方法指定的优先级值。
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' IShellIconOverlayIdentifier::GetPriority method during initialization.
注册图标标记 Handler
Registering Icon Overlay Handlers
除了普通的 COM 注册，你还必须为该 handler 在这个键下创建一个子键。
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
将子键的默认值设置为该对象的类标识符（CLSID）GUID 的字符串形式。下面的例子展示了如何注册一个命名为 MyOverlay 的图标标记 handler。
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
(Default) = {MyOverlay CLSID GUID}
MyOverlay.rgs:
HKCR { NoRemove CLSID { ForceRemove {CB36C229-73C6-442E-926B-78FB1E8DB581} = s 'MyOverlay Class' { ForceRemove Programmable InprocServer32 = s '%MODULE%' { val ThreadingModel = s 'Apartment' } TypeLib = s '{914BCF58-3175-46D5-BE46-702284548A17}' Version = s '1.0' } } } HKLM { NoRemove SOFTWARE { NoRemove Microsoft { NoRemove Windows { NoRemove CurrentVersion { NoRemove Explorer { NoRemove ShellIconOverlayIdentifiers { ForceRemove 'MyOverlay' = s '{CB36C229-73C6-442E-926B-78FB1E8DB581}' { } } } } } } } }
实现图标标记 Handler
Implementing Icon Overlay Handlers
图标标记 handler 是进程内 COM 对象，作为 DLL 来实现。它除了 IUnknown 外还输出一个接口：IShellIconOverlayIdentifier。这个接口有三个方法：IShellIconOverlayIdentifier::GetOverlayInfo、IShellIconOverlayIdentifier::GetPriority和IShellIconOverlayIdentifier::IsMemberOf。
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: IShellIconOverlayIdentifier::GetOverlayInfo, IShellIconOverlayIdentifier::GetPriority, and IShellIconOverlayIdentifier::IsMemberOf.
实现 GetOverlayInfo
Implementing GetOverlayInfo
这个方法在初始化期间被第一次调用。该方法会返回包含了图标标记图像的文件的完全有效的路径，以及文件中基于0的索引。然后 Shell 将图像加入到系统图像列表中。图标标记可以被任何标准文件类型的文件所包含，包括 .exe、.dll、.ico。
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.
在初始化完成后，当 Shell 需要显示handler的图标标记时，将会调用 IShellIconOverlayIdentifier::GetOverlayInfo。该方法应该返回与初始化期间一样的文件名和索引。尽管 Shell 是使用系统图像列表中缓存的图像而不是从文件中载入，图标标记仍然由它的文件名和索引来标识。
After initialization is complete, the Shell calls IShellIconOverlayIdentifier::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.
实现 GetPriority
Implementing GetPriority
该方法仅在初始化期间被调用。它为handler的图标标记赋予优先级值。该值的范围是从0到100，其中100是最低优先级。这个优先级值的目的在于帮助 Shell 解决当多个图标标记指定到一个对象时产生的冲突。 Shell 一开始使用一系列规则来确定最高优先级的图标标记。如果这些规则不能解决冲突，那么 IShellIconOverlayIdentifier::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 IShellIconOverlayIdentifier::GetPriority determine priority.
IShellIconOverlayIdentifier::GetPriority 设置的优先级值并不是一个可靠的方式来解决两个不相关的图标标记之间的冲突。你的 handler 无法确定其他 handler 在使用什么优先级值。通常情况下，你应该将值设为0。然而，当你为同一个对象实现了两个或更多图标标记 handler 时，优先级值是十分有用的。通过适当地设置优先级值，你可以指定哪个被请求的图标标记将被显示。
The priority value set by IShellIconOverlayIdentifier::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.
实现 IsMemberOf
Implementing IsMemberOf
Shell 调用该方法来确定是否应该为一个特定对象显示一个 handler 的图标标记。它通过传递它的名字给该方法来指定对象。如果一个 handler 希望它的图标标记被显示，IShellIconOverlayIdentifier::IsMemberOf 返回 S_OK。如果不，返回S_FALSE。
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, IShellIconOverlayIdentifier::IsMemberOf returns S_OK. If not, it returns S_FALSE.
图标标记 handler 通常试图与特定的一组文件一起工作。一个典型的例子就是由特定的文件拓展名标识的文件类型。一个图标标记 handler 可以为该文件类型的所有文件请求一个图标标记。有些 handler 仅当该类型的一个文件处于某种特定状态时请求一个图标标记。然而，图标标记 handler 可以自由地为任意它们想要的对象请求图标标记。
Icon overlay handlers are normally intended to work with a particular group of files. A typical example is a file type, identified by a specific file name extension. An icon overlay handler can request an icon overlay for all files of the file type. Some handlers request an icon overlay only if a file of the file type is in a particular state. However, icon overlay handlers are free to request their icon overlay for any object that they want.
Send comments about this topic to Microsoft
Build date: 4/28/2010
—————————————————————————————————————
本文翻译自MSDN，图片及代码为本人原创，如需转载请注明出处。
