Taskbar Notifications

The Windows taskbar includes an area in which applications can display status information. In Figure 11-3, for instance, this taskbar notification area (sometimes called the tray notification area) includes an electrical plug icon to signal that my laptop is plugged in, another icon to indicate that my PCMCIA card is active, and a time display telling me that it's getting close to teatime.

Figure 11-3.

The taskbar notification area.

An icon in the taskbar notification area can have a ToolTip associated with it, which is helpful for displaying additional status information. For example, when my laptop is running off its battery, a battery icon replaces the electrical plug icon. If I allow my mouse to linger over the battery icon, a ToolTip pops up, indicating how much battery life is left. A printer icon and an associated ToolTip can also be useful. When you print a document, the printer icon appears in the notification area, and its ToolTip can tell you the status of the print job (whether it's spooling, printing, and so on).

In the SHELLFUN sample, the user can add an icon to the taskbar notification area. You need to provide an icon and, optionally, a ToolTip string. SHELLFUN uses the built-in Windows logo icon, IDI_WINLOGO. The user can add or remove the icon or modify its state in the taskbar notification area by choosing menu commands:

case IDM_ADDICON:

TrayMessage (hWnd, NIM_ADD);

break;



case IDM_STATECHANGE:

TrayMessage (hWnd, NIM_MODIFY);

break;



case IDM_REMOVEICON:

TrayMessage (hWnd, NIM_DELETE);

break;

TrayMessage is an application-defined function that fills out a NOTIFYICONDATA structure and sends the message passed in the second parameter through the Shell_NotifyIcon function. Notice that a member of the structure is filled in with flags. This member can be a combination of the following flags:

The following code demonstrates how SHELLFUN fills out this structure and uses the Shell_NotifyIcon function:

void TrayMessage (HWND hWnd, UINT message)

{

NOTIFYICONDATA tnd;



// Change the state of the small icon in the taskbar.

if (g_State1)

{

lstrcpyn (tnd.szTip, g_szState2, sizeof (tnd.szTip));

g_State1 = FALSE;

}

else

{

lstrcpyn (tnd.szTip, g_szState1, sizeof (tnd.szTip));

g_State1 = TRUE;

}



switch (message)

{

case NIM_ADD:

tnd.uFlags = NIF_MESSAGE | NIF_ICON | NIF_TIP;

break;



case NIM_MODIFY:

tnd.uFlags = NIF_TIP;

break;



case NIM_DELETE:

tnd.uFlags = 0;

g_State1 = FALSE;

break;

}



tnd.uID = (UINT)IDI_WINLOGO;

tnd.cbSize = sizeof (NOTIFYICONDATA);

tnd.hWnd = hWnd;

tnd.uCallbackMessage = TRAY_CALLBACK;

tnd.hIcon = g_hIconState;



Shell_NotifyIcon (message, &tnd);

}

Your application can send three messages using Shell_NotifyIcon:

SHELLFUN permits the user to modify (change the state of) the icon in the taskbar notification area by choosing the Change State command on the AppBar menu. When the user does this, the ToolTip text changes from State 1 to State 2, as illustrated in Figure 11-4.

Figure 11-4.

Changing the state of an icon in the taskbar notification area.

The application can provide a special callback message that handles mouse messages intended for a taskbar icon. This is useful if you want a context menu to pop up when the user clicks the icon with the right mouse button. The SHELLFUN sample displays a message box when the user clicks the icon with the left mouse button, as shown in Figure 11-5. Here is the callback function that SHELLFUN uses:

void TrayCallback (WPARAM wParam, LPARAM lParam)

{

UINT uID;

UINT uMouseMsg;



uID = (UINT)wParam;

uMouseMsg = (UINT)lParam;



if (uMouseMsg == WM_LBUTTONDOWN)

{

if (uID == (UINT)IDI_WINLOGO)

MessageBox (NULL, "Click!", "This sure is
fun!", MB_OK);

}

}

Figure 11-5.

SHELLFUN responds to the user clicking the taskbar icon.

NOTE: A taskbar notification can be especially useful if you are writing an installer or a Control Panel application for a hardware item such as a sound card. It's nice to let users know when the hardware is up and running, allowing them to check status without having to open an application.