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.
class CMFCRibbonBar : public CPane
| Name | Description |
|---|---|
CMFCRibbonBar::CMFCRibbonBar |
Default constructor. |
| 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 |
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.
Header: afxribbonbar.h
Activates a context category that is already visible.
BOOL ActivateContextCategory(UINT uiContextID);
uiContextID
[in] The context category ID.
TRUE if a context category with uiContextID is found and activated; otherwise FALSE.
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);
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.
A pointer to the new ribbon category if the method was successful; otherwise, NULL.
If the pRTI parameter isn't NULL, the new ribbon category is created dynamically using the run-time class.
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);
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);
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.
A pointer to the newly created category, or NULL if the CreateObject method of pRTI can't create the specified category.
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_NoneAFX_CategoryColor_RedAFX_CategoryColor_OrangeAFX_CategoryColor_YellowAFX_CategoryColor_GreenAFX_CategoryColor_BlueAFX_CategoryColor_IndigoAFX_CategoryColor_Violet
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));
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.
Pointer to the new main ribbon category if the method was successful; otherwise, NULL.
If a main ribbon category already exists, it's deleted.
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);
Creates a print preview category on the ribbon bar.
CMFCRibbonCategory* AddPrintPreviewCategory();
A pointer to the new ribbon category if the method was successful; otherwise, NULL.
This method creates a ribbon category and the controls that it needs in order to provide a print preview.
Creates a quick access toolbar ribbon category.
CMFCRibbonCategory* AddQATOnlyCategory(
LPCTSTR lpszName,
UINT uiSmallImagesResID,
CSize sizeSmallImage = CSize(16,
16));
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.
A pointer to the new category if the method was successful; otherwise, NULL.
The quick access toolbar ribbon category is only used on the quick access toolbar customization dialog box.
Adds the specified ribbon element to the tabs row of the ribbon bar.
void AddToTabs(CMFCRibbonBaseElement* pElement);
pElement
[in] Pointer to a ribbon element.
The ribbon element is positioned before any system buttons.
Constructs and initializes a CMFCRibbonBar object.
CMFCRibbonBar(BOOL bReplaceFrameCaption = TRUE);
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.
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);
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.
TRUE if the window was created; otherwise FALSE.
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);
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);
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.
TRUE if the window was created; otherwise FALSE.
Closes all keytip controls on the ribbon bar.
void DeactivateKeyboardFocus(BOOL bSetFocus = TRUE);
bSetFocus
[in] TRUE to set the focus to the parent window of the ribbon bar.
Draws the image for a menu button.
BOOL DrawMenuImage(
CDC* pDC,
const CMFCToolBarMenuButton* pMenuItem,
const CRect& rectImage);
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.
TRUE if the image was drawn; otherwise FALSE.
Adjusts the display of the ribbon bar when Desktop Window Manager (DWM) composition is enabled or disabled.
virtual void DWMCompositionChanged();
Enables or disables the keytip feature for the ribbon bar.
void EnableKeyTips(BOOL bEnable = TRUE);
bEnable
[in] TRUE to enable the keytips feature; FALSE to disable the keytips feature.
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.
Enables or disables the Print Preview feature.
void EnablePrintPreview(BOOL bEnable = TRUE);
bEnable
[in] TRUE to enable the Print Preview feature; FALSE to disable the Print Preview feature.
If bEnable is FALSE and a print preview category exists, it's deleted.
By default the Print Preview feature is enabled.
Enables or disables tooltips and optional tooltip descriptions on the ribbon bar.
void EnableToolTips(
BOOL bEnable = TRUE,
BOOL bEnableDescr = TRUE);
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.
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.
Retrieves a pointer to a ribbon element if it has the specified data and visibility.
CMFCRibbonBaseElement* FindByData(
DWORD_PTR dwData,
BOOL bVisibleOnly = TRUE) const;
dwData
[in] The data associated with a ribbon element.
bVisibleOnly
[in] TRUE to search visible ribbon elements only; FALSE to search all ribbon elements.
A pointer to a ribbon element if it has the specified data and visibility; otherwise NULL.
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.
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;
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.
A pointer to a ribbon element if it has the specified command ID and search values; otherwise, NULL.
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.
Retrieves the index of the ribbon category that contains the specified data.
int FindCategoryIndexByData(DWORD dwData) const;
dwData
[in] The data associated with a ribbon category.
The zero-based index of a ribbon category if the method was successful; otherwise -1.
Adjusts the layout of all items in the ribbon bar and parent window and redraws the whole window.
void ForceRecalcLayout();
Retrieves a pointer to the active ribbon category.
CMFCRibbonCategory* GetActiveCategory() const;
A pointer to the active ribbon category; or NULL if no category is active.
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.
Retrieves a pointer to the application button.
CMFCRibbonApplicationButton* GetApplicationButton() const;
A pointer to the application button; or NULL if the button hasn't been set.
Retrieves the height of the caption area for the ribbon bar.
int GetCaptionHeight() const;
The height, in pixels, of the caption area for the ribbon bar.
Retrieves a pointer to the ribbon category at the specified index.
CMFCRibbonCategory* GetCategory(int nIndex) const;
nIndex
[in] The zero-based index of a ribbon category in the list of ribbon categories that is contained in the ribbon bar.
A pointer to the ribbon category at the specified index; otherwise, NULL if nIndex was out of range.
Retrieves the number of ribbon categories in the ribbon bar.
int GetCategoryCount() const;
The number of the ribbon categories in the ribbon bar.
Retrieves the height of the category.
int GetCategoryHeight() const;
The height of the category.
The category height includes the height of the category tab.
Retrieves the index of the specified ribbon category.
int GetCategoryIndex(CMFCRibbonCategory* pCategory) const;
pCategory
[in] Pointer to a ribbon category.
The zero-based index of a ribbon category specified by pCategory; or -1 if the ribbon category isn't found.
Retrieves the name of the context category caption specified by a context ID.
BOOL GetContextName(
UINT uiContextID,
CString& strName) const;
uiContextID
[in] A ribbon category context ID.
strName
[out] The name of a context category caption.
TRUE if the method was successful; otherwise, FALSE if uiContextID was zero or the context category caption wasn't found.
Retrieves the ribbon element that is currently dropped down.
virtual CMFCRibbonBaseElement* GetDroppedDown();
The ribbon element that is currently dropped down; or NULL if no ribbon element is currently dropped down.
Retrieves an array of pointers to all ribbon elements that have a specific command ID.
void GetElementsByID(
UINT uiCmdID,
CArray<CMFCRibbonBaseElement*,CMFCRibbonBaseElement*>& arButtons);
uiCmdID
[in] Command ID of a ribbon element.
arButtons
[out] An array of pointers to ribbon elements.
Multiple ribbon elements can have the same command ID because some ribbon elements can be copied to the quick access toolbar.
Retrieves the flags that indicate how much of the ribbon bar is visible.
DWORD GetHideFlags() const;
The flags that indicate how much of the ribbon bar is visible.
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. |
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;
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.
Retrieves the current navigation level as the user presses the keytips that are contained on the ribbon bar.
int GetKeyboardNavigationLevel() const;
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. |
Retrieves the current keyboard navigation object on the ribbon bar.
CObject* GetKeyboardNavLevelCurrent() const;
The current keyboard navigation object on the ribbon bar; otherwise NULL if no object currently displays keytips.
The object that is currently displaying keytips is the current keyboard navigation object.
Retrieves the parent keyboard navigation object on the ribbon bar.
CObject* GetKeyboardNavLevelParent() const;
The parent keyboard navigation object on the ribbon bar; otherwise NULL.
When the user presses a keytip on the ribbon bar, the current keyboard navigation object becomes the parent keyboard navigation object.
Retrieves a pointer to the main ribbon category.
CMFCRibbonCategory* GetMainCategory() const;
A pointer to the main ribbon category.
The main ribbon category contains the main ribbon panel.
Retrieves the display rectangle for the commands section of the quick access toolbar.
CRect GetQATCommandsLocation() const;
The display rectangle for the commands section of the quick access toolbar.
The commands section of the display rectangle doesn't include the customization button.
Retrieves a pointer to the ribbon element on the quick access toolbar that has its pop-up menu dropped down.
CMFCRibbonBaseElement* GetQATDroppedDown();
A pointer to the ribbon element on the quick access toolbar that has its pop-up menu dropped down.
Retrieves a list of command IDs for the ribbon elements on the quick access toolbar.
void GetQuickAccessCommands(CList<UINT,UINT>& lstCommands);
lstCommands
[out] The list of command IDs for the ribbon elements on the quick access toolbar.
The list doesn't contain ribbon elements that are control separators.
Retrieves the display rectangle for the quick access toolbar.
CRect GetQuickAccessToolbarLocation() const;
The display rectangle for the quick access toolbar.
Retrieves the percent size reduction in the display width of the category tabs.
int GetTabTrancateRatio() const;
The percent size reduction in the display width of the category tabs.
Category tabs are reduced in width when there isn't enough width on the ribbon bar.
Retrieves the large size of tooltip width for the ribbon bar.
int GetTooltipFixedWidthLargeImage() const;
The large size of tooltip width in pixels.
If the large size of tooltip width is 0, the width varies.
Retrieves the regular size of tooltip width for the ribbon bar.
int GetTooltipFixedWidthRegular() const;
The regular size of tooltip width in pixels.
If the regular size of tooltip width is 0, the width varies.
Retrieves the number of visible categories on the ribbon bar.
int GetVisibleCategoryCount() const;
The number of visible categories on the ribbon bar.
Hides all the context categories on the ribbon bar.
BOOL HideAllContextCategories();
TRUE if at least one context category was hidden; otherwise, FALSE.
If a context category is active, the active category is reset to the first visible category in the category list.
Hides all keytips on the ribbon bar.
void HideKeyTips();
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);
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.
A pointer to the ribbon element located at the specified point; otherwise NULL if the point isn't located in a ribbon element.
The caption of the ribbon panel with the point located in it isn't tested unless the bCheckActiveCategory parameter is TRUE.
Indicates whether the keytips feature is enabled.
BOOL IsKeyTipEnabled() const;
TRUE if the keytips feature is enabled; otherwise FALSE.
Indicates whether the ribbon bar is the primary ribbon bar.
virtual BOOL IsMainRibbonBar() const;
Always returns TRUE.
By default this method always returns TRUE. Override this method to indicate whether the ribbon bar is the primary ribbon bar.
Indicates whether the Print Preview feature is enabled.
BOOL IsPrintPreviewEnabled() const;
TRUE if the Print Preview feature is enabled; otherwise FALSE.
Indicates whether the quick access toolbar contains command buttons.
BOOL IsQATEmpty() const;
TRUE if the quick access toolbar contains command buttons; otherwise FALSE.
Indicates whether the quick access toolbar is located over or under the ribbon bar.
BOOL IsQuickAccessToolbarOnTop() const;
TRUE if the quick access toolbar is located over the ribbon bar; FALSE if the quick access toolbar is located under the ribbon bar.
Indicates whether the ribbon bar replaces or is under the caption of the main frame window.
BOOL IsReplaceFrameCaption() const;
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.
Indicates whether button groups located on the ribbon bar display a group border.
virtual BOOL IsShowGroupBorder(CMFCRibbonButtonsGroup* pGroup) const;
pGroup
[in] This parameter isn't used.
Always returns FALSE.
By default this method always returns FALSE. Override this method to indicate whether button groups located on the ribbon bar display a group border.
Indicates whether tooltip descriptions are enabled.
BOOL IsToolTipDescrEnabled() const;
TRUE if tooltip descriptions are enabled; FALSE if tooltip descriptions are disabled.
Tooltip descriptions are additional descriptive text displayed with the tooltip text.
Indicates whether tooltips are enabled or disabled for the ribbon bar.
BOOL IsToolTipEnabled() const;
TRUE if tooltips are enabled; FALSE if tooltips are disabled.
Indicates whether the display is set for Windows Aero color scheme.
BOOL IsTransparentCaption() const;
TRUE if the color scheme is Windows Aero; otherwise FALSE.
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);
pButton
[in] Pointer to the button that was clicked.
point
[in] This parameter isn't used.
virtual void OnEditContextMenu(
CMFCRibbonRichEditCtrl* pEdit,
CPoint point);
[in] pEdit
[in] point\
Called by the framework when the layout changes direction.
virtual void OnRTLChanged(BOOL bIsRTL);
bIsRTL
[in] TRUE if the layout is right-to-left; FALSE if the layout is left-to-right.
This method adjusts the layout of all controls on the ribbon bar for the new layout direction.
This method is internal to the Framework and isn't intended to be called from user code.
BOOL OnSetAccData(long lVal);
long lVal
The index of the accessible object.
S_OK if successful; otherwise FALSE or S_FALSE.
virtual BOOL OnShowRibbonContextMenu(
CWnd* pWnd,
int x,
int y,
CMFCRibbonBaseElement* pHit);
[in] pWnd
[in] x
[in] y
[in] pHit\
virtual BOOL OnShowRibbonQATMenu(
CWnd* pWnd,
int x,
int y,
CMFCRibbonBaseElement* pHit);
[in] pWnd
[in] x
[in] y
[in] pHit\
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);
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.
TRUE if the keystroke event was processed; otherwise FALSE.
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);
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.
TRUE if the keystroke event was processed; otherwise FALSE.
Removes a tooltip from view.
void PopTooltip();
Determines if the specified message is processed by the ribbon bar.
virtual BOOL PreTranslateMessage(MSG* pMsg);
pMsg
[in] Pointer to a message.
TRUE if the message was processed by the ribbon bar; otherwise FALSE.
Adjusts the layout of all controls on the ribbon bar.
virtual void RecalcLayout();
After layout adjustment, the display of the ribbon bar is updated.
Deletes all ribbon categories from the ribbon bar.
void RemoveAllCategories();
This method deletes all ribbon categories from memory and from the category list.
Removes all ribbon elements from the tab area.
void RemoveAllFromTabs();
Use this function if you want to remove all the elements that you added to the tab area by using CMFCRibbonBar::AddToTabs method.
Deletes the specified ribbon category from the ribbon bar.
BOOL RemoveCategory(int nIndex);
nIndex
[in] The zero-based index of a category in the list of ribbon categories that is contained in the ribbon bar.
TRUE if the specified ribbon category was deleted; otherwise FALSE.
The specified ribbon category is deleted from memory and from the category list.
Sets the specified ribbon category as the active category.
BOOL SetActiveCategory(
CMFCRibbonCategory* pCategory,
BOOL bForceRestore= FALSE);
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.
TRUE if the specified category was set as the active category; otherwise FALSE.
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.
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);
pWnd
[in] Pointer to an MDI child window.
Assigns an application ribbon button to the ribbon bar.
void SetApplicationButton(
CMFCRibbonApplicationButton* pButton,
CSize sizeButton);
pButton
[in] A pointer to the application ribbon button.
sizeButton
[in] The size of the application ribbon button.
The application ribbon button is a large rounded button located at the upper-left corner of Ribbon control.
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));
Sets the keytips for all ribbon elements that have the specified command ID.
BOOL SetElementKeys(
UINT uiCmdID,
LPCTSTR lpszKeys,
LPCTSTR lpszMenuKeys= NULL);
uiCmdID
[in] The command ID of a ribbon element.
lpszKeys
[in] The keytip.
lpszMenuKeys
[in] The menu keytip.
TRUE if the keytips of at least one ribbon element are set; otherwise FALSE.
The optional menu keytip is for ribbon elements with a split button that opens a popup menu.
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);
pLevel
[in] Pointer to the current keyboard navigation object.
bSetFocus
[in] TRUE to set the keyboard focus to the ribbon bar.
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.
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);
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.
The ribbon bar displays system buttons for an MDI child window in the tab row when an MDI child window is maximized.
Adds one or more ribbon elements to the Quick Access Toolbar.
void SetQuickAccessCommands(
const CList<UINT,UINT>& lstCommands,
BOOL bRecalcLayout=TRUE);
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.
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);
Sets the quick access toolbar to the default state.
void SetQuickAccessDefaultState(const CMFCRibbonQuickAccessToolBarDefaultState& state);
state
[in] The quick access toolbar default state.
The quick access toolbar state includes a list of commands and their visibility.
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);
Positions the quick access toolbar above or below the ribbon bar.
void SetQuickAccessToolbarOnTop(BOOL bOnTop);
bOnTop
[in] TRUE to position the quick access toolbar above the ribbon bar; FALSE to position the quick access toolbar below the ribbon bar.
Sets the regular and large sizes of tooltip fixed widths for the ribbon bar.
void SetTooltipFixedWidth(
int nWidthRegular,
int nWidthLargeImage);
nWidthRegular
[in] The width, in pixels, of a regular fixed sized tooltip.
nWidthLargeImage
[in] The width, in pixels, of a large fixed sized tooltip.
Setting a parameter to 0 causes the corresponding width to vary.
Shows or hides the specified ribbon category.
void ShowCategory(
int nIndex,
BOOL bShow=TRUE);
nIndex
[in] The index of the ribbon category.
bShow
[in] If TRUE, show the ribbon category; otherwise, hide the ribbon category.
Shows or hides the context categories that have the specified ID.
void ShowContextCategories(
UINT uiContextID,
BOOL bShow=TRUE);
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.
Shows the keytips for each ribbon element on the ribbon bar.
void ShowKeyTips();
Toggles the ribbon bar between the minimized and maximized states.
void ToggleMimimizeState();
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.
Determines whether the specified keystroke character code is processed by the ribbon bar.
virtual BOOL TranslateChar(UINT nChar);
nChar
[in] A user keystroke character code.
TRUE if the character code was processed by the ribbon bar; otherwise FALSE.
The keytips feature enables users to navigate the ribbon bar by using the keyboard.
Returns a focused element.
virtual CMFCRibbonBaseElement* GetFocused();
A pointer to a focused element or NULL.
Indicates whether the ribbon has a Windows 7 look (small rectangular application button).
BOOL IsWindows7Look() const;
TRUE if the ribbon has a Windows 7 look; otherwise FALSE.
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);
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.
TRUE if load succeeds; otherwise FALSE.
Saves the Ribbon Bar to a buffer.
UINT SaveToXMLBuffer(LPBYTE* ppBuffer) const;
ppBuffer
When this function returns, ppBuffer points to a buffer allocated by this method and contains Ribbon Bar information in XML format.
TRUE if successful; otherwise FALSE.
Saves the Ribbon Bar to an XML file.
BOOL SaveToXMLFile(LPCTSTR lpszFilePath) const;
lpszFilePath
Specifies the output file.
TRUE if successful; otherwise FALSE.
Enables or disables a Windows 7 look (small rectangular application button) for the Ribbon.
void SetWindows7Look(
BOOL bWindows7Look,
BOOL bRecalc = TRUE);
bWindows7Look
TRUE sets a Windows 7 look; FALSE otherwise.
bRecalc
TRUE recalculates the ribbon layout; FALSE otherwise.
Hierarchy Chart
Classes
CPane Class
CMFCRibbonCategory Class
CMFCRibbonPanel Class
CMFCRibbonBaseElement Class
Walkthrough: Updating the MFC Scribble Application