
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 Updates in Internet Explorer
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.
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.
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.
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.
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.
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. |
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.
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. |
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 controls in Microsoft® Internet Explorer support the following new features.
This section contains information about the programming elements used with status bar controls.
| Functions |
| CreateStatusWindow |
| DrawStatusText |
| MenuHelp |
| Notifications |
| NM_CLICK (status bar) |
| NM_DBLCLK (status bar) |
| NM_RCLICK (status bar) |
| NM_RDBLCLK (status bar) |
| SBN_SIMPLEMODECHANGE |
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. |
This section contains information about the functions used with status bar controls.
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.
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.
void DrawStatusText(
HDC hdc,
LPRECT lprc,
LPCTSTR pszText,
UINT uFlags
);
Draws the specified text in the style of a status window with borders.
| 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. |
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.
This section contains information about the messages used with status bar controls.
SB_GETBORDERS
wParam = 0;
lParam = (LPARAM) (LPINT) aBorders;
Retrieves the current widths of the horizontal and vertical borders of a status window.
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
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.
SB_GETRECT
wParam = (WPARAM) iPart;
lParam = (LPARAM) (LPRECT) lprc;
Retrieves the bounding rectangle of a part in a status window.
SB_GETTEXT
wParam = (WPARAM) iPart;
lParam = (LPARAM) (LPSTR) szText;
Retrieves the text from the specified part of a status window.
| 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_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. |
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
wParam = (WPARAM) iPart;
lParam = 0;
Retrieves the length, in characters, of the text from the specified part of a status window.
| 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. |
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.
Version 4.71
See also Status Bar Updates in Internet Explorer
SB_GETUNICODEFORMAT
wParam = 0;
lParam = 0;
Retrieves the UNICODE character format flag for the control.
See also SB_SETUNICODEFORMAT
SB_ISSIMPLE
wParam = 0;
lParam = 0;
Checks a status bar control to determine if it is in simple mode.
Version 4.70
SB_SETBKCOLOR
wParam = 0;
lParam = (LPARAM)(COLORREF)clrBk;
Sets the background color in a status bar.
Version 4.71
SB_SETICON
wParam = (WPARAM)(INT)iPart;
lParam = (LPARAM)(HICON)hIcon;
Sets the icon for a part in a status bar.
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
wParam = (WPARAM) minHeight;
lParam = 0;
Sets the minimum height of a status window's drawing area.
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
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.
SB_SETTEXT
wParam = (WPARAM) iPart | uType;
lParam = (LPARAM) (LPSTR) szText;
Sets the text in the specified part of a status window.
| 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. |
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
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.
Version 4.71
See also Status Bar Updates in Internet Explorer
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.
See also SB_GETUNICODEFORMAT
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.
If the status window is being changed from nonsimple to simple, or vice versa, the window is immediately redrawn.
This section contains information about the notification messages used with status bar controls.
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.
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.
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.
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.
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.
Version 4.71
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.