CMFCRibbonBar Class

The CMFCRibbonBar class implements a ribbon bar similar to that used in Office 2007.

For more detail, see the source code located in the mfc folder of your Visual Studio installation. For example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

Syntax

class CMFCRibbonBar : public CPane

Members

Public Constructors

Name Description
CMFCRibbonBar::CMFCRibbonBar Default constructor.

Public Methods

Name Description
CMFCRibbonBar::ActivateContextCategory Activates a context category that is already visible.
CMFCRibbonBar::AddCategory Adds a new ribbon category to the ribbon.
CMFCRibbonBar::AddContextCategory Adds a context category.
CMFCRibbonBar::AddMainCategory Adds a new main ribbon category.
CMFCRibbonBar::AddPrintPreviewCategory
CMFCRibbonBar::AddQATOnlyCategory
CMFCRibbonBar::AddToTabs Add a ribbon element to the right side of a ribbon bar.
CMFCRibbonBar::CreateEx Creates a control bar and attaches it to the CPane object. (Overrides CPane::CreateEx.)
CMFCRibbonBar::Create Creates a ribbon bar control and attaches it to a ribbon bar.
CMFCRibbonBar::DeactivateKeyboardFocus
CMFCRibbonBar::DrawMenuImage
CMFCRibbonBar::DWMCompositionChanged
CMFCRibbonBar::EnableKeyTips Enable or disable key tips for the ribbon control.
CMFCRibbonBar::EnablePrintPreview Enable the Print Preview tab.
CMFCRibbonBar::EnableToolTips Enables or disables tooltips and tooltip descriptions on the ribbon bar.
CMFCRibbonBar::FindByData Find a ribbon element by using data that a user specifies.
CMFCRibbonBar::FindByID Finds a ribbon element that has the specified command ID.
CMFCRibbonBar::FindCategoryIndexByData Finds the index of the ribbon category that contains the user-defined data.
CMFCRibbonBar::ForceRecalcLayout
CMFCRibbonBar::GetActiveCategory Gets a pointer to an active category.
CMFCRibbonBar::GetCaptionHeight Returns the caption height. (Overrides CBasePane::GetCaptionHeight.)
CMFCRibbonBar::GetCategory Gets the pointer to a category located at a specified index.
CMFCRibbonBar::GetCategoryCount Gets the number of the ribbon categories in the ribbon bar.
CMFCRibbonBar::GetCategoryHeight
CMFCRibbonBar::GetCategoryIndex Returns the index of a ribbon category.
CMFCRibbonBar::GetContextName Retrieves the name of the context category caption that you specify by using an ID.
CMFCRibbonBar::GetDroppedDown
CMFCRibbonBar::GetElementsByID Gets an array that contains the pointers to all the ribbon elements that have the specified ID.
CMFCRibbonBar::GetApplicationButton Gets a pointer to a ribbon button.
CMFCRibbonBar::GetFocused Returns a focused element.
CMFCRibbonBar::GetHideFlags
CMFCRibbonBar::GetItemIDsList
CMFCRibbonBar::GetKeyboardNavigationLevel
CMFCRibbonBar::GetKeyboardNavLevelCurrent
CMFCRibbonBar::GetKeyboardNavLevelParent
CMFCRibbonBar::GetMainCategory Returns a pointer to the ribbon category that is currently selected.
CMFCRibbonBar::GetQATCommandsLocation
CMFCRibbonBar::GetQATDroppedDown
CMFCRibbonBar::GetQuickAccessCommands Fills a list that contains the command IDs of all the elements that appear on the Quick Access Toolbar.
CMFCRibbonBar::GetQuickAccessToolbarLocation
CMFCRibbonBar::GetTabTrancateRatio
CMFCRibbonBar::GetTooltipFixedWidthLargeImage
CMFCRibbonBar::GetTooltipFixedWidthRegular
CMFCRibbonBar::GetVisibleCategoryCount
CMFCRibbonBar::HideAllContextCategories Hides all the categories that are active and visible.
CMFCRibbonBar::HideKeyTips
CMFCRibbonBar::HitTest Finds a pointer to the ribbon element that is located at the specified point in the ribbon bar's client coordinates.
CMFCRibbonBar::IsKeyTipEnabled Determines whether keytips are enabled.
CMFCRibbonBar::IsMainRibbonBar
CMFCRibbonBar::IsPrintPreviewEnabled Determines whether the Print Preview tab is enabled.
CMFCRibbonBar::IsQATEmpty
CMFCRibbonBar::IsQuickAccessToolbarOnTop Specifies whether the Quick Access Toolbar is located above the ribbon bar.
CMFCRibbonBar::IsReplaceFrameCaption Determines whether the ribbon bar replaces the main frame caption, or is added below the frame caption.
CMFCRibbonBar::IsShowGroupBorder
CMFCRibbonBar::IsToolTipDescrEnabled Determines whether the tooltip descriptions are enabled.
CMFCRibbonBar::IsToolTipEnabled Determines whether the tooltips for the ribbon bar are enabled.
CMFCRibbonBar::IsTransparentCaption
CMFCRibbonBar::IsWindows7Look Indicates whether the ribbon has Windows 7-style look (small rectangular application button).
CMFCRibbonBar::LoadFromResource Overloaded. Loads a Ribbon Bar from application resources.
CMFCRibbonBar::OnClickButton
CMFCRibbonBar::OnEditContextMenu
CMFCRibbonBar::OnRTLChanged (Overrides CPane::OnRTLChanged.)
CMFCRibbonBar::OnSetAccData (Overrides CBasePane::OnSetAccData.)
CMFCRibbonBar::OnShowRibbonContextMenu
CMFCRibbonBar::OnShowRibbonQATMenu
CMFCRibbonBar::OnSysKeyDown
CMFCRibbonBar::OnSysKeyUp
CMFCRibbonBar::PopTooltip
CMFCRibbonBar::PreTranslateMessage (Overrides CBasePane::PreTranslateMessage.)
CMFCRibbonBar::RecalcLayout (Overrides CPane::RecalcLayout.)
CMFCRibbonBar::RemoveAllCategories Removes all the ribbon categories from the ribbon bar.
CMFCRibbonBar::RemoveAllFromTabs Removes all ribbon elements from the tab area.
CMFCRibbonBar::RemoveCategory Removes the ribbon category that is located at the specified index.
CMFCRibbonBar::SaveToXMLBuffer Saves the Ribbon Bar to a buffer.
CMFCRibbonBar::SaveToXMLFile Saves the Ribbon Bar to XML file.
CMFCRibbonBar::SetActiveCategory Sets a specified ribbon category to active.
CMFCRibbonBar::SetActiveMDIChild
CMFCRibbonBar::SetElementKeys Sets the specified keytips for all ribbon elements that have the specified command ID.
CMFCRibbonBar::SetApplicationButton Assigns an application ribbon button to the ribbon bar.
CMFCRibbonBar::SetKeyboardNavigationLevel
CMFCRibbonBar::SetMaximizeMode
CMFCRibbonBar::SetQuickAccessCommands Adds one or more ribbon elements to the Quick Access Toolbar.
CMFCRibbonBar::SetQuickAccessDefaultState Specifies the default state for the Quick Access Toolbar.
CMFCRibbonBar::SetQuickAccessToolbarOnTop Positions the Quick Access Toolbar (QAT) above or below the ribbon bar.
CMFCRibbonBar::SetTooltipFixedWidth
CMFCRibbonBar::SetWindows7Look Enable/disable ribbon Windows 7-style look (small rectangular application button)
CMFCRibbonBar::ShowCategory Shows or hides the specified ribbon category.
CMFCRibbonBar::ShowContextCategories Shows or hides the context categories that have the specified ID.
CMFCRibbonBar::ShowKeyTips
CMFCRibbonBar::ToggleMimimizeState Toggles the ribbon bar between the minimized and maximized states..
CMFCRibbonBar::TranslateChar

