| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CMFCToolBarButton Class |
CMFCToolBarButton Class |
11/04/2016 |
|
|
8a6ecffb-86b0-4f5c-8211-a9146b463efd |
Provides button functionality to toolbars.
class CMFCToolBarButton : public CObject
| Name | Description |
|---|---|
| CMFCToolBarButton::CMFCToolBarButton | Constructs and initializes a CMFCToolBarButton object. |
CMFCToolBarButton::~CMFCToolBarButton |
Destructor. |
| Name | Description |
|---|---|
| CMFCToolBarButton::CanBeDropped | Specifies whether a user can position a button on a toolbar or menu during customization. |
| CMFCToolBarButton::CanBeStored | Specifies whether the button can be stored. |
| CMFCToolBarButton::CanBeStretched | Specifies whether a user can stretch the button during customization. |
| CMFCToolBarButton::CompareWith | Compares this instance with the provided CMFCToolBarButton object. |
| CMFCToolBarButton::CopyFrom | Copies the properties of another toolbar button to the current button. |
| CMFCToolBarButton::CreateFromOleData | Creates a CMFCToolBarButton object from the provided COleDataObject object. |
CMFCToolBarButton::CreateObject |
Used by the framework to create a dynamic instance of this class type. |
| CMFCToolBarButton::EnableWindow | Enables or disables mouse and keyboard input. |
| CMFCToolBarButton::ExportToMenuButton | Copies text from the toolbar button to a menu. |
| CMFCToolBarButton::GetClipboardFormat | Retrieves the global clipboard format for the application. |
| CMFCToolBarButton::GetHwnd | Retrieves the window handle that is associated with the toolbar button. |
| CMFCToolBarButton::GetImage | Retrieves the image index of the button. |
| CMFCToolBarButton::GetInvalidateRect | Retrieves the region of the client area of the button that must be redrawn. |
| CMFCToolBarButton::GetParentWnd | Retrieves the parent window of the button. |
| CMFCToolBarButton::GetProtectedCommands | Retrieves the list of commands that the user cannot customize. |
| CMFCToolBarButton::GetTextSize | Retrieves the size of the button text. |
| CMFCToolBarButton::HasFocus | Determines whether the button has the current input focus. |
| CMFCToolBarButton::HaveHotBorder | Determines whether a border of the button is displayed when a user selects the button. |
| CMFCToolBarButton::IsDrawImage | Determines whether an image is displayed on the button. |
| CMFCToolBarButton::IsDrawText | Determines whether a text label is displayed on the button. |
| CMFCToolBarButton::IsDroppedDown | Determines whether the button displays a submenu. |
| CMFCToolBarButton::IsEditable | Determines whether the button can be customized. |
| CMFCToolBarButton::IsExtraSize | Determines whether the button can be displayed with an extended border. |
| CMFCToolBarButton::IsFirstInGroup | Determines whether the button is in the first position in its button group. |
| CMFCToolBarButton::IsHidden | Determines whether the button is hidden. |
| CMFCToolBarButton::IsHorizontal | Determines whether the button is located on a horizontal toolbar. |
| CMFCToolBarButton::IsLastInGroup | Specifies whether the button is in the last position in its button group. |
| CMFCToolBarButton::IsLocked | Determines whether the button is on a locked (non-customizable) toolbar. |
| CMFCToolBarButton::IsOwnerOf | Determines whether the button is the owner of the provided window handle. |
| CMFCToolBarButton::IsVisible | Determines whether the toolbar button is visible. |
| CMFCToolBarButton::IsWindowVisible | Determines whether the underlying window handle of the button is visible. |
| CMFCToolBarButton::NotifyCommand | Specifies whether the button processes the WM_COMMAND message. |
| CMFCToolBarButton::OnAddToCustomizePage | Called by the framework when the button is added to a Customize dialog box. |
| CMFCToolBarButton::OnBeforeDrag | Specifies whether the button can be dragged. |
| CMFCToolBarButton::OnBeforeDrop | Specifies whether a user can drop the button onto the target toolbar. |
| CMFCToolBarButton::OnCalculateSize | Called by the framework to calculate the size of the button for the specified device context and docking state. |
| CMFCToolBarButton::OnCancelMode | Called by the framework to handle the WM_CANCELMODE message. |
| CMFCToolBarButton::OnChangeParentWnd | Called by the framework when the button is inserted into a new toolbar. |
| CMFCToolBarButton::OnClick | Called by the framework when the user clicks the mouse button. |
| CMFCToolBarButton::OnClickUp | Called by the framework when the user releases the mouse button. |
| CMFCToolBarButton::OnContextHelp | Called by the framework when the parent toolbar handles a WM_HELPHITTEST message. |
| CMFCToolBarButton::OnCtlColor | Called by the framework when the parent toolbar handles a WM_CTLCOLOR message. |
| CMFCToolBarButton::OnCustomizeMenu | Allows the button to modify the provided menu when the application displays a shortcut menu on the parent toolbar. |
| CMFCToolBarButton::OnDblClk | Called by the framework when the parent toolbar handles a WM_LBUTTONDBLCLK message. |
| CMFCToolBarButton::OnDraw | Called by the framework to draw the button by using the specified styles and options. |
| CMFCToolBarButton::OnDrawOnCustomizeList | Called by the framework to draw the button in the Commands pane of the Customize dialog box. |
| CMFCToolBarButton::OnGetCustomToolTipText | Called by the framework to retrieve the custom tooltip text for the button. |
| CMFCToolBarButton::OnGlobalFontsChanged | Called by the framework when the global font has changed. |
| CMFCToolBarButton::OnMove | Called by the framework when the parent toolbar moves. |
| CMFCToolBarButton::OnShow | Called by the framework when the button becomes visible or invisible. |
| CMFCToolBarButton::OnSize | Called by the framework when the parent toolbar changes its size or position and this change requires the button to change size. |
| CMFCToolBarButton::OnToolHitTest | Called by the framework when the parent toolbar must determine whether a point is in the bounding rectangle of the button. |
| CMFCToolBarButton::OnUpdateToolTip | Called by the framework when the parent toolbar updates its tooltip text. |
| CMFCToolBarButton::PrepareDrag | Called by the framework when the button is about to perform a drag-and-drop operation. |
| CMFCToolBarButton::Rect | Retrieves the bounding rectangle of the button. |
| CMFCToolBarButton::ResetImageToDefault | Sets to the default value the image that is associated with the button. |
| CMFCToolBarButton::SaveBarState | Saves the state of the toolbar button. |
| CMFCToolBarButton::Serialize | Reads this object from an archive or writes it to an archive. (Overrides CObject::Serialize.) |
| CMFCToolBarButton::SetACCData | Populates the provided CAccessibilityData object with accessibility data from the toolbar button. |
| CMFCToolBarButton::SetClipboardFormatName | Renames the global clipboard format. |
| CMFCToolBarButton::SetImage | Sets the image index of the button. |
| CMFCToolBarButton::SetProtectedCommands | Sets the list of commands that the user cannot customize. |
| CMFCToolBarButton::SetRadio | Called by the framework when a button changes its checked state. |
| CMFCToolBarButton::SetRect | Sets the bounding rectangle of the button. |
| CMFCToolBarButton::SetStyle | Sets the style of the button. |
| CMFCToolBarButton::SetVisible | Specifies whether the button is visible. |
| CMFCToolBarButton::Show | Shows or hides the button. |
| Name | Description |
|---|---|
| CMFCToolBarButton::m_bImage | Specifies whether an image is displayed on the button. |
| CMFCToolBarButton::m_bText | Specifies whether a text label is displayed on the button. |
| CMFCToolBarButton::m_bTextBelow | Specifies whether the text label is displayed underneath the image on the button. |
| CMFCToolBarButton::m_bUserButton | Specifies whether the button has a user-defined image. |
| CMFCToolBarButton::m_bWholeText | Specifies whether the button displays its full text label even if it does not fit in the bounding rectangle. |
| CMFCToolBarButton::m_bWrap | Specifies whether the button next to a separator will be put on the next row. |
| CMFCToolBarButton::m_bWrapText | Specifies whether multi-line text labels are enabled. |
| CMFCToolBarButton::m_nID | The command ID of the button. |
| CMFCToolBarButton::m_nStyle | The style of the button. |
| CMFCToolBarButton::m_strText | The text label of the button. |
A CMFCToolbarButton object is a control that resides on a toolbar. Its behavior resembles that of an ordinary button. You can assign an image and a text label to this object. A toolbar button can also have a command ID. When the user clicks the toolbar button, the framework executes the command that this ID specifies.
Typically, toolbar buttons can be customized: the user can drag buttons from one toolbar to another, and copy, paste, delete, and edit text labels and images. To prevent the user from customizing the toolbar, you can lock the toolbar in one of two ways. Either set the bLocked flag to TRUE when you call CMFCToolBar::LoadToolBar, or add the command ID of an individual button to the global list of protected commands by using the CMFCToolBarButton::SetProtectedCommands method.
CMFCToolBarButton objects display images from the global collections of toolbar images in the application. These collections are maintained by the parent toolbar, CMFCToolBar Class. For more information, see CMFCToolBarImages Class.
When the user clicks a toolbar button, its parent toolbar processes the mouse message and communicates the appropriate actions to the button. If the button has a valid command ID, the parent toolbar sends the WM_COMMAND message to the parent frame.
The CMFCToolBarButton class is the base class for other toolbar button classes, such as CMFCToolBarMenuButton Class, CMFCToolBarEditBoxButton Class, and CMFCToolBarComboBoxButton Class.
The following example demonstrates how to configure a CMFCToolBarButton object by using various methods in the CMFCToolBarButton class. The example illustrates how to enable the mouse and keyboard input, set the image index of the button, set the bounding rectangle of the button, and make the button visible. This code snippet is part of the Tab Control sample.
[!code-cppNVC_MFC_TabControl#1] [!code-cppNVC_MFC_TabControl#2]
Header: afxtoolbarbutton.h
Specifies whether a user can position a button on a toolbar or menu during customization.
virtual BOOL CanBeDropped(CMFCToolBar* pToolbar);
pToolbar
[in] Unused.
This method returns TRUE.
By default, a toolbar button can be dropped on every customizable (that is, non-locked) toolbar.
The default implementation of this method returns TRUE. Override this method and return FALSE if you want to prevent the user from repositioning the button.
Determines whether the button can be stored.
virtual BOOL CanBeStored() const;
This method returns TRUE.
The framework uses this method to determine whether the button can participate in a drag-and-drop operation.
The default implementation returns TRUE. Override this method if your button cannot be stored as part of a drag-and-drop operation. For more information about drag-and-drop operations, see OLE drag and drop.
Specifies whether a user can stretch the button during customization.
virtual BOOL CanBeStretched() const;
This method returns FALSE.
This method is used by the framework to determine whether the button can be stretched in customization mode.
The default implementation of this method returns FALSE. Override this method to return TRUE for a variable-width control such as a combo box or slider.
For more information about customization mode, see CMFCToolBar::SetCustomizeMode.
Constructs and initializes a CMFCToolBarButton object.
CMFCToolBarButton(
UINT uiID,
int iImage,
LPCTSTR lpszText=NULL,
BOOL bUserButton=FALSE,
BOOL bLocked=FALSE);
uiID
[in] The command ID of the button.
iImage
[in] The image index of the button in the collection of images.
lpszText
[in] The text label of the button. Can be NULL.
bUserButton
[in] A Boolean value that determines whether the button is user-defined. If this parameter is TRUE, the button is user-defined. Otherwise, the button image is loaded from a resource.
bLocked
[in] A Boolean value that determines whether the button can be customized. If this parameter is TRUE, the button cannot be customized. Otherwise, the button can be customized.
Compares this instance with the provided CMFCToolBarButton object.
virtual BOOL CompareWith(const CMFCToolBarButton& other) const;
other
[in] Reference to the object to compare with this instance.
Nonzero if the provided object equals the value of this instance; otherwise, 0.
The default implementation determines whether the command ID of the provided object equals the command ID of this instance. Override this method if you must perform additional processing to determine whether two CMFCToolBarButton objects are equal.
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.
Creates a CMFCToolBarButton object from the provided COleDataObject object.
static CMFCToolBarButton* __stdcall CreateFromOleData(COleDataObject* pDataObject);
pDataObject
[in] The source OLE data object.
The created CMFCToolBarButton object.
This method is used by the framework to perform data transfer in various formats. For example, the CMFCOutlookBarPane::OnDragOver method uses this method to perform drag-and-drop operations.
Enables or disables mouse and keyboard input.
virtual void EnableWindow(BOOL bEnable = TRUE);
bEnable
[in] Set this parameter to TRUE to enable input, or to FALSE to disable input.
This method calls the EnableWindow function to enable or disable input. For more information, see EnableWindow in the Windows SDK.
Copies text from the toolbar button to a menu.
virtual BOOL ExportToMenuButton(CMFCToolBarMenuButton& menuButton) const;
menuButton
[in] A reference to the target menu button.
This method returns TRUE.
The framework calls this method to copy the text from a toolbar button to a menu button. The default implementation copies the text label of the button. If the text label is empty, this method copies the tooltip text of the button.
The default implementation of this method returns TRUE. Override this method if you want to take additional actions when the framework converts an object that is derived from CMFCToolbarButton to a menu button.
Retrieves the global clipboard format for the application.
static CLIPFORMAT __stdcall GetClipboardFormat();
The global CLIPFORMAT value for the application.
The framework calls this method to retrieve the clipboard format for OLE data transfer operations. For example, the CMFCToolBarButton::CreateFromOleData method uses this method to copy data from a source OLE data object.
This method sets the global CLIPFORMAT value the first time this method is called. All subsequent calls to this method return this value.
To allow drag-and-drop operations to occur between applications, call the CMFCToolBarButton::SetClipboardFormatName method.
For more information about clipboards in MFC, see Clipboard.
Retrieves the window handle that is associated with the toolbar button.
virtual HWND GetHwnd();
The window handle that is associated with the toolbar button or NULL if the toolbar button has no associated window handle.
The default implementation of this method returns NULL. Override this method to return the window handle of your specific control.
Retrieves the image index of the button.
int GetImage() const;
The index of the image associated with this button.
If the button has a user-defined image (that is, if bUserButton was TRUE in the constructor), the returned index specifies an image in the collection of user-defined images (see CMFCToolBar::GetUserImages). Otherwise, the index specifies an image in the collection of images that are loaded from a resource file (see CMFCToolBar::GetImages). For more information about resource files, see Working with Resource Files.
Retrieves the region of the client area of the button that must be redrawn.
virtual const CRect GetInvalidateRect() const;
A CRect object that specifies the region that must be redrawn.
The default implementation of this method returns the whole client area. Override this method if you want a different area to be redrawn.
Retrieves the parent window of the button.
CWnd* GetParentWnd() const;
The parent window of the button.
Retrieves the list of commands that the user cannot customize.
static const CList<UINT,UINT>& GetProtectedCommands();
The list of protected commands.
In customization mode, the framework disables toolbar button commands that are protected. The user cannot perform drag-and-drop and edit operations on disabled toolbar buttons.
Use the CMFCToolBarButton::SetProtectedCommands method to define the list of protected commands.
Retrieves the size of the button text.
SIZE GetTextSize() const;
A SIZE object that contains the size, in pixels, of the button text.
Determines whether the button has the current input focus.
virtual BOOL HasFocus() const;
Nonzero if the button has the input focus; otherwise 0.
The default implementation of this method returns nonzero if the button has the input focus or is a child or descendant window of the window that has the input focus. You can override this function to customize this behavior.
Determines whether a border of the button is displayed when a user selects the button.
virtual BOOL HaveHotBorder() const;
This method returns TRUE.
The framework calls this method to determine whether the toolbar button should display its border when a user selects it.
The default implementation returns TRUE. You can override this method to customize this behavior.
Determines whether an image is displayed on the button.
BOOL IsDrawImage() const;
Nonzero if an image is displayed on the button; otherwise 0.
This method returns FALSE if the toolbar button has no associated image ( CMFCToolBarButton::GetImage returns -1) or if CMFCToolBarButton::m_bImage is set to FALSE.
Determines whether a text label is displayed on the button.
BOOL IsDrawText() const;
Nonzero if a text label is displayed; otherwise 0.
This method returns FALSE if the toolbar button has no associated text label ( CMFCToolBarButton::m_strText is empty) or CMFCToolBarButton::m_bText is set to FALSE.
Determines whether the button displays a submenu.
virtual BOOL IsDroppedDown() const;
This method returns FALSE.
The default implementation of this method returns FALSE. Override this method to return TRUE if your control displays a submenu.
Determines whether the button can be customized.
virtual BOOL IsEditable() const;
Nonzero if a button can be customized by the user; otherwise 0.
The framework calls this method to determine whether the user can customize the toolbar button by using drag-and-drop or edit operations.
The default implementation returns FALSE if the command ID of the button is a standard command (you can determine this by calling the IsStandardCommand function) or if the command ID is in the list of protected commands. For more information about protected commands, see CMFCToolBarButton::GetProtectedCommands and CMFCToolBarButton::SetProtectedCommands.
Override this method to customize its behavior.
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.
Several skins use extra size for the borders of toolbar buttons (for example, round buttons).
If the user moves this button from one toolbar to another, the framework calls the CMFCToolBarButton::OnChangeParentWnd method. The CMFCToolBarButton::OnChangeParentWnd method sets the extra size flag to that of the new parent toolbar (for more information, see CMFCToolBar::IsButtonExtraSizeAvailable).
Determines whether the button is in the first position in its button group.
virtual BOOL IsFirstInGroup() const;
TRUE if the button is the first button in its button group; otherwise FALSE.
This method defines a button group as a neighboring set of buttons that are positioned on the same row and are bounded by separators or the border of the toolbar. This method returns FALSE if the toolbar button refers to the Customize button. For more information about the Customize button, see CMFCToolBar::GetCustomizeButton.
Call the CMFCToolBarButton::IsLastInGroup method to determine whether the button is in the last position in its button group.
Determines whether the button is hidden.
BOOL IsHidden() const;
Nonzero if the button is hidden (invisible); otherwise 0.
The framework calls this method when the parent toolbar is stretched to determine whether the toolbar button is visible.
If you set the button to be invisible by using the CMFCToolBarButton::SetVisible method, use CMFCToolBarButton::IsVisible to determine whether the toolbar button is visible.
By default, all toolbar buttons are visible. Use the CMFCToolBarButton::Show method to hide or show toolbar buttons.
Determines whether the button is located on a horizontal toolbar.
BOOL IsHorizontal() const;
Nonzero if a toolbar button is located on a horizontal toolbar; otherwise 0.
The framework calls this method to determine the layout of toolbar buttons.
This method returns the m_bHorz data member. The default value of the m_bHorz data member is TRUE; it is reset on each call to the CMFCToolBarButton::OnDraw method.
Specifies whether the button is in the last position in its button group.
virtual BOOL IsLastInGroup() const;
TRUE if the button is the last button in its button group; otherwise FALSE.
This method defines a button group as a neighboring set of buttons that are positioned on the same row and are bounded by separators or the border of the toolbar This method returns FALSE if the toolbar button has no parent toolbar or the toolbar button refers to the Customize button. For more information about the Customize button, see CMFCToolBar::GetCustomizeButton.
Call the CMFCToolBarButton::IsFirstInGroup method to determine whether the button is in the first position in its button group.
Determines whether the button is on a locked (non-customizable) toolbar.
BOOL IsLocked() const;
Nonzero if the button is on a locked toolbar; otherwise 0.
The framework calls this method to determine whether the user can customize the toolbar button by using drag-and-drop or edit operations. Set the locked attribute on the parent toolbar by using the CMFCToolBar::LoadToolBar method. The framework passes the value of this attribute to the constructor of each toolbar button ( CMFCToolbarButton) that it inserts into the parent toolbar.
Determines whether the button is the owner of the provided window handle.
virtual BOOL IsOwnerOf(HWND hwnd);
hwnd
[in] A window handle.
Nonzero if the button is the owner of the provided window handle; otherwise 0.
This method returns nonzero if hwnd either refers to the direct window handle or is a child of the window handle that is associated with the button. This method returns 0 if hwnd is NULL.
Determines whether the toolbar button is visible.
BOOL IsVisible() const;
Nonzero if the toolbar button is visible; otherwise 0.
You can show or hide the toolbar button by using the CMFCToolBarButton::SetVisible method. Call the CPane::AdjustSizeImmediate method on the parent toolbar after you call CMFCToolBarButton::SetVisible to recalculate the layout of a parent toolbar.
Determines whether the underlying window handle of the button is visible.
virtual BOOL IsWindowVisible();
Nonzero if the underlying window handle of the button is visible; otherwise 0.
This method returns nonzero if the styles attribute of the underlying window handle contains the WS_VISIBLE style. This method returns FALSE if the underlying window handle of the button is NULL.
Specifies whether an image is displayed on the button.
BOOL m_bImage;
If this data member is set to TRUE, the framework displays the image that is associated with the toolbar button; otherwise the framework does not display the image. This member affects the return value of the CMFCToolBarButton::m_bImage method.
Specifies whether a text label is displayed on the button.
BOOL m_bText;
If this data member is set to TRUE, the framework displays the text label of the toolbar button; otherwise the framework does not display the text label. This member affects the return value of the CMFCToolBarButton::m_bText method.
Specifies whether the text label is displayed underneath the image on the button.
BOOL m_bTextBelow;
If this member variable is set to TRUE, the framework displays the text of the button underneath the image. The default value of this member is FALSE.
Specifies whether the button has a user-defined image
BOOL m_bUserButton;
This data member is set to TRUE when the button has a user-defined image associated with it.
Specifies whether the button displays its full text label even if it does not fit in the bounding rectangle.
BOOL m_bWholeText;
If this data member is set to TRUE, the framework displays the full text label by enlarging the button. Otherwise, the framework truncates and appends an ellipsis ( ...) to the text label.
Specifies whether the button next to a separator will be put on the next row.
BOOL m_bWrap;
The framework sets this data member to TRUE when the toolbar button does not fit on the current row or when you specify a layout (for example, a specific number of toolbar buttons per row).
The framework places this button on the next row if this data member is set to TRUE and the toolbar is docked horizontally or floating.
The default value of this data member is FALSE.
Specifies whether multi-line text labels are enabled.
AFX_IMPORT_DATA static BOOL m_bWrapText;
If this static member variable is TRUE, the framework enables all toolbars to display multi-line text labels on toolbar buttons.
The default value of this data member is FALSE.
The command ID of the button.
UINT m_nID;
A command ID of -1 indicates that the button is a separator. All button separators have the TBBS_SEPARATOR style. See CMFCToolBarButton::m_nStyle for more information about button styles.
The style of the button.
UINT m_nStyle;
See ToolBar Control Styles for the list of available toolbar button styles.
The text label of the button.
CString m_strText;
This data member contains the text label of the button. The text label can be empty.
Specifies whether the button processes the WM_COMMAND message.
virtual BOOL NotifyCommand(int iNotifyCode);
iNotifyCode
[in] The notification message that is associated with the command.
This method returns FALSE.
The framework calls this method when it is about to send a WM_COMMAND message to the parent window.
By default, this method returns FALSE. Override this method to return TRUE if you want to process the WM_COMMAND message or FALSE to indicate that the parent toolbar should handle the message.
Called by the framework when the button is added to a Customize dialog box.
virtual void OnAddToCustomizePage();
The default implementation of this method does nothing. Override this method if you want to perform some action when the button is added to a Customize dialog box.
Specifies whether the button can be dragged.
virtual BOOL OnBeforeDrag() const;
TRUE if the button can be dragged; otherwise FALSE.
The framework calls this method before the user starts to drag the button.
The default implementation of this method returns TRUE. Override this method to return FALSE to disable dragging of the button.
Specifies whether a user can drop the button onto the target toolbar.
virtual BOOL OnBeforeDrop(CMFCToolBar* pTarget);
pTarget
[in] The target of the drag-and-drop operation.
TRUE if the button can be dropped onto the provided target toolbar; otherwise FALSE.
The framework calls this method before the button is dropped onto a toolbar.
The default implementation of this method returns TRUE. Override this method to return FALSE to disable the drop operation on the specified target.
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.
The framework calls this method to determine the size of the toolbar button for the specified device context and dock state.
The default implementation considers the text and image sizes (if they are displayed), the text and image positions (the text below or at the right-hand side of the image), and the toolbar dock state.
Override this method if you want to provide the size of a non-standard button (for example, an edit box button).
Called by the framework to handle the WM_CANCELMODE message.
virtual void OnCancelMode();
The default implementation of this method does nothing. Override this method if you want to handle the WM_CANCELMODE message.
Called by the framework when the button is inserted into a new toolbar.
virtual void OnChangeParentWnd(CWnd* pWndParent);
pWndParent
[in] The new parent window.
The button is inserted into a toolbar, for example, when the user drags it from one toolbar to another toolbar.
The default implementation of this method does nothing.
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.
This method returns FALSE.
The framework calls this method when the user clicks the toolbar button.
The default implementation does nothing and returns FALSE. Override this method to return a nonzero value if the button processes the click message.
Called by the framework when the user releases the mouse button.
virtual BOOL OnClickUp();
This method returns FALSE.
The framework calls this method when the user releases the toolbar button.
The default implementation does nothing and returns FALSE. Override this method to return a nonzero value if the button processes the click message.
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.
This method returns FALSE.
The default implementation of this method does nothing and returns FALSE. Override this method to return a nonzero value if the button processes the help message.
For more information about the WM_HELPHITTEST message, see TN028: Context-Sensitive Help Support.
Called by the framework when the parent toolbar handles a WM_CTLCOLOR message.
virtual HBRUSH OnCtlColor(
CDC* pDC,
UINT nCtlColor);
pDC
[in] The device context that displays the button.
nCtlColor
[in] The specific color notification.
A handle to the brush object that the framework uses to paint the background of the button.
The framework calls this method when the parent toolbar processes the WM_CTLCOLOR message for a toolbar button that contains a Windows control. The framework does not call this method if the toolbar button is windowless.
The framework calls this method when the toolbar framework is in customization mode and the toolbar button is unlocked. For more information about customization mode, see CMFCToolBar::SetCustomizeMode. For more information about locking toolbar buttons, see CMFCToolBarButton::IsLocked.
The default implementation does nothing and returns NULL.
Allows the button to modify 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 FALSE.
The default implementation does nothing and returns FALSE. Override this method and return a nonzero value if you want to modify the contents of the provided menu.
Called by the framework when the parent toolbar handles a WM_LBUTTONDBLCLK message.
virtual void OnDblClk(CWnd* pWnd);
pWnd
[in] - The parent window of the button.
This method is called by the CMFCToolBar::OnLButtonDblClk method when the parent toolbar handles a WM_LBUTTONDBLCLK message.
The default implementation of this method does nothing.
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] Specifies 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 about to display itself on the owner-draw list box.
The default implementation of this method displays the image and text label of the button if they are available. If the text label of the button is not available, the method displays the tooltip text.
Override this method to perform custom drawing.
Called by the framework to retrieve the custom tooltip text for the button.
virtual BOOL OnGetCustomToolTipText(CString& strToolTip);
strToolTip
[out] A CString object that receives the custom tooltip text.
This method returns FALSE.
The framework calls this method when it displays the tooltip for the toolbar button. If this method returns FALSE, the framework uses a default tooltip.
The default implementation does nothing and returns FALSE. Override this method and return a nonzero value to provide custom tooltip text for the toolbar button.
Called by the framework when the global font has changed.
virtual void OnGlobalFontsChanged();
The default implementation of this method does nothing. Override this method to update the font that is used to display the button text.
Called by the framework when the parent toolbar moves.
virtual void OnMove();
The default implementation of this method does nothing. Override this method to reposition the button when the parent toolbar moves.
Called by the framework when the button becomes visible or invisible.
virtual void OnShow(BOOL bShow);
bShow
[in] Specifies whether the button is visible. If this parameter is TRUE, the button is visible. Otherwise, the button is not visible.
The default implementation of this method does nothing. Override this method to update the visibility of the button.
Called by the framework when the parent toolbar changes its size or position and this change causes the button to change size.
virtual void OnSize(int iSize);
iSize
[in] The new width of the button.
The default implementation of this method does nothing. Override this method to resize the button when the size or position of the parent toolbar changes.
Called by the framework when the parent toolbar must determine whether a point is in the bounding rectangle of the button.
virtual BOOL OnToolHitTest(
const CWnd* pWnd,
TOOLINFO* pTI);
pWnd
[in] The parent window of the button. Can be NULL.
pTI
[in] A TOOLINFO structure that contains information about a tool in a tooltip control.
The result of OnMenuButtonToolHitTest if the button can retrieve a pointer to the parent frame window; otherwise FALSE.
This method calls one of the following methods if it can convert the parent window to a valid frame object:
Called by the framework when the parent toolbar updates its tooltip text.
virtual BOOL OnUpdateToolTip(
CWnd* pWndParent,
int iButtonIndex,
CToolTipCtrl& wndToolTip,
CString& str);
pWndParent
[in] The parent window.
iButtonIndex
[in] The zero-based index of the button in the parent button collection.
wndToolTip
[in] The control that displays the tooltip text.
str
[out] A CString object that receives the updated tooltip text.
This method returns FALSE.
The default implementation of this method does nothing and returns FALSE. Override this method to return a nonzero value if you provide a tooltip text string.
Called by the framework when the button is about to perform a drag-and-drop operation.
virtual BOOL PrepareDrag(COleDataSource& srcItem);
srcItem
[in] A COleDataSource object that stores state information about the drag-and-drop operation.
TRUE if the operation succeeds; otherwise FALSE.
The framework calls this method to prepare the toolbar button to store its state in the provided COleDataSource object. This method stores its state by serializing itself to a shared file and then passing that file to the COleDataSource::CacheGlobalData method. For more information about toolbar button serialization, see CMFCToolBarButton::Serialize.
This method does nothing and returns TRUE if the button cannot be stored (the CMFCToolBarButton::CanBeStored method returns FALSE). It returns FALSE if an exception occurs during object serialization.
For more information about OLE drag-and-drop operations, see OLE drag and drop.
Retrieves the bounding rectangle of the button.
const CRect& Rect() const;
A CRect object that contains the bounding rectangle of a button.
Sets to the default value the image that is associated with the button.
virtual void ResetImageToDefault();
This method retrieves the default image from its parent toolbar by using the CMFCToolBar::GetDefaultImage method. If the button has no associated default image, this method sets the text label of the button according to its string resource by using the CStringT::LoadString method. For more information about string resources, see Working with Resource Files.
This method does nothing if the button has a user-defined image.
Saves the state of the toolbar button.
virtual void SaveBarState();
The framework calls this method when it creates a CMFCToolBarButton object as the result of a drag-and-drop operation.
The default implementation of this method does nothing. Override this method to save the state of the toolbar button to an external data source.
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 supports data transfer processes such as clipboard or drag-and-drop operations. It reads or writes properties of the button such as the ID, text label, and image ID from or to the provided CArchive object.
For serialization examples, see Serialization: Serializing an Object.
Populates the provided CAccessibilityData object with accessibility data from the toolbar button.
virtual BOOL SetACCData(
CWnd* pParent,
CAccessibilityData& data);
pParent
[in] The parent window of the toolbar button.
data
[in] A CAccessibilityData object that is populated with the accessibility data of the toolbar button.
This method returns TRUE.
Override this method to return FALSE if your toolbar button does not provide accessibility data.
Renames the global clipboard format.
static void __stdcall SetClipboardFormatName(LPCTSTR lpszName);
lpszName
[in] The new name of the global clipboard format. Cannot be NULL.
This method makes it possible for drag-and-drop operations to occur among multiple applications. Each application must supply the same clipboard format name.
You must call this method before the framework calls CMFCToolBarButton::GetClipboardFormat.
Sets the image index of the button.
virtual void SetImage(int iImage);
iImage
[in] The index of the image in the collection of toolbar images.
If the toolbar button is a separator, iImage refers to the new width of the separator button.
If iImage is less than zero, this method disables drawing of the image and enables drawing of the text label of the button.
Sets the list of commands that the user cannot customize.
static void SetProtectedCommands(const CList<UINT,UINT>& lstCmds);
lstCmds
[in] The list of protected commands.
In customization mode, the framework disables toolbar button commands that are protected. The user cannot perform drag-and-drop and edit operations on disabled toolbar buttons.
Use the CMFCToolBarButton::GetProtectedCommands method to retrieve the list of protected commands.
Called by the framework when a button changes its checked state.
virtual void SetRadio();
The default implementation of this method does nothing. Override this method to perform a custom action when the button changes its checked state.
Sets the bounding rectangle of the button.
void SetRect(const CRect rect);rect
[in] The new bounding rectangle of the button.
This method calls the CMFCToolBarButton::OnMove method after it sets the new bounding rectangle.
Sets the style of the button.
virtual void SetStyle(UINT nStyle);
nStyle
[in] The new style of the button.
The default implementation sets the CMFCToolBarButton::m_nStyle data member to nStyle. Override this method if you want to perform additional processing to handle the change in style. See ToolBar Control Styles for a list of valid style flags.
Specifies whether the button is visible.
void SetVisible(BOOL bShow=TRUE);bShow
[in] A Boolean value that specifies whether to show or hide the button. If this parameter is TRUE, the button is shown. If the parameter is FALSE, the button is hidden.
Use this function to hide or show a particular toolbar button. Call the CPane::AdjustSizeImmediate method after you call this method.
Shows or hides the button.
void Show(BOOL bShow);bShow
[in] A Boolean value that specifies whether to show or hide the button. If this parameter is TRUE, the button is shown. If the parameter is FALSE, the button is hidden.
The framework calls this method to update the visibility of toolbar buttons when their parent toolbar is resized. The framework calls this method with bShow set to FALSE when the button no longer fits within the bounds of the toolbar. The framework calls this method with bShow set to TRUE when after resizing the button again fits within the bounds of the toolbar.
Use the CMFCToolBarButton::SetVisible method to set the general visibility of the button.
This method calls the CMFCToolBarButton::OnShow method after it updates the visibility state of the button.
Hierarchy Chart
Classes
CMFCToolBar Class
CMFCToolBarImages Class