CMFCRibbonStatusBar Class

 

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 CMFCRibbonStatusBar Class.

The CMFCRibbonStatusBar class implements a status bar control that can display ribbon elements.

Syntax

class CMFCRibbonStatusBar : public CMFCRibbonBar  

Members

Public Methods

Name Description
CMFCRibbonStatusBar::AddDynamicElement Adds a dynamic element to the ribbon status bar.
CMFCRibbonStatusBar::AddElement Adds a new ribbon element to the ribbon status bar.
CMFCRibbonStatusBar::AddExtendedElement Adds a ribbon element to the extended area of the ribbon status bar.
CMFCRibbonStatusBar::AddSeparator Adds a separator to the ribbon status bar.
CMFCRibbonStatusBar::Create Creates a ribbon status bar.
CMFCRibbonStatusBar::CreateEx Creates a ribbon status bar with an extended style.
CMFCRibbonStatusBar::FindByID
CMFCRibbonStatusBar::FindElement Returns a pointer to the element that has the specified command ID.
CMFCRibbonStatusBar::GetCount Returns the number of elements that are located in the main area of the ribbon status bar.
CMFCRibbonStatusBar::GetElement Returns a pointer to the element that is located at a specified index.
CMFCRibbonStatusBar::GetExCount Returns the number of elements that are located in the extended area of the ribbon status bar.
CMFCRibbonStatusBar::GetExElement Returns a pointer to the element that is located at a specified index in the extended area of the ribbon status bar.
CMFCRibbonStatusBar::GetExtendedArea
CMFCRibbonStatusBar::GetSpace
CMFCRibbonStatusBar::IsBottomFrame
CMFCRibbonStatusBar::IsExtendedElement
CMFCRibbonStatusBar::IsInformationMode Determines whether information mode is enabled for the ribbon status bar.
CMFCRibbonStatusBar::RecalcLayout (Overrides CMFCRibbonBar::RecalcLayout.)
CMFCRibbonStatusBar::RemoveAll Removes all elements from the ribbon status bar.
CMFCRibbonStatusBar::RemoveElement Removes the element that has a specified command ID from the ribbon status bar.
CMFCRibbonStatusBar::SetInformation Enables or disables the information mode for the ribbon status bar.

Protected Methods

Name Description
CMFCRibbonStatusBar::OnDrawInformation Displays the information string that appears on the ribbon status bar when the information mode is enabled.

Remarks

Users can change the visibility of ribbon elements on a ribbon status bar by using the built-in context menu for the ribbon status bar. You can add or remove elements dynamically.

A ribbon status bar has two areas: a main area and an extended area. The extended area is displayed on the right side of the ribbon status bar and appears in a different color than the main area does.

Typically, the main area of the status bar displays status notifications, and the extended area displays view controls. The extended area remains visible as long as possible when the user resizes the ribbon status bar.

Example

The following example demonstrates how to use various methods in the CMFCRibbonStatusBar class. The example shows how to add a new ribbon element to the ribbon status bar, add a ribbon element to the extended area of the ribbon status bar, add a separator, and enable the regular mode for the ribbon status bar.

 // CMFCRibbonStatusBar  m_wndStatusBar
    m_wndStatusBar.AddElement(rsbp, strTitlePane1);
    m_wndStatusBar.AddExtendedElement(new CMFCRibbonStatusBarPane(ID_STATUSBAR_PANE2, strTitlePane2, TRUE), 
        strTitlePane2);
   m_wndStatusBar.AddSeparator();
    m_wndStatusBar.SetInformation(NULL);

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCRibbonBar

CMFCRibbonStatusBar

Requirements

Header: afxribbonstatusbar.h

CMFCRibbonStatusBar::AddDynamicElement

Adds a dynamic element to the ribbon status bar.

void AddDynamicElement(CMFCRibbonBaseElement* pElement);

Parameters

[in] pElement
A pointer to a dynamic element.

Remarks

Unlike regular elements, dynamic elements are not customizable and the customize menu of the status bar does not display them.

CMFCRibbonStatusBar::AddElement

Adds a new ribbon element to the ribbon status bar.

void AddElement(
    CMFCRibbonBaseElement* pElement,  
    LPCTSTR lpszLabel,  
    BOOL bIsVisible=TRUE);

Parameters

[in] pElement
A pointer to the added element.

[in] lpszLabel
A text label of the element.

[in] bIsVisible
TRUE if you want to add the element as visible, FALSE if you want to add the element as hidden.

CMFCRibbonStatusBar::AddExtendedElement

Adds a ribbon element to the extended area of the ribbon status bar.

void AddExtendedElement(
    CMFCRibbonBaseElement* pElement,  
    LPCTSTR lpszLabel,  
    BOOL bIsVisible=TRUE);

Parameters

[in] pElement
A pointer to the added element.

[in] lpszLabel
The text label of the element.

[in] bIsVisible
TRUE if you want to add the element as visible, FALSE if you want to add the element as hidden.

Remarks

The extended area is on the right side of the status bar control.

CMFCRibbonStatusBar::AddSeparator

Adds a separator to the ribbon status bar.

void AddSeparator();

Remarks

The framework adds a separator after the method CMFCRibbonStatusBar::AddElement. inserts the last element.

CMFCRibbonStatusBar::Create

Creates a ribbon status bar.

BOOL Create(
    CWnd* pParentWnd,  
    DWORD dwStyle=WS_CHILD|WS_VISIBLE|CBRS_BOTTOM,  
    UINT nID=AFX_IDW_STATUS_BAR);

