Status Bars

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.

Status Bar Reference

This section contains information about the programming elements used with status bar controls.

Status Bar Styles

Functions
CreateStatusWindow
DrawStatusText
MenuHelp

Messages
SB_GETBORDERS
SB_GETPARTS
SB_GETRECT
SB_GETTEXT
SB_GETTEXTLENGTH
SB_GETTIPTEXT
SB_GETUNICODEFORMAT
SB_ISSIMPLE
SB_SETBKCOLOR
SB_SETICON
SB_SETMINHEIGHT
SB_SETPARTS
SB_SETTEXT
SB_SETTIPTEXT
SB_SETUNICODEFORMAT
SB_SIMPLE

Notifications
NM_CLICK (status bar)
NM_DBLCLK (status bar)
NM_RCLICK (status bar)
NM_RDBLCLK (status bar)
SBN_SIMPLEMODECHANGE

Status Bar Styles

Status bar controls support the following style in addition to standard window styles.
SBARS_SIZEGRIP The status bar control will include a sizing grip at the right end of the status bar. A sizing grip is similar to a sizing border; it is a rectangular area that the user can click and drag to resize the parent window.

Status Bar Functions

This section contains information about the functions used with status bar controls.

CreateStatusWindow
HWND CreateStatusWindow(
    LONG style, 	
    LPCTSTR lpszText, 	
    HWND hwndParent, 	
    UINT wID	
);	

Creates a status window, which is typically used to display the status of an application. The window generally appears at the bottom of the parent window, and it contains the specified text.

style
Window styles for the status window. This parameter must include the WS_CHILD style and should also include the WS_VISIBLE style.
lpszText
Address of a null-terminated string that specifies the status text for the first part.
hwndParent
Handle to the parent window.
wID
Control identifier for the status window. The window procedure uses this value to identify messages it sends to the parent window.

The CreateStatusWindow function calls the CreateWindow function to create the window. It passes the parameters to CreateWindow without modification and sets the position, width, and height parameters to default values.

DrawStatusText
void DrawStatusText(
    HDC hdc, 	
    LPRECT lprc, 	
    LPCTSTR pszText, 	
    UINT uFlags 	
);	

Draws the specified text in the style of a status window with borders.

hdc
Handle to the display context for the window.
lprc
Address of a RECT structure that contains the position, in client coordinates, of the rectangle in which the text is drawn. The function draws the borders just inside the edges of the specified rectangle.
pszText
Address of a null-terminated string that specifies the text to display. Tab characters in the string determine whether the string is left-aligned, right-aligned, or centered.
uFlags
Text drawing flags. This parameter can be a combination of these values:
SBT_NOBORDERS Prevents borders from being drawn around the specified text.
SBT_POPOUT Draws highlighted borders that make the text stand out.
SBT_RTLREADING Displays text using right-to-left reading order on Hebrew or Arabic systems.
MenuHelp
void MenuHelp(
    UINT uMsg, 	
    WPARAM wParam, 	
    LPARAM lParam, 	
    HMENU hMainMenu, 	
    HINSTANCE hInst, 	
    HWND hwndStatus, 	
    LPUINT lpwIDs	
);	

Processes WM_MENUSELECT and WM_COMMAND messages and displays Help text about the current menu in the specified status window.

uMsg
Specifies the message being processed. This can be either WM_MENUSELECT or WM_COMMAND.
wParam
Specifies the wParam of the message specified in uMsg.
lParam
Specifies the lParam of the message specified in uMsg.
hMainMenu
Handle to the application's main menu.
hInst
Handle to the module that contains the string resources.
hwndStatus
Handle to the status window.
lpwIDs
Address of an array that contains pairs of string resource identifiers and menu handles. The function searches the array for the handle to the selected menu and, if found, uses the corresponding resource identifier to load the appropriate Help string.

Status Bar Messages

This section contains information about the messages used with status bar controls.

SB_GETBORDERS
SB_GETBORDERS 
    wParam = 0; 
    lParam = (LPARAM) (LPINT) aBorders; 

Retrieves the current widths of the horizontal and vertical borders of a status window.

aBorders
Address of an integer array that has three elements. The first element receives the width of the horizontal border, the second receives the width of the vertical border, and the third receives the width of the border between rectangles.

The borders determine the spacing between the outside edge of the window and the rectangles within the window that contain text. The borders also determine the spacing between rectangles.

SB_GETPARTS
SB_GETPARTS 
    wParam = (WPARAM) nParts; 
    lParam = (LPARAM) (LPINT) aRightCoord; 

Retrieves a count of the parts in a status window. The message also retrieves the coordinate of the right edge of the specified number of parts.

nParts
Number of parts for which to retrieve coordinates. If this parameter is greater than the number of parts in the window, the message retrieves coordinates for existing parts only.
aRightCoord
Address of an integer array that has the same number of elements as parts specified by nParts. Each element in the array receives the client coordinate of the right edge of the corresponding part. If an element is set to -1, the position of the right edge for that part extends to the right edge of the window. To retrieve the current number of parts, set this parameter to zero.
SB_GETRECT
SB_GETRECT 
    wParam = (WPARAM) iPart; 
    lParam = (LPARAM) (LPRECT) lprc; 

Retrieves the bounding rectangle of a part in a status window.

iPart
Zero-based index of the part whose bounding rectangle is to be retrieved.
lprc
Address of a RECT structure that receives the bounding rectangle.
SB_GETTEXT
SB_GETTEXT 
    wParam = (WPARAM) iPart; 
    lParam = (LPARAM) (LPSTR) szText; 

Retrieves the text from the specified part of a status window.

iPart
Zero-based index of the part from which to retrieve text.
szText
Address of the buffer that receives the text. This parameter is a null-terminated string.

