CMFCToolBarButton Class
Provides button functionality to toolbars.
Syntax
class CMFCToolBarButton : public CObject
Members
Public Constructors
| Name | Description |
|---|---|
| CMFCToolBarButton::CMFCToolBarButton | Constructs and initializes a CMFCToolBarButton object. |
CMFCToolBarButton::~CMFCToolBarButton |
Destructor. |
Public Methods
| 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. |
Data Members
| 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. |
Remarks
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.
Example
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.
CMFCToolBarButton *pOffice2007 = NULL;
int nIndex = -1;
for (UINT uiCmd = ID_VIEW_APPLOOK_2007_1; uiCmd <= ID_VIEW_APPLOOK_2007_4; uiCmd++)
{
// CMFCToolBar m_wndToolBarTheme
nIndex = m_wndToolBarTheme.CommandToIndex(uiCmd);
CMFCToolBarButton *pButton = m_wndToolBarTheme.GetButton(nIndex);
if (pButton != NULL)
{
pOffice2007 = pButton;
break;
}
}
pOffice2007->EnableWindow();
pOffice2007->SetImage(1);
pOffice2007->SetRect(CRect(1, 1, 1, 1));
pOffice2007->SetVisible();
pOffice2007->Show(true);
Inheritance Hierarchy
Requirements
Header: afxtoolbarbutton.h
CMFCToolBarButton::CanBeDropped
Specifies whether a user can position a button on a toolbar or menu during customization.
virtual BOOL CanBeDropped(CMFCToolBar* pToolbar);
Parameters
pToolbar
[in] Unused.
Return Value
This method returns TRUE.
Remarks
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.
CMFCToolBarButton::CanBeStored
Determines whether the button can be stored.
virtual BOOL CanBeStored() const;
Return Value
This method returns TRUE.
Remarks
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.
CMFCToolBarButton::CanBeStretched
Specifies whether a user can stretch the button during customization.
virtual BOOL CanBeStretched() const;
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::CMFCToolBarButton
Constructs and initializes a CMFCToolBarButton object.
CMFCToolBarButton(
UINT uiID,
int iImage,
LPCTSTR lpszText=NULL,
BOOL bUserButton=FALSE,
BOOL bLocked=FALSE);
Parameters
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.
CMFCToolBarButton::CompareWith
Compares this instance with the provided CMFCToolBarButton object.
virtual BOOL CompareWith(const CMFCToolBarButton& other) const;
Parameters
other
[in] Reference to the object to compare with this instance.
Return Value
Nonzero if the provided object equals the value of this instance; otherwise, 0.
Remarks
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.
CMFCToolBarButton::CopyFrom
Copies the properties of another toolbar button to the current button.
virtual void CopyFrom(const CMFCToolBarButton& src);
Parameters
src
[in] A reference to the source button from which to copy.
Remarks
Call this method to copy another toolbar button to this toolbar button.
CMFCToolBarButton::CreateFromOleData
Creates a CMFCToolBarButton object from the provided COleDataObject object.
static CMFCToolBarButton* __stdcall CreateFromOleData(COleDataObject* pDataObject);
Parameters
pDataObject
[in] The source OLE data object.
Return Value
The created CMFCToolBarButton object.
Remarks
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.
CMFCToolBarButton::EnableWindow
Enables or disables mouse and keyboard input.
virtual void EnableWindow(BOOL bEnable = TRUE);
Parameters
bEnable
[in] Set this parameter to TRUE to enable input, or to FALSE to disable input.
Remarks
This method calls the EnableWindow function to enable or disable input. For more information, see EnableWindow in the Windows SDK.
CMFCToolBarButton::ExportToMenuButton
Copies text from the toolbar button to a menu.
virtual BOOL ExportToMenuButton(CMFCToolBarMenuButton& menuButton) const;
Parameters
menuButton
[in] A reference to the target menu button.
Return Value
This method returns TRUE.
Remarks
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.
CMFCToolBarButton::GetClipboardFormat
Retrieves the global clipboard format for the application.
static CLIPFORMAT __stdcall GetClipboardFormat();
Return Value
The global CLIPFORMAT value for the application.
Remarks
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.
CMFCToolBarButton::GetHwnd
Retrieves the window handle that is associated with the toolbar button.
virtual HWND GetHwnd();
Return Value
The window handle that is associated with the toolbar button or NULL if the toolbar button has no associated window handle.
Remarks
The default implementation of this method returns NULL. Override this method to return the window handle of your specific control.
CMFCToolBarButton::GetImage
Retrieves the image index of the button.
int GetImage() const;
Return Value
The index of the image associated with this button.
Remarks
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.
CMFCToolBarButton::GetInvalidateRect
Retrieves the region of the client area of the button that must be redrawn.
virtual const CRect GetInvalidateRect() const;
Return Value
A CRect object that specifies the region that must be redrawn.
Remarks
The default implementation of this method returns the whole client area. Override this method if you want a different area to be redrawn.
CMFCToolBarButton::GetParentWnd
Retrieves the parent window of the button.
CWnd* GetParentWnd() const;
Return Value
The parent window of the button.
CMFCToolBarButton::GetProtectedCommands
Retrieves the list of commands that the user cannot customize.
static const CList<UINT,UINT>& GetProtectedCommands();
Return Value
The list of protected commands.
Remarks
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.
CMFCToolBarButton::GetTextSize
Retrieves the size of the button text.
SIZE GetTextSize() const;
Return Value
A SIZE object that contains the size, in pixels, of the button text.
CMFCToolBarButton::HasFocus
Determines whether the button has the current input focus.
virtual BOOL HasFocus() const;
Return Value
Nonzero if the button has the input focus; otherwise 0.
Remarks
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.
CMFCToolBarButton::HaveHotBorder
Determines whether a border of the button is displayed when a user selects the button.
virtual BOOL HaveHotBorder() const;
Return Value
This method returns TRUE.
Remarks
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.
CMFCToolBarButton::IsDrawImage
Determines whether an image is displayed on the button.
BOOL IsDrawImage() const;
Return Value
Nonzero if an image is displayed on the button; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsDrawText
Determines whether a text label is displayed on the button.
BOOL IsDrawText() const;
Return Value
Nonzero if a text label is displayed; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsDroppedDown
Determines whether the button displays a submenu.
virtual BOOL IsDroppedDown() const;
Return Value
This method returns FALSE.
Remarks
The default implementation of this method returns FALSE. Override this method to return TRUE if your control displays a submenu.
CMFCToolBarButton::IsEditable
Determines whether the button can be customized.
virtual BOOL IsEditable() const;
Return Value
Nonzero if a button can be customized by the user; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsExtraSize
Determines whether the button can be displayed with an extended border.
virtual BOOL IsExtraSize() const;
Return Value
Nonzero if the toolbar button can be displayed with an extended border; otherwise 0.
Remarks
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).
CMFCToolBarButton::IsFirstInGroup
Determines whether the button is in the first position in its button group.
virtual BOOL IsFirstInGroup() const;
Return Value
TRUE if the button is the first button in its button group; otherwise FALSE.
Remarks
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.
CMFCToolBarButton::IsHidden
Determines whether the button is hidden.
BOOL IsHidden() const;
Return Value
Nonzero if the button is hidden (invisible); otherwise 0.
Remarks
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.
CMFCToolBarButton::IsHorizontal
Determines whether the button is located on a horizontal toolbar.
BOOL IsHorizontal() const;
Return Value
Nonzero if a toolbar button is located on a horizontal toolbar; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsLastInGroup
Specifies whether the button is in the last position in its button group.
virtual BOOL IsLastInGroup() const;
Return Value
TRUE if the button is the last button in its button group; otherwise FALSE.
Remarks
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.
CMFCToolBarButton::IsLocked
Determines whether the button is on a locked (non-customizable) toolbar.
BOOL IsLocked() const;
Return Value
Nonzero if the button is on a locked toolbar; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsOwnerOf
Determines whether the button is the owner of the provided window handle.
virtual BOOL IsOwnerOf(HWND hwnd);
Parameters
hwnd
[in] A window handle.
Return Value
Nonzero if the button is the owner of the provided window handle; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsVisible
Determines whether the toolbar button is visible.
BOOL IsVisible() const;
Return Value
Nonzero if the toolbar button is visible; otherwise 0.
Remarks
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.
CMFCToolBarButton::IsWindowVisible
Determines whether the underlying window handle of the button is visible.
virtual BOOL IsWindowVisible();
Return Value
Nonzero if the underlying window handle of the button is visible; otherwise 0.
Remarks
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.
CMFCToolBarButton::m_bImage
Specifies whether an image is displayed on the button.
BOOL m_bImage;
Remarks
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.
CMFCToolBarButton::m_bText
Specifies whether a text label is displayed on the button.
BOOL m_bText;
Remarks
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.
CMFCToolBarButton::m_bTextBelow
Specifies whether the text label is displayed underneath the image on the button.
BOOL m_bTextBelow;
Remarks
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.
CMFCToolBarButton::m_bUserButton
Specifies whether the button has a user-defined image
BOOL m_bUserButton;
Remarks
This data member is set to TRUE when the button has a user-defined image associated with it.
CMFCToolBarButton::m_bWholeText
Specifies whether the button displays its full text label even if it does not fit in the bounding rectangle.
BOOL m_bWholeText;
Remarks
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.
CMFCToolBarButton::m_bWrap
Specifies whether the button next to a separator will be put on the next row.
BOOL m_bWrap;
Remarks
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.
CMFCToolBarButton::m_bWrapText
Specifies whether multi-line text labels are enabled.
AFX_IMPORT_DATA static BOOL m_bWrapText;
Remarks
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.
CMFCToolBarButton::m_nID
The command ID of the button.
UINT m_nID;
Remarks
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.
CMFCToolBarButton::m_nStyle
The style of the button.
UINT m_nStyle;
Remarks
See ToolBar Control Styles for the list of available toolbar button styles.
CMFCToolBarButton::m_strText
The text label of the button.
CString m_strText;
Remarks
This data member contains the text label of the button. The text label can be empty.
CMFCToolBarButton::NotifyCommand
Specifies whether the button processes the WM_COMMAND message.
virtual BOOL NotifyCommand(int iNotifyCode);
Parameters
iNotifyCode
[in] The notification message that is associated with the command.
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::OnAddToCustomizePage
Called by the framework when the button is added to a Customize dialog box.
virtual void OnAddToCustomizePage();
Remarks
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.
CMFCToolBarButton::OnBeforeDrag
Specifies whether the button can be dragged.
virtual BOOL OnBeforeDrag() const;
Return Value
TRUE if the button can be dragged; otherwise FALSE.
Remarks
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.
CMFCToolBarButton::OnBeforeDrop
Specifies whether a user can drop the button onto the target toolbar.
virtual BOOL OnBeforeDrop(CMFCToolBar* pTarget);
Parameters
pTarget
[in] The target of the drag-and-drop operation.
Return Value
TRUE if the button can be dropped onto the provided target toolbar; otherwise FALSE.
Remarks
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.
CMFCToolBarButton::OnCalculateSize
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);
Parameters
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.
Return Value
A SIZE structure that contains the dimensions of the button, in pixels.
Remarks
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).
CMFCToolBarButton::OnCancelMode
Called by the framework to handle the WM_CANCELMODE message.
virtual void OnCancelMode();
Remarks
The default implementation of this method does nothing. Override this method if you want to handle the WM_CANCELMODE message.
CMFCToolBarButton::OnChangeParentWnd
Called by the framework when the button is inserted into a new toolbar.
virtual void OnChangeParentWnd(CWnd* pWndParent);
Parameters
pWndParent
[in] The new parent window.
Remarks
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.
CMFCToolBarButton::OnClick
Called by the framework when the user clicks the mouse button.
virtual BOOL OnClick(
CWnd* pWnd,
BOOL bDelay=TRUE);
Parameters
pWnd
[in] The parent window of the toolbar button.
bDelay
[in] TRUE if the message should be handled with a delay.
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::OnClickUp
Called by the framework when the user releases the mouse button.
virtual BOOL OnClickUp();
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::OnContextHelp
Called by the framework when the parent toolbar handles a WM_HELPHITTEST message.
virtual BOOL OnContextHelp(CWnd* pWnd);
Parameters
pWnd
[in] The parent window of the toolbar button.
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::OnCtlColor
Called by the framework when the parent toolbar handles a WM_CTLCOLOR message.
virtual HBRUSH OnCtlColor(
CDC* pDC,
UINT nCtlColor);
Parameters
pDC
[in] The device context that displays the button.
nCtlColor
[in] The specific color notification.
Return Value
A handle to the brush object that the framework uses to paint the background of the button.
Remarks
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.
CMFCToolBarButton::OnCustomizeMenu
Allows the button to modify the provided menu when the application displays a shortcut menu on the parent toolbar.
virtual BOOL OnCustomizeMenu(CMenu* pMenu);
Parameters
pMenu
[in] The menu to customize.
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::OnDblClk
Called by the framework when the parent toolbar handles a WM_LBUTTONDBLCLK message.
virtual void OnDblClk(CWnd* pWnd);
Parameters
pWnd
[in] - The parent window of the button.
Remarks
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.
CMFCToolBarButton::OnDraw
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);
Parameters
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.
Remarks
Override this method to customize toolbar button drawing.
CMFCToolBarButton::OnDrawOnCustomizeList
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);
Parameters
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.
Return Value
The width, in pixels, of the button on the specified device context.
Remarks
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.
CMFCToolBarButton::OnGetCustomToolTipText
Called by the framework to retrieve the custom tooltip text for the button.
virtual BOOL OnGetCustomToolTipText(CString& strToolTip);
Parameters
strToolTip
[out] A CString object that receives the custom tooltip text.
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::OnGlobalFontsChanged
Called by the framework when the global font has changed.
virtual void OnGlobalFontsChanged();
Remarks
The default implementation of this method does nothing. Override this method to update the font that is used to display the button text.
CMFCToolBarButton::OnMove
Called by the framework when the parent toolbar moves.
virtual void OnMove();
Remarks
The default implementation of this method does nothing. Override this method to reposition the button when the parent toolbar moves.
CMFCToolBarButton::OnShow
Called by the framework when the button becomes visible or invisible.
virtual void OnShow(BOOL bShow);
Parameters
bShow
[in] Specifies whether the button is visible. If this parameter is TRUE, the button is visible. Otherwise, the button is not visible.
Remarks
The default implementation of this method does nothing. Override this method to update the visibility of the button.
CMFCToolBarButton::OnSize
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);
Parameters
iSize
[in] The new width of the button.
Remarks
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.
CMFCToolBarButton::OnToolHitTest
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);
Parameters
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.
Return Value
The result of OnMenuButtonToolHitTest if the button can retrieve a pointer to the parent frame window; otherwise FALSE.
Remarks
This method calls one of the following methods if it can convert the parent window to a valid frame object:
CMFCToolBarButton::OnUpdateToolTip
Called by the framework when the parent toolbar updates its tooltip text.
virtual BOOL OnUpdateToolTip(
CWnd* pWndParent,
int iButtonIndex,
CToolTipCtrl& wndToolTip,
CString& str);
Parameters
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.
Return Value
This method returns FALSE.
Remarks
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.
CMFCToolBarButton::PrepareDrag
Called by the framework when the button is about to perform a drag-and-drop operation.
virtual BOOL PrepareDrag(COleDataSource& srcItem);
Parameters
srcItem
[in] A COleDataSource object that stores state information about the drag-and-drop operation.
Return Value
TRUE if the operation succeeds; otherwise FALSE.
Remarks
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.
CMFCToolBarButton::Rect
Retrieves the bounding rectangle of the button.
const CRect& Rect() const;
Return Value
A CRect object that contains the bounding rectangle of a button.
CMFCToolBarButton::ResetImageToDefault
Sets to the default value the image that is associated with the button.
virtual void ResetImageToDefault();
Remarks
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.
CMFCToolBarButton::SaveBarState
Saves the state of the toolbar button.
virtual void SaveBarState();
Remarks
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.
CMFCToolBarButton::Serialize
Reads this object from an archive or writes it to an archive.
virtual void Serialize(CArchive& ar);
Parameters
ar
[in] The CArchive object from which or to which to serialize.
Remarks
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.
CMFCToolBarButton::SetACCData
Populates the provided CAccessibilityData object with accessibility data from the toolbar button.
virtual BOOL SetACCData(
CWnd* pParent,
CAccessibilityData& data);
Parameters
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.
Return Value
This method returns TRUE.
Remarks
Override this method to return FALSE if your toolbar button does not provide accessibility data.
CMFCToolBarButton::SetClipboardFormatName
Renames the global clipboard format.
static void __stdcall SetClipboardFormatName(LPCTSTR lpszName);
Parameters
lpszName
[in] The new name of the global clipboard format. Cannot be NULL.
Remarks
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.
CMFCToolBarButton::SetImage
Sets the image index of the button.
virtual void SetImage(int iImage);
Parameters
iImage
[in] The index of the image in the collection of toolbar images.
Remarks
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.
CMFCToolBarButton::SetProtectedCommands
Sets the list of commands that the user cannot customize.
static void SetProtectedCommands(const CList<UINT,UINT>& lstCmds);
Parameters
lstCmds
[in] The list of protected commands.
Remarks
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.
CMFCToolBarButton::SetRadio
Called by the framework when a button changes its checked state.
virtual void SetRadio();
Remarks
The default implementation of this method does nothing. Override this method to perform a custom action when the button changes its checked state.
CMFCToolBarButton::SetRect
Sets the bounding rectangle of the button.
void SetRect(const CRect rect);
Parameters
rect
[in] The new bounding rectangle of the button.
Remarks
This method calls the CMFCToolBarButton::OnMove method after it sets the new bounding rectangle.
CMFCToolBarButton::SetStyle
Sets the style of the button.
virtual void SetStyle(UINT nStyle);
Parameters
nStyle
[in] The new style of the button.
Remarks
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.
CMFCToolBarButton::SetVisible
Specifies whether the button is visible.
void SetVisible(BOOL bShow=TRUE);
Parameters
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.
Remarks
Use this function to hide or show a particular toolbar button. Call the CPane::AdjustSizeImmediate method after you call this method.
CMFCToolBarButton::Show
Shows or hides the button.
void Show(BOOL bShow);
Parameters
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.
Remarks
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.
See also
Hierarchy Chart
Classes
CMFCToolBar Class
CMFCToolBarImages Class
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for