Adding Annunciators to the Taskbar

If the fill H/PC-like shell is included, Windows CE supports the use of annunciators, icons placed onto the taskbar to indicate user notifications are active. Applications can add, change, and delete an annunciator using the Shell_NotifyIcon function. The following code example shows the prototype for this function.

BOOL Shell_NotifyIcon (DWORD dwMessage, PNOTIFYICONDATA pnid);

The first parameter, dwMessage, specifies the task the function should perform. This parameter can be one of the following three values:

NIM_ADD

This function adds an annunciator to the taskbar.

NIM_DELETE

This function deletes an annunciator from the taskbar.

NIM_MODIFY

This function modifies an existing annunciator on the taskbar.

The other parameter, pnid, points to the NOTIFYICONDATA structure. The following code example shows the structure definition.

typedef struct _NOTIFYICONDATA { 
   DWORD cbSize;
   HWND hWnd; 
   UINT uID; 
   UINT uFlags; 
   UINT uCallbackMessage; 
   HICON hIcon; 
   WCHAR szTip[64]; 
} NOTIFYICONDATA;

The first member, cbSize, contains the structure size, in bytes. The hWnd member specifies the window handle that owns the icon. This window receives messages notifying the window that a user has tapped, double-tapped, or moved a pen on the icon. The uID member identifies the icon being added, deleted, or modified. Assigning a uID to an icon enables an application to have more than one icon on the taskbar. The uFlags member contains flags that identify which of the remaining structure fields contain valid data.

The uCallbackMessage member contains an application-defined message identifier. Windows CE uses the identifier to notify the window specified in hWnd of any user actions on the icon. This value is based on WM_USER so that the message value does not conflict with other messages the window receives. The taskbar looks at uCallbackMessage only if uFlags contains the NIF_MESSAGE flag.

The hIcon member contains a handle to the icon to be displayed on the taskbar. Notification icons must be 16 x 16 pixels. Call the LoadImage function instead of the LoadIcon function to load the icon because LoadIcon does not return a small format icon. The taskbar looks at hIcon only if the NIF_ICON flag is set in uFlags. The last member, szTip, contains ToolTip text to display for the icon.

To effectively manage an annuciator, your application must handle any notification messages the taskbar sends to it. The wParam parameter of the message contains the identifier value of the taskbar icon that the message references. This identifier value is the same identifier defined in the call to the Shell_NotifyIcon function. The lParam parameter contains a code indicating the reason for the message. These values are actually the message codes for various mouse events. For example, if a user taps on a taskbar icon, the lParam value in the notification message will be WM_LBUTTONDOWN, followed by another message containing WM_LBUTTONUP.