Remarks

Microsoft introduced the Office Fluent Ribbon when it simultaneously released Microsoft Office 2007. This ribbon bar isn't just a new control. It represents a new user-interface paradigm. The ribbon is a pane that contains a set of tabs called categories. Each category is logically split into ribbon panels and each panel can contain various controls and command buttons.

The elements that appear on the ribbon bar expand and contract to make the best use of available space. For example, if a ribbon panel has insufficient space to display its elements, it becomes a menu button that displays subitems on a pop-up menu. The ribbon bar behaves as a static (non-floating) control bar and can be docked at the top of a frame.

You can use the CMFCRibbonStatusBar class to implement a status bar similar to the one used in Office 2007. A ribbon category contains (and displays) a group of ribbon panels. Each ribbon panel contains one or more ribbon elements, which are derived from CMFCRibbonBaseElement.

For information about how to add a ribbon bar to your existing MFC application, see Walkthrough: Updating the MFC Scribble Application.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCRibbonBar

Requirements

Header: afxribbonbar.h

CMFCRibbonBar::ActivateContextCategory

Activates a context category that is already visible.

BOOL ActivateContextCategory(UINT uiContextID);

Parameters

uiContextID
[in] The context category ID.

Return Value

TRUE if a context category with uiContextID is found and activated; otherwise FALSE.

CMFCRibbonBar::AddCategory

Creates and initializes a new ribbon category for the ribbon bar.

CMFCRibbonCategory* AddCategory(
    LPCTSTR lpszName,
    UINT uiSmallImagesResID,
    UINT uiLargeImagesResID,
    CSize sizeSmallImage= CSize(16,
    16),
    CSize sizeLargeImage= CSize(32,
    32),
    int nInsertAt = -1,
    CRuntimeClass* pRTI= NULL);

Parameters

lpszName
[in] Name of the ribbon category.

uiSmallImagesResID
[in] Resource ID of the small image list for the ribbon category.

uiLargeImagesResID
[in] Resource ID of the large image list for the ribbon category.

sizeSmallImage
[in] Specifies the size of small images for the ribbon category.

sizeLargeImage
[in] Specifies the size of large images for the ribbon category.

nInsertAt
[in] Zero based index of the category location.

pRTI
[in] Pointer to a CMFCRibbonCategory Class run-time class to dynamically create a ribbon category at run-time.

Return Value

A pointer to the new ribbon category if the method was successful; otherwise, NULL.

Remarks

If the pRTI parameter isn't NULL, the new ribbon category is created dynamically using the run-time class.

Example

The following example demonstrates how to use the AddCategory method in the CMFCRibbonBar class.

// Add "Home" category.
// CMFCRibbonBar m_wndRibbonBar
strTemp.LoadString(IDS_RIBBON_HOME);
CMFCRibbonCategory *pCategoryHome = m_wndRibbonBar.AddCategory(strTemp,
                                                               IDB_WRITESMALL, IDB_WRITELARGE);

CMFCRibbonBar::AddContextCategory

Creates and initializes a new context category for the ribbon bar.

CMFCRibbonCategory* AddContextCategory(
    LPCTSTR lpszName,
    LPCTSTR lpszContextName,
    UINT uiContextID,
    AFX_RibbonCategoryColor clrContext,
    UINT uiSmallImagesResID,
    UINT uiLargeImagesResID,
    CSize sizeSmallImage = CSize(16,
    16),
    CSize sizeLargeImage = CSize(32,
    32),
    CRuntimeClass* pRTI = NULL);

Parameters

lpszName
[in] Name of the category.

lpszContextName
[in] Name of the context category caption.

uiContextID
[in] Context ID.

clrContext
[in] Color of the context category caption.

uiSmallImagesResID
[in] Resource ID of the small image of a context category.

uiLargeImagesResID
[in] Resource ID of the large image of a context category.

sizeSmallImage
[in] Size of a small image.

sizeLargeImage
[in] Size of a large image.

pRTI
[in] Pointer to a runtime class.

Return Value

A pointer to the newly created category, or NULL if the CreateObject method of pRTI can't create the specified category.

Remarks

Use this function to add a context category. Context categories are a special type of category that can be shown or hidden at runtime, depending on the current application context. For example, when the user selects an object, you can display special tabs with context categories, which you use to change the specific selected object.

