Shell_NotifyIcon
Sends a message to the taskbar's status area.
BOOL Shell_NotifyIcon(
DWORD dwMessage,
PNOTIFYICONDATA lpdata
);
Parameters
- dwMessage
- [in] Variable of type DWORD that specifies the action to be taken. It can have one of the following values.
- NIM_ADD
- Adds an icon to the status area. The hWnd and uID members of the NOTIFYICONDATA structure pointed to by lpdata will be used to identify the icon in later calls to Shell_NotifyIcon.
- NIM_DELETE
- Deletes an icon from the status area. Use the hWnd and uID members of the NOTIFYICONDATA structure pointed to by lpdata to identify the icon to be deleted.
- NIM_MODIFY
- Modifies an icon in the status area. Use the hWnd and uID members of the NOTIFYICONDATA structure pointed to by lpdata to identify the icon to be modified.
- NIM_SETFOCUS
- Version 5.0. Returns focus to the taskbar notification area. Taskbar icons should use this message when they have completed their user interface operation. For example, if the taskbar icon displays a shortcut menu, but the user presses ESCAPE to cancel it, use NIM_SETFOCUS to return focus to the taskbar notification area.
- NIM_SETVERSION
- Version 5.0. Instructs the taskbar to behave according to the version number specified in the uVersion member of the structure pointed to by lpdata. This message allows you to specify whether you want the version 5.0 behavior found on Microsoft® Windows® 2000 systems, or that found with earlier Shell versions. The default value for uVersion is zero, indicating that the original Windows 95 notify icon behavior should be used. For details, see the Remarks section.
- lpdata
- [in] Address of a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage.
Return Values
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
The taskbar notification area is sometimes erroneously called the "tray."
Version 5.0 of the Shell, found on Windows 2000, handles Shell_NotifyIcon mouse and keyboard events differently than earlier Shell versions found on Windows NT® 4.0, Windows 95, and Windows 98. The differences are:
- If a user selects a notify icon's shortcut menu with the keyboard, the version 5.0 Shell 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 space bar 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 version 5.0 Shell sends the associated application an NIN_SELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
- If a user passes the mouse pointer over an icon with which a balloon ToolTip is associated, the version 5.0 Shell sends the following messages.
- NIN_BALLOONSHOW - Sent when the balloon is shown (balloons are queued).
- NIN_BALLOONHIDE - Sent when the balloon disappears—when the icon is deleted, for example. This message is not sent if the balloon is dismissed because of a timeout or mouse click by the user.
- 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.
You can select which way the Shell should behave by calling Shell_NotifyIcon with dwMessage set to NIM_SETVERSION. Set the uVersion member of the NOTIFYICONDATA structure to indicate whether you want pre-version 5.0 behavior or version 5.0 and later behavior.
Note The messages discussed above are not conventional Windows messages. They are sent as the lParam value of the application-defined message that is specified when the icon is added with NIM_ADD.
Windows 95/98/Me: Shell_NotifyIcon is supported by the Microsoft Layer for Unicode. To use this, you must add certain files to your application as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.
Requirements
Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.