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

Implements a panel that contains a set of ribbon elements. When the panel is drawn, it displays as many elements as possible, given the size of the panel.

class CMFCRibbonPanel : public CObject  

Protected Constructors

NameDescription
CMFCRibbonPanel::CMFCRibbonPanelConstructs and initializes a CMFCRibbonPanel object.

Public Methods

NameDescription
CMFCRibbonPanel::AddAdds a ribbon element to the panel.
CMFCRibbonPanel::AddSeparatorAdds a separator to the ribbon panel.
CMFCRibbonPanel::AddToolBarAdds a toolbar to the ribbon panel.
CMFCRibbonPanel::FindByData
CMFCRibbonPanel::FindByIDReturns an element identified by a specified command ID.
CMFCRibbonPanel::GetCaptionHeight
CMFCRibbonPanel::GetCountReturns the number of elements in the ribbon panel.
CMFCRibbonPanel::GetDataReturns the user-defined data associated with the panel.
CMFCRibbonPanel::GetDefaultButton
CMFCRibbonPanel::GetDroppedDown
CMFCRibbonPanel::GetElementReturns the ribbon element located at a specified index.
CMFCRibbonPanel::GetElementsRetrieves all elements that are contained in the ribbon panel.
CMFCRibbonPanel::GetElementsByID
CMFCRibbonPanel::GetFocusedReturns a focused element.
CMFCRibbonPanel::GetGalleryRectReturns a bounding rectangle of Gallery element.
CMFCRibbonPanel::GetHighlighted
CMFCRibbonPanel::GetIndex
CMFCRibbonPanel::GetItemIDsList
CMFCRibbonPanel::GetName
CMFCRibbonPanel::GetParentButton
CMFCRibbonPanel::GetParentCategoryReturns the parent category of the ribbon panel.
CMFCRibbonPanel::GetParentMenuBar
CMFCRibbonPanel::GetPreferedMenuLocation
CMFCRibbonPanel::GetPressed
CMFCRibbonPanel::GetRect
CMFCRibbonPanel::GetVisibleElementsObtains an array of visible elements.
CMFCRibbonPanel::HasElement
CMFCRibbonPanel::HitTest
CMFCRibbonPanel::HitTestEx
CMFCRibbonPanel::InsertInserts a ribbon element at the given position.
CMFCRibbonPanel::InsertSeparatorInserts a separator at the given position.
CMFCRibbonPanel::IsCenterColumnVertSpecifies whether all panel elements should be centered (aligned) vertically, by column.
CMFCRibbonPanel::IsCollapsed
CMFCRibbonPanel::IsHighlighted
CMFCRibbonPanel::IsJustifyColumnsSpecifies whether all panel columns have the same width.
CMFCRibbonPanel::IsMainPanel
CMFCRibbonPanel::IsMenuMode
CMFCRibbonPanel::MakeGalleryItemVisibleScrolls the gallery to make the specified Ribbon element visible.
CMFCRibbonPanel::OnKey
CMFCRibbonPanel::RecalcWidths
CMFCRibbonPanel::RemoveRemoves and optionally deletes an element located at the specified index.
CMFCRibbonPanel::RemoveAllRemoves all elements from the ribbon panel.
CMFCRibbonPanel::ReplaceReplaces one element with another based on their respective index values.
CMFCRibbonPanel::ReplaceByIDReplaces one element with another based on a specified command ID.
CMFCRibbonPanel::SetCenterColumnVertOrders the panel to align elements vertically, by column.
CMFCRibbonPanel::SetDataAssociates user-defined data with the ribbon panel.
CMFCRibbonPanel::SetElementMenuAssigns a popup menu to the element that has the given command ID.
CMFCRibbonPanel::SetElementRTCAdds a ribbon element specified by the provided runtime class information to the ribbon panel.
CMFCRibbonPanel::SetElementRTCByIDAdds a ribbon element specified by the provided runtime class information to the ribbon panel.
CMFCRibbonPanel::SetFocusedSets focus to the specified Ribbon element.
CMFCRibbonPanel::SetJustifyColumnsEnables or disables column justification.
CMFCRibbonPanel::SetKeysSets the keyboard shortcut that displays the ribbon panel.
CMFCRibbonPanel::ShowPopup

