CMFCRibbonButton Class

Article
08/03/2021

The CMFCRibbonButton class implements buttons that you can position on ribbon bar elements such as panels, Quick Access Toolbars, and pop-up menus.

For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

Syntax

class CMFCRibbonButton : public CMFCRibbonBaseElement

Members

Public Constructors

Name	Description
CMFCRibbonButton::CMFCRibbonButton	Constructs a ribbon button object.

Public Methods

Name	Description
CMFCRibbonButton::AddSubItem	Adds a menu item to the pop-up menu that is associated with the button.
CMFCRibbonButton::CanBeStretched	(Overrides CMFCRibbonBaseElement::CanBeStretched.)
CMFCRibbonButton::CleanUpSizes	(Overrides CMFCRibbonBaseElement::CleanUpSizes.)
CMFCRibbonButton::ClosePopupMenu	(Overrides CMFCRibbonBaseElement::ClosePopupMenu.)
CMFCRibbonButton::DrawBottomText
CMFCRibbonButton::DrawImage	(Overrides CMFCRibbonBaseElement::DrawImage.)
CMFCRibbonButton::DrawRibbonText
CMFCRibbonButton::FindSubItemIndexByID	Returns the index of a pop-up menu item that is associated with the specified command ID.
CMFCRibbonButton::GetCommandRect
CMFCRibbonButton::GetCompactSize	Returns the compact size of the ribbon element. (Overrides CMFCRibbonBaseElement::GetCompactSize.)
CMFCRibbonButton::GetIcon
CMFCRibbonButton::GetImageIndex	Returns the index of the image that is associated with the button.
CMFCRibbonButton::GetImageSize	Returns the image size of the ribbon element. (Overrides CMFCRibbonBaseElement::GetImageSize.)
CMFCRibbonButton::GetIntermediateSize	Returns the size of the ribbon element in its intermediate state. (Overrides CMFCRibbonBaseElement::GetIntermediateSize.)
CMFCRibbonButton::GetMenu	Returns a handle to a Windows menu that is assigned to the ribbon button.
CMFCRibbonButton::GetMenuRect
CMFCRibbonButton::GetRegularSize	Returns the regular size of the ribbon element. (Overrides CMFCRibbonBaseElement::GetRegularSize.)
CMFCRibbonButton::GetSubItems
CMFCRibbonButton::GetTextRowHeight
CMFCRibbonButton::GetToolTipText	Returns tooltip text of the ribbon element. (Overrides CMFCRibbonBaseElement::GetToolTipText.)
CMFCRibbonButton::HasCompactMode	Specifies whether the ribbon element has a compact mode. (Overrides CMFCRibbonBaseElement::HasCompactMode.)
CMFCRibbonButton::HasIntermediateMode	Specifies whether the ribbon element has an intermediate mode. (Overrides CMFCRibbonBaseElement::HasIntermediateMode.)
CMFCRibbonButton::HasLargeMode	Determines whether the ribbon element has a large mode. (Overrides CMFCRibbonBaseElement::HasLargeMode.)
CMFCRibbonButton::HasMenu	(Overrides CMFCRibbonBaseElement::HasMenu.)
CMFCRibbonButton::IsAlwaysDrawBorder
CMFCRibbonButton::IsAlwaysLargeImage	(Overrides CMFCRibbonBaseElement::IsAlwaysLargeImage.)
CMFCRibbonButton::IsApplicationButton
CMFCRibbonButton::IsCommandAreaHighlighted
CMFCRibbonButton::IsDefaultCommand	Determines whether you have enabled the default command for a ribbon button.
CMFCRibbonButton::IsDefaultPanelButton
CMFCRibbonButton::IsDrawTooltipImage
CMFCRibbonButton::IsLargeImage
CMFCRibbonButton::IsMenuAreaHighlighted
CMFCRibbonButton::IsMenuOnBottom
CMFCRibbonButton::IsPopupDefaultMenuLook
CMFCRibbonButton::IsRightAlignMenu	Determines whether the menu is right-aligned.
CMFCRibbonButton::IsSingleLineText
CMFCRibbonButton::OnCalcTextSize	(Overrides CMFCRibbonBaseElement::OnCalcTextSize.)
CMFCRibbonButton::OnDrawBorder
CMFCRibbonButton::OnDraw	Called by the framework to draw the ribbon element. (Overrides CMFCRibbonBaseElement::OnDraw.)
CMFCRibbonButton::OnFillBackground
CMFCRibbonButton::RemoveAllSubItems	Removes all menu items from the pop-up menu.
CMFCRibbonButton::RemoveSubItem	Removes a menu item from the pop-up menu.
CMFCRibbonButton::SetACCData	(Overrides CMFCRibbonBaseElement::SetACCData.)
CMFCRibbonButton::SetAlwaysLargeImage	Specifies whether the button displays a large or a small image when the user collapses the button.
CMFCRibbonButton::SetDefaultCommand	Enables the default command for the ribbon button.
CMFCRibbonButton::SetDescription	Sets the description for the ribbon element. (Overrides CMFCRibbonBaseElement::SetDescription.)
CMFCRibbonButton::SetImageIndex	Assigns an index to the image of the button.
CMFCRibbonButton::SetMenu	Assigns a pop-up menu to the ribbon button.
CMFCRibbonButton::SetParentCategory	(Overrides CMFCRibbonBaseElement::SetParentCategory.)
CMFCRibbonButton::SetRightAlignMenu	Aligns the pop-up menu to the right of the button.
CMFCRibbonButton::SetText	Sets the text for the ribbon element. (Overrides CMFCRibbonBaseElement::SetText.)

Protected Methods

Name	Description
CMFCRibbonButton::OnClick	Called by the framework when the user clicks the button.

Example

The following example demonstrates how to use the various methods in the CMFCRibbonButton class. The example shows how to construct an object of the CMFCRibbonButton class, assign a pop-up menu to the ribbon button, set the description of the button, remove a menu item from the pop-up menu, and right align the pop-up menu to the edge of the button.

strTemp.LoadString(IDS_RIBBON_STYLE);
// The first parameter is the command ID of the button.
// The third parameter is a zero-based index of the button's small image in the
// image list of the parent category.
// The fourth parameter is a zero-based index of the button's large image in the
// image list of the parent category.
CMFCRibbonButton *pVisualStyleButton = new CMFCRibbonButton(1, strTemp, -1, -1);

pVisualStyleButton->SetMenu(IDR_THEME_MENU, TRUE, TRUE);

strTemp.LoadString(IDS_RIBBON_STYLE_TIP);
pVisualStyleButton->SetToolTipText(strTemp);
strTemp.LoadString(IDS_RIBBON_STYLE_DESC);
pVisualStyleButton->SetDescription(strTemp);
pVisualStyleButton->RemoveSubItem(0);
pVisualStyleButton->SetRightAlignMenu(TRUE);

Remarks

To use a ribbon button in an application, construct the button object and add it to the appropriate ribbon panel.

CMFCRibbonPanel* pPanel = pCategory->AddPanel (
    _T("Clipboard"), // Panel name
    m_PanelIcons.ExtractIcon (0)); // Panel icon

// Create the first button ("Paste"):
CMFCRibbonButton* pPasteButton =
    new CMFCRibbonButton (ID_EDIT_PASTE, _T("Paste"), -1, 0);

// The third parameter (-1) disables small images for button.
// This button is always displayed with a large image
// Associate a pop-up menu with the "Paste" button:
pPasteButton->SetMenu (IDR_CONTEXT_MENU);

// Add buttons to the panel. These buttons have only small images.
pPanel->Add (new CMFCRibbonButton (ID_EDIT_CUT, _T("Cut"), 1));
pPanel->Add (new CMFCRibbonButton (ID_EDIT_COPY, _T("Copy"), 2));
pPanel->Add (new CMFCRibbonButton (ID_EDIT_PAINT, _T("Paint"), 9));

