CStatusBarCtrl Class

Provides the functionality of the Windows common status bar control.

class CStatusBarCtrl : public CWnd

A "status bar control" is a horizontal window, usually displayed at the bottom of a parent window, in which an application can display various kinds of status information. The status bar control can be divided into parts to display more than one type of information.

This control (and therefore the CStatusBarCtrl class) is available only to programs running under Windows 95/98 and Windows NT version 3.51 and later.

For more information on using CStatusBarCtrl, see Controls and Using CStatusBarCtrl.

CObject

CCmdTarget

CWnd

CStatusBarCtrl

Header: afxcmn.h

Creates a status bar control and attaches it to a CStatusBarCtrl object.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

dwStyle
Specifies the status bar control's style. Apply any combination of status bar control styles listed in Common Control Styles in the Windows SDK. This parameter must include the WS_CHILD style. It should also include the WS_VISIBLE style.

rect
Specifies the status bar control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the status bar control's parent window, usually a CDialog. It must not be NULL.

nID
Specifies the status bar control's ID.

Nonzero if successful; otherwise zero.

You construct a CStatusBarCtrl in two steps. First, call the constructor, and then call Create, which creates the status bar control and attaches it to the CStatusBarCtrl object.

The default position of a status window 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 window. Combining the CCS_TOP and SBARS_SIZEGRIP styles is not recommended, because the resulting sizing grip is not functional even though the system draws it in the status window.

To create a status bar with extended window styles, call CStatusBarCtrl::CreateEx instead of Create.

VERIFY(m_wndSBC.Create(WS_CHILD | WS_VISIBLE | CCS_BOTTOM | SBARS_SIZEGRIP,
                       CRect(0, 0, 0, 0), this, IDC_STATUSBARCTRL));

Creates a control (a child window) and associates it with the CStatusBarCtrl object.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

dwExStyle
Specifies the extended style of the control being created. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

dwStyle
Specifies the status bar control's style. Apply any combination of status bar control styles listed in Common Control Styles in the Windows SDK. This parameter must include the WS_CHILD style. It should also include the WS_VISIBLE style.

rect
A reference to a RECT structure describing the size and position of the window to be created, in client coordinates of pParentWnd.

pParentWnd
A pointer to the window that is the control's parent.

nID
The control's child-window ID.

Nonzero if successful; otherwise 0.

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_.

Constructs a CStatusBarCtrl object.

CStatusBarCtrl();

Called by the framework when a visual aspect of an owner-draw status bar control changes.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

lpDrawItemStruct
A long pointer to a DRAWITEMSTRUCT structure that contains information about the type of drawing required.

The itemAction member of the DRAWITEMSTRUCT structure defines the drawing action that is to be performed.

By default, this member function does nothing. Override this member function to implement drawing for an owner-draw CStatusBarCtrl object.

The application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct before this member function terminates.

Retrieves the status bar control's current widths of the horizontal and vertical borders and of the space between rectangles.

BOOL GetBorders(int* pBorders) const;

BOOL GetBorders(
    int& nHorz,
    int& nVert,
    int& nSpacing) const;

pBorders
Address of an integer array having 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.

nHorz
Reference to an integer that receives the width of the horizontal border.

nVert
Reference to an integer that receives the width of the vertical border.

nSpacing
Reference to an integer that receives the width of the border between rectangles.

Nonzero if successful; otherwise zero.

These borders determine the spacing between the outside edge of the control and the rectangles within the control that contain text.

RECT rectPane1;
VERIFY(m_wndSBC.GetRect(1, &rectPane1));

int borderArray[3];
VERIFY(m_wndSBC.GetBorders(borderArray));

int nHorz, nVert, nSpacing;
VERIFY(m_wndSBC.GetBorders(nHorz, nVert, nSpacing));

Retrieves the icon for a part (also known as a pane) in the current status bar control.

HICON GetIcon(int iPart) const;

iPart
[in] The zero-based index of the part that contains the icon to be retrieved. If this parameter is -1, the status bar is assumed to be a simple mode status bar.

The handle to the icon if the method successful; otherwise, NULL.

This method sends the SB_GETICON message, which is described in the Windows SDK.

A status bar control consists of a row of text output panes, which are also known as parts. For more information about the status bar, see Status Bar Implementation in MFC and Setting the Mode of a CStatusBarCtrl Object.

The first code example defines a variable, m_statusBar, that is used to access the current status bar control. This variable is used in the next example.

public:
CStatusBarCtrl m_statusBar;

The next code example copies an icon to two panes of the current status bar control. In an earlier section of the code example we created a status bar control with three panes and then added an icon to the first pane. This example retrieves the icon from the first pane and then adds it to the second and third pane.

// Get the icon from pane 1 and set it in panes 2 and 3.
HICON hIcon = m_statusBar.GetIcon(0);
m_statusBar.SetIcon(1, hIcon);
m_statusBar.SetIcon(2, hIcon);

Retrieves a count of the parts in a status bar control.

int GetParts(
    int nParts,
    int* pParts) const;

nParts
Number of parts for which to retrieve coordinates. If this parameter is greater than the number of parts in the control, the message retrieves coordinates for existing parts only.

pParts
Address of an integer array having the same number of elements as the number of 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 status bar.

The number of parts in the control if successful, or zero otherwise.

This member function also retrieves the coordinate of the right edge of the given number of parts.

