Status BarsStatus Bars*
*Contents  *Index  *Topic Contents
*Previous Topic: REBARINFO
*Next Topic: Status Bar Reference

Status Bars


A status bar is a horizontal window at the bottom of a parent window in which an application can display various kinds of status information. The status bar can be divided into parts to display more than one type of information. The following illustration shows the status bar in the Microsoft® Windows® Paint application. The status bar is the bar at the bottom of the window that contains Help text and coordinate information.

Status bar in the Microsoft® Windows® Paint application.

arrowy.gifUsing Status Bars

arrowy.gifStatus Bar Updates in Internet Explorer

arrowy.gifStatus Bar Reference

Using Status Bars

You can create a status bar by using the CreateStatusWindow function or by using the CreateWindowEx function and specifying the STATUSCLASSNAME window class. To ensure that the common control dynamic-link library (DLL) is loaded, use the InitCommonControls function first. After you create the status bar, you can divide it into parts, set the text for each part, and control the appearance of the window by using status bar messages.

Types and Styles

The default position of a status bar is along the bottom of the parent window, but you can specify the CCS_TOP style to have it appear at the top of the parent window's client area.

You can specify the SBARS_SIZEGRIP style to include a sizing grip at the right end of the status bar.

Note Combining the CCS_TOP and SBARS_SIZEGRIP styles is not recommended because the resulting sizing grip is not functional.

Size and Height

The window procedure for the status bar automatically sets the initial size and position of the window, ignoring the values specified in the CreateWindowEx function. The width is the same as that of the parent window's client area. The height is based on the metrics of the font that is currently selected into the status bar's device context and on the width of the window's borders.

The window procedure automatically adjusts the size of the status bar whenever it receives a WM_SIZE message. Typically, when the size of the parent window changes, the parent sends a WM_SIZE message to the status bar.

An application can set the minimum height of a status bar's drawing area by sending the window an SB_SETMINHEIGHT message, specifying the minimum height, in pixels. The drawing area does not include the window's borders. A minimum height is useful for drawing in an owner-drawn status bar. For more information, see Owner-Drawn Status Bars later in this chapter.

You retrieve the widths of the borders of a status bar by sending the window an SB_GETBORDERS message. The message includes the address of a three-element array that receives the widths.

Multiple-Part Status Bars

A status bar can have many different parts, each displaying a different line of text. You divide a status bar into parts by sending the window an SB_SETPARTS message, specifying the number of parts to create and the address of an integer array. The array contains one element for each part, and each element specifies the client coordinate of the right edge of a part.

A status bar can have a maximum of 255 parts, although applications typically use far fewer than that. You retrieve a count of the parts in a status bar, as well as the coordinate of the right edge of each part, by sending the window an SB_GETPARTS message.

Status Bar Text Operations

You set the text of any part of a status bar by sending the SB_SETTEXT message, specifying the zero-based index of a part, an address of the string to draw in the part, and the technique for drawing the string. The drawing technique determines whether the text has a border and, if it does, the style of the border. It also determines whether the parent window is responsible for drawing the text. For more information, see the Owner-Drawn Status Bars section below.

By default, text is left-aligned within the specified part of a status bar. You can embed tab characters (\ t) in the text to center or right-align it. Text to the right of a single tab character is centered, and text to the right of a second tab character is right-aligned.

To retrieve text from a status bar, use the SB_GETTEXTLENGTH and SB_GETTEXT messages.

If your application uses a status bar that has only one part, you can use the WM_SETTEXT, WM_GETTEXT, and WM_GETTEXTLENGTH messages to perform text operations. These messages deal only with the part that has an index of zero, allowing you to treat the status bar much like a static text control.

To display a line of status without creating a status bar, use the DrawStatusText function. The function uses the same techniques to draw the status as the window procedure for the status bar, but it does not automatically set the size and position of the status information. When calling the function, you must specify the size and position of the status information as well as the device context of the window in which to draw it.

Owner-Drawn Status Bars

You can define individual parts of a status bar to be owner-drawn parts. Using this technique gives you more control than you would otherwise have over the appearance of the window part. For example, you can display a bitmap rather than text or draw text using a different font.

To define a window part as owner-drawn, send the SB_SETTEXT message to the status bar, specifying the part and the SBT_OWNERDRAW drawing technique. When SBT_OWNERDRAW is specified, the lParam parameter is a 32-bit application-defined value that the application can use when drawing the part. For example, you can specify a font handle, a bitmap handle, an address of a string, and so on.

When a status bar needs to draw an owner-drawn part, it sends the WM_DRAWITEM message to the parent window. The wParam parameter of the message is the child window identifier of the status bar, and the lParam parameter is the address of a DRAWITEMSTRUCT structure. The parent window uses the information in the structure to draw the part. For an owner-drawn part of a status bar, DRAWITEMSTRUCT contains the following information.
Member Description
CtlType Undefined; do not use.
CtlID Child window identifier of the status bar.
itemID Zero-based index of the part to be drawn.
itemAction Undefined; do not use.
itemState Undefined; do not use.
hwndItem Handle to the status bar.
hDC Handle to the device context of the status bar.
rcItem Coordinates of the window part to be drawn. The coordinates are relative to the upper left corner of the status bar.
itemData Application-defined 32-bit value specified in the lParam parameter of the SB_SETTEXT message.

