Shell_NotifyIcon

Shell_NotifyIcon function

Sends a message to the taskbar's status area.向任务栏状态区发送消息。

Syntax

C++

BOOL Shell_NotifyIcon(
  _In_  DWORD dwMessage,
  _In_  PNOTIFYICONDATA lpdata
);

      

Parameters

dwMessage [in]

Type: DWORD

A value that specifies the action to be taken by this function. It can have one of the following values:这个函数可以执行的动作。可以是下面一个或几个值：（所谓NIM就是Notify Icon Message）

NIM_ADD (0x00000000)

0x00000000. Adds an icon to the status area. The icon is given an identifier in theNOTIFYICONDATA structure pointed to by lpdata—either through itsuID or guidItem member. This identifier is used in subsequent calls toShell_NotifyIcon to perform later actions on the icon.向状态区域添加图标。给图标指定一个由名为lpdata的NOTIFYICONDATA结构指向的标识符，这个标识符可以由uID或者guidItem给定。一旦函数Shell_NotifyIcon被调用，这个标识符就作用于图标了。

NIM_MODIFY (0x00000001)

0x00000001. Modifies an icon in the status area. NOTIFYICONDATA structure pointed to by lpdata uses the ID originally assigned to the icon when it was added to the notification area (NIM_ADD) to identify the icon to be modified.修改状态区域的图标。当（使用NIM_ADD）添加到通知区域的图标被修改时，NOTIFYICONDATA类型的lpdata使用原始的图标ID。

NIM_DELETE (0x00000002)

0x00000002. Deletes an icon from the status area. NOTIFYICONDATA structure pointed to by lpdata uses the ID originally assigned to the icon when it was added to the notification area (NIM_ADD) to identify the icon to be deleted.删除状态区域的图标。当（使用NIM_ADD）添加到通知区域的图标被删除时，名为lpdata的NOTIFYICONDATA结构体使用原始的图标ID。

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll version 5.0 and later only. Returns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use NIM_SETFOCUS to return focus to the notification area.使通知区域获得焦点。当通知区域图标完成了UI操作后，应该使用这个消息。例如，如果图标显示了快捷菜单，但是用户按下了ESC取消操作，应当使用NIM_SETFOCUS消息以使焦点返回到通知区域。

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll version 5.0 and later only. Instructs the notification area to behave according to the version number specified in theuVersion member of the structure pointed to by lpdata. The version number specifies which members are recognized.让通知区域按照lpdata的uVersion字段标识的版本值来执行。版本号指定了哪些成员是有效的。

NIM_SETVERSION must be called every time a notification area icon is added (NIM_ADD)>. It does not need to be called with NIM_MOFIDY. The version setting is not persisted once a user logs off.每当添加通知区域的时候，NIM_SETVERSION必须添加。不必使用NIM_MODIFY。当用户登出的时候，版本设置不会持久保留。

For details, see the Remarks section.

lpdata [in]

Type: PNOTIFYICONDATA

A pointer to a NOTIFYICONDATA structure. The content of the structure depends on the value ofdwMessage. It can define an icon to add to the notification area, cause that icon to display a notification, or identify an icon to modify or delete.指向NOTIFYICONDATA结构体。这个结构体的数据取决于dwMessage的值。它可以定义一个图标、添加到通知区域并显示通知，也可以修改或删除一个图标。

Return value

Type: BOOL

Returns TRUE if successful, or FALSE otherwise. IfdwMessage is set to NIM_SETVERSION, the function returns TRUE if the version was successfully changed, orFALSE if the requested version is not supported.

Remarks

（这一段讲2000，不翻译了。）

As of Windows 2000 (Shell32.dll version 5.0), if you set theuVersion member of the NOTIFYICONDATA structure pointed to by lpdata to NOTIFYICON_VERSION_4 or higher,Shell_NotifyIcon mouse and keyboard events are handled differently than in earlier versions of Windows. The differences include the following:

