托盘图标编程

from MSDN

Adding, Modifying, and Deleting Icons in the Status Area

Use the Shell_NotifyIcon function to add, modify, or delete icons from the status area. The dwMessage parameter of Shell_NotifyIcon is a message to the taskbar that specifies the action to be taken. The pnid parameter is a pointer to a NOTIFYICONDATA structure that is used to identify the icon and pass any additional information that is needed for the system to process the message.

You can perform the following actions with status area icons.

• To add an icon to the taskbar's status area, call Shell_NotifyIcon with the dwMessage parameter set to NIM_ADD. The NOTIFYICONDATA structure is used to specify the icon's handle and identifier, and any ToolTip text. If the user has selected the Show Clock check box in the taskbar properties, the system places the icon to the immediate left of the clock. Otherwise, the icon appears on the right side or at the bottom of the taskbar. Any existing icons are shifted to the left to make room for the new icon.
• To modify an icon's information, including its icon handle, ToolTip text, and callback message identifier, call Shell_NotifyIcon with dwMessage set to NIM_MODIFY.
• To delete an icon from the status area, call Shell_NotifyIcon with the dwMessage parameter set to NIM_DELETE.

When you have completed a user interface operation, return focus to the status area by calling Shell_NotifyIcon with dwMessage set to NIM_SETFOCUS. For example, you could do this when a taskbar icon displays a shortcut menu, but the user cancels it by pressing the ESCAPE key.

Receiving status area callback messages

Applications commonly put icons in the status area of the taskbar to serve as status indicators. You can provide additional information when the user performs mouse actions, such as moving the mouse pointer over the icon or clicking the icon.

The system notifies you of mouse and keyboard events by sending an application-defined callback message that is associated with a particular icon. In this way, the system can notify an application when the user, for instance, clicks the icon or selects it by pressing a key.

You define an icon's callback message when you add the icon to the taskbar. The callback message identifier is specified in the uCallbackMessage member of the NOTIFYICONDATA structure passed with NIM_ADD. When an event occurs, the system sends the callback message to the window procedure of the window specified by the hWnd member. The wParam parameter of the message contains the identifier of the taskbar icon in which the event occurred. The lParam parameter holds the mouse or keyboard message associated with the event. For example, when the mouse pointer moves onto a taskbar icon, lParam contains WM_MOUSEMOVE.

The results of various mouse events can be summarized as follows:

• When the user moves the mouse pointer over the icon, the system displays the ToolTip text that was specified in NOTIFYICONDATA.
• When the user clicks the icon, your application receives a WM_LBUTTONDOWN notification.
• When the user right-clicks the icon, your application receives a WM_RBUTTONDOWN notification.
• When the user double-clicks the icon, your application receives a WM_LBUTTONDBLCLK notification.

Typically, clicking the icon causes the application to display a window with additional information, right-clicking displays a shortcut menu, and double-clicking executes the default shortcut menu command.

For an example of how to change the ToolTip text associated with a status area icon, see Balloon ToolTips for Status Bar Icons.

Versions 5.0 and later of the Shell handle Shell_NotifyIcon mouse and keyboard events in different ways than earlier Shell versions found on Windows NT 4.0, Windows 95, and Windows 98. The differences are as follows:

• If a user requests 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—for example, when the icon is deleted. This message is not sent if the balloon is dismissed because of a timeout or a mouse click.
  • NIN_BALLOONTIMEOUT - Sent when the balloon is dismissed because of a timeout.
  • NIN_BALLOONUSERCLICK - Sent when the balloon is dismissed because of a mouse click.

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 version 5.0 or pre-version 5.0 behavior.

Taskbar Creation Notification

With Microsoft® Internet Explorer 4.0 and later, the Shell notifies applications that the taskbar has been created. When the taskbar is created, it registers a message with the TaskbarCreated string and then broadcasts this message to all top-level windows. When your taskbar application receives this message, it should assume that any taskbar icons it added have been removed and add them again. This feature generally applies only to services that are already running when the Shell begins execution. The following example shows a very simplified method for handling this case.

LRESULT CALLBACK WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, 
    LPARAM lParam)
{
static UINT s_uTaskbarRestart;

switch(uMessage)
    {
    case WM_CREATE:
        s_uTaskbarRestart = RegisterWindowMessage(TEXT("TaskbarCreated"));
        break;
        
    default:
        if(uMessage == s_uTaskbarRestart)
            AddTaskbarIcons();
        break;
    }
return DefWindowProc(hWnd, uMessage, wParam, lParam);
}

