CMFCRibbonBar 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 CMFCRibbonBar Class.
The CMFCRibbonBar
class implements a ribbon bar similar to that used in Office 2007.
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 is not 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
Requirements
Header: afxribbonbar.h
CMFCRibbonBar::ActivateContextCategory
Activates a context category that is already visible.
BOOL ActivateContextCategory(UINT uiContextID);
Parameters
[in] uiContextID
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
[in] lpszName
Name of the ribbon category.
[in] uiSmallImagesResID
Resource ID of the small image list for the ribbon category.
[in] uiLargeImagesResID
Resource ID of the large image list for the ribbon category.
[in] sizeSmallImage
Specifies the size of small images for the ribbon category.
[in] sizeLargeImage
Specifies the size of large images for the ribbon category.
[in] nInsertAt
Zero based index of the category location.
[in] pRTI
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 is not 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
[in] lpszName
Name of the category.
[in] lpszContextName
Name of the context category caption.
[in] uiContextID
Context ID.
[in] clrContext
Color of the context category caption.
[in] uiSmallImagesResID
Resource ID of the small image of a context category.
[in] uiLargeImagesResID
Resource ID of the large image of a context category.
[in] sizeSmallImage
Size of a small image.
[in] sizeLargeImage
Size of a large image.
[in] pRTI
Pointer to a runtime class.
Return Value
A pointer to the newly created category, or NULL
if the CreateObject
method of pRTI
cannot 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
[in] lpszName
Name of the main ribbon category.
[in] uiSmallImagesResID
Resource ID of small images.
[in] uiLargeImagesResID
Resource ID of large images.
[in] sizeSmallImage
The size of small images.
[in] sizeLargeImage
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 is 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
[in] lpszName
Name of the category.
[in] uiSmallImagesResID
Resource ID of the image list for the category.
[in] sizeSmallImage
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
[in] pElement
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
[in] bReplaceFrameCaption
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
[in] pParentWnd
Pointer to the parent window for the ribbon bar.
[in] dwStyle
A logical combination of styles for the new window.
[in] nID
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
[in] pParentWnd
Pointer to the parent window for the ribbon bar.
[in] dwCtrlStyle
This parameter is not used.
[in] dwStyle
A logical combination of styles for the new window.
[in] nID
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
[in] bSetFocus
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
[in] pDC
Pointer to a device context for the menu button.
[in] pMenuItem
Pointer to a toolbar menu button.
[in] rectImage
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
[in] bEnable
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 button. 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 does not interfere with other combinations that include the ALT key.
CMFCRibbonBar::EnablePrintPreview
Enables or disables the Print Preview feature.
void EnablePrintPreview(BOOL bEnable = TRUE);
Parameters
[in] bEnable
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 is 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
[in] bEnable
TRUE
to enable tooltips on the ribbon bar; FALSE
to disable tooltips on the ribbon bar.
[in] bEnableDescr
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
[in] dwData
The data associated with a ribbon element.
[in] bVisibleOnly
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
[in] uiCmdID
Command ID for a ribbon element.
[in] bVisibleOnly
TRUE
to search visible ribbon elements only; FALSE
to search all ribbon elements.
[in] bExcludeQAT
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
[in] dwData
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 cannot 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 has not 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
[in] nIndex
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
[in] pCategory
Pointer to a ribbon category.
Return Value
The zero-based index of a ribbon category specified by pCategory
; or -1 if the ribbon category is not found.
CMFCRibbonBar::GetContextName
Retrieves the name of the context category caption specified by a context ID.
BOOL GetContextName(
UINT uiContextID,
CString& strName) const;
Parameters
[in] uiContextID
A ribbon category context ID.
[out] strName
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 was not 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
[in] uiCmdID
Command ID of a ribbon element.
[out] arButtons
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:
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
[out] lstItems
The list of command IDs for ribbon elements that are contained in the ribbon bar.
[in] bHiddenOnly
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:
-1
Keytips are not 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 does not 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
[out] lstCommands
The list of command IDs for the ribbon elements on the quick access toolbar.
Remarks
The list does not 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 is not 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
[in] point
Location of the point in ribbon bar coordinates.
[in] bCheckActiveCategory
TRUE
to search the active category; FALSE
not to search the active category.
[in] bCheckPanelCaption
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 is not located in a ribbon element.
Remarks
The caption of the ribbon panel with the point located in it is not 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
[in] pGroup
This parameter is not 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 should not be used for new development.
virtual void OnClickButton(
CMFCRibbonButton* pButton,
CPoint point);
Parameters
[in] pButton
Pointer to the button that was clicked.
[in] point
This parameter is not used.
Remarks
CMFCRibbonBar::OnEditContextMenu
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 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
[in] bIsRTL
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 is not 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
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 OnShowRibbonContextMenu(
CWnd* pWnd,
int x,
int y,
CMFCRibbonBaseElement* pHit);
Parameters
[in] pWnd
[in] x
[in] y
[in] pHit
Return Value
Remarks
CMFCRibbonBar::OnShowRibbonQATMenu
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 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
[in] pFrameWnd
Pointer to the parent main frame window of the ribbon bar.
[in] wParam
Virtual key code of the key being pressed.
[in] lParam
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
[in] pFrameWnd
Pointer to the parent main frame window of the ribbon bar.
[in] wParam
Virtual key code of the key being released.
[in] lParam
This parameter is not 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
[in] pMsg
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
[in] nIndex
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
[in] pCategory
A ribbon category that is contained in the ribbon bar.
[in] bForceRestore
TRUE
to maximize the ribbon bar if it is 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 cannot be the active category.
If the category specified by pCategory
is not displayed, it cannot 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
[in] pWnd
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
[in] pButton
A pointer to the application ribbon button.
[in] sizeButton
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
[in] uiCmdID
The command ID of a ribbon element.
[in] lpszKeys
The keytip.
[in] lpszMenuKeys
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
[in] pLevel
Pointer to the current keyboard navigation object.
[in] bSetFocus
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
[in] bMax
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.
[in] pWnd
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
[in] lstCommands
The list of commands to be placed on the Quick Access Toolbar.
[in] bRecalcLayout
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
[in] state
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
[in] bOnTop
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
[in] nWidthRegular
The width, in pixels, of a regular fixed sized tooltip.
[in] nWidthLargeImage
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
[in] nIndex
The index of the ribbon category.
[in] bShow
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
[in] uiContextID
The context category ID.
[in] bShow
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
[in] nChar
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 Windows 7 look (small rectangular application button).
BOOL IsWindows7Look() const;
Return Value
TRUE
if the ribbon has 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 Windows 7 look (small rectangular application button) for the Ribbon.
void SetWindows7Look(
BOOL bWindows7Look,
BOOL bRecalc = TRUE);
Parameters
bWindows7Look
TRUE
sets 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