The color of a context category can be one of the following values:

  • AFX_CategoryColor_None

  • AFX_CategoryColor_Red

  • AFX_CategoryColor_Orange

  • AFX_CategoryColor_Yellow

  • AFX_CategoryColor_Green

  • AFX_CategoryColor_Blue

  • AFX_CategoryColor_Indigo

  • AFX_CategoryColor_Violet

CMFCRibbonBar::AddMainCategory

Creates a new main ribbon category for the ribbon bar.

CMFCRibbonMainPanel* AddMainCategory(
    LPCTSTR lpszName,
    UINT uiSmallImagesResID,
    UINT uiLargeImagesResID,
    CSize sizeSmallImage = CSize(16,
    16),
    CSize sizeLargeImage = CSize(32,
    32));

Parameters

lpszName
[in] Name of the main ribbon category.

uiSmallImagesResID
[in] Resource ID of small images.

uiLargeImagesResID
[in] Resource ID of large images.

sizeSmallImage
[in] The size of small images.

sizeLargeImage
[in] The size of large images.

Return Value

Pointer to the new main ribbon category if the method was successful; otherwise, NULL.

Remarks

If a main ribbon category already exists, it's deleted.

Example

The following example demonstrates how to use the AddMainCategory method in the CMFCRibbonBar class.

// m_wndRibbonBar is declared as a protected member variable
// CMFCRibbonBar m_wndRibbonBar.
// strTemp is a CString variable.
strTemp.LoadString(IDS_RIBBON_FILE);
CMFCRibbonMainPanel *pMainPanel = m_wndRibbonBar.AddMainCategory(strTemp,
                                                                 IDB_FILESMALL, IDB_FILELARGE);

CMFCRibbonBar::AddPrintPreviewCategory

Creates a print preview category on the ribbon bar.

CMFCRibbonCategory* AddPrintPreviewCategory();

Return Value

A pointer to the new ribbon category if the method was successful; otherwise, NULL.

Remarks

This method creates a ribbon category and the controls that it needs in order to provide a print preview.

CMFCRibbonBar::AddQATOnlyCategory

Creates a quick access toolbar ribbon category.

CMFCRibbonCategory* AddQATOnlyCategory(
    LPCTSTR lpszName,
    UINT uiSmallImagesResID,
    CSize sizeSmallImage = CSize(16,
    16));

Parameters

lpszName
[in] Name of the category.

uiSmallImagesResID
[in] Resource ID of the image list for the category.

sizeSmallImage
[in] Size of images for ribbon elements in the category.

Return Value

A pointer to the new category if the method was successful; otherwise, NULL.

Remarks

The quick access toolbar ribbon category is only used on the quick access toolbar customization dialog box.

CMFCRibbonBar::AddToTabs

Adds the specified ribbon element to the tabs row of the ribbon bar.

void AddToTabs(CMFCRibbonBaseElement* pElement);

Parameters

pElement
[in] Pointer to a ribbon element.

Remarks

The ribbon element is positioned before any system buttons.

CMFCRibbonBar::CMFCRibbonBar

Constructs and initializes a CMFCRibbonBar object.

CMFCRibbonBar(BOOL bReplaceFrameCaption = TRUE);

Parameters

bReplaceFrameCaption
[in] TRUE for the ribbon bar to replace the caption of the main frame window; FALSE to locate the ribbon bar under the caption of the main frame window.

Remarks

CMFCRibbonBar::Create

Creates a window for the ribbon bar.

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

Parameters

pParentWnd
[in] Pointer to the parent window for the ribbon bar.

dwStyle
[in] A logical combination of styles for the new window.

nID
[in] ID of the new window.

Return Value

TRUE if the window was created; otherwise FALSE.

Remarks

Example

The following example demonstrates how to use the Create method of the CMFCRibbonBar class.

// CMFCRibbonBar m_wndRibbonBar
m_wndRibbonBar.Create(this, WS_CHILD | CBRS_TOP);

CMFCRibbonBar::CreateEx

Creates a window for the ribbon bar.

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

Parameters

pParentWnd
[in] Pointer to the parent window for the ribbon bar.

dwCtrlStyle
[in] This parameter isn't used.

dwStyle
[in] A logical combination of styles for the new window.

nID
[in] ID of the new window.

Return Value

TRUE if the window was created; otherwise FALSE.

Remarks

CMFCRibbonBar::DeactivateKeyboardFocus

Closes all keytip controls on the ribbon bar.

void DeactivateKeyboardFocus(BOOL bSetFocus = TRUE);

Parameters

bSetFocus
[in] TRUE to set the focus to the parent window of the ribbon bar.

Remarks

CMFCRibbonBar::DrawMenuImage

Draws the image for a menu button.

BOOL DrawMenuImage(
    CDC* pDC,
    const CMFCToolBarMenuButton* pMenuItem,
    const CRect& rectImage);

Parameters

pDC
[in] Pointer to a device context for the menu button.

pMenuItem
[in] Pointer to a toolbar menu button.

rectImage
[in] The display rectangle for a menu button.

Return Value

TRUE if the image was drawn; otherwise FALSE.

Remarks

CMFCRibbonBar::DWMCompositionChanged

Adjusts the display of the ribbon bar when Desktop Window Manager (DWM) composition is enabled or disabled.

virtual void DWMCompositionChanged();

Remarks

CMFCRibbonBar::EnableKeyTips

Enables or disables the keytip feature for the ribbon bar.

void EnableKeyTips(BOOL bEnable = TRUE);

Parameters

bEnable
[in] TRUE to enable the keytips feature; FALSE to disable the keytips feature.

Remarks

When you enable this feature, key tips are displayed when the user presses the ALT or F10 keys. When the user presses ALT key, key tips are displayed with a 200 millisecond delay. This delay allows for shortcuts to be executed so that the pressed ALT key doesn't interfere with other combinations that include the ALT key.

CMFCRibbonBar::EnablePrintPreview

Enables or disables the Print Preview feature.

void EnablePrintPreview(BOOL bEnable = TRUE);

Parameters

bEnable
[in] TRUE to enable the Print Preview feature; FALSE to disable the Print Preview feature.

Remarks