Ribbon panels are logical groupings of related tasks that you create within ribbon categories. As the size of the ribbon changes, the panel layout automatically adjusts to display as many elements as possible.

You can get a ribbon panels that is contained in a ribbon category by calling the CMFCRibbonCategory::GetPanel method.

The following example demonstrates how to configure a CMFCRibbonPanel object by using various methods in the CMFCRibbonPanel class. The example shows how to set the keyboard shortcut that displays the ribbon panel, align elements in the panel vertically by column, and enable column justification. This code snippet is part of the MS Office 2007 Demo sample.

	// CMFCRibbonCategory* pCategory
	// CMFCToolBarImages m_PanelImages
	CMFCRibbonPanel* pPanelClipboard = pCategory->AddPanel(_T("Clipboard"), m_PanelImages.ExtractIcon(1));
	pPanelClipboard->SetKeys(_T("zc"));
	pPanelClipboard->SetCenterColumnVert();
	pPanelClipboard->SetJustifyColumns();

CObject

CMFCRibbonPanel

Header: afxRibbonPanel.h

Appends the specified ribbon element to the array of ribbon elements that is contained in the ribbon panel.

virtual void Add(CMFCRibbonBaseElement* pElem);

Parameters

[in, out] pElem
Pointer to a ribbon element.

Remarks

Adds a separator to the ribbon panel.

virtual void AddSeparator();

Remarks

Call this method to add a separator to the ribbon panel. The separator will be added next to the ribbon element that was added by the previous call to CMFCRibbonPanel::Add. To insert a separator at a given position, call CMFCRibbonPanel::InsertSeparator.

Adds a toolbar to the ribbon panel.

CMFCRibbonButtonsGroup* AddToolBar(
UINT uiToolbarResID,  
UINT uiColdResID = 0,  
UINT uiHotResID = 0,  
UINT uiDisabledResID = 0);

Parameters

[in] uiToolbarResID
Specifies the resource ID of the toolbar to add.

[in] uiColdResID
Specifies the resource ID of the toolbar's cold images.

[in] uiHotResID
Specifies the resource ID of the toolbar's hot images.

[in] uiDisabledResID
Specifies the resource ID of the toolbar's disabled images.

Return Value

Call this method to add a toolbar to the ribbon panel. The toolbar will be added next to the ribbon element added by the previous call to CMFCRibbonPanel::Add.

Remarks

For more information about toolbars, hot images, cold images, and disabled images, see CMFCToolBar Class.

Constructs and initializes a CMFCRibbonPanel object.

CMFCRibbonPanel(
LPCTSTR lpszName = NULL,  
HICON hIcon = NULL);  
  
CMFCRibbonPanel(CMFCRibbonGallery* pPaletteButton);

Parameters

[in] lpszName
The name of the ribbon panel.

[in] hIcon
Handle to the icon of the default button for the ribbon panel.

[in] pPaletteButton
Pointer to a ribbon gallery for the ribbon panel.

Retrieves the ribbon element that is associated with the specified data.

CMFCRibbonBaseElement* FindByData(DWORD_PTR dwData) const;  

Parameters

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

Return Value

Pointer to a ribbon element if the method was successful; otherwise NULL.

Remarks

Retrieves the ribbon element that is identified by the specified command ID.

CMFCRibbonBaseElement* FindByID(UINT uiCmdID) const;  

Parameters

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

Return Value

The ribbon element that is identified by the specified command ID; otherwise NULL if no ribbon element is identified with the specified command ID.

Retrieves the height of a caption for the ribbon panel.

int GetCaptionHeight() const;  

Return Value

The height, in pixels, of a caption for the ribbon panel.

Remarks

Retrieves the number of ribbon elements that are contained in the ribbon panel.

int GetCount() const;  

Return Value

The number of ribbon elements that are contained in the ribbon panel.

Returns the user-defined data associated with the panel.

DWORD_PTR GetData() const;  

Return Value

The user-defined data associated with the panel.

Retrieves the default button for the ribbon panel.

CMFCRibbonButton& GetDefaultButton();

Return Value

The default button for the ribbon panel.

Remarks

The default button is displayed when a ribbon panel has insufficient space to display its ribbon elements.

Retrieves a pointer to a ribbon element if its pop-up menu is dropped down.

CMFCRibbonBaseElement* GetDroppedDown() const;  

Return Value

Pointer to the ribbon element that has its pop-up menu dropped down; otherwise NULL if no ribbon element has its pop-up menu dropped down.

Remarks

Only ribbon elements that are contained in the ribbon panel are tested.

Returns the ribbon element located at a specified index.

CMFCRibbonBaseElement* GetElement(int nIndex) const;  

Parameters

[in] nIndex
Specifies the zero-based index of the element to retrieve.

Return Value

A valid pointer to the base ribbon element located at position nIndex in the ribbon panel, or NULL if there is no element at the specified index.

Retrieves all ribbon elements that are contained in the ribbon panel.

void GetElements(
    CArray <CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);

Parameters

[out] arElements
An array to fill with all the ribbon elements that are contained in the ribbon panel.

Remarks

Adds ribbon elements that have the specified command ID to the specified array.

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

Parameters

[in] uiCmdID
Command ID for a ribbon element.

[in] arElements
Array of ribbon elements.

Remarks

Only ribbon elements that are contained in the ribbon panel are tested.

Retrieves the ribbon element that is highlighted on the ribbon panel.

CMFCRibbonBaseElement* GetHighlighted() const;  

Return Value

Pointer to the ribbon element that is highlighted on the ribbon panel.

Remarks

Retrieves the zero-based index of the specified ribbon element from the array of ribbon elements that are contained in the ribbon panel.

virtual int GetIndex(CMFCRibbonBaseElement* pElem) const;  

Parameters

[in] pElem
Pointer to a ribbon element.

Return Value

Zero-based index of the specified ribbon element if the method was successful; otherwise -1.

Remarks

Retrieves the command IDs for all ribbon elements in the ribbon panel.

void GetItemIDsList(CList<UINT, UINT>& lstItems) const;  

Parameters

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

Remarks

Retrieves the name of the ribbon panel.

LPCTSTR GetName() const;  

Return Value

The name of the ribbon panel.

Remarks

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

CMFCRibbonBaseElement* GetParentButton() const;  

Return Value

Remarks

Returns the parent category of the ribbon panel.

CMFCRibbonCategory* GetParentCategory() const;  

Return Value

A pointer to the ribbon category that contains this ribbon panel.

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.

CMFCRibbonPanelMenuBar* GetParentMenuBar() const;  

Return Value

Remarks

Retrieves the preferred display rectangle for the pop-up menu of the ribbon panel.

virtual BOOL GetPreferedMenuLocation(CRect& rect);

Parameters

[out] rect
This parameter is not used.

Return Value

Always returns FALSE.

Remarks

This method always returns FALSE. Override this method to retrieve the preferred display rectangle for the pop-up menu of the ribbon panel.

Retrieves a pointer to a ribbon element on the ribbon panel if the user currently presses it.

CMFCRibbonBaseElement* GetPressed() const;  

Return Value

A pointer to a ribbon element if the user currently presses it; otherwise NULL.

Remarks

Retrieves the display rectangle for the ribbon panel.

const CRect& GetRect() const;  

Return Value

The display rectangle for the ribbon panel.

Remarks

Indicates whether the ribbon panel contains the specified ribbon element.

BOOL HasElement(const CMFCRibbonBaseElement* pElem) const;  

Parameters

[in] pElem
Pointer to a ribbon element.

Return Value

TRUE if the ribbon panel contains the specified ribbon element; otherwise FALSE.

Remarks

Sets the highlight color for the selected ribbon panel and for the ribbon element specified by the point.

virtual void Highlight(
BOOL bHighlight,  
CPoint point);

Parameters

[in] bHighlight
TRUE to highlight the ribbon panel; FALSE to unhighlight the ribbon panel.