Simple Mode Status Bars

You put a status bar in "simple mode" by sending it an SB_SIMPLE message. A simple mode status bar displays only one part. When the text of the window is set, the window is invalidated, but it is not redrawn until the next WM_PAINT message. Waiting for the message reduces screen flicker by minimizing the number of times the window is redrawn. A simple mode status bar is useful for displaying Help text for menu items while the user is scrolling through the menu.

The string that a status bar displays while in simple mode is maintained separately from the strings that it displays while in nonsimple mode. This means you can put the window in simple mode, set its text, and switch back to nonsimple mode without the nonsimple mode text being changed.

When setting the text of a simple mode status bar, you can specify any drawing technique except SBT_OWNERDRAW. A simple mode status bar does not support owner drawing.

Default Status Bar Message Processing

This section describes the messages handled by the window procedure for the predefined STATUSCLASSNAME class.
Message Default processing
WM_CREATE Initializes the status bar.
WM_DESTROY Frees resources allocated for the status bar.
WM_GETFONT Returns the handle to the current font with which the status bar draws its text.
WM_GETTEXT Copies the text from the first part of a status bar to a buffer. It returns a 32-bit value that specifies the length, in characters, of the text and the technique used to draw the text.
WM_GETTEXTLENGTH Returns a 32-bit value that specifies the length, in characters, of the text in the first part of a status bar and the technique used to draw the text.
WM_NCHITTEST Returns the HTBOTTOMRIGHT value if the mouse cursor is in the sizing grip, causing the system to display the sizing cursor. If the mouse cursor is not in the sizing grip, the status bar passes this message to the DefWindowProc function.
WM_PAINT Paints the invalid region of the status bar. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETFONT Selects the font handle into the device context for the status bar.
WM_SETTEXT Copies the specified text into the first part of a status bar, using the default drawing operation (specified as zero). It returns TRUE if successful, or FALSE otherwise.
WM_SIZE Resizes the status bar based on the current width of the parent window's client area and the height of the current font of the status bar.

Status Bar Example

The following example demonstrates how to create a status bar that has a sizing grip and divide the window into four equal parts based on the width of the parent window's client area. 

	// DoCreateStatusBar - creates a status bar and divides it into 
	//     the specified number of parts. 
	// Returns the handle to the status bar. 
	// hwndParent - parent window for the status bar. 
	// nStatusID - child window identifier. 
	// hinst - handle to the application instance. 
	// nParts - number of parts into which to divide the status bar. 
	HWND DoCreateStatusBar(HWND hwndParent, int nStatusID, 
	    HINSTANCE hinst, int nParts) 
	{ 
    HWND hwndStatus; 
    RECT rcClient; 
    HLOCAL hloc; 
    LPINT lpParts; 
    int i, nWidth; 
 
    // Ensure that the common control DLL is loaded. 
    InitCommonControls(); 
 
    // Create the status bar. 
    hwndStatus = CreateWindowEx( 
        0,                       // no extended styles 
        STATUSCLASSNAME,         // name of status bar class 
        (LPCTSTR) NULL,          // no text when first created 
        SBARS_SIZEGRIP |         // includes a sizing grip 
        WS_CHILD,                // creates a child window 
        0, 0, 0, 0,              // ignores size and position 
        hwndParent,              // handle to parent window 
        (HMENU) nStatusID,       // child window identifier 
        hinst,                   // handle to application instance 
        NULL);                   // no window creation data 
 
    // Get the coordinates of the parent window's client area. 
    GetClientRect(hwndParent, &rcClient); 
 
    // Allocate an array for holding the right edge coordinates. 
    hloc = LocalAlloc(LHND, sizeof(int) * nParts); 
    lpParts = LocalLock(hloc); 
 
    // Calculate the right edge coordinate for each part, and 
    // copy the coordinates to the array. 
    nWidth = rcClient.right / nParts; 
    for (i = 0; i < nParts; i++) { 
        lpParts[i] = nWidth; 
        nWidth += nWidth; 
    } 
 
    // Tell the status bar to create the window parts. 
    SendMessage(hwndStatus, SB_SETPARTS, (WPARAM) nParts, 
        (LPARAM) lpParts); 
 
    // Free the array, and return. 
    LocalUnlock(hloc); 
    LocalFree(hloc); 
    return hwndStatus; 
	}

Status Bar Updates in Internet Explorer

Status bar controls in Microsoft® Internet Explorer support the following new features.

Icon Support
Icons can now be displayed in a status bar. The SB_SETICON message is used to set the icon.
Tooltip Support
The status bar now supports tooltips. To enable tooltips, the SBT_TOOLTIPS style must be set when the status bar is created. The SB_SETTIPTEXT and SB_GETTIPTEXT messages are used to set and get the tooltip text, respectively. The tooltip for a part will only be displayed if the part has an icon and no text or if all of the text cannot be displayed inside the part. Tooltips are not supported in simple mode.
Enhanced Simple Mode Support
The SB_ISSIMPLE message has been added to determine if a status bar is in simple mode. The SBN_SIMPLEMODECHANGE notification has been added to inform the owner that the simple mode has changed.
Background Color Support
The SB_SETBKCOLOR message has been added to allow the background color of a status bar to be modified.

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