Edit

Share via

CMFCToolBarButton Class

  • Article

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

CObject

CMFCToolBarButton

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