CMFCToolBarMenuButton Class
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.
class CMFCToolBarMenuButton : public CMFCToolBarButton
| Name | Description |
|---|---|
| CMFCToolBarMenuButton::CMFCToolBarMenuButton | Constructs a CMFCToolBarMenuButton object. |
| 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. |
| Name | Description |
|---|---|
| CMFCToolBarMenuButton::DrawDocumentIcon | Draws an icon on the menu button. |
| Name | Description |
|---|---|
| CMFCToolBarMenuButton::m_bAlwaysCallOwnerDraw | If 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 macro. The 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);
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);
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.
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.
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"));
virtual BOOL CompareWith(const CMFCToolBarButton& other) const;
[in] other
virtual void CopyFrom(const CMFCToolBarButton& src);
[in] src
Initializes the toolbar menu from a Windows menu handle.
virtual void CreateFromMenu(HMENU hMenu);
hMenu
[in] A handle to a menu.
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;
A handle to the menu if success. NULL if the list of commands associated with the toolbar menu button is empty.
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();
A pointer to a CMFCPopupMenu object that displays the drop-down menu associated with the toolbar menu button.
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.
Draws a document icon on the menu button.
void DrawDocumentIcon(
CDC* pDC,
const CRect& rectImage,
HICON hIcon);
pDC
[in] A pointer to the device context.
rectImage
[in] Coordinates of the image bounding rectangle.
hIcon
[in] A handle to the icon.
This method takes a document icon and draws it on the menu button, centered in the area specified by rectImage.
void EnableQuickCustomize();
virtual BOOL HasButton() const;
virtual BOOL HaveHotBorder() const;
virtual BOOL IsBorder() const;
BOOL IsClickedOnMenu() const;
BOOL IsQuickMode();
Gives read-only access to the list of commands in the toolbar menu.
const CObList& GetCommands() const;
A const reference to a CObList Class object, which contains a collection of CMFCToolBarButton Class objects.
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);
rectImage
[out] 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;
The number of rows in the palette.
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;
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.
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;
TRUE if the toolbar menu button displays its submenu; otherwise FALSE.
Specifies whether menu items shows empty submenus.
virtual BOOL IsEmptyMenuAllowed() const;
TRUE if the framework opens a submenu from the currently selected menu item even when the submenu is empty; otherwise FALSE.
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;
TRUE if the button is working in exclusive mode; otherwise FALSE.
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;
TRUE if the palette mode is enabled, otherwise FALSE.
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;
TRUE if the toolbar menu button has a tear-off bar; otherwise FALSE.
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;
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.
virtual void OnAfterCreatePopupMenu();
virtual BOOL OnBeforeDrag() const;
virtual SIZE OnCalculateSize(
CDC* pDC,
const CSize& sizeDefault,
BOOL bHorz);
[in] pDC
[in] sizeDefault
[in] bHorz
virtual void OnCancelMode();
virtual void OnChangeParentWnd(CWnd* pWndParent);
[in] pWndParent
virtual BOOL OnClick(
CWnd* pWnd,
BOOL bDelay = TRUE);
[in] pWnd
[in] bDelay
Called by the framework when the user selects an item in the drop-down menu.
virtual BOOL OnClickMenuItem();
FALSE if the framework should continue the default menu item processing; otherwise TRUE. The default implementation always returns FALSE.
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.
virtual BOOL OnContextHelp(CWnd* pWnd);
[in] pWnd
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);
[in] pDC
[in] rect
[in] pImages
[in] bHorz
[in] bCustomizeMode
[in] bHighlight
[in] bDrawBorder
[in] bGrayDisabledButtons
virtual int OnDrawOnCustomizeList(
CDC* pDC,
const CRect& rect,
BOOL bSelected);
[in] pDC
[in] rect
[in] bSelected
Called by the framework when the user opens the drop-down menu of a toolbar menu button.
virtual BOOL OpenPopupMenu(CWnd* pWnd=NULL);
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.
TRUE when a CMFCPopupMenu Class object was created and opened successfully; otherwise FALSE.
This function is called by the framework when the user opens a drop-down menu from a toolbar menu button.
virtual void ResetImageToDefault();
virtual void SaveBarState();
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.
virtual void Serialize(CArchive& ar);
[in] ar
Sets the accessibility data for the ribbon element.
virtual BOOL SetACCData(
CWnd* pParent,
CAccessibilityData& data);
pParent
The parent window for the ribbon element.
data
The accessibility data for the ribbon element.
Always returns TRUE.
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);
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.
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);
bMenuPaletteMode
[in] Specifies whether the drop-down menu is in palette mode.
nPaletteRows
[in] Number of rows in palette.
In the palette mode, all menu items are displayed as a multicolumn palette. You specify the number of rows by using nPaletteRows.
void SetMessageWnd(CWnd* pWndMessage);
[in] pWndMessage
Sets the toolbar menu button to display a radio button style icon when it is checked.
virtual void SetRadio();
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);
uiBarID
[in] Specifies a new tear-off bar ID.
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