If the text has the SBT_OWNERDRAW drawing type, this message returns the 32-bit value associated with the text instead of the length and operation type.

SB_GETTEXTLENGTH
SB_GETTEXTLENGTH 
    wParam = (WPARAM) iPart; 
    lParam = 0; 

Retrieves the length, in characters, of the text from the specified part of a status window.

iPart
Zero-based index of the part from which to retrieve text.
SB_GETTIPTEXT
SB_GETTIPTEXT
    wParam = MAKEWPARAM(iPart, nSize);
    lParam = (LPARAM)(LPCTSTR)lpszTooltip;

Retrieves the tooltip text for a part in a status bar. The status bar must have been created with the SBT_TOOLTIPS style to enable tooltips.

iPart
Zero-based index of the part that will receive the tooltip text.
nSize
Size of the buffer at lpszTooltip, in characters.
lpszTooltip
Address of a character buffer that receives the tooltip text.

Version 4.71

See also Status Bar Updates in Internet Explorer

SB_GETUNICODEFORMAT
SB_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Retrieves the UNICODE character format flag for the control.

See also SB_SETUNICODEFORMAT

SB_ISSIMPLE
SB_ISSIMPLE
    wParam = 0;
    lParam = 0;

Checks a status bar control to determine if it is in simple mode.

Version 4.70

SB_SETBKCOLOR
SB_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBk;

Sets the background color in a status bar.

clrBk
COLORREF value that specifies the new background color. Specify the CLR_DEFAULT value to cause the status bar to use its default background color.

Version 4.71

SB_SETICON
SB_SETICON
    wParam = (WPARAM)(INT)iPart;
    lParam = (LPARAM)(HICON)hIcon;

Sets the icon for a part in a status bar.

iPart
Zero-based index of the part that will receive the icon. If this parameter is -1, the status bar is assumed to be a simple status bar.
hIcon
Handle to the icon to be set. If this value is NULL, the icon is removed from the part.

The status bar will not destroy the icon. It is the calling application's responsibility to keep track of and destroy any icons.

Version 4.71

SB_SETMINHEIGHT
SB_SETMINHEIGHT 
    wParam = (WPARAM) minHeight; 
    lParam = 0; 

Sets the minimum height of a status window's drawing area.

minHeight
Minimum height, in pixels, of the window.

The minimum height is the sum of wParam and twice the width, in pixels, of the vertical border of the status window. An application must send the WM_SIZE message to the status window to redraw the window. The wParam and lParam parameters of the WM_SIZE message should be set to zero.

SB_SETPARTS
SB_SETPARTS 
    wParam = (WPARAM) nParts; 
    lParam = (LPARAM) (LPINT) aWidths; 

Sets the number of parts in a status window and the coordinate of the right edge of each part.

nParts
Number of parts to set (cannot be greater than 255).
aWidths
Address of an integer array that has the same number of elements as parts specified by nParts. Each element in the array specifies the position, in client coordinates, of the right edge of the corresponding part. If an element is -1, the position of the right edge for that part extends to the right edge of the window.
SB_SETTEXT
SB_SETTEXT 
    wParam = (WPARAM) iPart | uType; 
    lParam = (LPARAM) (LPSTR) szText; 

Sets the text in the specified part of a status window.

iPart
Zero-based index of the part to set. If this value is 255, the status window is assumed to be a simple window having only one part.
uType
Type of drawing operation. This parameter can be one of the following values:
0 The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS The text is drawn without borders.
SBT_OWNERDRAW The text is drawn by the parent window.
SBT_POPOUT The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING Displays text using right-to-left reading order on Hebrew or Arabic systems.
szText
Address of a null-terminated string that specifies the text to set. If uType is SBT_OWNERDRAW, this parameter represents 32 bits of data. The parent window must interpret the data and draw the text when it receives the WM_DRAWITEM message. The text for each part is limited to 127 characters.

The message invalidates the portion of the window that has changed, causing it to display the new text when the window next receives the WM_PAINT message.

SB_SETTIPTEXT
SB_SETTIPTEXT
    wParam = (WPARAM)(INT)iPart;
    lParam = (LPARAM)(LPCTSTR)lpszTooltip;

Sets the tooltip text for a part in a status bar. The status bar must have been created with the SBT_TOOLTIPS style to enable tooltips.

iPart
Zero-based index of the part that will receive the tooltip text.
lpszTooltip
Address of a character buffer that contains the new tooltip text.

Version 4.71

See also Status Bar Updates in Internet Explorer

SB_SETUNICODEFORMAT
SB_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also SB_GETUNICODEFORMAT

SB_SIMPLE
SB_SIMPLE 
    wParam = (WPARAM) (BOOL) fSimple; 
    lParam = 0; 

Specifies whether a status window displays simple text or displays all window parts set by a previous SB_SETPARTS message.

fSimple
Display type flag. If this parameter is TRUE, the window displays simple text. If it is FALSE, it displays multiple parts.

If the status window is being changed from nonsimple to simple, or vice versa, the window is immediately redrawn.

Status Bar Notifications

This section contains information about the notification messages used with status bar controls.

NM_CLICK (status bar)
NM_CLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a status bar control's parent window that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.
NM_DBLCLK (status bar)
NM_DBLCLK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a status bar control's parent window that the user has double-clicked the left mouse button within the control. NM_DBLCLK is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.
NM_RCLICK (status bar)
NM_RCLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a status bar control's parent window that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.
NM_RDBLCLK (status bar)
NM_RDBLCLK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a status bar control's parent window that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.
SBN_SIMPLEMODECHANGE
SBN_SIMPLEMODECHANGE
    lpnmh = (NMHDR*) lParam;

Sent by a status bar control when the simple mode changes due to a SB_SIMPLE message. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains information about the notification.

Version 4.71

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.