CMFCToolBarMenuButton Class

Article
08/03/2021

A toolbar button that contains a pop-up menu. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

Syntax

class CMFCToolBarMenuButton : public CMFCToolBarButton

Members

Public Constructors

Name	Description
CMFCToolBarMenuButton::CMFCToolBarMenuButton	Constructs a `CMFCToolBarMenuButton` object.

Public Methods

Name	Description
CMFCToolBarMenuButton::CompareWith	Compares this instance with the provided `CMFCToolBarButton` object. (Overrides CMFCToolBarButton::CompareWith.)
CMFCToolBarMenuButton::CopyFrom	Copies the properties of another toolbar button to the current button. (Overrides CMFCToolBarButton::CopyFrom.)
CMFCToolBarMenuButton::CreateFromMenu	Initializes the toolbar menu from a Windows menu handle.
CMFCToolBarMenuButton::CreateMenu	Creates a Windows menu that consists of the commands in the toolbar menu. Returns a handle to the Windows menu.
CMFCToolBarMenuButton::CreatePopupMenu	Creates a pop-up menu object ( CMFCPopupMenu Class) to display the toolbar menu.
CMFCToolBarMenuButton::EnableQuickCustomize
CMFCToolBarMenuButton::GetCommands	Gives read-only access to the list of commands in the toolbar menu.
CMFCToolBarMenuButton::GetImageRect	Retrieves the bounding rectangle for the button image.
CMFCToolBarMenuButton::GetPaletteRows	Returns the number of rows in the pop-up menu when the menu is in palette mode.
CMFCToolBarMenuButton::GetPopupMenu	Returns a pointer to the pop-up menu object that is associated with the button.
CMFCToolBarMenuButton::HasButton
CMFCToolBarMenuButton::HaveHotBorder	Determines whether a border of the button is displayed when a user selects the button. (Overrides CMFCToolBarButton::HaveHotBorder.)
CMFCToolBarMenuButton::IsBorder
CMFCToolBarMenuButton::IsClickedOnMenu
CMFCToolBarMenuButton::IsDroppedDown	Determines whether the pop-up menu is displayed.
CMFCToolBarMenuButton::IsEmptyMenuAllowed	Called by the framework to determine whether a user can open a submenu from the selected menu item.
CMFCToolBarMenuButton::IsExclusive	Determines 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::IsMenuPaletteMode	Determines whether the pop-up menu is in palette mode.
CMFCToolBarMenuButton::IsQuickMode
CMFCToolBarMenuButton::IsTearOffMenu	Determines whether the pop-up menu has a tear-off bar.
CMFCToolBarMenuButton::OnAfterCreatePopupMenu
CMFCToolBarMenuButton::OnBeforeDrag	Specifies whether the button can be dragged. (Overrides CMFCToolBarButton::OnBeforeDrag.)
CMFCToolBarMenuButton::OnCalculateSize	Called by the framework to calculate the size of the button for the specified device context and docking state. (Overrides CMFCToolBarButton::OnCalculateSize.)
CMFCToolBarMenuButton::OnCancelMode	Called by the framework to handle the WM_CANCELMODE message. (Overrides CMFCToolBarButton::OnCancelMode.)
CMFCToolBarMenuButton::OnChangeParentWnd	Called by the framework when the button is inserted into a new toolbar. (Overrides CMFCToolBarButton::OnChangeParentWnd.)
CMFCToolBarMenuButton::OnClick	Called by the framework when the user clicks the mouse button. (Overrides CMFCToolBarButton::OnClick.)
CMFCToolBarMenuButton::OnClickMenuItem	Called by the framework when the user selects an item in the pop-up menu.
CMFCToolBarMenuButton::OnContextHelp	Called by the framework when the parent toolbar handles a WM_HELPHITTEST message. (Overrides CMFCToolBarButton::OnContextHelp.)
CMFCToolBarMenuButton::OnDraw	Called by the framework to draw the button by using the specified styles and options. (Overrides CMFCToolBarButton::OnDraw.)
CMFCToolBarMenuButton::OnDrawOnCustomizeList	Called by the framework to draw the button in the Commands pane of the Customize dialog box. (Overrides CMFCToolBarButton::OnDrawOnCustomizeList.)
CMFCToolBarMenuButton::OpenPopupMenu	Called by the framework when the user opens the pop-up menu.
CMFCToolBarMenuButton::ResetImageToDefault	Sets to the default value the image that is associated with the button. (Overrides CMFCToolBarButton::ResetImageToDefault.)
CMFCToolBarMenuButton::SaveBarState	Saves the state of the toolbar button. (Overrides CMFCToolBarButton::SaveBarState.)
CMFCToolBarMenuButton::Serialize	Reads this object from an archive or writes it to an archive. (Overrides CMFCToolBarButton::Serialize.)
CMFCToolBarMenuButton::SetACCData	Populates the provided `CAccessibilityData` object with accessibility data from the toolbar button. (Overrides CMFCToolBarButton::SetACCData.)
CMFCToolBarMenuButton::SetMenuOnly	Specifies whether the button can be added to a toolbar.
CMFCToolBarMenuButton::SetMenuPaletteMode	Specifies whether the pop-up menu is in palette mode.
CMFCToolBarMenuButton::SetMessageWnd
CMFCToolBarMenuButton::SetRadio	Forces the toolbar menu button to display an icon indicating that it is selected.
CMFCToolBarMenuButton::SetTearOff	Specifies a tear-off bar ID for the pop-up menu.