Inheritance Hierarchy

CObject

CMFCRibbonBaseElement

CMFCRibbonButton

Requirements

Header: afxribbonbutton.h

CMFCRibbonButton::AddSubItem

Adds a menu item to the pop-up menu that is associated with the button.

void AddSubItem(
    CMFCRibbonBaseElement* pSubItem,
    int nIndex=-1);

Parameters

pSubItem
[in] Specifies a pointer to the new element to add.

nIndex
[in] Specifies the index at which to add the element to the array of menu items of the button; -1 to add the element at the end of the array of menu items.

CMFCRibbonButton::CanBeStretched

virtual BOOL CanBeStretched();

Return Value

Remarks

CMFCRibbonButton::CleanUpSizes

virtual void CleanUpSizes();

Remarks

CMFCRibbonButton::ClosePopupMenu

virtual void ClosePopupMenu();

Remarks

CMFCRibbonButton::CMFCRibbonButton

Constructs a ribbon button object.

CMFCRibbonButton(
    UINT nID,
    LPCTSTR lpszText,
    int nSmallImageIndex=-1,
    int nLargeImageIndex=-1,
    BOOL bAlwaysShowDescription=FALSE);

CMFCRibbonButton(
    UINT nID,
    LPCTSTR lpszText,
    HICON hIcon,
    BOOL bAlwaysShowDescription=FALSE,
    HICON hIconSmall=NULL,
    BOOL bAutoDestroyIcon=FALSE,
    BOOL bAlphaBlendIcon=FALSE);

Parameters

nID
[in] Specifies the command ID of the button.

lpszText
[in] Specifies the text label of the button.

nSmallImageIndex
[in] Specifies a zero-based index of the button's small image in the image list of the parent category.

nLargeImageIndex
[in] Specifies a zero-based index of the button's large image in the image list of the parent category.

hIcon
[in] Specifies a handle to the icon that the application uses as the button's image.

Example

The following example demonstrates how to construct a CMFCRibbonButton object.

strTemp.LoadString(IDS_RIBBON_CUT);
CMFCRibbonButton *butn = new CMFCRibbonButton(ID_EDIT_CUT, strTemp, 1);
butn->SetKeys(_T("k"));

CMFCRibbonButton::DrawBottomText

CSize DrawBottomText(
    CDC* pDC,
    BOOL bCalcOnly);

Parameters

[in] pDC
[in] bCalcOnly

Return Value

Remarks

CMFCRibbonButton::DrawImage

virtual void DrawImage(
    CDC* pDC,
    RibbonImageType type,
    CRect rectImage);

Parameters

[in] pDC
[in] type
[in] rectImage

Remarks

CMFCRibbonButton::DrawRibbonText

virtual int DrawRibbonText(
    CDC* pDC,
    const CString& strText,
    CRect rectText,
    UINT uiDTFlags,
    COLORREF clrText = (COLORREF)-1);

Parameters

[in] pDC
[in] strText
[in] rectText
[in] uiDTFlags
[in] clrText

Return Value

Remarks

CMFCRibbonButton::FindSubItemIndexByID

Returns the index of a pop-up menu item that is associated with the specified command ID.

int FindSubItemIndexByID(UINT uiID) const;

Parameters

uiID
[in] Specifies the command ID of the pop-up menu item.

Return Value

The zero-based index of the sub-item that is associated with the uiID. -1 if there is no such sub-item.

CMFCRibbonButton::GetCommandRect

CRect GetCommandRect() const;

Return Value

Remarks

CMFCRibbonButton::GetCompactSize

virtual CSize GetCompactSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonButton::GetIcon

HICON GetIcon(BOOL bLargeIcon = TRUE) const;

Parameters

[in] bLargeIcon

Return Value

Remarks

CMFCRibbonButton::GetImageIndex

Returns the index of the image that is associated with the button.

int GetImageIndex(BOOL bLargeImage) const;