If bEnable is FALSE and a print preview category exists, it's deleted.

By default the Print Preview feature is enabled.

CMFCRibbonBar::EnableToolTips

Enables or disables tooltips and optional tooltip descriptions on the ribbon bar.

void EnableToolTips(
    BOOL bEnable = TRUE,
    BOOL bEnableDescr = TRUE);

Parameters

bEnable
[in] TRUE to enable tooltips on the ribbon bar; FALSE to disable tooltips on the ribbon bar.

bEnableDescr
[in] TRUE to enable tooltip descriptions on the tooltip; FALSE to disable tooltip descriptions on the tooltip.

Remarks

The bEnable parameter determines whether tooltips are displayed when the mouse hovers over a ribbon element. The bEnableDescr parameter determines whether additional descriptive text appears with the tooltip text.

CMFCRibbonBar::FindByData

Retrieves a pointer to a ribbon element if it has the specified data and visibility.

CMFCRibbonBaseElement* FindByData(
    DWORD_PTR dwData,
    BOOL bVisibleOnly = TRUE) const;

Parameters

dwData
[in] The data associated with a ribbon element.

bVisibleOnly
[in] TRUE to search visible ribbon elements only; FALSE to search all ribbon elements.

Return Value

A pointer to a ribbon element if it has the specified data and visibility; otherwise NULL.

Remarks

A ribbon element is any control that you can add to the ribbon, such as a ribbon button, or a ribbon category, or a ribbon slider.

CMFCRibbonBar::FindByID

Retrieves a pointer to the ribbon element that has the specified command ID and search values.

CMFCRibbonBaseElement* FindByID(
    UINT uiCmdID,
    BOOL bVisibleOnly = TRUE,
    BOOL bExcludeQAT = FALSE) const;

Parameters

uiCmdID
[in] Command ID for a ribbon element.

bVisibleOnly
[in] TRUE to search visible ribbon elements only; FALSE to search all ribbon elements.

bExcludeQAT
[in] TRUE to exclude quick access toolbar elements from the search; otherwise, FALSE.

Return Value

A pointer to a ribbon element if it has the specified command ID and search values; otherwise, NULL.

Remarks

A ribbon element is any ribbon control that can be added to the ribbon, such as a ribbon button, or a ribbon category, or a ribbon slider.

In general, there can be more than one ribbon element that has the same command ID. If you want to obtain pointers to all ribbon elements that use a specified command ID, use the CMFCRibbonBar::GetElementsByID method.

CMFCRibbonBar::FindCategoryIndexByData

Retrieves the index of the ribbon category that contains the specified data.

int FindCategoryIndexByData(DWORD dwData) const;

Parameters

dwData
[in] The data associated with a ribbon category.

Return Value

The zero-based index of a ribbon category if the method was successful; otherwise -1.

CMFCRibbonBar::ForceRecalcLayout

Adjusts the layout of all items in the ribbon bar and parent window and redraws the whole window.

void ForceRecalcLayout();

Remarks

CMFCRibbonBar::GetActiveCategory

Retrieves a pointer to the active ribbon category.

CMFCRibbonCategory* GetActiveCategory() const;

Return Value

A pointer to the active ribbon category; or NULL if no category is active.

Remarks

A category is active if it has the focus. By default, the active category is the first category on the left side of the ribbon bar.

The main category is displayed when the user presses the application button and it can't be the active category.

CMFCRibbonBar::GetApplicationButton

Retrieves a pointer to the application button.

CMFCRibbonApplicationButton* GetApplicationButton() const;

Return Value

A pointer to the application button; or NULL if the button hasn't been set.

CMFCRibbonBar::GetCaptionHeight

Retrieves the height of the caption area for the ribbon bar.

int GetCaptionHeight() const;

Return Value

The height, in pixels, of the caption area for the ribbon bar.

Remarks

CMFCRibbonBar::GetCategory

Retrieves a pointer to the ribbon category at the specified index.

CMFCRibbonCategory* GetCategory(int nIndex) const;

Parameters

nIndex
[in] The zero-based index of a ribbon category in the list of ribbon categories that is contained in the ribbon bar.

Return Value

A pointer to the ribbon category at the specified index; otherwise, NULL if nIndex was out of range.

CMFCRibbonBar::GetCategoryCount

Retrieves the number of ribbon categories in the ribbon bar.

int GetCategoryCount() const;

Return Value

The number of the ribbon categories in the ribbon bar.

CMFCRibbonBar::GetCategoryHeight

Retrieves the height of the category.

int GetCategoryHeight() const;

Return Value

The height of the category.

Remarks

The category height includes the height of the category tab.

CMFCRibbonBar::GetCategoryIndex

Retrieves the index of the specified ribbon category.

int GetCategoryIndex(CMFCRibbonCategory* pCategory) const;

Parameters

pCategory
[in] Pointer to a ribbon category.

Return Value

The zero-based index of a ribbon category specified by pCategory; or -1 if the ribbon category isn't found.

CMFCRibbonBar::GetContextName

Retrieves the name of the context category caption specified by a context ID.

BOOL GetContextName(
    UINT uiContextID,
    CString& strName) const;

Parameters

uiContextID
[in] A ribbon category context ID.

strName
[out] The name of a context category caption.

Return Value

TRUE if the method was successful; otherwise, FALSE if uiContextID was zero or the context category caption wasn't found.

CMFCRibbonBar::GetDroppedDown

Retrieves the ribbon element that is currently dropped down.

virtual CMFCRibbonBaseElement* GetDroppedDown();

Return Value

The ribbon element that is currently dropped down; or NULL if no ribbon element is currently dropped down.

Remarks

CMFCRibbonBar::GetElementsByID

Retrieves an array of pointers to all ribbon elements that have a specific command ID.

void GetElementsByID(
    UINT uiCmdID,
    CArray<CMFCRibbonBaseElement*,CMFCRibbonBaseElement*>& arButtons);

Parameters

uiCmdID
[in] Command ID of a ribbon element.

arButtons
[out] An array of pointers to ribbon elements.

Remarks

Multiple ribbon elements can have the same command ID because some ribbon elements can be copied to the quick access toolbar.

