CMFCRibbonButton 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 CMFCRibbonButton Class.
The CMFCRibbonButton class implements buttons that you can position on ribbon bar elements such as panels, Quick Access Toolbars, and pop-up menus.
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
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
[in] pSubItem
Specifies a pointer to the new element to add.
[in] nIndex
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
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 CanBeStretched();
Return Value
Remarks
CMFCRibbonButton::CleanUpSizes
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 CleanUpSizes();
Remarks
CMFCRibbonButton::ClosePopupMenu
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 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
[in] nID
Specifies the command ID of the button.
[in] lpszText
Specifies the text label of the button.
[in] nSmallImageIndex
Specifies a zero-based index of the button's small image in the image list of the parent category.
[in] nLargeImageIndex
Specifies a zero-based index of the button's large image in the image list of the parent category.
[in] hIcon
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
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.
CSize DrawBottomText(
CDC* pDC,
BOOL bCalcOnly);
Parameters
[in] pDC
[in] bCalcOnly
Return Value
Remarks
CMFCRibbonButton::DrawImage
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 DrawImage(
CDC* pDC,
RibbonImageType type,
CRect rectImage);
Parameters
[in] pDC
[in] type
[in] rectImage
Remarks
CMFCRibbonButton::DrawRibbonText
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 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
[in] uiID
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
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.
CRect GetCommandRect() const;
Return Value
Remarks
CMFCRibbonButton::GetCompactSize
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 CSize GetCompactSize(CDC* pDC);
Parameters
[in] pDC
Return Value
Remarks
CMFCRibbonButton::GetIcon
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.
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
[in] bLargeImage
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
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 CSize GetImageSize(RibbonImageType type) const;
Parameters
[in] type
Return Value
Remarks
CMFCRibbonButton::GetIntermediateSize
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 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
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.
CRect GetMenuRect() const;
Return Value
Remarks
CMFCRibbonButton::GetRegularSize
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 CSize GetRegularSize(CDC* pDC);
Parameters
[in] pDC
Return Value
Remarks
CMFCRibbonButton::GetSubItems
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.
const CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& GetSubItems() const;
Return Value
Remarks
CMFCRibbonButton::GetTextRowHeight
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.
int GetTextRowHeight() const;
Return Value
Remarks
CMFCRibbonButton::GetToolTipText
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 CString GetToolTipText() const;
Return Value
Remarks
CMFCRibbonButton::HasCompactMode
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 HasCompactMode() const;
Return Value
Remarks
CMFCRibbonButton::HasIntermediateMode
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 HasIntermediateMode() const;
Return Value
Remarks
CMFCRibbonButton::HasLargeMode
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 HasLargeMode() const;
Return Value
Remarks
CMFCRibbonButton::HasMenu
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 HasMenu() const;
Return Value
Remarks
CMFCRibbonButton::IsAlwaysDrawBorder
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 IsAlwaysDrawBorder() const;
Return Value
Remarks
CMFCRibbonButton::IsAlwaysLargeImage
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 IsAlwaysLargeImage() const;
Return Value
Remarks
CMFCRibbonButton::IsApplicationButton
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 IsApplicationButton() const;
Return Value
Remarks
CMFCRibbonButton::IsCommandAreaHighlighted
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 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
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 IsDefaultPanelButton() const;
Return Value
Remarks
CMFCRibbonButton::IsDrawTooltipImage
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 IsDrawTooltipImage() const;
Return Value
Remarks
CMFCRibbonButton::IsLargeImage
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 IsLargeImage() const;
Return Value
Remarks
CMFCRibbonButton::IsMenuAreaHighlighted
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 IsMenuAreaHighlighted() const;
Return Value
Remarks
CMFCRibbonButton::IsMenuOnBottom
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 IsMenuOnBottom() const;
Return Value
Remarks
CMFCRibbonButton::IsPopupDefaultMenuLook
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 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
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 IsSingleLineText() const;
Return Value
Remarks
CMFCRibbonButton::OnCalcTextSize
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 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
[in] point
Specifies the position of the mouse click.
Remarks
Override this method in a derived class if you want to handle this event.
CMFCRibbonButton::OnDraw
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 OnDraw(CDC* pDC);
Parameters
[in] pDC
Remarks
CMFCRibbonButton::OnDrawBorder
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 OnDrawBorder(CDC* pDC);
Parameters
[in] pDC
Remarks
CMFCRibbonButton::OnFillBackground
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 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
[in] nIndex
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
[in] bSet
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
[in] bSet
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
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 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
[in] nIndex
Specifies the image index.
[in] bLargeImage
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
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 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
[in] bSet
If TRUE, the menu is right-aligned. Otherwise, the menu is left-aligned
CMFCRibbonButton::SetText
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 SetText(LPCTSTR lpszText);
Parameters
[in] lpszText