CStatusBarCtrl Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CStatusBarCtrl Class.

Provides the functionality of the Windows common status bar control.

Syntax

class CStatusBarCtrl : public CWnd

Members

Public Constructors

Name	Description
CStatusBarCtrl::CStatusBarCtrl	Constructs a `CStatusBarCtrl` object.

Public Methods

Name	Description
CStatusBarCtrl::Create	Creates a status bar control and attaches it to a `CStatusBarCtrl` object.
CStatusBarCtrl::CreateEx	Creates a status bar control with the specified Windows extended styles and attaches it to a `CStatusBarCtrl` object.
CStatusBarCtrl::DrawItem	Called when a visual aspect of an owner-draw status bar control changes.
CStatusBarCtrl::GetBorders	Retrieves the current widths of the horizontal and vertical borders of a status bar control.
CStatusBarCtrl::GetIcon	Retrieves the icon for a part (also known as a pane) in the current status bar control.
CStatusBarCtrl::GetParts	Retrieves a count of the parts in a status bar control.
CStatusBarCtrl::GetRect	Retrieves the bounding rectangle of a part in a status bar control.
CStatusBarCtrl::GetText	Retrieves the text from the given part of a status bar control.
CStatusBarCtrl::GetTextLength	Retrieve the length, in characters, of the text from the given part of a status bar control.
CStatusBarCtrl::GetTipText	Retrieves the tooltip text for a pane in a status bar.
CStatusBarCtrl::IsSimple	Checks a status window control to determine if it is in simple mode.
CStatusBarCtrl::SetBkColor	Sets the background color in a status bar.
CStatusBarCtrl::SetIcon	Sets the icon for a pane in a status bar.
CStatusBarCtrl::SetMinHeight	Sets the minimum height of a status bar control's drawing area.
CStatusBarCtrl::SetParts	Sets the number of parts in a status bar control and the coordinate of the right edge of each part.
CStatusBarCtrl::SetSimple	Specifies whether a status bar control displays simple text or displays all control parts set by a previous call to `SetParts`.
CStatusBarCtrl::SetText	Sets the text in the given part of a status bar control.
CStatusBarCtrl::SetTipText	Sets the tooltip text for a pane in a status bar.

Remarks

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.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CStatusBarCtrl

Requirements

Header: afxcmn.h

CStatusBarCtrl::Create

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

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

Parameters

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.

Return Value

Nonzero if successful; otherwise zero.

Remarks

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.

Example

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

CStatusBarCtrl::CreateEx

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);

Parameters

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.

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.

Return Value

Nonzero if successful; otherwise 0.

Remarks

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

CStatusBarCtrl::CStatusBarCtrl

Constructs a CStatusBarCtrl object.

CStatusBarCtrl();

CStatusBarCtrl::DrawItem

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

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

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

Remarks

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.

CStatusBarCtrl::GetBorders

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;

Parameters

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.

Return Value

Nonzero if successful; otherwise zero.

Remarks

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

Example

      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));

CStatusBarCtrl::GetIcon

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

HICON GetIcon(int iPart) const;

Parameters

Parameter	Description
[in] `iPart`	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.

Return Value

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

Remarks

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.

Example

The following 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;

Example

The following 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 );

CStatusBarCtrl::GetParts

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

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

Parameters

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.

Return Value

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

Remarks

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

Example

      int pParts[2];

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

CStatusBarCtrl::GetRect

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

BOOL GetRect(
    int nPane,  
    LPRECT lpRect) const;

Parameters

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.

Return Value

Nonzero if successful; otherwise zero.

Example

      CRect rectPane1;

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

CStatusBarCtrl::GetText

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;

Parameters

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.

Return Value

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

Example

      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;

CStatusBarCtrl::GetTextLength

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;

Parameters

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.

Return Value

The length, in characters, of the text.

Example

      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;
      }

CStatusBarCtrl::GetTipText

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

CString GetTipText(int nPane) const;

Parameters

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

Return Value

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

Remarks

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

Example

      CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl::IsSimple

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

BOOL IsSimple() const;

Return Value

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

Remarks

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

CStatusBarCtrl::SetBkColor

Sets the background color in a status bar.

COLORREF SetBkColor(COLORREF cr);

Parameters

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.

Return Value

A COLORREF value that represents the previous default background color.

Remarks

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

Example

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

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

CStatusBarCtrl::SetIcon

Sets the icon for a pane in a status bar.

BOOL SetIcon(
    int nPane,  
    HICON hIcon);

Parameters

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.

Return Value

Nonzero if successful; otherwise zero.

Remarks

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

Example

See the example for CStatusBarCtrl::SetBkColor.

CStatusBarCtrl::SetMinHeight

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

void SetMinHeight(int nMin);

Parameters

nMin
Minimum height, in pixels, of the control.

Remarks

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

Example

      m_wndSBC.SetMinHeight(40);

CStatusBarCtrl::SetParts

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);

Parameters

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.

Return Value

Nonzero if successful; otherwise zero.

Example

      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));

CStatusBarCtrl::SetSimple

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);

Parameters

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

Return Value

Always returns 0.

Remarks

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

CStatusBarCtrl::SetText

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

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

Parameters

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.

Return Value

Nonzero if successful; otherwise zero.

Remarks

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.

Example

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

CStatusBarCtrl::SetTipText

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

void SetTipText(
    int nPane,  
    LPCTSTR pszTipText);

Parameters

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

pszTipText
A pointer to a string containing the tooltip text.

Remarks

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

Example

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

Share via

CStatusBarCtrl Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CStatusBarCtrl::Create

Parameters

Return Value

Remarks

Example

CStatusBarCtrl::CreateEx

Parameters

Return Value

Remarks

CStatusBarCtrl::CStatusBarCtrl

CStatusBarCtrl::DrawItem

Parameters

Remarks

CStatusBarCtrl::GetBorders

Parameters

Return Value

Remarks

Example

CStatusBarCtrl::GetIcon

Parameters

Return Value

Remarks

Example

Example

CStatusBarCtrl::GetParts

Parameters

Return Value

Remarks

Example

CStatusBarCtrl::GetRect

Parameters

Return Value

Example

CStatusBarCtrl::GetText

Parameters

Return Value

Example

CStatusBarCtrl::GetTextLength

Parameters

Return Value

Example

CStatusBarCtrl::GetTipText

Parameters

Return Value

Remarks

Example

CStatusBarCtrl::IsSimple

Return Value

Remarks

CStatusBarCtrl::SetBkColor

Parameters

Return Value

Remarks

Example

CStatusBarCtrl::SetIcon

Parameters

Return Value

Remarks

Example

CStatusBarCtrl::SetMinHeight

Parameters

Remarks

Example

CStatusBarCtrl::SetParts

Parameters

Return Value

Example

CStatusBarCtrl::SetSimple

Parameters

Return Value

Remarks