[This documentation is preliminary and is subject to change.]

Contains information that the system needs to process taskbar status area messages.

Syntax

typedef struct _NOTIFYICONDATAA{
    DWORD cbSize;
    HWND hWnd;
    UINT uID;
    UINT uFlags;
    UINT uCallbackMessage;
    HICON hIcon;
#if (NTDDI_VERSION < NTDDI_WIN2K)
    TCHAR szTip[64];
#endif
#if (NTDDI_VERSION >= NTDDI_WIN2K)
    TCHAR szTip[128];
    DWORD dwState;
    DWORD dwStateMask;
    TCHAR szInfo[256];
    union{
        UINT  uTimeout;
        UINT  uVersion;  // Used with Shell_NotifyIcon flag NIM_SETVERSION.
    } DUMMYUNIONNAME;
    TCHAR szInfoTitle[64];
    DWORD dwInfoFlags;
#endif
#if (NTDDI_VERSION >= NTDDI_WINXP)
    GUID guidItem;
#endif
#if (NTDDI_VERSION >= NTDDI_VISTA)
    HICON hBalloonIcon;
#endif

Members

cbSize

The size of this structure, in bytes.

hWnd

A handle to the window that receives notification messages associated with an icon in the taskbar status area. The Shell uses hWnd together with uID to identify which icon to operate on when Shell_NotifyIcon is invoked. If guidItem is specified, hWnd is not required.

uID

The application-defined identifier of the taskbar icon. The Shell uses either hWnd plus uID or guidItem to identify which icon to operate on when Shell_NotifyIcon is invoked. You can have multiple icons associated with a single hWnd by assigning each a different uID. If guidItem is specified, uID is ignored.

uFlags

Flags that either indicate which of the other members contain valid data or provide additional information to the ToolTip as to how it should display. This member can be a combination of the following values:

NIF_MESSAGE

0x00000001. The uCallbackMessage member is valid.

NIF_ICON

0x00000002. The hIcon member is valid.

NIF_TIP

0x00000004. The szTip member is valid.

NIF_STATE

0x00000008. The dwState and dwStateMask members are valid.

NIF_INFO

0x00000010. Use a balloon ToolTip instead of a standard ToolTip. The szInfo, uTimeout, szInfoTitle, and dwInfoFlags members are valid.

NIF_GUID

0x00000020. Reserved.

NIF_REALTIME

0x00000040. Windows Vista (Shell32.dll version 6.0.6) and later. If the ToolTip cannot be displayed immediately, discard it. Use this flag for ToolTips that represent real-time information which would be meaningless or misleading if displayed at a later time. For example, a message that states "Your telephone is ringing." NIF_REALTIME modifies and must be combined with the NIF_INFO flag.

NIF_SHOWTIP

0x00000080. Windows Vista (Shell32.dll version 6.0.6) and later. Use the standard ToolTip. Normally, when uVersion is set to NOTIFYICON_VERSION_4, the standard ToolTip is replaced by the application-drawn pop-up user interface (UI). If the application wants to show the standard tooltip in that case, regardless of whether the on-hover UI is showing, it can specify NIF_SHOWTIP to indicate the standard tooltip should still be shown. Note that the NIF_SHOWTIP flag is effective until the next call to Shell_NotifyIcon.

uCallbackMessage

An application-defined message identifier. The system uses this identifier to send notifications to the window identified in hWnd. These notifications are sent when a mouse event occurs in the bounding rectangle of the icon, or when the icon is selected or activated with the keyboard.

When the uVersion member is either 0 or NOTIFYICON_VERSION, the wParam parameter of the message contains the identifier of the taskbar icon in which the event occurred. This identifier can be 32 bits in length. The lParam parameter holds the mouse or keyboard message associated with the event. For example, when the pointer moves over a taskbar icon, lParam is set to WM_MOUSEMOVE.

When the uVersion member is NOTIFYICON_VERSION_4, applications continue to receive notification events in the form of application-defined messages through the uCallbackMessage member, but the interpretation of the lParam and wParam parameters of that message is changed as follows:

• LOWORD(lParam) contains notification events, such as NIN_BALLOONSHOW, NIN_POPUPOPEN, or WM_CONTEXTMENU.
• HIWORD(lParam) contains the icon ID. Icon IDs are restricted to a length of 16 bits.
• GET_X_LPARAM(wParam) returns the X anchor coordinate for notification events NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT, and all mouse messages between WM_MOUSEFIRST and WM_MOUSELAST. If any of those messages are generated by the keyboard, wParam is set to the upper-left corner of the target icon. For all other messages, wParam is undefined.
• GET_Y_LPARAM(wParam) returns the Y anchor coordinate for notification events and messages as defined for the X anchor.

hIcon

A handle to the icon to be added, modified, or deleted. To avoid icon distortion, be aware that notification area icons have different levels of support under different versions of Microsoft Windows. Windows 95, Windows 98, and Microsoft Windows NT 4.0 support icons of up to 4 bits per pixel (BPP). Windows Millennium Edition (Windows Me) and Windows 2000 support icons of a color depth up to the current display mode. Windows XP supports icons of up to 32 BPP.

If only a 16x16 pixel icon is provided, it is scaled to a larger size in a system set to a high dots per inch (dpi). This can lead to an unattractive result. It is recommended that you provide both a 16x16 pixel icon and a larger icon in your resource file. Use LoadIconMetric to ensure that the correct icon is loaded and scaled appropriately. See Remarks for a code example.

szTip

A null-terminated string that specifies the text for a standard ToolTip. It can have a maximum of 64 characters, including the terminating null character.

For Windows 2000 (Shell32.dll version 5.0) and later, szTip can have a maximum of 128 characters, including the terminating null character.

dwState

Windows 2000 (Shell32.dll version 5.0) and later. The state of the icon. There are two flags that can be set independently.

NIS_HIDDEN

0x00000001. The icon is hidden.

NIS_SHAREDICON

0x00000002. The icon is shared.

dwStateMask

Windows 2000 (Shell32.dll version 5.0) and later. A value that specifies which bits of the dwState member are retrieved or modified. The possible values are the same as those for dwState. For example, setting this member to NIS_HIDDEN causes only the item's hidden state to be retrieved while the icon sharing bit is ignored regardless of its value.

szInfo

Windows 2000 (Shell32.dll version 5.0) and later. A null-terminated string that specifies the text for a balloon ToolTip. It can have a maximum of 256 characters, including the terminating null character. To remove the ToolTip, set the NIF_INFO flag in uFlags and set szInfo to an empty string.

uTimeout

Note  This member is deprecated as of Windows Vista. Notification display times are now based on system settings.

Union with uVersion. The timeout value, in milliseconds, for a balloon ToolTip. The system enforces minimum and maximum timeout values. Values specified in uTimeout that are too large are set to the maximum value. Values that are too small default to the minimum value. The system minimum and maximum timeout values are currently set at 10 seconds and 30 seconds, respectively. See Remarks for further discussion of uTimeout.

uVersion

Windows 2000 (Shell32.dll version 5.0) and later. Union with uTimeout. Specifies whether the Shell notify icon interface should use Windows 95 or Windows 2000 behavior. For more information on the differences in these two behaviors, see Shell_NotifyIcon. This member is only employed when using Shell_NotifyIcon to send a NIM_SETVERSION message.

0

Use the Windows 95 behavior. Use this value for applications designed for Windows versions prior to Windows 2000.

NOTIFYICON_VERSION

Use the Windows 2000 behavior. Use this value for applications designed for Windows 2000 and later.

NOTIFYICON_VERSION_4

Use the Windows Vista behavior. Use this value for applications designed for Windows Vista and later.

szInfoTitle

Windows 2000 (Shell32.dll version 5.0) and later. A null-terminated string that specifies a title for a balloon ToolTip. This title appears in a bold type above the text. It can have a maximum of 64 characters, including the terminating null character.

dwInfoFlags

Windows 2000 (Shell32.dll version 5.0) and later. Flags that can be set to add an icon to a balloon ToolTip. It is placed to the left of the title. If the szInfoTitle member is zero-length, the icon is not shown.

NIIF_NONE

0x00000000. No icon.

NIIF_INFO

0x00000001. An information icon.

NIIF_WARNING

0x00000002. A warning icon.

NIIF_ERROR

0x00000003. An error icon.

NIIF_USER

0x00000004. Windows XP Service Pack 2 (SP2) and later. Use the icon identified in hIcon as the notification balloon's title icon.

NIIF_NOSOUND

0x00000010. Windows XP (Shell32.dll version 6.0) and later. Do not play the associated sound. Applies only to balloon ToolTips.

NIIF_LARGE_ICON

0x00000010. Windows Vista (Shell32.dll version 6.0.6) and later. The large version of the icon should be used as the balloon icon. This corresponds to the icon with dimensions SM_CXICON x SM_CYICON. If this flag is not set, the icon with dimensions XM_CXSMICON x SM_CYSMICON is used.

• This flag can be used with all stock icons.
• Applications that use older customized icons (NIIF_USER with hIcon) must provide a new SM_CXICON x SM_CYICON version in the tray icon (hIcon). These icons are scaled down when they are displayed in the System Tray or System Control Area (SCA).
• New customized icons (NIIF_USER with hBalloonIcon) must supply an SM_CXICON x SM_CYICON version in the supplied icon (hBalloonIcon).

NIIF_RESPECT_QUIET_TIME

0x00000080. Windows 7 and later. No icons are displayed during initial system setup.

NIIF_ICON_MASK

0x0000000F. Windows XP (Shell32.dll version 6.0) and later. Reserved.

guidItem

Windows XP (Shell32.dll version 6.0) and later.

• Windows 7 and later: A registered GUID that identifies the icon. This value overrides uID and is the recommended method of identifying the icon.
• Windows XP through Windows Vista: Reserved.

hBalloonIcon

Windows Vista (Shell32.dll version 6.0.6) and later. The handle of a customized balloon icon provided by the application that should be used independently of the tray icon. If this member is non-NULL and the NIIF_USER flag is set in the dwInfoFlags member, this icon is used as the balloon icon. If this member is NULL, the legacy behavior is carried out.

Remarks

If you set the NIF_INFO flag in the uFlags member, the standard ToolTip is replaced by a balloon ToolTip. For more discussion of balloon ToolTips, see Balloon ToolTips.

No more than one balloon ToolTip at a time can be displayed for the taskbar. If an application attempts to display a balloon ToolTip when one is already being displayed, the new ToolTip does not appear until the existing ToolTip has been visible for at least the system minimum timeout length. For example, a balloon ToolTip with uTimeout set to 30 seconds has been visible for 7 seconds when another application attempts to display a balloon ToolTip. If the system minimum timeout is 10 seconds, the first ToolTip displays for an additional 3 seconds before being replaced by the second ToolTip. If the user does not appear to be using the computer, the system does not count this time towards the timeout.

Several members of this structure are only supported for Windows 2000 (Shell32.dll version 5.0) and later. To enable these members, include one of the following lines in your header.

#define _WIN32_IE 0x0500
#define _WIN32_IE 0x0600

Note that you must initialize the structure with its size. If you use the size of the currently defined structure, the application might not run with earlier versions of Shell32.dll, which expect a smaller structure. You can run your application on pre-5.0 versions of Shell32.dll by defining the appropriate version number (see Shell and Common Controls Versions). However, this might cause problems if your application also needs to run on more recent systems.

You can maintain application compatibility with all Shell32.dll versions while still using the current header files by setting the size of the NOTIFYICONDATA structure appropriately. Before you initialize the structure, use DllGetVersion to determine which Shell32.dll version is installed on the system. If it is Shell32.dll version 5.0 or later, initialize the cbSize member as follows.

nid.cbSize = sizeof(NOTIFYICONDATA);

Setting cbSize to this value enables all the version 5.0 and 6.0 enhancements. For earlier versions, the size of the pre-6.0 structure is given by the NOTIFYICONDATA_V2_SIZE constant and the pre-5.0 structure is given by the NOTIFYICONDATA_V1_SIZE constant. Initialize the cbSize member as follows.

nid.cbSize = NOTIFYICONDATA_V2_SIZE;

Using this value for cbSize allows your application to use NOTIFYICONDATA with earlier Shell32.dll versions, although without the Shell32.dll version 6.0 enhancements.

The following code example shows the use of LoadIconMetric to load an icon for use with high DPI.

// Declare NOTIFYICONDATA details. 
// Error handling is omitted here for brevity. Do not omit it in your code.
NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP;

// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");

// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));

// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;

Structure Information

Header	shellapi.h
Minimum operating systems	Windows NT 4.0, Windows 95