• If a user selects a notify icon's shortcut menu with the keyboard, the Shell now sends the associated application aWM_CONTEXTMENU message. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
• If a user selects a notify icon with the keyboard and activates it with the SPACEBAR or ENTER key, the version 5.0 Shell sends the associated application an NIN_KEYSELECT notification. Earlier versions sendWM_RBUTTONDOWN and WM_RBUTTONUP messages.
• If a user selects a notify icon with the mouse and activates it with the ENTER key, the Shell now sends the associated application an NIN_SELECT notification. Earlier versions sendWM_RBUTTONDOWN and WM_RBUTTONUP messages.

As of Windows XP (Shell32.dll version 6.0), if a user passes the mouse pointer over an icon with which a balloon notification is associated, the Shell sends the following messages:在XP下，如果用户的鼠标经过一个关联了气泡同志的图标，Shell会发送下面的消息：

• NIN_BALLOONSHOW. Sent when the balloon is shown (balloons are queued).在气泡显示是发送。

• NIN_BALLOONHIDE. Sent when the balloon disappears. For example, when the icon is deleted. This message is not sent if the balloon is dismissed because of a timeout or if the user clicks the mouse.在气泡消失时发送。例如，当删除图标的时候。当超时或者用户点击鼠标时，气泡消失的时候不会发这个消息。

  As of Windows 7, NIN_BALLOONHIDE is also sent when a notification with the NIIF_RESPECT_QUIET_TIME flag set attempts to display during quiet time (a user's first hour on a new computer). In that case, the balloon is never displayed at all.在Win7下，当使用了NIIF_RESPECT_QUIET_TIME标签的通知企图在退出的时候显示时，依旧会发送这个消息。这种情况下，气泡永远不会显示。

• NIN_BALLOONTIMEOUT. Sent when the balloon is dismissed because of a timeout.当气泡因超时没有显示时。
• NIN_BALLOONUSERCLICK. Sent when the balloon is dismissed because the user clicked the mouse.因为用户点击鼠标而导致气泡没有显示时。

（Vista的不翻译了）

In addition to those messages, as of Windows Vista (Shell32.dll version 6.0.6), if a user passes the mouse pointer over an icon with which a balloon notification is associated, the Windows Vista Shell also adds the following messages:

• NIN_POPUPOPEN. Sent when the user hovers the cursor over an icon to indicate that the richer pop-up UI should be used in place of a standard textual tooltip.
• NIN_POPUPCLOSE. Sent when a cursor no longer hovers over an icon to indicate that the rich pop-up UI should be closed.

Regardless of the operating system version, you can select which way the Shell should behave by callingShell_NotifyIcon with dwMessage set to NIM_SETVERSION. Set theuVersion member of the NOTIFYICONDATA structure pointed to by lpdata to indicate whether you want Windows 2000, Windows Vista, or pre-version 5.0 (Windows 95) behavior.无论什么系统版本，你可以通过将Shell_NotifyIcon的dwMessage设置为NIM_SETVERSION来选择。你可以通过NOTIFYICONDATA的uVersion来设置你想要的系统风格，例如2000风格、Vista风格，95风格等。

Note  The messages discussed above are not conventional Windows messages. They are sent as thelParam value of the application-defined message that is specified in theuCallbackMessage member of the NOTIFYICONDATA structure pointed to by lpdata, whenShell_NotifyIcon is called with the NIM_ADD flag set indwMessage.

As of Windows XP Service Pack 2 (SP2), a custom icon can be displayed in the notification balloon. This allows the calling process to customize the notification beyond the previously available options of info, warning, and error, and distinguish it from other types of notification for the user.

Requirements

Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Shellapi.h
Library	Shell32.lib
DLL	Shell32.dll (version 4.0 or later)
Unicode and ANSI names	Shell_NotifyIconW (Unicode) and Shell_NotifyIconA (ANSI)

See also

Notifications and the Notification Area