TaskbarTaskbar*
*Contents  *Index  *Topic Contents
*Previous Topic: DLLVERSIONINFO
*Next Topic: Shell Reference

Taskbar


The Microsoft® Windows® interface includes a special application desktop toolbar called the taskbar. The taskbar can be used for such tasks as switching between open windows and starting new applications.

The taskbar is also known as an appbar. For more information on appbars, see Application Desktop Toolbars.

arrowy.gifAbout the Taskbar

arrowy.gifUsing the Taskbar

About the Taskbar

The taskbar includes the Start menu, taskbar buttons, a shortcut menu, and a status area.

The Start menu contains commands that can be used to access programs, documents, and settings. These commands include Programs, Documents, Settings, Find, Help, Run, and Shut Down.

A button is placed on the taskbar whenever an application creates a window that isn't owned. To switch to a window, the user simply clicks its window button.

To open the shortcut menu, the user clicks the taskbar with the right mouse button. The shortcut menu includes commands to cascade windows, tile windows, minimize all windows, and set taskbar properties.

Applications can put icons in the status area to indicate the status of an operation or to notify the user about an event. For example, an application might put a printer icon in the status area to show that a print job is underway. The status area is at the right end of the taskbar (if the taskbar is horizontal) or at the bottom (if the taskbar is vertical). The status area will also contain the current time if the Show Clock check box is selected in the taskbar properties.

Taskbar Display Options

The taskbar supports two display options: Auto Hide and Always on Top. To set these options, open the taskbar shortcut menu, click Properties, and select or clear the Auto Hide check box or the Always on Top check box. To retrieve the state of these display options, use the ABM_GETSTATE message. If you would like to be notified when the state of these display options changes, process the ABN_STATECHANGE notification message in your window procedure.

The work area is the portion of the screen not obscured by the taskbar. To retrieve the size of the work area, call the SystemParametersInfo function with the SPI_GETWORKAREA value set. To retrieve the rectangle coordinates that describe the location of the taskbar, use the ABM_GETTASKBARPOS message.

Adding Shortcuts to the Start Menu

Applications can use the shell dynamic data exchange interface to add items to the Programs submenu of the Start menu, just as they would use it to add items to a group in Program Manager in earlier versions of Windows. However, this is not the recommended method to use with the Microsoft® Windows NT® version 4.0 and Windows 95 operating systems.

To add an item to the Programs submenu, follow these steps:

Visibility of Taskbar Buttons

The shell creates a button on the taskbar whenever an application creates a window that isn't owned. To ensure that the window button is placed on the taskbar, create an unowned window with the WS_EX_APPWINDOW extended style. To prevent the window button from being placed on the taskbar, create the unowned window with the WS_EX_TOOLWINDOW extended style. As an alternative, you can create a hidden window and make this hidden window the owner of your visible window.

The window button typically contains the application icon and title. However, if the application does not contain a system menu, the window button is created without the icon.

If you want your application to display a message to the user while its window is not active, use the FlashWindow function to let the user know that a message is waiting. This function flashes the window button. Once the user clicks the window button to activate the window, your application can display the message.

Modifying the Contents of the Taskbar

Microsoft® Internet Explorer 4.0 adds the capability to modify the contents of the taskbar. From an application, you can now add, remove, and activate taskbar items. Activating the item does not activate the window; it simply shows the item as pressed on the taskbar.

The taskbar modification capabilities are implemented in an OLE COM object. This object is created by calling CoCreateInstance with CLSID_TaskbarList. The interface you request for this object is IID_ITaskbarList. This will create the object and return you an ITaskbarList interface pointer. You must then call the object's ITaskbarList::HrInit method to initialize the object. If HrInit succeeds, you can use the methods of the ITaskbarList interface to modify the contents of the taskbar.

Working with the Status Area

Applications use the Shell_NotifyIcon function to put icons in the status area of the taskbar to serve as status indicators. You should allow the user to obtain additional information by moving the mouse over the icon, clicking the icon, clicking the icon with the right mouse button, and double-clicking the icon. The system notifies you of this mouse movement. The information the user can receive can be summarized as follows:

Sending taskbar messages

Use the Shell_NotifyIcon function to send messages to add, modify, or delete icons from the status area. The parameters for Shell_NotifyIcon include the identifier of the message to send and the address of a NOTIFYICONDATA structure. Members of this structure contain information that the system needs to process the specified message.

To add an icon to the taskbar's status area, send the NIM_ADD message. The NOTIFYICONDATA structure that accompanies the message specifies the handle to the icon, the identifier of the icon, and any tooltip text for the icon. If the Show Clock check box (in the taskbar properties) is selected, 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.

You can delete an icon from the status area by sending the NIM_DELETE message. You can send the NIM_MODIFY message to modify the information that the system maintains for a taskbar icon, including its icon handle, tooltip text, and callback message identifier.

Receiving callback messages

Each taskbar icon can have an application-defined callback message associated with it. If an icon has a callback message, the system will send the message to the application whenever a mouse event occurs within the icon. In this way, the system can notify an application whenever the user clicks or double-clicks the icon or moves the mouse cursor into the icon's bounding rectangle.

An application defines an icon's callback message when it adds the icon to the taskbar. The uCallbackMessage member of the NOTIFYICONDATA structure included with the NIM_ADD message specifies the identifier of the callback message. When a mouse event occurs, the system sends the callback message to the window identified by the hWnd member. The message's lParam parameter is the identifier of the mouse message that the system generated as a result of the mouse event. For example, when the mouse cursor moves into a taskbar icon, the lParam parameter of the resulting callback message contains the WM_MOUSEMOVE identifier. The wParam parameter contains the identifier of the taskbar icon in which the mouse event occurred.

Taskbar Creation Notification

Microsoft® Internet Explorer 4.0 will notify applications that the taskbar has been created. When the taskbar is created, it will register a message with the "TaskbarCreated" string and then broadcast 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. 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

You add an icon to the taskbar status area by filling in a NOTIFYICONDATA structure and then passing the structure to Shell_NotifyIcon with the NIM_ADD message. 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 send it to the system when you send an NIM_DELETE message. When deleting a taskbar icon, specify only the cbSize, hWnd, and uID members, as the following example shows. 

// 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 specifies the identifier of the taskbar icon, and the lParam parameter specifies the mouse 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; 
 }

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.