CMFCRibbonBar::GetHideFlags

Retrieves the flags that indicate how much of the ribbon bar is visible.

DWORD GetHideFlags() const;

Return Value

The flags that indicate how much of the ribbon bar is visible.

Remarks

The following table lists the possible combination of flags for the return value:

Flag Description
AFX_RIBBONBAR_HIDE_ELEMENTS The ribbon bar is minimized vertically and only the category tabs, main button, and quick access toolbar are visible.
AFX_RIBBONBAR_HIDE_ALL The width of the ribbon bar is less than the minimum width and is completely hidden.

CMFCRibbonBar::GetItemIDsList

Retrieves the command IDs for the specified collection of ribbon elements on the ribbon bar.

void GetItemIDsList(CList<UINT, UINT>& lstItems,
    BOOL bHiddenOnly = FALSE) const;

Parameters

lstItems
[out] The list of command IDs for ribbon elements that are contained in the ribbon bar.

bHiddenOnly
[in] TRUE to exclude ribbon elements that are displayed; FALSE to include all ribbon elements in the ribbon bar.

Remarks

CMFCRibbonBar::GetKeyboardNavigationLevel

Retrieves the current navigation level as the user presses the keytips that are contained on the ribbon bar.

int GetKeyboardNavigationLevel() const;

Return Value

The current navigation level as the user presses the keytips that are contained on the ribbon bar. The following table lists possible return values:

Value Description
-1 Keytips aren't displayed.
0 Keytips are displayed.
1 User has pressed a displayed keytip.

Remarks

CMFCRibbonBar::GetKeyboardNavLevelCurrent

Retrieves the current keyboard navigation object on the ribbon bar.

CObject* GetKeyboardNavLevelCurrent() const;

Return Value

The current keyboard navigation object on the ribbon bar; otherwise NULL if no object currently displays keytips.

Remarks

The object that is currently displaying keytips is the current keyboard navigation object.

CMFCRibbonBar::GetKeyboardNavLevelParent

Retrieves the parent keyboard navigation object on the ribbon bar.

CObject* GetKeyboardNavLevelParent() const;

Return Value

The parent keyboard navigation object on the ribbon bar; otherwise NULL.

Remarks

When the user presses a keytip on the ribbon bar, the current keyboard navigation object becomes the parent keyboard navigation object.

CMFCRibbonBar::GetMainCategory

Retrieves a pointer to the main ribbon category.

CMFCRibbonCategory* GetMainCategory() const;

Return Value

A pointer to the main ribbon category.

Remarks

The main ribbon category contains the main ribbon panel.

CMFCRibbonBar::GetQATCommandsLocation

Retrieves the display rectangle for the commands section of the quick access toolbar.

CRect GetQATCommandsLocation() const;

Return Value

The display rectangle for the commands section of the quick access toolbar.

Remarks

The commands section of the display rectangle doesn't include the customization button.

CMFCRibbonBar::GetQATDroppedDown

Retrieves a pointer to the ribbon element on the quick access toolbar that has its pop-up menu dropped down.

CMFCRibbonBaseElement* GetQATDroppedDown();

Return Value

A pointer to the ribbon element on the quick access toolbar that has its pop-up menu dropped down.

Remarks

CMFCRibbonBar::GetQuickAccessCommands

Retrieves a list of command IDs for the ribbon elements on the quick access toolbar.

void GetQuickAccessCommands(CList<UINT,UINT>& lstCommands);

Parameters

lstCommands
[out] The list of command IDs for the ribbon elements on the quick access toolbar.

Remarks

The list doesn't contain ribbon elements that are control separators.

CMFCRibbonBar::GetQuickAccessToolbarLocation

Retrieves the display rectangle for the quick access toolbar.

CRect GetQuickAccessToolbarLocation() const;

Return Value

The display rectangle for the quick access toolbar.

Remarks

CMFCRibbonBar::GetTabTrancateRatio

Retrieves the percent size reduction in the display width of the category tabs.

int GetTabTrancateRatio() const;

Return Value

The percent size reduction in the display width of the category tabs.

Remarks

Category tabs are reduced in width when there isn't enough width on the ribbon bar.

CMFCRibbonBar::GetTooltipFixedWidthLargeImage

Retrieves the large size of tooltip width for the ribbon bar.

int GetTooltipFixedWidthLargeImage() const;

Return Value

The large size of tooltip width in pixels.

Remarks

If the large size of tooltip width is 0, the width varies.

CMFCRibbonBar::GetTooltipFixedWidthRegular

Retrieves the regular size of tooltip width for the ribbon bar.

int GetTooltipFixedWidthRegular() const;

Return Value

The regular size of tooltip width in pixels.

Remarks

If the regular size of tooltip width is 0, the width varies.

CMFCRibbonBar::GetVisibleCategoryCount

Retrieves the number of visible categories on the ribbon bar.

int GetVisibleCategoryCount() const;

Return Value

The number of visible categories on the ribbon bar.

Remarks

CMFCRibbonBar::HideAllContextCategories

Hides all the context categories on the ribbon bar.

BOOL HideAllContextCategories();

Return Value

TRUE if at least one context category was hidden; otherwise, FALSE.

Remarks

If a context category is active, the active category is reset to the first visible category in the category list.

CMFCRibbonBar::HideKeyTips

Hides all keytips on the ribbon bar.

void HideKeyTips();

Remarks

CMFCRibbonBar::HitTest

Retrieves a pointer to the ribbon element specified by the location of the point.

virtual CMFCRibbonBaseElement* HitTest(
    CPoint point,
    BOOL bCheckActiveCategory= FALSE,
    BOOL bCheckPanelCaption= FALSE);

Parameters

point
[in] Location of the point in ribbon bar coordinates.

bCheckActiveCategory
[in] TRUE to search the active category; FALSE not to search the active category.

bCheckPanelCaption
[in] TRUE to test the caption of the ribbon panel with the point located in it; FALSE not to test the caption of the ribbon panel with the point located in it. See the Remarks section for more information.

Return Value

A pointer to the ribbon element located at the specified point; otherwise NULL if the point isn't located in a ribbon element.