Protected Methods

Name	Description
CMFCToolBarMenuButton::DrawDocumentIcon	Draws an icon on the menu button.

Data Members

Name	Description
CMFCToolBarMenuButton::m_bAlwaysCallOwnerDraw	If TRUE, the framework always calls CFrameWndEx::OnDrawMenuImage when a button is drawn.

Remarks

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 macro. The DECLARE_DYNCREATE macro generates an error when the application closes.

Example

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

Inheritance Hierarchy

CObject

CMFCToolBarButton

CMFCToolBarMenuButton

Requirements

Header: afxtoolbarmenubutton.h

CMFCToolBarMenuButton::CMFCToolBarMenuButton

Constructs a CMFCToolBarMenuButton object.

CMFCToolBarMenuButton();
CMFCToolBarMenuButton(const CMFCToolBarMenuButton& src);

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

Parameters

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

uiID
[in] 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.

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

iImage
[in] 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.

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

bUserButton
[in] 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"));

CMFCToolBarMenuButton::CompareWith

virtual BOOL CompareWith(const CMFCToolBarButton& other) const;

Parameters

[in] other

Return Value

Remarks

CMFCToolBarMenuButton::CopyFrom

virtual void CopyFrom(const CMFCToolBarButton& src);

Parameters

[in] src

Remarks

CMFCToolBarMenuButton::CreateFromMenu

Initializes the toolbar menu from a Windows menu handle.

virtual void CreateFromMenu(HMENU hMenu);

Parameters

hMenu
[in] 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.

CMFCToolBarMenuButton::CreateMenu

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.

CMFCToolBarMenuButton::CreatePopupMenu

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 or to perform additional initialization.

CMFCToolBarMenuButton::DrawDocumentIcon

Draws a document icon on the menu button.

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

Parameters

pDC
[in] A pointer to the device context.

rectImage
[in] Coordinates of the image bounding rectangle.

hIcon
[in] 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.

CMFCToolBarMenuButton::EnableQuickCustomize

void EnableQuickCustomize();

Remarks

CMFCToolBarMenuButton::HasButton

virtual BOOL HasButton() const;

Return Value

Remarks

CMFCToolBarMenuButton::HaveHotBorder

virtual BOOL HaveHotBorder() const;

Return Value