int pParts[2];

int nParts = m_wndSBC.GetParts(2, pParts);

Retrieves the bounding rectangle of a part in a status bar control.

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

nPane
Zero-based index of the part whose bounding rectangle is to be retrieved.

lpRect
Address of a RECT structure that receives the bounding rectangle.

Nonzero if successful; otherwise zero.

CRect rectPane1;

VERIFY(m_wndSBC.GetRect(1, &rectPane1));

Retrieves the text from the given part of a status bar control.

CString GetText(
    int nPane,
    int* pType = NULL) const;

int GetText(
    LPCTSTR lpszText,
    int nPane,
    int* pType = NULL) const;

lpszText
Address of the buffer that receives the text. This parameter is a null-terminated string.

nPane
Zero-based index of the part from which to retrieve text.

pType
Pointer to an integer that receives the type information. The type can be one of these values:

• 0 The text is drawn with a border to appear lower than the plane of the status bar.

• 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 status bar.

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

The length, in characters, of the text or a CString containing the current text.

int nType;
TCHAR *pszPaneOneText;

pszPaneOneText = new TCHAR[m_wndSBC.GetTextLength(1, &nType) + 1];
int nTextLength = m_wndSBC.GetText(pszPaneOneText, 1, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

delete pszPaneOneText;

Retrieves the length, in characters, of the text from the given part of a status bar control.

int GetTextLength(
    int nPane,
    int* pType = NULL) const;

nPane
Zero-based index of the part from which to retrieve text.

pType
Pointer to an integer that receives the type information. The type can be one of these values:

• 0 The text is drawn with a border to appear lower than the plane of the status bar.

• 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 status bar.

The length, in characters, of the text.

int nType;
int nLength = m_wndSBC.GetTextLength(0, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

Retrieves the tooltip text for a pane in a status bar.

CString GetTipText(int nPane) const;

nPane
The zero-based index of status bar pane to receive the tooltip text.

A CString object containing the text to be used in the tooltip.

This member function implements the behavior of the Win32 message SB_GETTIPTEXT, as described in the Windows SDK.

CString csPane0TipText = m_wndSBC.GetTipText(0);

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

BOOL IsSimple() const;

Nonzero if the status window control is in simple mode; otherwise zero.

This member function implements the behavior of the Win32 message SB_ISSIMPLE, as described in the Windows SDK.

Sets the background color in a status bar.

COLORREF SetBkColor(COLORREF cr);

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

A COLORREF value that represents the previous default background color.

This member function implements the behavior of the Win32 message SB_SETBKCOLOR, as described in the Windows SDK.

m_wndSBC.SetBkColor(RGB(0, 0, 250));

HICON hIcon = AfxGetApp()->LoadIcon(IDI_PANE_0_ICON);
VERIFY(hIcon);
VERIFY(m_wndSBC.SetIcon(0, hIcon));

Sets the icon for a pane in a status bar.

BOOL SetIcon(
    int nPane,
    HICON hIcon);

nPane
The zero-based index of the pane 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.

Nonzero if successful; otherwise zero.

This member function implements the behavior of the Win32 message SB_SETICON, as described in the Windows SDK.

See the example for CStatusBarCtrl::SetBkColor.

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

void SetMinHeight(int nMin);

nMin
Minimum height, in pixels, of the control.

The minimum height is the sum of nMin and twice the width, in pixels, of the vertical border of the status bar control.

m_wndSBC.SetMinHeight(40);

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

BOOL SetParts(
    int nParts,
    int* pWidths);

nParts
Number of parts to set. The number of parts cannot be greater than 255.

pWidths
Address of an integer array having 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 control.

Nonzero if successful; otherwise zero.

const int c_nParts = 4;
CRect rect;

m_wndSBC.GetClientRect(&rect);
int aWidths[c_nParts] = {rect.right - 300, rect.right - 200, rect.right - 100,
                         -1};

VERIFY(m_wndSBC.SetParts(c_nParts, aWidths));

Specifies whether a status bar control displays simple text or displays all control parts set by a previous call to SetParts.

BOOL SetSimple(BOOL bSimple = TRUE);

bSimple
[in] Display-type flag. If this parameter is TRUE, the control displays simple text; if it is FALSE, it displays multiple parts.

Always returns 0.

If your application changes the status bar control from non-simple to simple, or vice versa, the system immediately redraws the control.

Sets the text in the given part of a status bar control.

BOOL SetText(
    LPCTSTR lpszText,
    int nPane,
    int nType);

lpszText
Address of a null-terminated string specifying the text to set. If nType is SBT_OWNERDRAW, lpszText represents 32 bits of data.

nPane
Zero-based index of the part to set. If this value is 255, the status bar control is assumed to be a simple control having only one part.

nType
Type of drawing operation. See SB_SETTEXT message for a list of possible values.

Nonzero if successful; otherwise zero.

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

VERIFY(m_wndSBC.SetText(_T("Text For Pane 1"), 1, 0));

Sets the tooltip text for a pane in a status bar.

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

nPane
The zero-based index of status bar pane to receive the tooltip text.

pszTipText
A pointer to a string containing the tooltip text.

This member function implements the behavior of the Win32 message SB_SETTIPTEXT, as described in the Windows SDK.

m_wndSBC.SetTipText(0, _T("This is Pane 0"));

CWnd Class
Hierarchy Chart
CToolBarCtrl Class