Remarks

The caption of the ribbon panel with the point located in it isn't tested unless the bCheckActiveCategory parameter is TRUE.

CMFCRibbonBar::IsKeyTipEnabled

Indicates whether the keytips feature is enabled.

BOOL IsKeyTipEnabled() const;

Return Value

TRUE if the keytips feature is enabled; otherwise FALSE.

CMFCRibbonBar::IsMainRibbonBar

Indicates whether the ribbon bar is the primary ribbon bar.

virtual BOOL IsMainRibbonBar() const;

Return Value

Always returns TRUE.

Remarks

By default this method always returns TRUE. Override this method to indicate whether the ribbon bar is the primary ribbon bar.

CMFCRibbonBar::IsPrintPreviewEnabled

Indicates whether the Print Preview feature is enabled.

BOOL IsPrintPreviewEnabled() const;

Return Value

TRUE if the Print Preview feature is enabled; otherwise FALSE.

CMFCRibbonBar::IsQATEmpty

Indicates whether the quick access toolbar contains command buttons.

BOOL IsQATEmpty() const;

Return Value

TRUE if the quick access toolbar contains command buttons; otherwise FALSE.

Remarks

CMFCRibbonBar::IsQuickAccessToolbarOnTop

Indicates whether the quick access toolbar is located over or under the ribbon bar.

BOOL IsQuickAccessToolbarOnTop() const;

Return Value

TRUE if the quick access toolbar is located over the ribbon bar; FALSE if the quick access toolbar is located under the ribbon bar.

CMFCRibbonBar::IsReplaceFrameCaption

Indicates whether the ribbon bar replaces or is under the caption of the main frame window.

BOOL IsReplaceFrameCaption() const;

Return Value

TRUE if the ribbon bar replaces the caption of the main frame window; FALSE if ribbon bar is under the caption of the main frame window.

CMFCRibbonBar::IsShowGroupBorder

Indicates whether button groups located on the ribbon bar display a group border.

virtual BOOL IsShowGroupBorder(CMFCRibbonButtonsGroup* pGroup) const;

Parameters

pGroup
[in] This parameter isn't used.

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method to indicate whether button groups located on the ribbon bar display a group border.

CMFCRibbonBar::IsToolTipDescrEnabled

Indicates whether tooltip descriptions are enabled.

BOOL IsToolTipDescrEnabled() const;

Return Value

TRUE if tooltip descriptions are enabled; FALSE if tooltip descriptions are disabled.

Remarks

Tooltip descriptions are additional descriptive text displayed with the tooltip text.

CMFCRibbonBar::IsToolTipEnabled

Indicates whether tooltips are enabled or disabled for the ribbon bar.

BOOL IsToolTipEnabled() const;

Return Value

TRUE if tooltips are enabled; FALSE if tooltips are disabled.

CMFCRibbonBar::IsTransparentCaption

Indicates whether the display is set for Windows Aero color scheme.

BOOL IsTransparentCaption() const;

Return Value

TRUE if the color scheme is Windows Aero; otherwise FALSE.

Remarks

CMFCRibbonBar::OnClickButton

This method is retained for backward compatibility with existing applications and shouldn't be used for new development.

virtual void OnClickButton(
    CMFCRibbonButton* pButton,
    CPoint point);

Parameters

pButton
[in] Pointer to the button that was clicked.

point
[in] This parameter isn't used.

Remarks

CMFCRibbonBar::OnEditContextMenu

virtual void OnEditContextMenu(
    CMFCRibbonRichEditCtrl* pEdit,
    CPoint point);

Parameters

[in] pEdit
[in] point\

Remarks

CMFCRibbonBar::OnRTLChanged

Called by the framework when the layout changes direction.

virtual void OnRTLChanged(BOOL bIsRTL);

Parameters

bIsRTL
[in] TRUE if the layout is right-to-left; FALSE if the layout is left-to-right.

Remarks

This method adjusts the layout of all controls on the ribbon bar for the new layout direction.

CMFCRibbonBar::OnSetAccData

This method is internal to the Framework and isn't intended to be called from user code.

BOOL OnSetAccData(long lVal);

Parameters

long lVal The index of the accessible object.

Return Value

S_OK if successful; otherwise FALSE or S_FALSE.

Remarks

CMFCRibbonBar::OnShowRibbonContextMenu

virtual BOOL OnShowRibbonContextMenu(
    CWnd* pWnd,
    int x,
    int y,
    CMFCRibbonBaseElement* pHit);

Parameters

[in] pWnd
[in] x
[in] y
[in] pHit\

Return Value

Remarks

CMFCRibbonBar::OnShowRibbonQATMenu

virtual BOOL OnShowRibbonQATMenu(
    CWnd* pWnd,
    int x,
    int y,
    CMFCRibbonBaseElement* pHit);

Parameters

[in] pWnd
[in] x
[in] y
[in] pHit\

Return Value

Remarks

CMFCRibbonBar::OnSysKeyDown

Called by the framework when the user presses the F10 key or holds down the ALT key and then presses another key.

BOOL OnSysKeyDown(
    CFrameWnd* pFrameWnd,
    WPARAM wParam,
    LPARAM lParam);

Parameters

pFrameWnd
[in] Pointer to the parent main frame window of the ribbon bar.

wParam
[in] Virtual key code of the key being pressed.

lParam
[in] Keyboard state flags when the key was pressed.

Return Value

TRUE if the keystroke event was processed; otherwise FALSE.

Remarks

CMFCRibbonBar::OnSysKeyUp

Called by the framework when the user releases the F10 key, the ALT key, or a key that was pressed when the ALT key was held down.

BOOL OnSysKeyUp(
    CFrameWnd* pFrameWnd,
    WPARAM wParam,
    LPARAM lParam);

Parameters

pFrameWnd
[in] Pointer to the parent main frame window of the ribbon bar.

wParam
[in] Virtual key code of the key being released.

lParam
[in] This parameter isn't used.

Return Value

TRUE if the keystroke event was processed; otherwise FALSE.

Remarks

CMFCRibbonBar::PopTooltip

Removes a tooltip from view.

void PopTooltip();

