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