Shell_NotifyIconA 函数 (shellapi.h)

项目
03/01/2024

将消息发送到任务栏的状态区域。

语法

BOOL Shell_NotifyIconA(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAA lpData
);

参数

[in] dwMessage

类型：DWORD

一个值，该值指定要由此函数执行的操作。可以具有以下一个值：

NIM_ADD (0x00000000)

0x00000000。将图标添加到状态区域。图标在 lpdata 所指向的 NOTIFYICONDATA 结构中提供一个标识符（通过其 uID 或 guidItem 成员）。此标识符用于对 Shell_NotifyIcon 的后续调用，以便对图标执行后续操作。

NIM_MODIFY (0x00000001)

0x00000001。修改状态区域中的图标。 lpdata 指向的 NOTIFYICONDATA 结构在添加到通知区域时使用最初分配给图标的 ID (NIM_ADD) 来标识要修改的图标。

NIM_DELETE (0x00000002)

0x00000002。从状态区域中删除图标。 lpdata 指向的 NOTIFYICONDATA 结构在添加到通知区域时使用最初分配给图标的 ID (NIM_ADD) 标识要删除的图标。

NIM_SETFOCUS (0x00000003)

0x00000003。仅Shell32.dll 版本 5.0 及更高版本。将焦点返回到任务栏通知区域。通知区域图标在完成 UI 操作后应使用此消息。例如，如果图标显示快捷菜单，但用户按 ESC 将其取消，请使用 NIM_SETFOCUS 将焦点返回到通知区域。

NIM_SETVERSION (0x00000004)

0x00000004。仅Shell32.dll 版本 5.0 及更高版本。指示通知区域根据 lpdata 指向的结构的 uVersion 成员中指定的版本号运行。版本号指定可识别的成员。

每次 (NIM_ADD) 添加通知区域图标时，都必须调用NIM_SETVERSION。无需使用 NIM_MODIFY 调用它。用户注销后，不会保留版本设置。

有关详细信息，请参见“备注”部分。

[in] lpData

类型： PNOTIFYICONDATA

指向 NOTIFYICONDATA 结构的指针。结构的内容取决于 dwMessage 的值。它可以定义图标以添加到通知区域，使该图标显示通知，或者标识要修改或删除的图标。

返回值

类型： BOOL

如果成功，则返回 TRUE ，否则返回 FALSE 。如果 dwMessage 设置为 NIM_SETVERSION，则如果成功更改版本，则函数返回 TRUE ;如果不支持请求的版本，则返回 FALSE 。

注解

从 Windows 2000 (Shell32.dll 版本 5.0) 开始，如果将 lpdata 指向的 NOTIFYICONDATA 结构的 uVersion 成员设置为 NOTIFYICON_VERSION_4 或更高版本，Shell_NotifyIcon鼠标和键盘事件的处理方式与早期版本的 Windows 不同。差异包括以下内容：

如果用户使用键盘选择通知图标的快捷菜单，Shell 现在会向关联的应用程序发送 WM_CONTEXTMENU 消息。早期版本发送 WM_RBUTTONDOWN 和 WM_RBUTTONUP 消息。
如果用户使用键盘选择通知图标并使用空格键或 ENTER 键激活它，则 5.0 版 Shell 会向关联的应用程序发送NIN_KEYSELECT通知。早期版本发送 WM_RBUTTONDOWN 和 WM_RBUTTONUP 消息。
如果用户使用鼠标选择通知图标并使用 Enter 键激活它，则 Shell 现在会向关联的应用程序发送NIN_SELECT通知。早期版本发送 WM_RBUTTONDOWN 和 WM_RBUTTONUP 消息。

从 Windows XP (Shell32.dll 版本 6.0) 起，如果用户将鼠标指针传递到与气球通知关联的图标上，Shell 将发送以下消息：

NIN_BALLOONSHOW。显示气球时发送 (气球排队) 。
NIN_BALLOONHIDE。气球消失时发送。例如，删除图标时。如果气球因超时而关闭，或者用户单击鼠标，则不会发送此消息。
从 Windows 7 开始，当设置了 NIIF_RESPECT_QUIET_TIME 标志的通知尝试在用户在新计算机上的第一小时) (安静时间显示时，也会发送NIN_BALLOONHIDE。在这种情况下，从不显示气球。
NIN_BALLOONTIMEOUT。当气球因超时而消除时发送。
NIN_BALLOONUSERCLICK。由于用户单击鼠标而关闭气球时发送。

除了这些消息，从 Windows Vista (Shell32.dll 版本 6.0.6) 开始，如果用户将鼠标指针传递到与气球通知关联的图标上，Windows Vista Shell 还会添加以下消息：

NIN_POPUPOPEN。当用户将光标悬停在图标上以指示应使用更丰富的弹出 UI 来代替标准文本工具提示时发送。
NIN_POPUPCLOSE。当光标不再悬停在图标上以指示应关闭丰富弹出 UI 时发送。

无论操作系统版本如何，都可以通过在 dwMessage 设置为 NIM_SETVERSION 的情况下调用 Shell_NotifyIcon 来选择 Shell 的行为方式。 设置 lpdata 指向的 NOTIFYICONDATA 结构的 uVersion 成员，以指示你希望 Windows 2000、Windows Vista 或 5.0 版本 (Windows 95) 行为。

注意上面讨论的消息不是传统的 Windows 消息。当使用 dwMessage 中设置的 NIM_ADD 标志调用Shell_NotifyIcon 时，它们将作为应用程序定义的消息的 lParam 值发送，该消息在 lpdata 所指向的 NOTIFYICONDATA 结构的 uCallbackMessage 成员中指定。

从 Windows XP Service Pack 2 (SP2) 开始，可以在通知气球中显示自定义图标。这样，调用进程就可以自定义之前可用的信息、警告和错误选项之外的通知，并将其与其他类型的用户通知区分开来。

注意

shellapi.h 标头将 Shell_NotifyIcon 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shellapi.h
Library	Shell32.lib
DLL	Shell32.dll (版本 4.0 或更高版本)
API 集	Windows 10版本 10.0.10240 中引入的 ext-ms-win-shell-shell32-l1-2-1 ()

另请参阅

通知和通知区域

通过