[in] point
The x and y coordinates of the pointer, relative to the upper-left corner of the window.

Remarks

Retrieves a ribbon element if the specified point is located in it.

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

Parameters

[in] point
The x and y coordinates of the pointer, relative to the upper-left corner of the window.

[in] bCheckPanelCaption
TRUE to test the ribbon panel caption; otherwise FALSE.

Return Value

Pointer to a ribbon element if the specified point is located in it; otherwise NULL.

Remarks

Only ribbon elements that are contained in the ribbon panel are tested.

Retrieves the zero-based index of the ribbon element that has the specified point located in it.

virtual int HitTestEx(CPoint point) const;  

Parameters

[in] point
The x and y coordinates of the pointer, relative to the upper-left corner of the window.

Return Value

The zero-based index of the ribbon element that has the specified point located in it; otherwise -1.

Remarks

Only ribbon elements that are contained in the ribbon panel are tested.

Inserts the specified ribbon element at the specified position in the array of ribbon elements that is contained in the ribbon panel.

virtual BOOL Insert(
CMFCRibbonBaseElement* pElem,  
int nIndex);

Parameters

[in, out] pElem
Pointer to a ribbon element.

[in] nIndex
Zero-based value, ranging from -1 to the number of ribbon elements that are contained in the array.

Return Value

TRUE if the ribbon element was inserted successfully; otherwise FALSE.

Remarks

If the value of nIndex is -1, or if nIndex equals the number of ribbon elements in the array, the specified ribbon element is added to the end of the array. If the value of nIndex is out of range, the method will fail.

Inserts a separator at the given position.

virtual BOOL InsertSeparator(int nIndex);

Parameters

[in] nIndex
Specifies the zero-based index where the separator is inserted.

Return Value

TRUE if the separator has been inserted successfully; otherwise, FALSE.

Remarks

Call this method to insert a separator at the position specified by nIndex. To insert a separator next to the most recently added ribbon element, call CMFCRibbonPanel::AddSeparator.

Indicates whether the vertical positions of ribbon elements are centered within their display rectangle.

BOOL IsCenterColumnVert() const;  

Return Value

TRUE if the vertical positions of ribbon elements are centered within their display rectangle; otherwise FALSE.

Indicates whether the display size of the ribbon panel is minimized in the horizontal direction.

BOOL IsCollapsed() const;  

Return Value

TRUE if the display size of the ribbon panel is minimized in the horizontal direction; otherwise FALSE.

Remarks

When a ribbon panel is collapsed, it only displays its default button, its name, and a drop-down arrow.

Indicates whether the display of the ribbon panel is highlighted.

BOOL IsHighlighted() const;  

Return Value

TRUE if the display of the ribbon panel is highlighted; otherwise FALSE.

Remarks

The display of a ribbon panel is highlighted when the pointer is over it.

Indicates whether the display dimensions of ribbon elements that are in the same column in the ribbon panel are set to the same width.

BOOL IsJustifyColumns() const;  

Return Value

TRUE if the display dimensions of ribbon elements that are in the same column in the ribbon panel are set to the same width; otherwise FALSE.

Indicates whether the ribbon panel is the main ribbon panel.

virtual BOOL IsMainPanel() const;  

Return Value

Always returns FALSE.

Remarks

This method always returns FALSE. Override this method to indicate whether the ribbon panel is the main ribbon panel.

The main ribbon panel is displayed when the user selects the application button.

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

BOOL IsMenuMode() const;  

Return Value

Remarks

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 OnKey(UINT nChar);

Parameters

[in] nChar

Return Value

Remarks

Recalculates the width of each display layout configuration for the ribbon panel.

virtual void RecalcWidths(
CDC* pDC,  
int nHeight);

Parameters

[in] pDC
Pointer to a device context for the ribbon panel.

[in] nHeight
The height of the ribbon panel.

Remarks

A ribbon panel changes its layout configuration as the available width changes.

Removes and optionally deletes an element located at the specified index.

BOOL Remove(
int nIndex,  
BOOL bDelete = TRUE);