Remarks

CMFCRibbonBar::PreTranslateMessage

Determines if the specified message is processed by the ribbon bar.

virtual BOOL PreTranslateMessage(MSG* pMsg);

Parameters

pMsg
[in] Pointer to a message.

Return Value

TRUE if the message was processed by the ribbon bar; otherwise FALSE.

Remarks

CMFCRibbonBar::RecalcLayout

Adjusts the layout of all controls on the ribbon bar.

virtual void RecalcLayout();

Remarks

After layout adjustment, the display of the ribbon bar is updated.

CMFCRibbonBar::RemoveAllCategories

Deletes all ribbon categories from the ribbon bar.

void RemoveAllCategories();

Remarks

This method deletes all ribbon categories from memory and from the category list.

CMFCRibbonBar::RemoveAllFromTabs

Removes all ribbon elements from the tab area.

void RemoveAllFromTabs();

Remarks

Use this function if you want to remove all the elements that you added to the tab area by using CMFCRibbonBar::AddToTabs method.

CMFCRibbonBar::RemoveCategory

Deletes the specified ribbon category from the ribbon bar.

BOOL RemoveCategory(int nIndex);

Parameters

nIndex
[in] The zero-based index of a category in the list of ribbon categories that is contained in the ribbon bar.

Return Value

TRUE if the specified ribbon category was deleted; otherwise FALSE.

Remarks

The specified ribbon category is deleted from memory and from the category list.

CMFCRibbonBar::SetActiveCategory

Sets the specified ribbon category as the active category.

BOOL SetActiveCategory(
    CMFCRibbonCategory* pCategory,
    BOOL bForceRestore= FALSE);

Parameters

pCategory
[in] A ribbon category that is contained in the ribbon bar.

bForceRestore
[in] TRUE to maximize the ribbon bar if it's minimized; FALSE to display the active category in a pop-up window if the ribbon bar is minimized.

Return Value

TRUE if the specified category was set as the active category; otherwise FALSE.

Remarks

The main ribbon category can't be the active category.

If the category specified by pCategory isn't displayed, it can't be set as the active category.

CMFCRibbonBar::SetActiveMDIChild

Associates the system buttons on the ribbon bar that belong to a multiple-document interface (MDI) child window to the specified MDI child window.

void SetActiveMDIChild(CWnd* pWnd);

Parameters

pWnd
[in] Pointer to an MDI child window.

Remarks

CMFCRibbonBar::SetApplicationButton

Assigns an application ribbon button to the ribbon bar.

void SetApplicationButton(
    CMFCRibbonApplicationButton* pButton,
    CSize sizeButton);

Parameters

pButton
[in] A pointer to the application ribbon button.

sizeButton
[in] The size of the application ribbon button.

Remarks

The application ribbon button is a large rounded button located at the upper-left corner of Ribbon control.

Example

The following example demonstrates how to use the SetApplicationButton method in the CMFCRibbonBar class.

// Init main button:
// CMFCRibbonApplicationButton m_MainButton
m_MainButton.SetImage(IDB_MAIN);
m_MainButton.SetText(_T("\nf"));
m_MainButton.SetToolTipText(strTemp);

// CMFCRibbonBar m_wndRibbonBar
m_wndRibbonBar.SetApplicationButton(&m_MainButton, CSize(45, 45));

CMFCRibbonBar::SetElementKeys

Sets the keytips for all ribbon elements that have the specified command ID.

BOOL SetElementKeys(
    UINT uiCmdID,
    LPCTSTR lpszKeys,
    LPCTSTR lpszMenuKeys= NULL);

Parameters

uiCmdID
[in] The command ID of a ribbon element.

lpszKeys
[in] The keytip.

lpszMenuKeys
[in] The menu keytip.

Return Value

TRUE if the keytips of at least one ribbon element are set; otherwise FALSE.

Remarks

The optional menu keytip is for ribbon elements with a split button that opens a popup menu.

CMFCRibbonBar::SetKeyboardNavigationLevel

Sets the keyboard navigation level as the user presses the keytips that are contained on the ribbon bar.

void SetKeyboardNavigationLevel(
    CObject* pLevel,
    BOOL bSetFocus = TRUE);

Parameters

pLevel
[in] Pointer to the current keyboard navigation object.

bSetFocus
[in] TRUE to set the keyboard focus to the ribbon bar.

Remarks

Keyboard navigation of the ribbon bar starts when the user presses the ALT or F10 key. The user selects the next navigation level by pressing a keytip on the ribbon bar. The user can return to the previous navigation level by pressing the escape key.

CMFCRibbonBar::SetMaximizeMode

Adjusts the ribbon bar when the window size of a multiple-document interface (MDI) child window enters or leaves the maximized state.

void SetMaximizeMode(
    BOOL bMax,
    CWnd* pWnd = NULL);

Parameters

bMax
[in] TRUE to display the system buttons for an MDI child window on the ribbon bar; FALSE to remove the system buttons for an MDI child window from the ribbon bar.

pWnd
[in] Pointer to the main frame window for the ribbon bar.

Remarks

The ribbon bar displays system buttons for an MDI child window in the tab row when an MDI child window is maximized.

CMFCRibbonBar::SetQuickAccessCommands

Adds one or more ribbon elements to the Quick Access Toolbar.

void SetQuickAccessCommands(
    const CList<UINT,UINT>& lstCommands,
    BOOL bRecalcLayout=TRUE);

Parameters

lstCommands
[in] The list of commands to be placed on the Quick Access Toolbar.

bRecalcLayout
[in] TRUE if want to redraw the ribbon after you add the ribbon elements; FALSE otherwise.

Example

The following example demonstrates how to use the SetQuickAccessCommands method in the CMFCRibbonBar class.

// Add quick access commands to the toolbar
CList<UINT, UINT> lstQATCmds;

lstQATCmds.AddTail(ID_FILE_NEW);
lstQATCmds.AddTail(ID_FILE_OPEN);
lstQATCmds.AddTail(ID_FILE_SAVE);
lstQATCmds.AddTail(ID_FILE_PRINT_DIRECT);