Parameters

bLargeImage
[in] If TRUE, returns the image index in the image list that contains the large images; otherwise returns the image index in the image list that contains the small images.

Return Value

The index of the button's image in the associated image list.

CMFCRibbonButton::GetImageSize

virtual CSize GetImageSize(RibbonImageType type) const;

Parameters

[in] type

Return Value

Remarks

CMFCRibbonButton::GetIntermediateSize

virtual CSize GetIntermediateSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonButton::GetMenu

Returns a handle to a Windows menu that is assigned to the ribbon button.

HMENU GetMenu() const;

Return Value

A handle to a Windows menu assigned to the button; NULL if there is no menu assigned.

CMFCRibbonButton::GetMenuRect

CRect GetMenuRect() const;

Return Value

Remarks

CMFCRibbonButton::GetRegularSize

virtual CSize GetRegularSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonButton::GetSubItems

const CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& GetSubItems() const;

Return Value

Remarks

CMFCRibbonButton::GetTextRowHeight

int GetTextRowHeight() const;

Return Value

Remarks

CMFCRibbonButton::GetToolTipText

virtual CString GetToolTipText() const;

Return Value

Remarks

CMFCRibbonButton::HasCompactMode

virtual BOOL HasCompactMode() const;

Return Value

Remarks

CMFCRibbonButton::HasIntermediateMode

virtual BOOL HasIntermediateMode() const;

Return Value

Remarks

CMFCRibbonButton::HasLargeMode

virtual BOOL HasLargeMode() const;

Return Value

Remarks

CMFCRibbonButton::HasMenu

virtual BOOL HasMenu() const;

Return Value

Remarks

CMFCRibbonButton::IsAlwaysDrawBorder

virtual BOOL IsAlwaysDrawBorder() const;

Return Value

Remarks

CMFCRibbonButton::IsAlwaysLargeImage

virtual BOOL IsAlwaysLargeImage() const;

Return Value

Remarks

CMFCRibbonButton::IsApplicationButton

virtual BOOL IsApplicationButton() const;

Return Value

Remarks

CMFCRibbonButton::IsCommandAreaHighlighted

virtual BOOL IsCommandAreaHighlighted() const;

Return Value

Remarks

CMFCRibbonButton::IsDefaultCommand

Specifies whether the default command for a ribbon button is enabled.

BOOL IsDefaultCommand() const;

Return Value

TRUE if you have enabled the default command for a ribbon button; FALSE otherwise.

CMFCRibbonButton::IsDefaultPanelButton

virtual BOOL IsDefaultPanelButton() const;

Return Value

Remarks

CMFCRibbonButton::IsDrawTooltipImage

virtual BOOL IsDrawTooltipImage() const;

Return Value

Remarks

CMFCRibbonButton::IsLargeImage

BOOL IsLargeImage() const;

Return Value

Remarks

CMFCRibbonButton::IsMenuAreaHighlighted

virtual BOOL IsMenuAreaHighlighted() const;

Return Value

Remarks

CMFCRibbonButton::IsMenuOnBottom

BOOL IsMenuOnBottom() const;

Return Value

Remarks

CMFCRibbonButton::IsPopupDefaultMenuLook

virtual BOOL IsPopupDefaultMenuLook() const;

Return Value

Remarks

CMFCRibbonButton::IsRightAlignMenu

Specifies whether the menu is right-aligned.

BOOL IsRightAlignMenu() const;

Return Value

TRUE if menu is right-aligned; otherwise FALSE.

CMFCRibbonButton::IsSingleLineText

BOOL IsSingleLineText() const;

Return Value

Remarks

CMFCRibbonButton::OnCalcTextSize