Parameters

[in] nIndex
Specifies the zero-based index of the element that is removed from the ribbon panel.

[in] bDelete
TRUE to delete the element being removed; otherwise, FALSE.

Return Value

TRUE if the element has been removed and deleted (if bDelete is TRUE); FALSE if the element was not removed or if there is no ribbon element located at nIndex.

Remarks

Call this method to remove an element from the ribbon panel.

Deletes all ribbon elements from the ribbon panel.

void RemoveAll();

Remarks

All ribbon elements are deleted from the ribbon panel and destroyed.

Replaces one element with another based on their index value.

BOOL Replace(
int nIndex,  
CMFCRibbonBaseElement* pElem);

Parameters

[in] nIndex
Specifies the zero-based index of the element to replace.

[in] [out] pElem
A valid pointer to the element that replaces the original element.

Return Value

TRUE if the original ribbon element has been replaced successfully by the new ribbon element; FALSE if the ribbon element was not replaced or if there is no element at the specified index.

Remarks

To replace a ribbon element by command ID, call CMFCRibbonPanel::ReplaceByID.

Replaces one element with another based on a specified command ID.

BOOL ReplaceByID(
UINT uiCmdID,  
CMFCRibbonBaseElement* pElem);

Parameters

[in] uiCmdID
Specifies the command ID of the element to replace.

[in] [out] pElem
A valid pointer to the element that will replace the original element.

Return Value

TRUE if the original ribbon element has been replaced successfully by the new ribbon element; FALSE if the ribbon element was not replaced or if no element with the specified command ID actually exists.

Remarks

To replace a ribbon element based on position, call CMFCRibbonPanel::Replace.

Enables or disables the centering of the vertical positions of ribbon elements within their display rectangle.

void SetCenterColumnVert(BOOL bSet = TRUE);

Parameters

[in] bSet
TRUE to center the vertical positions of ribbon elements within their display rectangle; FALSE to disable this feature.

Remarks

Associates user-defined data with the ribbon panel.

void SetData(DWORD_PTR dwData);

Parameters

[in] dwData
Specifies the user-defined data to set.

Remarks

Call this method to associate user-defined data with the ribbon panel.

Assigns a popup menu to the element that has the given command ID.

BOOL SetElementMenu(
UINT uiCmdID,  
HMENU hMenu,  
BOOL bIsDefautCommand = FALSE,  
BOOL bRightAlign = FALSE);

 
BOOL SetElementMenu(
UINT uiCmdID,  
UINT uiMenuResID,  
BOOL bIsDefautCommand = FALSE,  
BOOL bRightAlign = FALSE);

Parameters

[in] uiCmdID
Specifies the command ID of the ribbon element where the menu is added.

[in] hMenu
Specifies the handle to the Windows menu to add to the ribbon panel.

[in] bIsDefautCommand
TRUE to specify that the command associated with the ribbon element should be executed if the ribbon element is clicked. In this case, the menu is only opened when the user clicks the arrow next to the ribbon element. FALSE to specify that the command associated with the ribbon element should not be executed if the ribbon element is clicked. In this case, the popup menu appears regardless of where the user clicks on the element.

[in] bRightAlign
TRUE to specify that the popup menu is right-aligned; otherwise, FALSE.

[in] uiMenuResID
Specifies the resource ID of the menu to add to the ribbon panel.

Return Value

TRUE if the menu has been assigned to the ribbon element; otherwise, FALSE.

Remarks

Call this method to assign a popup menu to the ribbon element that has the given command ID.

Adds the ribbon element that is specified by the provided runtime class information to the ribbon panel.

CMFCRibbonBaseElement* SetElementRTC(
int nIndex,  
CRuntimeClass* pRTC);

Parameters

[in] nIndex
Specifies the zero-based index of the ribbon element to add.

[in] [out] pRTC
A pointer to the runtime class information for the ribbon element that is added to the ribbon panel.

Return Value

The ribbon element that was created by using the specified runtime class information.

Remarks

