ITaskbarList3::SetOverlayIcon 方法 (shobjidl_core.h)

将覆盖应用于任务栏按钮,以指示应用程序状态或给用户的通知。

语法

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

参数

[in] hwnd

类型:HWND

其关联任务栏按钮接收覆盖的窗口的句柄。 此句柄必须属于与按钮的应用程序关联的调用进程,并且必须是有效的 HWND ,否则调用将被忽略。

[in] hIcon

类型: HICON

要用作覆盖的图标的句柄。 这应该是一个小图标,分辨率为 16x16 像素,分辨率为 96 dpi。 如果覆盖图标已应用于任务栏按钮,则会替换现有覆盖。

此值可以为 NULL如何处理 NULL 值取决于任务栏按钮是表示单个窗口还是一组窗口。

  • 如果任务栏按钮表示单个窗口,则会从显示中删除覆盖图标。
  • 如果任务栏按钮表示一组窗口,并且上一个覆盖层仍可用, (早于当前覆盖接收,但尚未被 null 值) 释放,则显示上一个覆盖来代替当前覆盖。

调用应用程序负责在不再需要 hIcon 时释放 hIcon 。 这通常可以在调用 SetOverlayIcon 后完成,因为任务栏创建并使用其自己的图标副本。

[in] pszDescription

类型: LPCWSTR

指向字符串的指针,该字符串提供覆盖所传达信息的替换文字版本,以提供辅助功能。

返回值

类型: HRESULT

如果该方法成功,则返回 S_OK。 否则,将返回 HRESULT 错误代码。

注解

在 Windows 7 之前的 Windows 版本中,应用程序通常使用任务栏通知区域中的图标向用户显示应用程序状态和通知。 Windows 7 任务栏允许应用程序通过其任务栏按钮提供相同类型的用户反馈,将更多应用程序信息集中到一个位置。 这些覆盖类似于用于快捷图标或安全通知的现有覆盖,显示在按钮右下角。

下图显示了一个覆盖 (绿色小方块,指示用户状态为“可用”) 应用于最右侧的任务栏按钮。

带有覆盖的 Windows Messenger 任务栏按钮的屏幕截图,指示“可用”状态 图标覆盖用作状态的上下文通知,旨在无需单独的通知区域状态图标即可向用户传达该信息。 应用程序设计器必须在开发周期中决定哪种方法(图标覆盖或通知区域状态图标)最适合该应用程序。 覆盖图标旨在提供重要的长期状态或通知,例如网络状态、信使状态或新邮件。 它们不应频繁更改,也不应对其进行动画处理。

若要显示覆盖图标,任务栏必须处于默认的大图标模式。 如果通过 任务栏和“开始”菜单属性配置任务栏 以显示小图标,则无法应用覆盖并忽略对此方法的调用。

由于单个覆盖应用于任务栏按钮而不是单个窗口缩略图,因此这是按组而不是每个窗口的功能。 可以从任务栏组中的各个窗口接收覆盖图标的请求,但它们不会排队。 最后收到的覆盖层是显示的覆盖。 如果删除了上次收到的覆盖,则只要它仍然处于活动状态,它所替换的覆盖就会还原。 例如,Windows 1、2 和 3 按顺序设置覆盖 A、B 和 C。由于覆盖 C 是最后收到的,因此它显示在任务栏按钮上。 Window 2 调用具有 NULL 值的 SetOverlayIcon 以删除覆盖 B。然后,窗口 3 执行相同的操作以删除覆盖 C。由于窗口 1 的覆盖 A 仍然处于活动状态,因此该覆盖随后会显示在任务栏按钮上。

如果 Windows 资源管理器意外关闭,则还原 Windows 资源管理器时不会还原覆盖。 应用程序应等待接收指示 Windows 资源管理器已重启且已重新创建任务栏按钮的 TaskbarButtonCreated 消息,然后再次调用 SetOverlayIcon 以重新应用覆盖。

要求

要求
最低受支持的客户端 Windows 7 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 [仅限桌面应用]
目标平台 Windows
标头 shobjidl_core.h (包括 Shobjidl.h)
Library Explorerframe.lib
DLL Explorerframe.dll

另请参阅

ITaskbarList

ITaskbarList2

ITaskbarList3

任务栏扩展