Remarks

CMFCToolBarMenuButton::IsBorder

virtual BOOL IsBorder() const;

Return Value

Remarks

CMFCToolBarMenuButton::IsClickedOnMenu

BOOL IsClickedOnMenu() const;

Return Value

Remarks

CMFCToolBarMenuButton::IsQuickMode

BOOL IsQuickMode();

Return Value

Remarks

CMFCToolBarMenuButton::GetCommands

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.

CMFCToolBarMenuButton::GetImageRect

Retrieves the bounding rectangle for the button image.

void GetImageRect(CRect& rectImage);

Parameters

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

CMFCToolBarMenuButton::GetPaletteRows

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.

CMFCToolBarMenuButton::GetPopupMenu

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.

CMFCToolBarMenuButton::IsDroppedDown

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.

CMFCToolBarMenuButton::IsEmptyMenuAllowed

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.

CMFCToolBarMenuButton::IsExclusive

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.

CMFCToolBarMenuButton::IsMenuPaletteMode

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.

CMFCToolBarMenuButton::IsTearOffMenu

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.

CMFCToolBarMenuButton::m_bAlwaysCallOwnerDraw

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.

CMFCToolBarMenuButton::OnAfterCreatePopupMenu

virtual void OnAfterCreatePopupMenu();

Remarks

CMFCToolBarMenuButton::OnBeforeDrag

virtual BOOL OnBeforeDrag() const;

Return Value

Remarks

CMFCToolBarMenuButton::OnCalculateSize

virtual SIZE OnCalculateSize(
    CDC* pDC,
    const CSize& sizeDefault,
    BOOL bHorz);

Parameters

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

Return Value

Remarks

CMFCToolBarMenuButton::OnCancelMode

virtual void OnCancelMode();

Remarks

CMFCToolBarMenuButton::OnChangeParentWnd

virtual void OnChangeParentWnd(CWnd* pWndParent);

Parameters

[in] pWndParent

Remarks

CMFCToolBarMenuButton::OnClick

virtual BOOL OnClick(
    CWnd* pWnd,
    BOOL bDelay = TRUE);

Parameters

[in] pWnd
[in] bDelay

Return Value

Remarks

CMFCToolBarMenuButton::OnClickMenuItem

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.

CMFCToolBarMenuButton::OnContextHelp

virtual BOOL OnContextHelp(CWnd* pWnd);

Parameters

[in] pWnd

Return Value

Remarks

CMFCToolBarMenuButton::OnDraw

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

CMFCToolBarMenuButton::OnDrawOnCustomizeList

virtual int OnDrawOnCustomizeList(
    CDC* pDC,
    const CRect& rect,
    BOOL bSelected);

Parameters

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

Return Value

Remarks

CMFCToolBarMenuButton::OpenPopupMenu

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

virtual BOOL OpenPopupMenu(CWnd* pWnd=NULL);

Parameters

pWnd
[in] 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.

CMFCToolBarMenuButton::ResetImageToDefault

virtual void ResetImageToDefault();

Remarks

CMFCToolBarMenuButton::SaveBarState

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.

CMFCToolBarMenuButton::Serialize

virtual void Serialize(CArchive& ar);

Parameters

[in] ar

Remarks

CMFCToolBarMenuButton::SetACCData

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.

CMFCToolBarMenuButton::SetMenuOnly

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

bMenuOnly
[in] 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 .

CMFCToolBarMenuButton::SetMenuPaletteMode

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

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

Parameters

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

nPaletteRows
[in] 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.

CMFCToolBarMenuButton::SetMessageWnd

void SetMessageWnd(CWnd* pWndMessage);

Parameters

[in] pWndMessage

Remarks

CMFCToolBarMenuButton::SetRadio

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.

CMFCToolBarMenuButton::SetTearOff

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

virtual void SetTearOff(UINT uiBarID);

Parameters

uiBarID
[in] 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.