virtual void OnCalcTextSize(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCRibbonButton::OnClick

Called by the framework when the user clicks the button.

virtual void OnClick(CPoint point);

Parameters

point
[in] Specifies the position of the mouse click.

Remarks

Override this method in a derived class if you want to handle this event.

CMFCRibbonButton::OnDraw

virtual void OnDraw(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCRibbonButton::OnDrawBorder

virtual void OnDrawBorder(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCRibbonButton::OnFillBackground

virtual COLORREF OnFillBackground(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonButton::RemoveAllSubItems

Removes all menu items from the pop-up menu.

void RemoveAllSubItems();

CMFCRibbonButton::RemoveSubItem

Removes a menu item from the pop-up menu.

BOOL RemoveSubItem(int nIndex);

Parameters

nIndex
[in] Specifies the zero-based index of the menu item that you want to remove.

Return Value

TRUE if the specified item has been removed successfully; otherwise FALSE if nIndex is negative or exceeds the number of menu items in the pop-up menu.

CMFCRibbonButton::SetACCData

Sets the accessibility data for the ribbon button.

virtual BOOL SetACCData(
    CWnd* pParent,
    CAccessibilityData& data);

Parameters

pParent
The parent window for the ribbon element.

data
The accessibility data for the ribbon element.

Return Value

Returns TRUE if successful; otherwise FALSE.

Remarks

CMFCRibbonButton::SetAlwaysLargeImage

Specifies whether the button displays a large or a small image when the user collapses the button.

void SetAlwaysLargeImage(BOOL bSet=TRUE);

Parameters

bSet
[in] If TRUE, the button displays a large image. Otherwise, the button displays a small image.

CMFCRibbonButton::SetDefaultCommand

Enables the default command for the ribbon button.

void SetDefaultCommand(BOOL bSet=TRUE);

Parameters

bSet
[in] If TRUE, the button can execute its default command. If FALSE, the button cannot execute its default command.

Remarks

bSet is relevant only when the button has a menu. If bSet is TRUE, the button can execute its default command and the assigned pop-up menu appears only when a user clicks the arrow at the right edge of the button. Otherwise, the button cannot execute its default command, and the pop-up menu appears regardless of which area of the button the user clicks.

CMFCRibbonButton::SetDescription

virtual void SetDescription(LPCTSTR lpszText);

Parameters

[in] lpszText

Remarks

CMFCRibbonButton::SetImageIndex

Assigns an index to the image of the button.

void SetImageIndex(
    int nIndex,
    BOOL bLargeImage);

Parameters

nIndex
[in] Specifies the image index.

bLargeImage
[in] If TRUE, the specified index refers to the list of large images. Otherwise, the index refers to the list of the small images.

CMFCRibbonButton::SetMenu

Assigns a pop-up menu to the ribbon button.

void SetMenu(
    HMENU hMenu,
    BOOL bIsDefaultCommand=FALSE,
    BOOL bRightAlign=FALSE);

void SetMenu(
    UINT uiMenuResID,
    BOOL bIsDefaultCommand=FALSE,
    BOOL bRightAlign=FALSE);

Parameters

hMenu
A handle to a Windows menu.

bIsDefaultCommand
If TRUE, the button can execute its default command; otherwise, the button displays a pop-up menu.

bRightAlign
If TRUE, the menu is right-aligned. Otherwise, the menu is left-aligned.

uiMenuResID
A menu resource ID.

Remarks

When the application assigns the menu to the button, the button displays an arrow on its right side. If bIsDefaultCommand is TRUE, the menu appears only when the user clicks the arrow. If the user clicks the button, its default command is executed. If bIsDefaultCommand is FALSE, the menu appears by clicking anywhere on the button.

CMFCRibbonButton::SetParentCategory

virtual void SetParentCategory(CMFCRibbonCategory* pParent);

Parameters

[in] pParent

Remarks

CMFCRibbonButton::SetRightAlignMenu

Aligns the pop-up menu to the edge of the button.

void SetRightAlignMenu(BOOL bSet=TRUE);

Parameters

bSet
[in] If TRUE, the menu is right-aligned. Otherwise, the menu is left-aligned

CMFCRibbonButton::SetText

virtual void SetText(LPCTSTR lpszText);

Parameters

[in] lpszText