| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CMFCDropDownToolbarButton Class |
CMFCDropDownToolbarButton Class |
11/04/2016 |
|
|
bc9d69e6-bd3e-4c15-9368-e80a504a0ba7 |
A type of toolbar button that behaves like a regular button when it is clicked. However, it opens a drop-down toolbar ( CMFCDropDownToolBar Class if the user presses and holds the toolbar button down.
class CMFCDropDownToolbarButton : public CMFCToolBarButton
| Name | Description |
|---|---|
| CMFCDropDownToolbarButton::CMFCDropDownToolbarButton | Constructs a CMFCDropDownToolbarButton object. |
CMFCDropDownToolbarButton::~CMFCDropDownToolbarButton |
Destructor. |
| Name | Description |
|---|---|
| CMFCDropDownToolbarButton::CopyFrom | Copies the properties of another toolbar button to the current button. (Overrides CMFCToolBarButton::CopyFrom.) |
CMFCDropDownToolbarButton::CreateObject |
Used by the framework to create a dynamic instance of this class type. |
| CMFCDropDownToolbarButton::DropDownToolbar | Opens a drop-down toolbar. |
| CMFCDropDownToolbarButton::ExportToMenuButton | Copies text from the toolbar button to a menu. (Overrides CMFCToolBarButton::ExportToMenuButton.) |
| CMFCDropDownToolbarButton::GetDropDownToolBar | Retrieves the drop-down toolbar that is associated with the button. |
CMFCDropDownToolbarButton::GetThisClass |
Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type. |
| CMFCDropDownToolbarButton::IsDropDown | Determines whether the drop-down toolbar is currently open. |
| CMFCDropDownToolbarButton::IsExtraSize | Determines whether the button can be displayed with an extended border. (Overrides CMFCToolBarButton::IsExtraSize.) |
| CMFCDropDownToolbarButton::OnCalculateSize | Called by the framework to calculate the size of the button for the specified device context and docking state. (Overrides CMFCToolBarButton::OnCalculateSize.) |
CMFCDropDownToolbarButton::OnCancelMode |
Called by the framework to handle the WM_CANCELMODE message. (Overrides CMCToolBarButton::OnCancelMode.) |
| CMFCDropDownToolbarButton::OnChangeParentWnd | Called by the framework when the button is inserted into a new toolbar. (Overrides CMFCToolBarButton::OnChangeParentWnd.) |
| CMFCDropDownToolbarButton::OnClick | Called by the framework when the user clicks the mouse button. (Overrides CMFCToolBarButton::OnClick.) |
| CMFCDropDownToolbarButton::OnClickUp | Called by the framework when the user releases the mouse button. (Overrides CMFCToolBarButton::OnClickUp.) |
| CMFCDropDownToolbarButton::OnContextHelp | Called by the framework when the parent toolbar handles a WM_HELPHITTEST message. (Overrides CMFCToolBarButton::OnContextHelp.) |
| CMFCDropDownToolbarButton::OnCustomizeMenu | Modifies the provided menu when the application displays a shortcut menu on the parent toolbar. (Overrides CMFCToolBarButton::OnCustomizeMenu.) |
| CMFCDropDownToolbarButton::OnDraw | Called by the framework to draw the button by using the specified styles and options. (Overrides CMFCToolBarButton::OnDraw.) |
| CMFCDropDownToolbarButton::OnDrawOnCustomizeList | Called by the framework to draw the button in the Commands pane of the Customize dialog box. (Overrides CMFCToolBarButton::OnDrawOnCustomizeList.) |
| CMFCDropDownToolbarButton::Serialize | Reads this object from an archive or writes it to an archive. (Overrides CMFCToolBarButton::Serialize.) |
| CMFCDropDownToolbarButton::SetDefaultCommand | Sets the default command that the framework uses when a user clicks the button. |
| Name | Description |
|---|---|
| CMFCDropDownToolbarButton::m_uiShowBarDelay | Specifies the length of time that a user must hold the mouse button down before the drop-down toolbar appears. |
A CMFCDropDownToolBarButton differs from an ordinary button in that it has a small arrow in the lower-right corner of the button. After the user selects a button from the drop-down toolbar, the framework displays its icon on the top-level toolbar button (the button with the small arrow in the lower-right corner).
For information about how to implement a drop-down toolbar, see CMFCDropDownToolBar Class.
The CMFCDropDownToolBarButton object can be exported to a CMFCToolBarMenuButton Class object and displayed as a menu button with a pop-up menu.
Header: afxdropdowntoolbar.h
Copies the properties of another toolbar button to the current button.
virtual void CopyFrom(const CMFCToolBarButton& src);
src
[in] A reference to the source button from which to copy.
Call this method to copy another toolbar button to this toolbar button. src must be of type CMFCDropDownToolbarButton.
Constructs a CMFCDropDownToolbarButton object.
CMFCDropDownToolbarButton();
CMFCDropDownToolbarButton(
LPCTSTR lpszName,
CMFCDropDownToolBar* pToolBar);
lpszName
[in] The default text of the button.
pToolBar
[in] A pointer to the CMFCDropDownToolBar object that is displayed when the user presses the button.
The second overload of the constructor copies to the drop-down button the first button from the toolbar that pToolBar specifies.
Typically, a drop-down toolbar button uses the text from the most recently used button in the toolbar that pToolBar specifies. It uses the text specified by lpszName when the button is converted to a menu button or is displayed in the Commands tab of the Customize dialog box. For more information about the Customize dialog box, see CMFCToolBarsCustomizeDialog Class.
The following example demonstrates how to construct an object of the CMFCDropDownToolbarButton class. This code snippet is part of the Visual Studio Demo sample.
[!code-cppNVC_MFC_VisualStudioDemo#31]
Opens a drop-down toolbar.
BOOL DropDownToolbar(CWnd* pWnd);
pWnd
[in] The parent window of the drop-down frame, or NULL to use the parent window of the drop-down toolbar button.
Nonzero if the method is successful; otherwise 0.
The CMFCDropDownToolbarButton::OnClick method calls this method to open the drop-down toolbar when the user presses and holds the toolbar button down.
This methods creates the drop-down toolbar by using the CMFCDropDownFrame::Create method. If the parent toolbar is docked vertically, this method positions the drop-down toolbar either to the left-hand or right-hand side of the parent toolbar, depending on the fit. Otherwise, this method positions the drop-down toolbar underneath the parent toolbar.
This method fails if pWnd is NULL and the drop-down toolbar button does not have a parent window.
Copies text from the toolbar button to a menu.
virtual BOOL ExportToMenuButton(CMFCToolBarMenuButton& menuButton) const;
menuButton
[in] A reference to the target menu button.
Nonzero if the method succeeds; otherwise 0.
This method calls the base class implementation ( CMFCToolBarButton::ExportToMenuButton) and then appends to the target menu button a pop-up menu that contains each toolbar menu item in this button. This method does not append sub-menus to the pop-up menu.
This method fails if the parent toolbar, m_pToolBar, is NULL or the base class implementation returns FALSE.
Retrieves the drop-down toolbar that is associated with the button.
CMFCToolBar* GetDropDownToolBar() const;
The drop-down toolbar that is associated with the button.
This method returns the m_pToolBar data member.
Determines whether the drop-down toolbar is currently open.
BOOL IsDropDown() const;
Nonzero if the drop-down toolbar is currently open; otherwise 0.
The framework opens the drop-down toolbar by using the CMFCDropDownToolbarButton::DropDownToolbar method. The framework closes the drop-down toolbar when the user presses the left-mouse button in the non-client area of the drop-down toolbar.
Determines whether the button can be displayed with an extended border.
virtual BOOL IsExtraSize() const;
Nonzero if the toolbar button can be displayed with an extended border; otherwise 0.
For more information about extended borders, see CMFCToolBarButton::IsExtraSize.
Specifies the length of time that a user must hold the mouse button down before the drop-down toolbar appears.
static UINT m_uiShowBarDelay;
The delay time is measured in milliseconds. The default value is 500. You can set another delay by changing the value of this shared data member.
Called by the framework to calculate the size of the button for the specified device context and docking state.
virtual SIZE OnCalculateSize(
CDC* pDC,
const CSize& sizeDefault,
BOOL bHorz);
pDC
[in] The device context that displays the button.
sizeDefault
[in] The default size of the button.
bHorz
[in] The dock state of the parent toolbar. This parameter is TRUE if the toolbar is docked horizontally or is floating, or FALSE if the toolbar is docked vertically.
A SIZE structure that contains the dimensions of the button, in pixels.
This method extends the base class implementation ( CMFCToolBarButton::OnCalculateSize) by adding the width of the drop-down arrow to the horizontal dimension of the button size.
Called by the framework when the button is inserted into a new toolbar.
virtual void OnChangeParentWnd(CWnd* pWndParent);
pWndParent
[in] The new parent window.
This method overrides the base class implementation ( CMFCToolBarButton::OnChangeParentWnd) by clearing the text label ( CMFCToolBarButton::m_strText) and setting the CMFCToolBarButton::m_bText and CMFCToolBarButton::m_bUserButton data members to FALSE.
Called by the framework when the user clicks the mouse button.
virtual BOOL OnClick(
CWnd* pWnd,
BOOL bDelay = TRUE);
pWnd
[in] The parent window of the toolbar button.
bDelay
[in] TRUE if the message should be handled with a delay.
Nonzero if the button processes the click message; otherwise 0.
This method extends the base class implementation, CMFCToolBarButton::OnClick, by updating the state of the drop-down toolbar.
When a user clicks the toolbar button, this method creates a timer that waits the length of time specified by the CMFCDropDownToolbarButton::m_uiShowBarDelay data member and then opens the drop-down toolbar by using the CMFCDropDownToolbarButton::DropDownToolbar method. This method closes the drop-down toolbar the second time the user clicks the toolbar button.
Called by the framework when the user releases the mouse button.
virtual BOOL OnClickUp();
Nonzero if the button processes the click message; otherwise 0.
This method extends the base class implementation, CMFCToolBarButton::OnClickUp, by updating the state of the drop-down toolbar.
This method stops the drop-down toolbar timer if it is active. It closes the drop-down toolbar if it is open.
For more information about the drop-down toolbar and drop-down toolbar timer, see CMFCDropDownToolbarButton::OnClick.
Called by the framework when the parent toolbar handles a WM_HELPHITTEST message.
virtual BOOL OnContextHelp(CWnd* pWnd);
pWnd
[in] The parent window of the toolbar button.
Nonzero if the button processes the help message; otherwise 0.
This method extends the base class implementation ( CMFCToolBarButton::OnContextHelp) by calling the CMFCDropDownToolbarButton::OnClick method with bDelay set to FALSE. This method returns the value that is returned by CMFCDropDownToolbarButton::OnClick.
For more information about the WM_HELPHITTEST message, see TN028: Context-Sensitive Help Support.
Modifies the provided menu when the application displays a shortcut menu on the parent toolbar.
virtual BOOL OnCustomizeMenu(CMenu* pMenu);
pMenu
[in] The menu to customize.
This method returns TRUE.
This method extends the base class implementation ( CMFCToolBarButton::OnCustomizeMenu) by disabling the following menu items:
-
Copy Button Image
-
Button Appearance
-
Image
-
Text
-
Image and Text
Override this method to modify the shortcut menu that the framework displays in customization mode.
Called by the framework to draw the button by using the specified styles and options.
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);
pDC
[in] The device context that displays the button.
rect
[in] The bounding rectangle of the button.
pImages
[in] The collection of toolbar images that is associated with the button.
bHorz
[in] The dock state of the parent toolbar. This parameter is TRUE when the button is docked horizontally and FALSE when the button is docked vertically.
bCustomizeMode
[in] Specifies whether the toolbar is in customization mode. This parameter is TRUE when the toolbar is in customization mode and FALSE when the toolbar is not in customization mode.
bHighlight
[in] Specifies whether the button is highlighted. This parameter is TRUE when the button is highlighted and FALSE when the button is not highlighted.
bDrawBorder
[in] Specifies whether the button should display its border. This parameter is TRUE when the button should display its border and FALSE when the button should not display its border.
bGrayDisabledButtons
[in] Specifies whether to shade disabled buttons or use the disabled images collection. This parameter is TRUE when disabled buttons should be shaded and FALSE when this method should use the disabled images collection.
Override this method to customize toolbar button drawing.
Called by the framework to draw the button in the Commands pane of the Customize dialog box.
virtual int OnDrawOnCustomizeList(
CDC* pDC,
const CRect& rect,
BOOL bSelected);
pDC
[in] The device context that displays the button.
rect
[in] The bounding rectangle of the button.
bSelected
[in] Whether the button is selected. If this parameter is TRUE, the button is selected. If this parameter is FALSE, the button is not selected.
The width, in pixels, of the button on the specified device context.
This method is called by the customization dialog box ( Commands tab) when the button is required to display itself on the owner-draw list box.
This method extends the base class implementation ( CMFCToolBarButton::OnDrawOnCustomizeList) by changing the text label of the button to the name of the button (that is,to the value of the lpszName parameter that you passed to the constructor).
Reads this object from an archive or writes it to an archive.
virtual void Serialize(CArchive& ar);
ar
[in] The CArchive object from which or to which to serialize.
This method extends the base class implementation ( CMFCToolBarButton::Serialize) by serializing the resource ID of the parent toolbar. When the archive is loading ( CArchive::IsLoading returns a nonzero value), this method sets the m_pToolBar data member to the toolbar that contains the serialized resource ID.
Sets the default command that the framework uses when a user clicks the button.
void SetDefaultCommand(UINT uiCmd);uiCmd
[in] The ID of the default command.
Call this method to specify a default command that the framework executes when the user clicks the button. An item with the command ID specified by uiCmd must be located in the parent drop-down toolbar.
Hierarchy Chart
Classes
CMFCDropDownToolBar Class
CMFCToolBar Class
CMFCToolBarMenuButton Class
Walkthrough: Putting Controls On Toolbars