Using the Taskbar

This section includes examples that demonstrate how to add icons to the taskbar status area and how to process callback messages for taskbar icons.

Adding and Deleting Taskbar Icons in the Status Area

You add an icon to the taskbar status area by filling in a NOTIFYICONDATA structure and then passing the structure to Shell_NotifyIcon with dwMessage set to NIM_ADD. The structure members must specify the handle to the window that is adding the icon, as well as the icon identifier and icon handle. You can also specify ToolTip text for the icon. If you need to receive mouse messages for the icon, specify the identifier of the callback message that the system should use to send the message to the window procedure.

The function in the following example demonstrates how to add an icon to the taskbar.

// MyTaskBarAddIcon - adds an icon to the taskbar status area. 
// Returns TRUE if successful, or FALSE otherwise. 
// hwnd - handle to the window to receive callback messages. 
// uID - identifier of the icon. 
// hicon - handle to the icon to add. 
// lpszTip - ToolTip text. 
BOOL MyTaskBarAddIcon(HWND hwnd, UINT uID, HICON hicon, LPSTR lpszTip) 
{ 
    BOOL res; 
    NOTIFYICONDATA tnid; 
 
    tnid.cbSize = sizeof(NOTIFYICONDATA); 
    tnid.hWnd = hwnd; 
    tnid.uID = uID; 
    tnid.uFlags = NIF_MESSAGE | NIF_ICON | NIF_TIP; 
    tnid.uCallbackMessage = MYWM_NOTIFYICON; 
    tnid.hIcon = hicon; 
    if (lpszTip) 
        lstrcpyn(tnid.szTip, lpszTip, sizeof(tnid.szTip)); 
    else 
        tnid.szTip[0] = '/0'; 
 
    res = Shell_NotifyIcon(NIM_ADD, &tnid); 
 
    if (hicon) 
        DestroyIcon(hicon); 
 
    return res; 
} 

To delete an icon from the taskbar status area, fill a NOTIFYICONDATA structure and call Shell_NotifyIcon with dwMessage set to NIM_DELETE. When deleting a taskbar icon, specify only the cbSize, hWnd, and uID members of the structure. For example

// MyTaskBarDeleteIcon - deletes an icon from the taskbar status area. 
// Returns TRUE if successful, or FALSE otherwise. 
// hwnd - handle to the window that added the icon. 
// uID - identifier of the icon to delete. 
BOOL MyTaskBarDeleteIcon(HWND hwnd, UINT uID) 
{ 
    BOOL res; 
    NOTIFYICONDATA tnid; 
 
    tnid.cbSize = sizeof(NOTIFYICONDATA); 
    tnid.hWnd = hwnd; 
    tnid.uID = uID; 
         
    res = Shell_NotifyIcon(NIM_DELETE, &tnid); 
    return res; 
} 

Receiving Mouse Events

If you specify a callback message for a taskbar icon, the system sends the message to your application whenever a mouse event occurs in the icon's bounding rectangle. The wParam parameter of the message specifies the identifier of the taskbar icon, and the lParam parameter of the message specifies the message that the system generated as a result of the mouse event.

The function in the following example is from an application that adds both battery and printer icons to the taskbar. The application calls the function when it receives a callback message. The function determines whether the user has clicked one of the icons and, if a click has occurred, calls an application-defined function to display status information.

// On_MYWM_NOTIFYICON - processes callback messages for taskbar icons. 
// wParam - first message parameter of the callback message. 
// lParam - second message parameter of the callback message. 
void On_MYWM_NOTIFYICON(WPARAM wParam, LPARAM lParam) 
{ 
    UINT uID; 
    UINT uMouseMsg; 
 
    uID = (UINT) wParam; 
    uMouseMsg = (UINT) lParam; 
 
    if (uMouseMsg == WM_LBUTTONDOWN) { 
        switch (uID) { 
            case IDI_MYBATTERYICON: 
 
                // The user clicked the battery icon. Display the 
                // battery status. 
                ShowBatteryStatus(); 
                break; 
 
            case IDI_MYPRINTERICON: 
 
                // The user clicked the printer icon. Display the 
                // status of the print job. 
                ShowJobStatus(); 
                break; 
 
            default: 
                break; 
        } 
     } 
     return; 
 }