// CMFCRibbonBar m_wndRibbonBar
m_wndRibbonBar.SetQuickAccessCommands(lstQATCmds);

CMFCRibbonBar::SetQuickAccessDefaultState

Sets the quick access toolbar to the default state.

void SetQuickAccessDefaultState(const CMFCRibbonQuickAccessToolBarDefaultState& state);

Parameters

state
[in] The quick access toolbar default state.

Remarks

The quick access toolbar state includes a list of commands and their visibility.

Example

The following example demonstrates how to use the SetQuickAccessDefaultState method in the CMFCRibbonBar class.

CMFCRibbonQuickAccessToolBarDefaultState *qaToolBarState =
    new CMFCRibbonQuickAccessToolBarDefaultState();
qaToolBarState->AddCommand(ID_FILE_NEW, true);
qaToolBarState->AddCommand(ID_FILE_OPEN, true);
// CMFCRibbonBar m_wndRibbonBar
m_wndRibbonBar.SetQuickAccessDefaultState(*qaToolBarState);

CMFCRibbonBar::SetQuickAccessToolbarOnTop

Positions the quick access toolbar above or below the ribbon bar.

void SetQuickAccessToolbarOnTop(BOOL bOnTop);

Parameters

bOnTop
[in] TRUE to position the quick access toolbar above the ribbon bar; FALSE to position the quick access toolbar below the ribbon bar.

CMFCRibbonBar::SetTooltipFixedWidth

Sets the regular and large sizes of tooltip fixed widths for the ribbon bar.

void SetTooltipFixedWidth(
    int nWidthRegular,
    int nWidthLargeImage);

Parameters

nWidthRegular
[in] The width, in pixels, of a regular fixed sized tooltip.

nWidthLargeImage
[in] The width, in pixels, of a large fixed sized tooltip.

Remarks

Setting a parameter to 0 causes the corresponding width to vary.

CMFCRibbonBar::ShowCategory

Shows or hides the specified ribbon category.

void ShowCategory(
    int nIndex,
    BOOL bShow=TRUE);

Parameters

nIndex
[in] The index of the ribbon category.

bShow
[in] If TRUE, show the ribbon category; otherwise, hide the ribbon category.

CMFCRibbonBar::ShowContextCategories

Shows or hides the context categories that have the specified ID.

void ShowContextCategories(
    UINT uiContextID,
    BOOL bShow=TRUE);

Parameters

uiContextID
[in] The context category ID.

bShow
[in] If TRUE, show the categories that have the specified ID; otherwise, hide the categories that have the specified ID.

CMFCRibbonBar::ShowKeyTips

Shows the keytips for each ribbon element on the ribbon bar.

void ShowKeyTips();

Remarks

CMFCRibbonBar::ToggleMimimizeState

Toggles the ribbon bar between the minimized and maximized states.

void ToggleMimimizeState();

Remarks

The misspelling in the method name is a known issue.

In the minimized state, the ribbon control is hidden and only the tabs are displayed. When the user clicks a tab, the ribbon control is displayed as a popup window. The window closes when the user clicks away or executes a command.

CMFCRibbonBar::TranslateChar

Determines whether the specified keystroke character code is processed by the ribbon bar.

virtual BOOL TranslateChar(UINT nChar);

Parameters

nChar
[in] A user keystroke character code.

Return Value

TRUE if the character code was processed by the ribbon bar; otherwise FALSE.

Remarks

The keytips feature enables users to navigate the ribbon bar by using the keyboard.

CMFCRibbonBar::GetFocused

Returns a focused element.

virtual CMFCRibbonBaseElement* GetFocused();

Return Value

A pointer to a focused element or NULL.

Remarks

CMFCRibbonBar::IsWindows7Look

Indicates whether the ribbon has a Windows 7 look (small rectangular application button).

BOOL IsWindows7Look() const;

Return Value

TRUE if the ribbon has a Windows 7 look; otherwise FALSE.

Remarks

CMFCRibbonBar::LoadFromResource

Overloaded. Loads a Ribbon Bar from application resources.

virtual BOOL LoadFromResource(
    UINT uiXMLResID,
    LPCTSTR lpszResType = RT_RIBBON,
    HINSTANCE hInstance = NULL);

virtual BOOL LoadFromResource(
    LPCTSTR lpszXMLResID,
    LPCTSTR lpszResType = RT_RIBBON,
    HINSTANCE hInstance = NULL);

Parameters

uiXMLResID
Specifies resource ID of XML string with Ribbon Bar information.

lpszResType
Specifies type of the resource located at uiXMLResID.

hInstance
Handle to the module whose executable file contains the resource. If hInstance is NULL, the system loads the resource from the module that was used to create the current process.

lpszXMLResID
Specifies resource ID (in string form) with Ribbon Bar information.

Return Value

TRUE if load succeeds; otherwise FALSE.

Remarks

CMFCRibbonBar::SaveToXMLBuffer

Saves the Ribbon Bar to a buffer.

UINT SaveToXMLBuffer(LPBYTE* ppBuffer) const;

Parameters

ppBuffer
When this function returns, ppBuffer points to a buffer allocated by this method and contains Ribbon Bar information in XML format.

Return Value

TRUE if successful; otherwise FALSE.

Remarks

CMFCRibbonBar::SaveToXMLFile

Saves the Ribbon Bar to an XML file.

BOOL SaveToXMLFile(LPCTSTR lpszFilePath) const;

Parameters

lpszFilePath
Specifies the output file.

Return Value

TRUE if successful; otherwise FALSE.

Remarks

CMFCRibbonBar::SetWindows7Look

Enables or disables a Windows 7 look (small rectangular application button) for the Ribbon.

void SetWindows7Look(
    BOOL bWindows7Look,
    BOOL bRecalc = TRUE);

Parameters

bWindows7Look
TRUE sets a Windows 7 look; FALSE otherwise.

bRecalc
TRUE recalculates the ribbon layout; FALSE otherwise.

Remarks

See also

Hierarchy Chart
Classes
CPane Class
CMFCRibbonCategory Class
CMFCRibbonPanel Class
CMFCRibbonBaseElement Class
Walkthrough: Updating the MFC Scribble Application