NOTIFYICONDATAA structure (shellapi.h)
Contains information that the system needs to display notifications in the notification area. Used by Shell_NotifyIcon.
Syntax
typedef struct _NOTIFYICONDATAA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
CHAR szTip[64];
#else
CHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
CHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
CHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAA, *PNOTIFYICONDATAA;
Members
cbSize
Type: DWORD
The size of this structure, in bytes.
hWnd
Type: HWND
A handle to the window that receives notifications associated with an icon in the notification area.
uID
Type: UINT
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
Type: UINT
Flags that either indicate which of the other members of the structure 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)
0x00000001. The uCallbackMessage member is valid.
NIF_ICON (0x00000002)
0x00000002. The hIcon member is valid.
NIF_TIP (0x00000004)
0x00000004. The szTip member is valid.
NIF_STATE (0x00000008)
0x00000008. The dwState and dwStateMask members are valid.
NIF_INFO (0x00000010)
0x00000010. Display a balloon notification. The szInfo, szInfoTitle, dwInfoFlags, and uTimeout members are valid. Note that uTimeout is valid only in Windows 2000 and Windows XP.
- To display the balloon notification, specify NIF_INFO and provide text in szInfo.
- To remove a balloon notification, specify NIF_INFO and provide an empty string through szInfo.
- To add a notification area icon without displaying a notification, do not set the NIF_INFO flag.
NIF_GUID (0x00000020)
0x00000020.
- Windows 7 and later: The guidItem is valid.
- Windows Vista and earlier: Reserved.
NIF_REALTIME (0x00000040)
0x00000040. Windows Vista and later. If the balloon notification cannot be displayed immediately, discard it. Use this flag for notifications 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 is meaningful only when combined with the NIF_INFO flag.
NIF_SHOWTIP (0x00000080)
0x00000080. Windows Vista and later. Use the standard tooltip. Normally, when uVersion is set to NOTIFYICON_VERSION_4, the standard tooltip is suppressed and can be replaced by the application-drawn, pop-up UI. If the application wants to show the standard tooltip with NOTIFYICON_VERSION_4, it can specify NIF_SHOWTIP to indicate the standard tooltip should still be shown.
uCallbackMessage
Type: UINT
An application-defined message identifier. The system uses this identifier to send notification messages to the window identified in hWnd. These notification messages are sent when a mouse event or hover occurs in the bounding rectangle of the icon, when the icon is selected or activated with the keyboard, or when those actions occur in the balloon notification.
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
Type: HICON
A handle to the icon to be added, modified, or deleted. Windows XP and later support 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 dpi value. This can lead to an unattractive result. It is recommended that you provide both a 16x16 pixel icon and a 32x32 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[64]
Type: TCHAR[64]
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 and later, szTip can have a maximum of 128 characters, including the terminating null character.
szTip[128]
Type: TCHAR[64]
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 and later, szTip can have a maximum of 128 characters, including the terminating null character.
dwState
Type: DWORD
Windows 2000 and later. The state of the icon. One or both of the following values:
NIS_HIDDEN (0x00000001)
0x00000001. The icon is hidden.
NIS_SHAREDICON (0x00000002)
0x00000002. The icon resource is shared between multiple icons.
dwStateMask
Type: DWORD
Windows 2000 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 modified while the icon sharing bit is ignored regardless of its value.
szInfo[256]
Type: TCHAR[256]
Windows 2000 and later. A null-terminated string that specifies the text to display in a balloon notification. It can have a maximum of 256 characters, including the terminating null character, but should be restricted to 200 characters in English to accommodate localization. To remove the balloon notification from the UI, either delete the icon (with NIM_DELETE) or set the NIF_INFO flag in uFlags and set szInfo to an empty string.
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
Type: UINT
Windows 2000 and later.
DUMMYUNIONNAME.uVersion
Type: UINT
Windows 2000 and later. Union with uTimeout (deprecated as of Windows Vista). Specifies which version of the Shell notification icon interface should be used. For more information on the differences in these versions, see Shell_NotifyIcon. This member is employed only when using Shell_NotifyIcon to send an NIM_SETVERSION message.
szInfoTitle[64]
Type: TCHAR[64]
Windows 2000 and later. A null-terminated string that specifies a title for a balloon notification. This title appears in a larger font immediately above the text. It can have a maximum of 64 characters, including the terminating null character, but should be restricted to 48 characters in English to accommodate localization.
dwInfoFlags
Type: DWORD
Windows 2000 and later. Flags that can be set to modify the behavior and appearance of a balloon notification. The icon is placed to the left of the title. If the szInfoTitle member is zero-length, the icon is not shown.
NIIF_NONE (0x00000000)
0x00000000. No icon.
NIIF_INFO (0x00000001)
0x00000001. An information icon.
NIIF_WARNING (0x00000002)
0x00000002. A warning icon.
NIIF_ERROR (0x00000003)
0x00000003. An error icon.
NIIF_USER (0x00000004)
0x00000004. Windows XP SP2 and later.
- Windows XP: Use the icon identified in hIcon as the notification balloon's title icon.
- Windows Vista and later: Use the icon identified in hBalloonIcon as the notification balloon's title icon.
NIIF_NOSOUND (0x00000010)
0x00000010. Windows XP and later. Do not play the associated sound. Applies only to notifications.
NIIF_LARGE_ICON (0x00000020)
0x00000020. Windows Vista and later. The large version of the icon should be used as the notification icon. This corresponds to the icon with dimensions SM_CXICON x SM_CYICON. If this flag is not set, the icon with dimensions SM_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)
0x00000080. Windows 7 and later. Do not display the balloon notification if the current user is in "quiet time", which is the first hour after a new user logs into his or her account for the first time. During this time, most notifications should not be sent or shown. This lets a user become accustomed to a new computer system without those distractions. Quiet time also occurs for each user after an operating system upgrade or clean installation. A notification sent with this flag during quiet time is not queued; it is simply dismissed unshown. The application can resend the notification later if it is still valid at that time.
Because an application cannot predict when it might encounter quiet time, we recommended that this flag always be set on all appropriate notifications by any application that means to honor quiet time.
During quiet time, certain notifications should still be sent because they are expected by the user as feedback in response to a user action, for instance when he or she plugs in a USB device or prints a document.
If the current user is not in quiet time, this flag has no effect.
NIIF_ICON_MASK (0x0000000F)
0x0000000F. Windows XP and later. Reserved.
guidItem
Type: GUID
Windows XP 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. The NIF_GUID flag must be set in the uFlags member.
- Windows XP and Windows Vista: Reserved; must be set to 0.
If you identify the notification icon with a GUID in one call to Shell_NotifyIcon, you must use that same GUID to identify the icon in any subsequent Shell_NotifyIcon calls that deal with that same icon.
To generate a GUID for use in this member, use a GUID-generating tool such as Guidgen.exe.
hBalloonIcon
Type: HICON
Windows Vista and later. The handle of a customized notification icon provided by the application that should be used independently of the notification area icon. If this member is non-NULL and the NIIF_USER flag is set in the dwInfoFlags member, this icon is used as the notification icon. If this member is NULL, the legacy behavior is carried out.
Remarks
See "Notifications" in the Windows User Experience Interaction Guidelines for more information on notification UI and content best practices.
If you set the NIF_INFO flag in the uFlags member, the balloon-style notification is used. For more discussion of these notifications, see Balloon tooltips.
No more than one balloon notification at a time can be displayed for the taskbar. If an application attempts to display a notification when one is already being displayed, the new notification is queued and displayed when the older notification goes away. In versions of Windows before Windows Vista, the new notification would not appear until the existing notification has been visible for at least the system minimum timeout length, regardless of the original notification's uTimeout value. If the user does not appear to be using the computer, the system does not count this time toward the timeout.
Several members of this structure are only supported for Windows 2000 and later. To enable these members, include one of the following lines in your header:
// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA
// Windows XP and earlier:
#define _WIN32_IE 0x0500
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 against earlier 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 and initialize cbSize with one of these values:
| Shell32.dll Version | cbSize |
|---|---|
| 6.0.6 or higher (Windows Vista and later) | sizeof(NOTIFYICONDATA) |
| 6.0 (Windows XP) | NOTIFYICONDATA_V3_SIZE |
| 5.0 (Windows 2000) | NOTIFYICONDATA_V2_SIZE |
| Versions lower than 5.0 | NOTIFYICONDATA_V1_SIZE |
Using this value for cbSize allows your application to use NOTIFYICONDATA in a method compatible with earlier Shell32.dll versions.
The following code example shows version checking that can enable an application that uses the guidItem member to run on both Windows Vista and Windows 7. It provides a Boolean function that returns TRUE if the operating system is Windows 7. Unless this member returns TRUE, the guidItem member must be set to 0.
BOOL IsWin7OrLater()
{
// Initialize the OSVERSIONINFOEX structure.
OSVERSIONINFOEX osvi;
ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osvi.dwMajorVersion = 6;
osvi.dwMinorVersion = 1;
// Initialize the condition mask.
DWORDLONG dwlConditionMask = 0;
VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);
// Perform the test.
return VerifyVersionInfo(&osvi,
VER_MAJORVERSION | VER_MINORVERSION,
dwlConditionMask);
}
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 | NIF_GUID;
// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID =
{0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;
// 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;
Troubleshooting
If you are using the guidItem member to identify the icon, and that icon is not seen or some calls to Shell_NotifyIcon fail, one of the following cases is the likely cause:- The NIF_GUID flag was not set in every call to Shell_NotifyIcon. Once you identify the notification icon with a GUID in one call to Shell_NotifyIcon, you must use that same GUID to identify the icon in any subsequent Shell_NotifyIcon calls that deal with that same icon.
-
The binary file that contains the icon was moved. The path of the binary file is included in the registration of the icon's GUID and cannot be changed. Settings associated with the icon are preserved through an upgrade only if the file path and GUID are unchanged. If the path must be changed, the application should remove any GUID information that was added when the existing icon was registered. Once that information is removed, you can move the binary file to a new location and reregister it with a new GUID. Any settings associated with the original GUID registration will be lost.
This also occurs in the case of a side-by-side installation. When dealing with a side-by-side installation, new versions of the application should update the GUID of the binary file.
Note The only exception to a moved file occurs when both the original and moved binary files are Authenticode-signed by the same company. In that case, settings are preserved through the move.
Note
The shellapi.h header defines NOTIFYICONDATA as an alias that 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 is 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] |
| Header | shellapi.h |