Parameters

[in] pParentWnd
A pointer to the parent window.

[in] dwStyle
A logical OR combination of control styles.

[in] nID
The control ID of the status bar.

Return Value

TRUE if the status bar is created successfully, FALSE otherwise.

CMFCRibbonStatusBar::CreateEx

Creates a ribbon status bar that has an extended style.

BOOL CreateEx(
    CWnd* pParentWnd,  
    DWORD dwCtrlStyle=0,  
    DWORD dwStyle=WS_CHILD|WS_VISIBLE|CBRS_BOTTOM,  
    UINT nID=AFX_IDW_STATUS_BAR);

Parameters

pParentWnd
A pointer to the parent window.

dwCtrlStyle
A logical OR combination of additional styles for creating the status bar object.

dwStyle
The control style of the status bar.

nID
The control ID of the status bar.

Return Value

TRUE if the status bar is created successfully, FALSE otherwise.

CMFCRibbonStatusBar::FindByID

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

CMFCRibbonBaseElement* FindByID(UINT uiCmdID, BOOL = TRUE);

Parameters

[in] uiCmdID
[in] BOOL

Return Value

Remarks

CMFCRibbonStatusBar::FindElement

Returns a pointer to the element that has the specified command ID.

CMFCRibbonBaseElement* FindElement(UINT uiID);

Parameters

[in] uiID
The ID of the element.

Return Value

A pointer to the element that has the specified command ID. NULL if there is no such element.

CMFCRibbonStatusBar::GetCount

Returns the number of elements that are located in the main area of the ribbon status bar.

int GetCount() const;  

Return Value

The number of elements that are located in the main area of the ribbon status bar.

CMFCRibbonStatusBar::GetElement

Returns a pointer to the element that is located at a specified index.

CMFCRibbonBaseElement* GetElement(int nIndex);

Parameters

[in] nIndex
Specifies a zero-based index of an element that is located in the main area of the status bar control.

Return Value

A pointer to the element that is located at the specified index. NULL if the index is negative or exceeds the number of elements in the status bar.

Remarks

CMFCRibbonStatusBar::GetExCount

Returns the number of elements that are located in the extended area of the ribbon status bar.

int GetExCount() const;  

Return Value

The number of elements that are located in the extended area of the ribbon status bar.

CMFCRibbonStatusBar::GetExElement

Returns a pointer to the element that is located at a specified index in the extended area of the ribbon status bar. The extended area is on the right side of the status bar control.

CMFCRibbonBaseElement* GetExElement(int nIndex);

Parameters

[in] nIndex
Specifies the zero-based index of an element that is located in the extended area of the status bar control.

Return Value

A pointer to the element that is located at a specified index in the extended area of the ribbon status bar. NULL if nIndex is negative or exceeds the number of elements in the extended area of the ribbon status bar.

Remarks

CMFCRibbonStatusBar::GetExtendedArea

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual BOOL GetExtendedArea(CRect& rect) const;  

Parameters

[in] rect

Return Value

Remarks

CMFCRibbonStatusBar::GetSpace

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

int GetSpace() const;  

Return Value

Remarks

CMFCRibbonStatusBar::IsBottomFrame

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

BOOL IsBottomFrame() const;  

Return Value

Remarks

CMFCRibbonStatusBar::IsExtendedElement

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

BOOL IsExtendedElement(CMFCRibbonBaseElement* pElement) const;  

Parameters

[in] pElement

Return Value

Remarks

CMFCRibbonStatusBar::IsInformationMode

Determines whether information mode is enabled for the ribbon status bar.

BOOL IsInformationMode() const;  

Return Value

TRUE if the status bar can work in information mode; otherwise FALSE.

Remarks

In information mode, the status bar hides all regular panes and displays a message string.

CMFCRibbonStatusBar::OnDrawInformation

Displays the string that appears on the ribbon status bar when the information mode is enabled.

virtual void OnDrawInformation(
    CDC* pDC,  
    CString& strInfo,  
    CRect rectInfo);

Parameters

[in] pDC
A pointer to a device context.

[in] strInfo
The information string.

[in] rectInfo
The bounding rectangle.

Remarks

Override this method in a derived class if you want to customize the appearance of the information string on the status bar. Use the CMFCRibbonStatusBar::SetInformation method to put the status bar in information mode. In this mode, the status bar hides all panes and displays the information string specified by strInfo.

CMFCRibbonStatusBar::RecalcLayout

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual void RecalcLayout();

Remarks

CMFCRibbonStatusBar::RemoveAll

Removes all elements from the ribbon status bar.

void RemoveAll();

CMFCRibbonStatusBar::RemoveElement

Removes the element that has a specified command ID from the ribbon status bar.

BOOL RemoveElement(UINT uiID);

Parameters

[in] uiID
The ID of the element to remove from the status bar.

Return Value

TRUE if an element with the specified uiID is removed. FALSE otherwise.

CMFCRibbonStatusBar::SetInformation

Enables or disables the information mode for the ribbon status bar.

void SetInformation(LPCTSTR lpszInfo);

Parameters

[in] lpszInfo
The information string.

Remarks

Use this method to put the status bar in the information mode. In this mode, the status bar hides all panes and displays the information string specified by lpszInfo.

When lpszInfo is NULL, the status bar reverts to regular mode.

See Also

Hierarchy Chart
Classes
CMFCRibbonBar Class
CMFCRibbonBaseElement Class
CMFCRibbonBar Class