CMFCToolBarMenuButton Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

A toolbar button that contains a pop-up menu.

class CMFCToolBarMenuButton : public CMFCToolBarButton  

Public Constructors

NameDescription
CMFCToolBarMenuButton::CMFCToolBarMenuButtonConstructs a CMFCToolBarMenuButton object.

Public Methods

NameDescription
CMFCToolBarMenuButton::CompareWithCompares this instance with the provided CMFCToolBarButton object. (Overrides CMFCToolBarButton::CompareWith.)
CMFCToolBarMenuButton::CopyFromCopies the properties of another toolbar button to the current button. (Overrides CMFCToolBarButton::CopyFrom.)
CMFCToolBarMenuButton::CreateFromMenuInitializes the toolbar menu from a Windows menu handle.
CMFCToolBarMenuButton::CreateMenuCreates a Windows menu that consists of the commands in the toolbar menu. Returns a handle to the Windows menu.
CMFCToolBarMenuButton::CreatePopupMenuCreates a pop-up menu object ( CMFCPopupMenu Class) to display the toolbar menu.
CMFCToolBarMenuButton::EnableQuickCustomize
CMFCToolBarMenuButton::GetCommandsGives read-only access to the list of commands in the toolbar menu.
CMFCToolBarMenuButton::GetImageRectRetrieves the bounding rectangle for the button image.
CMFCToolBarMenuButton::GetPaletteRowsReturns the number of rows in the pop-up menu when the menu is in palette mode.
CMFCToolBarMenuButton::GetPopupMenuReturns a pointer to the pop-up menu object that is associated with the button.
CMFCToolBarMenuButton::HasButton
CMFCToolBarMenuButton::HaveHotBorderDetermines whether a border of the button is displayed when a user selects the button. (Overrides CMFCToolBarButton::HaveHotBorder.)
CMFCToolBarMenuButton::IsBorder
CMFCToolBarMenuButton::IsClickedOnMenu
CMFCToolBarMenuButton::IsDroppedDownDetermines whether the pop-up menu is displayed.
CMFCToolBarMenuButton::IsEmptyMenuAllowedCalled by the framework to determine whether a user can open a submenu from the selected menu item.
CMFCToolBarMenuButton::IsExclusiveDetermines whether the button is in exclusive mode, that is, whether the pop-up menu remains open even when the user moves the pointer over another toolbar or button.
CMFCToolBarMenuButton::IsMenuPaletteModeDetermines whether the pop-up menu is in palette mode.
CMFCToolBarMenuButton::IsQuickMode
CMFCToolBarMenuButton::IsTearOffMenuDetermines whether the pop-up menu has a tear-off bar.
CMFCToolBarMenuButton::OnAfterCreatePopupMenu
CMFCToolBarMenuButton::OnBeforeDragSpecifies whether the button can be dragged. (Overrides CMFCToolBarButton::OnBeforeDrag.)
CMFCToolBarMenuButton::OnCalculateSizeCalled by the framework to calculate the size of the button for the specified device context and docking state. (Overrides CMFCToolBarButton::OnCalculateSize.)
CMFCToolBarMenuButton::OnCancelModeCalled by the framework to handle the WM_CANCELMODE message. (Overrides CMFCToolBarButton::OnCancelMode.)
CMFCToolBarMenuButton::OnChangeParentWndCalled by the framework when the button is inserted into a new toolbar. (Overrides [CMFCToolBarButton::OnChangeParentWnd]--brokenlink--(../Topic/CMFCToolBarButton%20Class.md#cmfctoolbarbutton__onchangeparentwnd).)
CMFCToolBarMenuButton::OnClickCalled by the framework when the user clicks the mouse button. (Overrides CMFCToolBarButton::OnClick.)
CMFCToolBarMenuButton::OnClickMenuItemCalled by the framework when the user selects an item in the pop-up menu.
CMFCToolBarMenuButton::OnContextHelpCalled by the framework when the parent toolbar handles a WM_HELPHITTEST message. (Overrides CMFCToolBarButton::OnContextHelp.)
CMFCToolBarMenuButton::OnDrawCalled by the framework to draw the button by using the specified styles and options. (Overrides CMFCToolBarButton::OnDraw.)
CMFCToolBarMenuButton::OnDrawOnCustomizeListCalled by the framework to draw the button in the Commands pane of the Customize dialog box. (Overrides CMFCToolBarButton::OnDrawOnCustomizeList.)
CMFCToolBarMenuButton::OpenPopupMenuCalled by the framework when the user opens the pop-up menu.
CMFCToolBarMenuButton::ResetImageToDefaultSets to the default value the image that is associated with the button. (Overrides CMFCToolBarButton::ResetImageToDefault.)
CMFCToolBarMenuButton::SaveBarStateSaves the state of the toolbar button. (Overrides CMFCToolBarButton::SaveBarState.)
CMFCToolBarMenuButton::SerializeReads this object from an archive or writes it to an archive. (Overrides CMFCToolBarButton::Serialize.)
CMFCToolBarMenuButton::SetACCDataPopulates the provided CAccessibilityData object with accessibility data from the toolbar button. (Overrides CMFCToolBarButton::SetACCData.)
CMFCToolBarMenuButton::SetMenuOnlySpecifies whether the button can be added to a toolbar.
CMFCToolBarMenuButton::SetMenuPaletteModeSpecifies whether the pop-up menu is in palette mode.
CMFCToolBarMenuButton::SetMessageWnd
CMFCToolBarMenuButton::SetRadioForces the toolbar menu button to display an icon indicating that it is selected.
CMFCToolBarMenuButton::SetTearOffSpecifies a tear-off bar ID for the pop-up menu.

Protected Methods

NameDescription
CMFCToolBarMenuButton::DrawDocumentIconDraws an icon on the menu button.

Data Members

NameDescription
CMFCToolBarMenuButton::m_bAlwaysCallOwnerDrawIf TRUE, the framework always calls CFrameWndEx::OnDrawMenuImage when a button is drawn.

A CMFCToolBarMenuButton can appear as a menu, a menu item that has a sub-menu, a button that either executes a command or displays a menu, or a button that displays only a menu. You determine the behavior and appearance of the menu button by specifying parameters such as the image, text, menu handle, and command ID that is associated with the button in the constructor CMFCToolbarMenuButton::CMFCToolbarMenuButton.

A custom class derived from the CMFCToolbarMenuButton class must use the [DECLARE_SERIAL]--brokenlink--(../Topic/not%20found.md#declare_serial) macro. The [DECLARE_DYNCREATE]--brokenlink--(../Topic/not%20found.md#declare_dyncreate) macro generates an error when the application closes.

The following example demonstrates how to configure a CMFCToolBarMenuButton object. The code illustrates how to specify that the drop-down menu is in palette mode, and specify the ID for the tear-off bar that is created when the user drags the menu button off of a menu bar. This code snippet is part of the Word Pad sample.

	pBorderType->SetMenuPaletteMode (TRUE, 2 /* Rows number */);
	pBorderType->SetTearOff (ID_BORDER_TEAROFF);

[CObject]--brokenlink--(../Topic/CObject%20Class.md)

CMFCToolBarButton

CMFCToolBarMenuButton

Header: afxtoolbarmenubutton.h

Constructs a CMFCToolBarMenuButton object.

CMFCToolBarMenuButton();

CMFCToolBarMenuButton(
    const CMFCToolBarMenuButton& src);

CMFCToolBarMenuButton(
    UINT uiID,  
    HMENU hMenu,  
    int iImage,  
    LPCTSTR lpszText=NULL,  
    BOOL bUserButton=FALSE);

Parameters

[in] src
An existing CMFCToolBarMenuButton object to be copied into this CMFCToolBarMenuButton object.

[in] uiID
The ID of the command to execute when a user clicks the button; or ( UINT)-1 for a menu button that does not directly execute a command.

[in] hMenu
A handle to a menu; or NULL if the button does not have a menu.

[in] iImage
Index of the image for the button; or -1 if this button does not have an icon or uses the icon for the command specified by uiID. The index is the same for each CMFCToolBarImages object in your application.

[in] lpszText
The text of the toolbar menu button.

[in] bUserButton
TRUE if the button displays a user-defined image; FALSE if the button displays a predefined image associated with the command specified by uiID.

Remarks

If uiID is a valid command ID, the button performs that command when the user clicks it. If hMenu is a valid menu handle, the button provides a drop-down menu when it appears in a toolbar or a submenu when it appears in a menu. If both uiID and hMenu are valid, the button is a split-button with a portion that will perform the command when the user clicks on it and a portion with a down arrow that will drop-down a menu when the user clicks on it. However, if hMenu is valid, a user will not be able to click the button to perform a command when the button is inserted into a menu.

Example

The following example demonstrates how to construct an object of the CMFCToolBarMenuButton class. This code snippet is part of the Word Pad sample.

	CMFCToolBarMenuButton* pBorderType = new 
		CMFCToolBarMenuButton (ID_BORDER_1, pPopup->GetSafeHmenu (),
		GetCmdMgr ()->GetCmdImage  (ID_BORDER_1, FALSE),
		_T("Borders"));

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 CompareWith(const CMFCToolBarButton& other) const;

 

Parameters

[in] other

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 void CopyFrom(const CMFCToolBarButton& src);

Parameters

[in] src

Remarks

Initializes the toolbar menu from a Windows menu handle.

virtual void CreateFromMenu(HMENU hMenu);

Parameters

[in] hMenu
A handle to a menu.

Remarks

A toolbar menu button can display a drop-down submenu.

The framework calls this method to initialize the commands in the submenu from a menu.

Creates a menu that consists of the commands in the toolbar menu. Returns a handle to the menu.

virtual HMENU CreateMenu() const;

 

Return Value

A handle to the menu if success. NULL if the list of commands associated with the toolbar menu button is empty.

Remarks

You can override this method in a derived class to customize the way the menu is generated.

Creates a CMFCPopupMenu object to display the toolbar menu.

virtual CMFCPopupMenu* CreatePopupMenu();

Return Value

A pointer to a CMFCPopupMenu object that displays the drop-down menu associated with the toolbar menu button.

Remarks

This method is called by the framework to prepare the display of the drop-down menu associated with the button.

The default implementation just constructs and returns a new CMFCPopupMenu object. Override this method if you want to use a derived type of [CMFCPopupMenu Class]--brokenlink--(../Topic/CMFCPopupMenu%20Class.md) or to perform additional initialization.

Draws a document icon on the menu button.

void DrawDocumentIcon(
    CDC* pDC,  
    const CRect& rectImage,  
    HICON hIcon);

Parameters

[in] pDC
A pointer to the device context.

[in] rectImage
Coordinates of the image bounding rectangle.

[in] hIcon
A handle to the icon.

Remarks

This method takes a document icon and draws it on the menu button, centered in the area specified by rectImage.

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.

void EnableQuickCustomize();

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 HasButton() 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 HaveHotBorder() 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 IsBorder() 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.

BOOL IsClickedOnMenu() 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.

BOOL IsQuickMode();

Return Value

Remarks

Gives read-only access to the list of commands in the toolbar menu.

const CObList& GetCommands() const;

 

Return Value

A const reference to a CObList Class object, which contains a collection of CMFCToolBarButton Class objects.

Remarks

A toolbar menu button can display a submenu. You can provide the list of commands in the submenu in the constructor or in CMFCToolBarMenuButton::CreateFromMenu as a handle to a menu ( HMENU). The menu is converted to a list of objects that are derived from CMFCToolBarButton Class and stored in the internal CObList object. You can access this list by calling this method.

Retrieves the bounding rectangle for the button image.

void GetImageRect(CRect& rectImage);

Parameters

[out] rectImage
A reference to a CRect object that receives the coordinates of the image bounding rectangle.

Returns the number of rows in the drop-down menu when the menu is in palette mode.

int GetPaletteRows() const;

 

Return Value

The number of rows in the palette.

Remarks

When the menu button is set to palette mode, menu items will appear in multiple columns with only a limited number of rows. Call this method to obtain the number of rows. You can enable or disable palette mode and specify the number of rows using CMFCToolBarMenuButton::SetMenuPaletteMode.

Returns a pointer to the CMFCPopupMenu Class object that represents the drop-down menu of the button.

CMFCPopupMenu* GetPopupMenu() const;

 

Return Value

A pointer to a CMFCPopupMenu Class object that was created when the framework drew the submenu of the toolbar menu button; NULL if no submenu is displayed.

Remarks

When a toolbar menu button displays a drop-down menu, the button creates a CMFCPopupMenu Class object to represent the menu. Call this method to obtain a pointer to the CMFCPopupMenu object. You should not store the returned pointer, because it is temporary and becomes invalid when the user closes the drop-down menu.

Indicates whether the pop-up menu is currently displayed.

virtual BOOL IsDroppedDown() const;

 

Return Value

TRUE if the toolbar menu button displays its submenu; otherwise FALSE.

Specifies whether menu items shows empty submenus.

virtual BOOL IsEmptyMenuAllowed() const;

 

Return Value

TRUE if the framework opens a submenu from the currently selected menu item even when the submenu is empty; otherwise FALSE.

Remarks

The framework calls this method when a user tries to open the submenu from the currently selected menu item. If the submenu is empty and IsEmptyMenuAllowed returns FALSE, the submenu will not open.

The default implementation returns FALSE. Override this method to customize this behavior.

Indicates whether the button is in exclusive mode.

virtual BOOL IsExclusive() const;

 

Return Value

TRUE if the button is working in exclusive mode; otherwise FALSE.

Remarks

When a user opens a popup menu for a button and then moves the mouse pointer over another toolbar or menu button, the popup menu closes unless the button is in exclusive mode.

The default implementation always returns FALSE. Override this method in a derived class if you want to turn on exclusive mode.

Determines whether the drop-down menu is in palette mode.

BOOL IsMenuPaletteMode() const;

 

Return Value

TRUE if the palette mode is enabled, otherwise FALSE.

Remarks

When the menu button is set to palette mode, menu items appear in multiple columns with only a limited number of rows. Call this method to obtain the number of rows. You can enable or disable the palette mode by calling CMFCToolBarMenuButton::SetMenuPaletteMode.

Indicates whether the drop-down menu has a tear-off bar.

virtual BOOL IsTearOffMenu() const;

 

Return Value

TRUE if the toolbar menu button has a tear-off bar; otherwise FALSE.

Remarks

To enable the tear-off feature and set the tear-off bar ID, call CMFCToolBarMenuButton::SetTearOff.

Specifies whether the framework always calls CFrameWndEx::OnDrawMenuImage when a button is drawn.

static BOOL m_bAlwaysCallOwnerDraw;  

Remarks

When this member variable is set to TRUE, the button always calls CFrameWndEx::OnDrawMenuImage method to display the image on the button. When m_bAlwaysCallOwnerDraw is FALSE, the button itself draws the image if the image is predefined. Otherwise, it calls OnDrawMenuImage.

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 OnAfterCreatePopupMenu();

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 OnBeforeDrag() 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 SIZE OnCalculateSize(
    CDC* pDC,  
    const CSize& sizeDefault,  
    BOOL bHorz);

Parameters

[in] pDC
[in] sizeDefault
[in] bHorz

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 void OnCancelMode();

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 void OnChangeParentWnd(CWnd* pWndParent);

Parameters

[in] pWndParent

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 OnClick(
    CWnd* pWnd,  
    BOOL bDelay = TRUE);

Parameters

[in] pWnd
[in] bDelay

Return Value

Remarks

Called by the framework when the user selects an item in the drop-down menu.

virtual BOOL OnClickMenuItem();

Return Value

FALSE if the framework should continue the default menu item processing; otherwise TRUE. The default implementation always returns FALSE.

Remarks

When the user clicks a menu item, the framework executes a command that is associated with that item.

To customize the menu item processing, override OnClickMenuItem in a class derived from CMFCToolBarMenuButton class. You must also override CFrameWndEx::OnShowPopupMenu and replace the menu buttons that require special processing with instances of the derived class.

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 OnContextHelp(CWnd* pWnd);

Parameters

[in] pWnd

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 void OnDraw(
    CDC* pDC,  
    const CRect& rect,  
    CMFCToolBarImages* pImages,  
    BOOL bHorz = TRUE,  
    BOOL bCustomizeMode = FALSE,  
    BOOL bHighlight = FALSE,  
    BOOL bDrawBorder = TRUE,  
    BOOL bGrayDisabledButtons = TRUE);

Parameters

[in] pDC
[in] rect
[in] pImages
[in] bHorz
[in] bCustomizeMode
[in] bHighlight
[in] bDrawBorder
[in] bGrayDisabledButtons

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 int OnDrawOnCustomizeList(
    CDC* pDC,  
    const CRect& rect,  
    BOOL bSelected);

Parameters

[in] pDC
[in] rect
[in] bSelected

Return Value

Remarks

Called by the framework when the user opens the drop-down menu of a toolbar menu button.

virtual BOOL OpenPopupMenu(CWnd* pWnd=NULL);

Parameters

[in] pWnd
Specifies the window that receives the drop-down menu commands. It can be NULL only if the toolbar menu button has a parent window.

Return Value

TRUE when a CMFCPopupMenu Class object was created and opened successfully; otherwise FALSE.

Remarks

This function is called by the framework when the user opens a drop-down menu from a toolbar menu 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.

virtual void ResetImageToDefault();

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 void SaveBarState();

Remarks

The framework calls this method when it creates a toolbar button as the result of a drag-and-drop operation. This method calls the CMFCPopupMenu::SaveState method of the top-level pop-up menu, which causes the parent button of the pop-up menu to recreate its menu.

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 Serialize(CArchive& ar);

Parameters

[in] ar

Remarks

Sets the accessibility data for the ribbon element.

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

Always returns TRUE.

Remarks

By default this method sets the accessibility data for the ribbon element and always returns TRUE. Override this method to set the accessibility data and return a value that indicates success or failure.

Specifies whether the button is drawn as a menu button or a split button when it has both a valid command ID and a submenu.

void SetMenuOnly(BOOL bMenuOnly);

Parameters

[in] bMenuOnly
TRUE to show this button as a menu button when it has both a valid command ID and a submenu, FALSE to show this button as a split button when it has both a valid command ID and a submenu.

Remarks

Typically, when a toolbar menu button has both a submenu and a command ID, the menu appears to be a split button that has a main button and an attached down arrow button. If you call this method and bMenuOnly is TRUE, the button instead appears to be a single menu button with a down arrow in the button. When the user clicks the arrow in either mode, the submenu opens, and when the user clicks the non-arrow part of the button in either mode the framework executes the command .

Specifies whether the drop-down menu is in palette mode.

void SetMenuPaletteMode(
    BOOL bMenuPaletteMode=TRUE,  
    int nPaletteRows=1);

Parameters

[in] bMenuPaletteMode
Specifies whether the drop-down menu is in palette mode.

[in] nPaletteRows
Number of rows in palette.

Remarks

In the palette mode, all menu items are displayed as a multicolumn palette. You specify the number of rows by using nPaletteRows.

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.

void SetMessageWnd(CWnd* pWndMessage);

Parameters

[in] pWndMessage

Remarks

Sets the toolbar menu button to display a radio button style icon when it is checked.

virtual void SetRadio();

Remarks

When the menu button is drawn while it is checked, it calls CMFCVisualManager::OnDrawMenuCheck to draw a checkmark icon. By default, OnDrawMenuCheck requests that the current visual manager draws a checkbox style checkmark on the menu button. After you call this method, the current visual manager instead draws a radio button style checkmark on the menu button. This change cannot be undone.

When you call this method and the menu button is currently being displayed, it will refresh.

Specifies the ID of the tear-off bar for the drop-down menu.

virtual void SetTearOff(UINT uiBarID);

Parameters

[in] uiBarID
Specifies a new tear-off bar ID.

Remarks

Call this method to specify the ID for the tear-off bar that is created when the user drags the menu button off of a menu bar. If the uiBarID parameter is 0, the user cannot tear off the menu button.

Call CWinAppEx::EnableTearOffMenus to enable the tear-off menu feature in your application.

Hierarchy Chart
Classes
CMFCToolBarButton Class
CMFCToolBar Class
CMFCPopupMenu Class

Show: