| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CMFCRibbonButton Class |
CMFCRibbonButton Class |
11/04/2016 |
|
|
732e941c-9504-4b83-a691-d18075965d53 |
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.
class CMFCRibbonButton : public CMFCRibbonBaseElement
| Name | Description |
|---|---|
| CMFCRibbonButton::CMFCRibbonButton | Constructs a ribbon button object. |
| Name | Description |
|---|---|
| CMFCRibbonButton::OnClick | Called by the framework when the user clicks the button. |
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.
[!code-cppNVC_MFC_RibbonApp#7]
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));Header: afxribbonbutton.h
Adds a menu item to the pop-up menu that is associated with the button.
void AddSubItem(
CMFCRibbonBaseElement* pSubItem,
int nIndex=-1);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.
virtual BOOL CanBeStretched();
virtual void CleanUpSizes();
virtual void ClosePopupMenu();
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);
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.
The following example demonstrates how to construct a CMFCRibbonButton object.
[!code-cppNVC_MFC_RibbonApp#6]
CSize DrawBottomText(
CDC* pDC,
BOOL bCalcOnly);
[in] pDC
[in] bCalcOnly
virtual void DrawImage(
CDC* pDC,
RibbonImageType type,
CRect rectImage);
[in] pDC
[in] type
[in] rectImage
virtual int DrawRibbonText(
CDC* pDC,
const CString& strText,
CRect rectText,
UINT uiDTFlags,
COLORREF clrText = (COLORREF)-1);
[in] pDC
[in] strText
[in] rectText
[in] uiDTFlags
[in] clrText
Returns the index of a pop-up menu item that is associated with the specified command ID.
int FindSubItemIndexByID(UINT uiID) const;
uiID
[in] Specifies the command ID of the pop-up menu item.
The zero-based index of the sub-item that is associated with the uiID. -1 if there is no such sub-item.
CRect GetCommandRect() const;
virtual CSize GetCompactSize(CDC* pDC);
[in] pDC
HICON GetIcon(BOOL bLargeIcon = TRUE) const;
[in] bLargeIcon
Returns the index of the image that is associated with the button.
int GetImageIndex(BOOL bLargeImage) const;
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.
The index of the button's image in the associated image list.
virtual CSize GetImageSize(RibbonImageType type) const;
[in] type
virtual CSize GetIntermediateSize(CDC* pDC);
[in] pDC
Returns a handle to a Windows menu that is assigned to the ribbon button.
HMENU GetMenu() const;
A handle to a Windows menu assigned to the button; NULL if there is no menu assigned.
CRect GetMenuRect() const;
virtual CSize GetRegularSize(CDC* pDC);
[in] pDC
const CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& GetSubItems() const;
int GetTextRowHeight() const;
virtual CString GetToolTipText() const;
virtual BOOL HasCompactMode() const;
virtual BOOL HasIntermediateMode() const;
virtual BOOL HasLargeMode() const;
virtual BOOL HasMenu() const;
virtual BOOL IsAlwaysDrawBorder() const;
virtual BOOL IsAlwaysLargeImage() const;
virtual BOOL IsApplicationButton() const;
virtual BOOL IsCommandAreaHighlighted() const;
Specifies whether the default command for a ribbon button is enabled.
BOOL IsDefaultCommand() const;
TRUE if you have enabled the default command for a ribbon button; FALSE otherwise.
virtual BOOL IsDefaultPanelButton() const;
virtual BOOL IsDrawTooltipImage() const;
BOOL IsLargeImage() const;
virtual BOOL IsMenuAreaHighlighted() const;
BOOL IsMenuOnBottom() const;
virtual BOOL IsPopupDefaultMenuLook() const;
Specifies whether the menu is right-aligned.
BOOL IsRightAlignMenu() const;
TRUE if menu is right-aligned; otherwise FALSE.
BOOL IsSingleLineText() const;
virtual void OnCalcTextSize(CDC* pDC);
[in] pDC
Called by the framework when the user clicks the button.
virtual void OnClick(CPoint point);
point
[in] Specifies the position of the mouse click.
Override this method in a derived class if you want to handle this event.
virtual void OnDraw(CDC* pDC);
[in] pDC
virtual void OnDrawBorder(CDC* pDC);
[in] pDC
virtual COLORREF OnFillBackground(CDC* pDC);
[in] pDC
Removes all menu items from the pop-up menu.
void RemoveAllSubItems();Removes a menu item from the pop-up menu.
BOOL RemoveSubItem(int nIndex);
nIndex
[in] Specifies the zero-based index of the menu item that you want to remove.
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.
Sets the accessibility data for the ribbon button.
virtual BOOL SetACCData(
CWnd* pParent,
CAccessibilityData& data);
pParent
The parent window for the ribbon element.
data
The accessibility data for the ribbon element.
Returns TRUE if successful; otherwise FALSE.
Specifies whether the button displays a large or a small image when the user collapses the button.
void SetAlwaysLargeImage(BOOL bSet=TRUE);bSet
[in] If TRUE, the button displays a large image. Otherwise, the button displays a small image.
Enables the default command for the ribbon button.
void SetDefaultCommand(BOOL bSet=TRUE);bSet
[in] If TRUE, the button can execute its default command. If FALSE, the button cannot execute its default command.
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.
virtual void SetDescription(LPCTSTR lpszText);
[in] lpszText
Assigns an index to the image of the button.
void SetImageIndex(
int nIndex,
BOOL bLargeImage);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.
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);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.
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.
virtual void SetParentCategory(CMFCRibbonCategory* pParent);
[in] pParent
Aligns the pop-up menu to the edge of the button.
void SetRightAlignMenu(BOOL bSet=TRUE);bSet
[in] If TRUE, the menu is right-aligned. Otherwise, the menu is left-aligned
virtual void SetText(LPCTSTR lpszText);
[in] lpszText