If you want to add a custom element (for example, a color button) to the ribbon panel, you must specify the custom element's runtime class information. The ribbon stores this information, creates the custom element, and replaces an existing element that is located (identified by) the specified command ID. The ribbon then returns a pointer to the newly created element.

Adds a ribbon element that is specified by the provided runtime class information to the ribbon panel.

CMFCRibbonBaseElement* SetElementRTCByID(
UINT uiCmdID,  
CRuntimeClass* pRTC);

Parameters

[in] uiCmdID
Specifies the command ID of the ribbon element to add.

[in] [out] pRTC
A pointer to the runtime class information associated with the ribbon element that is added to the ribbon panel.

Return Value

The ribbon element that was created by using the specified runtime class information.

Remarks

If you want to add a custom element (for example, a color button) to the ribbon panel, you must specify the custom element's runtime class information. The ribbon stores this information, creates the custom element, and replaces an existing element located by the specified command ID. It then returns a pointer to the newly created element.

Example

The following example shows how to use the SetElementRTCByID method:

 
// Load and add toolbar with standard buttons. This toolbar  
// should display a custom color button with id ID_CHAR_COLOR:  
 
pPanel->AddToolBar(IDR_MAINFRAME,
    IDB_MAINFRAME256);

CMFCRibbonColorButton* pColorButton = 
(CMFCRibbonColorButton*)pPanel->SetElementRTCByID(
ID_CHAR_COLOR,
    RUNTIME_CLASS (CMFCRibbonColorButton));

 
// SetElementRTCByID sets runtime class and returns a pointer  
// to the newly created custom button,
    which can be set up immediately:  
pColorButton->EnableAutomaticButton(_T("Automatic"),
    RGB (0,
    0,
    0));  

Enables or disables the adjustment of the width of ribbon elements in the same column.

void SetJustifyColumns(BOOL bSet = TRUE);

Parameters

[in] bSet
TRUE to adjust the width of ribbon elements in the same column to the width of the largest ribbon element in the column; FALSE to disable this width adjustment.

Remarks

When this feature is enabled in a ribbon panel, the widths of ribbon elements in the same column are adjusted to the width of the largest ribbon element in the same column.

Sets the keytip for the default button of the ribbon panel.

void SetKeys(LPCTSTR lpszKeys);

Parameters

[in] lpszKeys
The keytip for the default button of the ribbon panel.

Remarks

The default button is displayed when a ribbon panel has insufficient space to display its ribbon elements.

Creates and displays a pop-up menu for the ribbon panel.

CMFCRibbonPanelMenu* ShowPopup(CMFCRibbonDefaultPanelButton* pButton = NULL);

Parameters

[in] pButton
Pointer to the default button for the ribbon panel.

Return Value

Pointer to the pop-up menu for the ribbon panel if the method was successful; otherwise NULL.

Remarks

The pop-up menu for the ribbon panel is only available when the display of the ribbon panel is collapsed.

Sets focus to the specified Ribbon element.

void SetFocused(CMFCRibbonBaseElement* pNewFocus);

Parameters

pNewFocus
A pointer to a Ribbon element that receives focus.

Remarks

Scrolls the gallery to make the specified Ribbon element visible.

void MakeGalleryItemVisible(CMFCRibbonBaseElement* pItem);

Parameters

pItem
A pointer to a Ribbon element to show.

Remarks

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

BOOL IsWindows7Look() const;  

Return Value

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

Remarks

Retrieves an array of visible elements.

void GetVisibleElements(
    CArray <CMFCRibbonBaseElement*,  
    CMFCRibbonBaseElement*>& arElements);

Parameters

arElements
When the function returns, this parameter contains an array of visible elements.

Remarks

Returns a bounding rectangle of a Gallery element.

CRect GetGalleryRect();

Return Value

Size and position of the Gallery element within this panel.

Remarks

Returns a focused element.

CMFCRibbonBaseElement* GetFocused() const;  

Return Value

A pointer to a focused element or NULL.

Remarks

Hierarchy Chart
Classes
CObject Class
CMFCRibbonCategory Class
CMFCRibbonBaseElement Class

Show: