Shell_NotifyIconA function (shellapi.h)
Sends a message to the taskbar's status area.
Syntax
BOOL Shell_NotifyIconA(
[in] DWORD dwMessage,
[in] PNOTIFYICONDATAA lpData
);
Parameters
[in] dwMessage
Type: DWORD
A value that specifies the action to be taken by this function. It can have one of the following values:
NIM_ADD (0x00000000)
0x00000000. Adds an icon to the status area. The icon is given an identifier in the NOTIFYICONDATA structure pointed to by lpdata—either through its uID or guidItem member. This identifier is used in subsequent calls to Shell_NotifyIcon to perform later actions on the icon.
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_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_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.
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 the uVersion member of the structure pointed to by lpdata. The version number specifies which members are recognized.
NIM_SETVERSION must be called every time a notification area icon is added (NIM_ADD). It does not need to be called with NIM_MODIFY. The version setting is not persisted once a user logs off.
For details, see the Remarks section.
[in] lpData
Type: PNOTIFYICONDATA
A pointer to a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage. 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.
Return value
Type: BOOL
Returns TRUE if successful, or FALSE otherwise. If dwMessage is set to NIM_SETVERSION, the function returns TRUE if the version was successfully changed, or FALSE if the requested version is not supported.
Remarks
As of Windows 2000 (Shell32.dll version 5.0), if you set the uVersion 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 a WM_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 send WM_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 send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
- 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.
- 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.
- 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.
Note
The shellapi.h header defines Shell_NotifyIcon as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows 2000 Server [desktop apps only] |
Target Platform | Windows |
Header | shellapi.h |
Library | Shell32.lib |
DLL | Shell32.dll (version 4.0 or later) |
API set | ext-ms-win-shell-shell32-l1-2-1 (introduced in Windows 10, version 10.0.10240) |