description

title

ms.date

f1_keywords

helpviewer_keywords

Learn more about: CToolBarCtrl Class

CToolBarCtrl Class

11/04/2016

CToolBarCtrl

AFXCMN/CToolBarCtrl

AFXCMN/CToolBarCtrl::CToolBarCtrl

AFXCMN/CToolBarCtrl::AddBitmap

AFXCMN/CToolBarCtrl::AddButtons

AFXCMN/CToolBarCtrl::AddString

AFXCMN/CToolBarCtrl::AddStrings

AFXCMN/CToolBarCtrl::AutoSize

AFXCMN/CToolBarCtrl::ChangeBitmap

AFXCMN/CToolBarCtrl::CheckButton

AFXCMN/CToolBarCtrl::CommandToIndex

AFXCMN/CToolBarCtrl::Create

AFXCMN/CToolBarCtrl::CreateEx

AFXCMN/CToolBarCtrl::Customize

AFXCMN/CToolBarCtrl::DeleteButton

AFXCMN/CToolBarCtrl::EnableButton

AFXCMN/CToolBarCtrl::GetAnchorHighlight

AFXCMN/CToolBarCtrl::GetBitmap

AFXCMN/CToolBarCtrl::GetBitmapFlags

AFXCMN/CToolBarCtrl::GetButton

AFXCMN/CToolBarCtrl::GetButtonCount

AFXCMN/CToolBarCtrl::GetButtonInfo

AFXCMN/CToolBarCtrl::GetButtonSize

AFXCMN/CToolBarCtrl::GetColorScheme

AFXCMN/CToolBarCtrl::GetDisabledImageList

AFXCMN/CToolBarCtrl::GetDropTarget

AFXCMN/CToolBarCtrl::GetExtendedStyle

AFXCMN/CToolBarCtrl::GetHotImageList

AFXCMN/CToolBarCtrl::GetHotItem

AFXCMN/CToolBarCtrl::GetImageList

AFXCMN/CToolBarCtrl::GetInsertMark

AFXCMN/CToolBarCtrl::GetInsertMarkColor

AFXCMN/CToolBarCtrl::GetItemRect

AFXCMN/CToolBarCtrl::GetMaxSize

AFXCMN/CToolBarCtrl::GetMaxTextRows

AFXCMN/CToolBarCtrl::GetMetrics

AFXCMN/CToolBarCtrl::GetPadding

AFXCMN/CToolBarCtrl::GetPressedImageList

AFXCMN/CToolBarCtrl::GetRect

AFXCMN/CToolBarCtrl::GetRows

AFXCMN/CToolBarCtrl::GetState

AFXCMN/CToolBarCtrl::GetString

AFXCMN/CToolBarCtrl::GetStyle

AFXCMN/CToolBarCtrl::GetToolTips

AFXCMN/CToolBarCtrl::HideButton

AFXCMN/CToolBarCtrl::HitTest

AFXCMN/CToolBarCtrl::Indeterminate

AFXCMN/CToolBarCtrl::InsertButton

AFXCMN/CToolBarCtrl::InsertMarkHitTest

AFXCMN/CToolBarCtrl::IsButtonChecked

AFXCMN/CToolBarCtrl::IsButtonEnabled

AFXCMN/CToolBarCtrl::IsButtonHidden

AFXCMN/CToolBarCtrl::IsButtonHighlighted

AFXCMN/CToolBarCtrl::IsButtonIndeterminate

AFXCMN/CToolBarCtrl::IsButtonPressed

AFXCMN/CToolBarCtrl::LoadImages

AFXCMN/CToolBarCtrl::MapAccelerator

AFXCMN/CToolBarCtrl::MarkButton

AFXCMN/CToolBarCtrl::MoveButton

AFXCMN/CToolBarCtrl::PressButton

AFXCMN/CToolBarCtrl::ReplaceBitmap

AFXCMN/CToolBarCtrl::RestoreState

AFXCMN/CToolBarCtrl::SaveState

AFXCMN/CToolBarCtrl::SetAnchorHighlight

AFXCMN/CToolBarCtrl::SetBitmapSize

AFXCMN/CToolBarCtrl::SetButtonInfo

AFXCMN/CToolBarCtrl::SetButtonSize

AFXCMN/CToolBarCtrl::SetButtonStructSize

AFXCMN/CToolBarCtrl::SetButtonWidth

AFXCMN/CToolBarCtrl::SetCmdID

AFXCMN/CToolBarCtrl::SetColorScheme

AFXCMN/CToolBarCtrl::SetDisabledImageList

AFXCMN/CToolBarCtrl::SetDrawTextFlags

AFXCMN/CToolBarCtrl::SetExtendedStyle

AFXCMN/CToolBarCtrl::SetHotImageList

AFXCMN/CToolBarCtrl::SetHotItem

AFXCMN/CToolBarCtrl::SetImageList

AFXCMN/CToolBarCtrl::SetIndent

AFXCMN/CToolBarCtrl::SetInsertMark

AFXCMN/CToolBarCtrl::SetInsertMarkColor

AFXCMN/CToolBarCtrl::SetMaxTextRows

AFXCMN/CToolBarCtrl::SetMetrics

AFXCMN/CToolBarCtrl::SetOwner

AFXCMN/CToolBarCtrl::SetPadding

AFXCMN/CToolBarCtrl::SetPressedImageList

AFXCMN/CToolBarCtrl::SetRows

AFXCMN/CToolBarCtrl::SetState

AFXCMN/CToolBarCtrl::SetStyle

AFXCMN/CToolBarCtrl::SetToolTips

AFXCMN/CToolBarCtrl::SetWindowTheme

CToolBarCtrl [MFC], CToolBarCtrl

CToolBarCtrl [MFC], AddBitmap

CToolBarCtrl [MFC], AddButtons

CToolBarCtrl [MFC], AddString

CToolBarCtrl [MFC], AddStrings

CToolBarCtrl [MFC], AutoSize

CToolBarCtrl [MFC], ChangeBitmap

CToolBarCtrl [MFC], CheckButton

CToolBarCtrl [MFC], CommandToIndex

CToolBarCtrl [MFC], Create

CToolBarCtrl [MFC], CreateEx

CToolBarCtrl [MFC], Customize

CToolBarCtrl [MFC], DeleteButton

CToolBarCtrl [MFC], EnableButton

CToolBarCtrl [MFC], GetAnchorHighlight

CToolBarCtrl [MFC], GetBitmap

CToolBarCtrl [MFC], GetBitmapFlags

CToolBarCtrl [MFC], GetButton

CToolBarCtrl [MFC], GetButtonCount

CToolBarCtrl [MFC], GetButtonInfo

CToolBarCtrl [MFC], GetButtonSize

CToolBarCtrl [MFC], GetColorScheme

CToolBarCtrl [MFC], GetDisabledImageList

CToolBarCtrl [MFC], GetDropTarget

CToolBarCtrl [MFC], GetExtendedStyle

CToolBarCtrl [MFC], GetHotImageList

CToolBarCtrl [MFC], GetHotItem

CToolBarCtrl [MFC], GetImageList

CToolBarCtrl [MFC], GetInsertMark

CToolBarCtrl [MFC], GetInsertMarkColor

CToolBarCtrl [MFC], GetItemRect

CToolBarCtrl [MFC], GetMaxSize

CToolBarCtrl [MFC], GetMaxTextRows

CToolBarCtrl [MFC], GetMetrics

CToolBarCtrl [MFC], GetPadding

CToolBarCtrl [MFC], GetPressedImageList

CToolBarCtrl [MFC], GetRect

CToolBarCtrl [MFC], GetRows

CToolBarCtrl [MFC], GetState

CToolBarCtrl [MFC], GetString

CToolBarCtrl [MFC], GetStyle

CToolBarCtrl [MFC], GetToolTips

CToolBarCtrl [MFC], HideButton

CToolBarCtrl [MFC], HitTest

CToolBarCtrl [MFC], Indeterminate

CToolBarCtrl [MFC], InsertButton

CToolBarCtrl [MFC], InsertMarkHitTest

CToolBarCtrl [MFC], IsButtonChecked

CToolBarCtrl [MFC], IsButtonEnabled

CToolBarCtrl [MFC], IsButtonHidden

CToolBarCtrl [MFC], IsButtonHighlighted

CToolBarCtrl [MFC], IsButtonIndeterminate

CToolBarCtrl [MFC], IsButtonPressed

CToolBarCtrl [MFC], LoadImages

CToolBarCtrl [MFC], MapAccelerator

CToolBarCtrl [MFC], MarkButton

CToolBarCtrl [MFC], MoveButton

CToolBarCtrl [MFC], PressButton

CToolBarCtrl [MFC], ReplaceBitmap

CToolBarCtrl [MFC], RestoreState

CToolBarCtrl [MFC], SaveState

CToolBarCtrl [MFC], SetAnchorHighlight

CToolBarCtrl [MFC], SetBitmapSize

CToolBarCtrl [MFC], SetButtonInfo

CToolBarCtrl [MFC], SetButtonSize

CToolBarCtrl [MFC], SetButtonStructSize

CToolBarCtrl [MFC], SetButtonWidth

CToolBarCtrl [MFC], SetCmdID

CToolBarCtrl [MFC], SetColorScheme

CToolBarCtrl [MFC], SetDisabledImageList

CToolBarCtrl [MFC], SetDrawTextFlags

CToolBarCtrl [MFC], SetExtendedStyle

CToolBarCtrl [MFC], SetHotImageList

CToolBarCtrl [MFC], SetHotItem

CToolBarCtrl [MFC], SetImageList

CToolBarCtrl [MFC], SetIndent

CToolBarCtrl [MFC], SetInsertMark

CToolBarCtrl [MFC], SetInsertMarkColor

CToolBarCtrl [MFC], SetMaxTextRows

CToolBarCtrl [MFC], SetMetrics

CToolBarCtrl [MFC], SetOwner

CToolBarCtrl [MFC], SetPadding

CToolBarCtrl [MFC], SetPressedImageList

CToolBarCtrl [MFC], SetRows

CToolBarCtrl [MFC], SetState

CToolBarCtrl [MFC], SetStyle

CToolBarCtrl [MFC], SetToolTips

CToolBarCtrl [MFC], SetWindowTheme

`CToolBarCtrl` Class

Provides the functionality of the Windows toolbar common control.

Syntax

class CToolBarCtrl : public CWnd

Members

Public Constructors

Name	Description
`CToolBarCtrl::CToolBarCtrl`	Constructs a `CToolBarCtrl` object.

Public Methods

Name	Description
`CToolBarCtrl::AddBitmap`	Adds one or more bitmap button images to the list of button images available for a toolbar control.
`CToolBarCtrl::AddButtons`	Adds one or more buttons to a toolbar control.
`CToolBarCtrl::AddString`	Adds a new string, passed as a resource ID, to the toolbar's internal list of strings.
`CToolBarCtrl::AddStrings`	Adds a new string or strings, passed as a pointer to a buffer of `NULL`-separated strings, to the toolbar's internal list of strings.
`CToolBarCtrl::AutoSize`	Resizes a toolbar control.
`CToolBarCtrl::ChangeBitmap`	Changes the bitmap for a button in the current toolbar control.
`CToolBarCtrl::CheckButton`	Checks or clears a given button in a toolbar control.
`CToolBarCtrl::CommandToIndex`	Retrieves the zero-based index for the button associated with the specified command identifier.
`CToolBarCtrl::Create`	Creates a toolbar control and attaches it to a `CToolBarCtrl` object.
`CToolBarCtrl::CreateEx`	Creates a toolbar control with the specified Windows extended styles and attaches it to a `CToolBarCtrl` object.
`CToolBarCtrl::Customize`	Displays the Customize Toolbar dialog box.
`CToolBarCtrl::DeleteButton`	Deletes a button from the toolbar control.
`CToolBarCtrl::EnableButton`	Enables or disables the specified button in a toolbar control.
`CToolBarCtrl::GetAnchorHighlight`	Retrieves the anchor highlight setting for a toolbar.
`CToolBarCtrl::GetBitmap`	Retrieves the index of the bitmap associated with a button in a toolbar.
`CToolBarCtrl::GetBitmapFlags`	Gets flags associated with the toolbar's bitmap.
`CToolBarCtrl::GetButton`	Retrieves information about the specified button in a toolbar control.
`CToolBarCtrl::GetButtonCount`	Retrieves a count of the buttons currently in the toolbar control.
`CToolBarCtrl::GetButtonInfo`	Retrieves the information for a button in a toolbar.
`CToolBarCtrl::GetButtonSize`	Retrieves the current width and height of toolbar buttons, in pixels.
`CToolBarCtrl::GetColorScheme`	Retrieves the color scheme of the current toolbar control.
`CToolBarCtrl::GetDisabledImageList`	Retrieves the image list that a toolbar control uses to display disabled buttons.
`CToolBarCtrl::GetDropTarget`	Retrieves the `IDropTarget` interface for a toolbar control.
`CToolBarCtrl::GetExtendedStyle`	Retrieves the extended styles for a toolbar control.
`CToolBarCtrl::GetHotImageList`	Retrieves the image list that a toolbar control uses to display "hot" buttons. A hot button appears highlighted when the mouse pointer is above it.
`CToolBarCtrl::GetHotItem`	Retrieves the index of the hot item in a toolbar.
`CToolBarCtrl::GetImageList`	Retrieves the image list that a toolbar control uses to display buttons in their default state.
`CToolBarCtrl::GetInsertMark`	Retrieves the current insertion mark for the toolbar.
`CToolBarCtrl::GetInsertMarkColor`	Retrieves the color used to draw the insertion mark for the toolbar.
`CToolBarCtrl::GetItemRect`	Retrieves the bounding rectangle of a button in a toolbar control.
`CToolBarCtrl::GetMaxSize`	Retrieves the total size of all of the visible buttons and separators in the toolbar.
`CToolBarCtrl::GetMaxTextRows`	Retrieves the maximum number of text rows displayed on a toolbar button.
`CToolBarCtrl::GetMetrics`	Retrieves the metrics of a toolbar control.
`CToolBarCtrl::GetPadding`	Retrieves the horizontal and vertical padding of the current toolbar control.
`CToolBarCtrl::GetPressedImageList`	Retrieves the image list that the current toolbar control uses to represent buttons in the pressed state.
`CToolBarCtrl::GetRect`	Retrieves the bounding rectangle for a specified toolbar button.
`CToolBarCtrl::GetRows`	Retrieves the number of rows of buttons currently displayed in the toolbar.
`CToolBarCtrl::GetState`	Retrieves information about the state of the specified button in a toolbar control, such as whether it's enabled, pressed, or checked.
`CToolBarCtrl::GetString`	Retrieves a toolbar string.
`CToolBarCtrl::GetStyle`	Retrieves the styles currently in use for a toolbar control.
`CToolBarCtrl::GetToolTips`	Retrieves the handle of the tool tip control, if any, associated with the toolbar control.
`CToolBarCtrl::HideButton`	Hides or shows the specified button in a toolbar control.
`CToolBarCtrl::HitTest`	Determines where a point lies in a toolbar control.
`CToolBarCtrl::Indeterminate`	Sets or clears the indeterminate (gray) state of the specified button in a toolbar control.
`CToolBarCtrl::InsertButton`	Inserts a button in a toolbar control.
`CToolBarCtrl::InsertMarkHitTest`	Retrieves the insertion mark information for a point in a toolbar.
`CToolBarCtrl::IsButtonChecked`	Tells whether the specified button in a toolbar control is checked.
`CToolBarCtrl::IsButtonEnabled`	Tells whether the specified button in a toolbar control is enabled.
`CToolBarCtrl::IsButtonHidden`	Tells whether the specified button in a toolbar control is hidden.
`CToolBarCtrl::IsButtonHighlighted`	Checks the highlight state of the toolbar button.
`CToolBarCtrl::IsButtonIndeterminate`	Tells whether the state of the specified button in a toolbar control is indeterminate (gray).
`CToolBarCtrl::IsButtonPressed`	Tells whether the specified button in a toolbar control is pressed.
`CToolBarCtrl::LoadImages`	Loads bitmaps into a toolbar control's image list.
`CToolBarCtrl::MapAccelerator`	Maps an accelerator character to a toolbar button.
`CToolBarCtrl::MarkButton`	Sets the highlight state of a given button in a toolbar control.
`CToolBarCtrl::MoveButton`	Moves a button from one index to another.
`CToolBarCtrl::PressButton`	Presses or releases the specified button in a toolbar control.
`CToolBarCtrl::ReplaceBitmap`	Replaces the existing bitmap in the current toolbar control with a new bitmap.
`CToolBarCtrl::RestoreState`	Restores the state of the toolbar control.
`CToolBarCtrl::SaveState`	Saves the state of the toolbar control.
`CToolBarCtrl::SetAnchorHighlight`	Sets the anchor highlight setting for a toolbar.
`CToolBarCtrl::SetBitmapSize`	Sets the size of the bitmapped images to be added to a toolbar control.
`CToolBarCtrl::SetButtonInfo`	Sets the information for an existing button in a toolbar.
`CToolBarCtrl::SetButtonSize`	Sets the size of the buttons to be added to a toolbar control.
`CToolBarCtrl::SetButtonStructSize`	Specifies the size of the `TBBUTTON` structure.
`CToolBarCtrl::SetButtonWidth`	Sets the minimum and maximum button widths in the toolbar control.
`CToolBarCtrl::SetCmdID`	Sets the command identifier to be sent to the owner window when the specified button is pressed.
`CToolBarCtrl::SetColorScheme`	Sets the color scheme of the current toolbar control.
`CToolBarCtrl::SetDisabledImageList`	Sets the image list that the toolbar control will use to display disabled buttons.
`CToolBarCtrl::SetDrawTextFlags`	Sets the flags in the Win32 function `DrawText`, which is used to draw the text in the specified rectangle, formatted according to how the flags are set.
`CToolBarCtrl::SetExtendedStyle`	Sets the extended styles for a toolbar control.
`CToolBarCtrl::SetHotImageList`	Sets the image list that the toolbar control will use to display "hot" buttons.
`CToolBarCtrl::SetHotItem`	Sets the hot item in a toolbar.
`CToolBarCtrl::SetImageList`	Sets the image list that the toolbar will use to display buttons that are in their default state.
`CToolBarCtrl::SetIndent`	Sets the indentation for the first button in a toolbar control.
`CToolBarCtrl::SetInsertMark`	Sets the current insertion mark for the toolbar.
`CToolBarCtrl::SetInsertMarkColor`	Sets the color used to draw the insertion mark for the toolbar.
`CToolBarCtrl::SetMaxTextRows`	Sets the maximum number of text rows displayed on a toolbar button.
`CToolBarCtrl::SetMetrics`	Sets the metrics of a toolbar control.
`CToolBarCtrl::SetOwner`	Sets the window to receive notification messages from the toolbar control.
`CToolBarCtrl::SetPadding`	Sets the horizontal and vertical padding of the current toolbar control.
`CToolBarCtrl::SetPressedImageList`	Sets the image list that the current toolbar control uses to represent buttons in the pressed state.
`CToolBarCtrl::SetRows`	Sets the number of rows of buttons displayed in the toolbar.
`CToolBarCtrl::SetState`	Sets the state for the specified button in a toolbar control.
`CToolBarCtrl::SetStyle`	Sets the styles for a toolbar control.
`CToolBarCtrl::SetToolTips`	Associates a tool tip control with the toolbar control.
`CToolBarCtrl::SetWindowTheme`	Sets the visual style of a toolbar control.

Remarks

This control (and therefore the CToolBarCtrl class) is available only to programs running under Windows 95/98 and Windows NT version 3.51 and later.

A Windows toolbar common control is a rectangular child window that contains one or more buttons. These buttons can display a bitmap image, a string, or both. When the user chooses a button, it sends a command message to the toolbar's owner window. Typically, the buttons in a toolbar correspond to items in the application's menu; they provide a more direct way for the user to access an application's commands.

CToolBarCtrl objects contain several important internal data structures: a list of button image bitmaps or an image list, a list of button label strings, and a list of TBBUTTON structures that associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a CToolBarCtrl object, you must set up these data structures. The list of strings can only be used for button labels; you can't retrieve strings from the toolbar.

To use a CToolBarCtrl object, you'll typically follow these steps:

Construct the CToolBarCtrl object.
Call Create to create the Windows toolbar common control and attach it to the CToolBarCtrl object. Indicate the style of toolbar by using styles, such as TBSTYLE_TRANSPARENT for a transparent toolbar or TBSTYLE_DROPDOWN for a toolbar that supports drop-down style buttons.
Identify how you want the buttons on the toolbar displayed:
- To use bitmap images for buttons, add the button bitmaps to the toolbar by calling AddBitmap.
- To use images displayed from an image list for buttons, specify the image list by calling SetImageList, SetHotImageList, or SetDisabledImageList.
- To use string labels for buttons, add the strings to the toolbar by calling AddString and/or AddStrings.
Add button structures to the toolbar by calling AddButtons.
If you want tool tips for a toolbar button in an owner window that isn't a CFrameWnd, you need to handle the TTN_NEEDTEXT messages in the toolbar's owner window as described in Handling Tool Tip Notifications. If the parent window of the toolbar is derived from CFrameWnd, tool tips are displayed without any extra effort from you because CFrameWnd provides a default handler.
If you want your user to be able to customize the toolbar, handle customization notification messages in the owner window as described in Handling Customization Notifications.

You can use SaveState to save the current state of a toolbar control in the registry and RestoreState to restore the state based on information previously stored in the registry. In addition to saving the toolbar state between uses of the application, applications typically store the state before the user begins customizing the toolbar in case the user later wants to restore the toolbar to its original state.

Support for Internet Explorer Version 4.0 and Later

To support functionality introduced in Internet Explorer, version 4.0 and later, MFC provides image list support and transparent and flat styles for toolbar controls.

A transparent toolbar allows the client under the toolbar to show through. To create a transparent toolbar, use both TBSTYLE_FLAT and TBSTYLE_TRANSPARENT styles. Transparent toolbars feature hot tracking; that is, when the mouse pointer moves over a hot button on the toolbar, the button's appearance changes. Toolbars created with just the TBSTYLE_FLAT style will contain buttons that aren't transparent.

Image list support allows a control greater flexibility for default behavior, hot images, and disabled images. Use GetImageList, GetHotImageList, and GetDisabledImageList with the transparent toolbar to manipulate the image according to its state:

For more information on using CToolBarCtrl, see Controls and Using CToolBarCtrl.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CToolBarCtrl

Requirements

Header: afxcmn.h

`CToolBarCtrl::AddBitmap`

Adds one or more button images to the list of button images stored in the toolbar control.

int AddBitmap(
    int nNumButtons,
    UINT nBitmapID);

int AddBitmap(
    int nNumButtons,
    CBitmap* pBitmap);

Parameters

nNumButtons
Number of button images in the bitmap.

nBitmapID
Resource identifier of the bitmap that contains the button image or images to add.

pBitmap
Pointer to the CBitmap object that contains the button image or images to add.

Return Value

Zero-based index of the first new image if successful; otherwise - 1.

Remarks

You can use the Windows API CreateMappedBitmap to map colors before adding the bitmap to the toolbar. If you pass a pointer to a CBitMap object, you must ensure that the bitmap isn't destroyed until after the toolbar is destroyed.

`CToolBarCtrl::AddButtons`

Adds one or more buttons to a toolbar control.

BOOL AddButtons(
    int nNumButtons,
    LPTBBUTTON lpButtons);

Parameters

nNumButtons
Number of buttons to add.

lpButtons
Address of an array of TBBUTTON structures that contains information about the buttons to add. There must be the same number of elements in the array as buttons specified by nNumButtons.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The lpButtons pointer points to an array of TBBUTTON structures. Each TBBUTTON structure associates the button being added with the button's style, image and/or string, command ID, state, and user-defined data:

typedef struct _TBBUTTON {
    int iBitmap;    // zero-based index of button image
    int idCommand;  // command to be sent when button pressed
    BYTE fsState;   // button state--see below
    BYTE fsStyle;   // button style--see below
    DWORD dwData;   // application-defined value
    int iString;    // zero-based index of button label string
} TBBUTTON;

The members are as follows:

iBitmap

Zero-based index of button image, -1 if no image for this button.
idCommand

Command identifier associated with the button. This identifier is sent in a WM_COMMAND message when the button is chosen. If the fsStyle member has the TBSTYLE_SEP value, this member must be zero.
fsState

Button state flags. It can be a combination of the values listed below:
- TBSTATE_CHECKED The button has the TBSTYLE_CHECKED style and is being pressed.
- TBSTATE_ENABLED The button accepts user input. A button that doesn't have this state doesn't accept user input and is grayed.
- TBSTATE_HIDDEN The button isn't visible and can't receive user input.
- TBSTATE_INDETERMINATE The button is grayed.
- TBSTATE_PRESSED The button is being pressed.
- TBSTATE_WRAP A line break follows the button. The button must also have the TBSTATE_ENABLED state.
fsStyle

Button style. It can be a combination of the values listed below:
- TBSTYLE_BUTTON Creates a standard push button.
- TBSTYLE_CHECK Creates a button that toggles between the pressed and unpressed states each time the user clicks it. The button has a different background color when it is in the pressed state.
- TBSTYLE_CHECKGROUP Creates a check button that stays pressed until another button in the group is pressed.
- TBSTYLE_GROUP Creates a button that stays pressed until another button in the group is pressed.
- TBSTYLE_SEP Creates a separator, providing a small gap between button groups. A button that has this style doesn't receive user input.
dwData

User-defined data.
iString

Zero-based index of the string to use as the button's label, -1 if there's no string for this button.

The image and/or string whose index you provide must have previously been added to the toolbar control's list using AddBitmap, AddString, and/or AddStrings.

`CToolBarCtrl::AddString`

Adds a new string, passed as a resource ID, to the toolbar's internal list of strings.

int AddString(UINT nStringID);

Parameters

nStringID
Resource identifier of the string resource to add to the toolbar control's string list.

Return Value

The zero-based index of the first new string added if successful; otherwise -1.

`CToolBarCtrl::AddStrings`

Adds a new string or strings to the list of strings available for a toolbar control.

int AddStrings(LPCTSTR lpszStrings);

Parameters

lpszStrings
Address of a buffer that contains one or more NULL-terminated strings to add to the toolbar's string list. The last string must be terminated with two NULL characters.

Return Value

The zero-based index of the first new string added if successful; otherwise -1.

Remarks

Strings in the buffer must be separated by a NULL character. You must ensure that the last string has two NULL terminators. To properly format a constant string, you might write it as:

[!code-cppNVC_MFCControlLadenDialog#72]

or:

[!code-cppNVC_MFCControlLadenDialog#73]

You shouldn't pass a CString object to this function since it isn't possible to have more than one NULL character in a CString.

`CToolBarCtrl::AutoSize`

Resizes the entire toolbar control.

void AutoSize();

Remarks

You should call this function when the size of the parent window changes or when the size of the toolbar changes (such as when you set the button or bitmap size, or add strings).

`CToolBarCtrl::ChangeBitmap`

Changes the bitmap for a button in the current toolbar control.

BOOL ChangeBitmap(
    int idButton,
    int iBitmap);

Parameters

idButton
[in] Command identifier of the button that is to receive a new bitmap.

iBitmap
[in] Zero-based index of an image in the current toolbar control's image list.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

If this method is successful, the system displays the specified image in the specified button.

This method sends the TB_CHANGEBITMAP message, which is described in the Windows SDK.

Example

The following code example changes the bitmap for the File Save button to the bitmap for the About button.

[!code-cppNVC_MFC_CToolBarCtrl_s1#1]

`CToolBarCtrl::CheckButton`

Checks or clears a given button in a toolbar control.

BOOL CheckButton(
    int nID,
    BOOL bCheck = TRUE);

Parameters

nID
Command identifier of the button to check or clear.

bCheck
TRUE to check the button, FALSE to clear it.

Return Value

Nonzero if successful; otherwise zero.

Remarks

When a button has been checked, it appears to have been pressed. If you want to change more than one button state, consider calling SetState instead.

`CToolBarCtrl::CommandToIndex`

Retrieves the zero-based index for the button associated with the specified command identifier.

UINT CommandToIndex(UINT nID) const;

Parameters

nID
Command ID whose button index you want to find.

Return Value

The zero-based index for the button associated with the command ID.

Remarks

`CToolBarCtrl::Create`

Creates a toolbar control and attaches it to a CToolBarCtrl object.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwStyle
Specifies the toolbar control's style. Toolbars must always have the WS_CHILD style. In addition, you can specify any combination of toolbar styles and window styles as described under Remarks.

rect
Optionally specifies the toolbar control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the toolbar control's parent window. It must not be NULL.

nID
Specifies the toolbar control's ID.

Return Value

Nonzero if successful; otherwise zero.

Remarks

You construct a CToolBarCtrl in two steps. First, call the constructor, and then call Create, which creates the toolbar control and attaches it to the CToolBarCtrl object. Apply the following window styles to a toolbar control.

WS_CHILD Always
WS_VISIBLE Usually
WS_DISABLED Rarely

See CreateWindow in the Windows SDK for a description of window styles.

Optionally, apply a combination of common control styles, as described in the Windows SDK.

Apply a combination of toolbar styles to either the control or the buttons themselves. The styles are described in the topic Toolbar Control and Button Styles in the Windows SDK.

To use extended toolbar styles, call SetExtendedStyle after you call Create. To create a toolbar with extended window styles, call CToolBarCtrl::CreateEx instead of Create.

The toolbar control automatically sets the size and position of the toolbar window. The height is based on the height of the buttons in the toolbar. The width is the same as the width of the parent window's client area. The CCS_TOP and CCS_BOTTOM styles determine whether the toolbar is positioned along the top or bottom of the client area. By default, a toolbar has the CCS_TOP style.

`CToolBarCtrl::CreateEx`

Creates a control (a child window) and associates it with the CToolBarCtrl object.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwExStyle
Specifies the extended style of the control being created. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

dwStyle
Specifies the toolbar control's style. Toolbars must always have the WS_CHILD style. In addition, you can specify any combination of toolbar styles and window styles as described in the Remarks section of Create.

rect
A reference to a RECT structure describing the size and position of the window to be created, in client coordinates of pParentWnd.

pParentWnd
A pointer to the window that is the control's parent.

nID
The control's child-window ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_. CreateEx creates the control with the extended Windows styles specified by dwExStyle. Set extended styles specific to a control using SetExtendedStyle. For example, use CreateEx to set such styles as WS_EX_CONTEXTHELP, but use SetExtendedStyle to set such styles as TBSTYLE_EX_DRAWDDARROWS. For more information, see the styles described in Toolbar Extended Styles in the Windows SDK.

`CToolBarCtrl::CToolBarCtrl`

Constructs a CToolBarCtrl object.

CToolBarCtrl();

Remarks

You must call Create to make the toolbar usable.

`CToolBarCtrl::Customize`

Displays the Customize Toolbar dialog box.

void Customize();

Remarks

This dialog box allows the user to customize the toolbar by adding and deleting buttons. To support customization, your toolbar's parent window must handle the customization notification messages as described in Handling Customization Notifications. Your toolbar must also have been created with the CCS_ADJUSTABLE style, as described in CToolBarCtrl::Create.

`CToolBarCtrl::DeleteButton`

Deletes a button from the toolbar control.

BOOL DeleteButton(int nIndex);

Parameters

nIndex
Zero-based index of the button to delete.

Return Value

Nonzero if successful; otherwise zero.

Remarks

`CToolBarCtrl::EnableButton`

Enables or disables the specified button in a toolbar control.

BOOL EnableButton(
    int nID,
    BOOL bEnable = TRUE);

Remarks

Implements the functionality of TB_GETBITMAP in the Windows SDK.

`CToolBarCtrl::GetBitmapFlags`

Retrieves the bitmap flags from the toolbar.

UINT GetBitmapFlags() const;

Return Value

A UINT that has the TBBF_LARGE flag set if the display can support large toolbar bitmaps, clear otherwise.

Remarks

You should call it after creating the toolbar but before adding bitmaps to the toolbar. The return value indicates whether the display supports large bitmaps or not. If the display supports large bitmaps and if you choose to use them, call SetBitmapSize and SetButtonSize before adding your large bitmap using AddBitmap.

`CToolBarCtrl::GetButton`

Retrieves information about the specified button in a toolbar control.

BOOL GetButton(
    int nIndex,
    LPTBBUTTON lpButton) const;

Parameters

nIndex
Zero-based index of the button for which to retrieve information.

lpButton
Address of the TBBUTTON structure that is to receive a copy of the button information. See CToolBarCtrl::AddButtons for information about the TBBUTTON structure.

Return Value

Nonzero if successful; otherwise zero.

`CToolBarCtrl::GetButtonCount`

Retrieves a count of the buttons currently in the toolbar control.

int GetButtonCount() const;

Return Value

The count of the buttons.

`CToolBarCtrl::GetButtonInfo`

Retrieves the information for a button in a toolbar.

int GetButtonInfo(
    int nID,
    TBBUTTONINFO* ptbbi) const;

Parameters

nID
The button identifier.

ptbbi
A pointer to a TBBUTTONINFO structure that receives the button information.

Return Value

The zero-based index of the button, if successful; otherwise -1.

Remarks

This member function implements the behavior of the Win32 message TB_GETBUTTONINFO, as described in the Windows SDK.

`CToolBarCtrl::GetButtonSize`

Gets the size of a toolbar button.

DWORD GetButtonSize() const;

Return Value

A DWORD value that contains the width and height values in the LOWORD and HIWORD, respectively.

`CToolBarCtrl::GetButtonText`

Retrieves the display text of a specified button on the current toolbar control.

CString GetButtonText(int idButton) const;

Parameters

idButton
[in] The identifier for the button whose display text is retrieved.

Return Value

A CString that contains the display text of the specified button.

Remarks

This method sends the TB_GETBUTTONTEXT message, which is described in the Windows SDK.

`CToolBarCtrl::GetColorScheme`

Retrieves the color scheme of the current toolbar control.

BOOL GetColorScheme(COLORSCHEME* lpColorScheme) const;

Parameters

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parameters

nIndex
Zero-based index of the button for which to retrieve information.

lpRect
Address of a RECT structure or a CRect object that receives the coordinates of the bounding rectangle.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This function doesn't retrieve the bounding rectangle for buttons whose state is set to TBSTATE_HIDDEN.

`CToolBarCtrl::GetMaxSize`

Retrieves the total size of all of the visible buttons and separators in the toolbar.

BOOL GetMaxSize(LPSIZE pSize) const;

Parameters

pSize
A pointer to a SIZE structure that receives the size of the items.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message TB_GETMAXSIZE, as described in the Windows SDK.

`CToolBarCtrl::GetMaxTextRows`

Retrieves the maximum number of text rows displayed on a toolbar button.

int GetMaxTextRows() const;

Return Value

The maximum number of text rows displayed on a toolbar button.

`CToolBarCtrl::GetMetrics`

Retrieves the metrics of the CToolBarCtrl object.

void GetMetrics(LPTBMETRICS ptbm) const;

Parameters

ptbm
A pointer to the TBMETRICS structure of the CToolBarCtrl object.

Remarks

This member function emulates the functionality of the TB_GETMETRICS message, as described in the Windows SDK.

`CToolBarCtrl::GetPadding`

Retrieves the horizontal and vertical padding of the current toolbar control.

BOOL GetPadding(
    int* pnHorzPadding,
    int* pnVertPadding) const;

Parameters

pnHorzPadding
[out] An integer that receives the horizontal padding of the toolbar control, in pixels.

pnVertPadding
[out] An integer that receives the vertical padding of the toolbar control, in pixels.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the TB_GETPADDING message, which is described in the Windows SDK.

`CToolBarCtrl::GetPressedImageList`

Retrieves the image list that the current toolbar control uses to represent buttons in the pressed state.

CImageList* GetPressedImageList();

Return Value

Pointer to a CImageList that contains the image list for the current control, or NULL if no such image list is set.

Remarks

This method sends the TB_GETPRESSEDIMAGELIST message, which is described in the Windows SDK.

`CToolBarCtrl::GetRect`

Retrieves the bounding rectangle for a specified toolbar button.

BOOL GetRect(
    int nID,
    LPRECT lpRect) const;

Remarks

This function is especially handy if you want to retrieve more than one of the button states. To just retrieve one state, use one of the following member functions: IsButtonEnabled, IsButtonChecked, IsButtonPressed, IsButtonHidden, or IsButtonIndeterminate. However, the GetState member function is the only way to detect the TBSTATE_WRAP button state.

`CToolBarCtrl::GetString`

Retrieves a toolbar string.

int GetString(
    int nString,
    LPTSTR lpstrString,
    int cchMaxLen) const;

int GetString(
    int nString,
    CString& str) const;

Parameters

nString
Index of the string.

lpstrString
Pointer to a buffer used to return the string.

cchMaxLen
Length of the buffer in bytes.

str
The string.

Return Value

The length of the string if successful, -1 if not.

Remarks

This member function implements the behavior of the Win32 message TB_GETSTRING, as described in the Windows SDK.

`CToolBarCtrl::GetStyle`

Gets the styles currently applied to a toolbar control.

DWORD GetStyle() const;

Return Value

A DWORD containing a combination of toolbar control styles, as described in the Windows SDK.

`CToolBarCtrl::GetToolTips`

Retrieves the handle of the tool tip control, if any, associated with the toolbar control.

CToolTipCtrl* GetToolTips() const;

Return Value

A pointer to the CToolTipCtrl object associated with this toolbar or NULL if the toolbar has no associated tool tip control.

Remarks

Since the toolbar control normally creates and maintains its own tool tip control, most programs don't need to call this function.

`CToolBarCtrl::HitTest`

Determines where a point lies in a toolbar control.

int HitTest(LPPOINT ppt) const;

Parameters

ppt
A pointer to a POINT structure that contains the x-coordinate of the hit test in the x member and the y-coordinate of the hit test in the y member. The coordinates are relative to the toolbar's client area.

Return Value

An integer value indicating the location of a point on a toolbar. If the value is zero or a positive value, this return value is the zero-based index of the nonseparator item in which the point lies.

If the return value is negative, the point doesn't lie within a button. The absolute value of the return value is the index of a separator item or the nearest nonseparator item.

Remarks

This member function implements the behavior of the Win32 message TB_HITTEST, as described in the Windows SDK.

`CToolBarCtrl::HideButton`

Hides or shows the specified button in a toolbar control.

BOOL HideButton(
    int nID,
    BOOL bHide = TRUE);

Parameters

nID
Command identifier of the button to hide or show.

bHide
TRUE to hide the button, FALSE to show it.

Return Value

Nonzero if successful; otherwise zero.

Remarks

If you want to change more than one button state, consider calling SetState instead.

`CToolBarCtrl::Indeterminate`

Sets or clears the indeterminate state of the specified button in a toolbar control.

BOOL Indeterminate(
    int nID,
    BOOL bIndeterminate = TRUE);

Parameters

nID
Command identifier of the button whose indeterminate state is to be set or cleared.

bIndeterminate
TRUE to set the indeterminate state for the specified button, FALSE to clear it.

Return Value

Nonzero if successful; otherwise zero.

Remarks

Indeterminate buttons are displayed grayed, such as the way the bold button on the toolbar of a word processor would look when the text selected contains both bold and regular characters. If you want to change more than one button state, consider calling SetState instead.

`CToolBarCtrl::InsertButton`

Inserts a button in a toolbar control.

BOOL InsertButton(
    int nIndex,
    LPTBBUTTON lpButton);

Parameters

nIndex
Zero-based index of a button. This function inserts the new button to the left of this button.

lpButton
Address of a TBBUTTON structure containing information about the button to insert. See CToolBarCtrl::AddButtons for a description of the TBBUTTON structure.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The image and/or string whose index you provide must have previously been added to the toolbar control's list using AddBitmap, AddString, and/or AddStrings.

`CToolBarCtrl::InsertMarkHitTest`

Retrieves the insertion mark information for a point in a toolbar.

BOOL InsertMarkHitTest(
    LPPOINT ppt,
    LPTBINSERTMARK ptbim) const;

Parameters

ppt
A pointer to a POINT structure that contains the hit test coordinates, relative to the client area of the toolbar.

ptbim
A pointer to a TBINSERTMARK structure that receives the insertion mark information.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the behavior of the Win32 message TB_INSERTMARKHITTEST, as described in the Windows SDK.

`CToolBarCtrl::IsButtonChecked`

Determines whether the specified button in a toolbar control is checked.

BOOL IsButtonChecked(int nID) const;

Parameters

nID
Command identifier of the button in the toolbar.

Return Value

Nonzero if the button is checked; otherwise zero.

Remarks

Consider calling GetState if you want to retrieve more than one button state.

`CToolBarCtrl::IsButtonEnabled`

Determines whether the specified button in a toolbar control is enabled.

BOOL IsButtonEnabled(int nID) const;

Parameters

nID
Command identifier of the button in the toolbar.

Return Value

Nonzero if the button is enabled; otherwise zero.

Remarks

Consider calling GetState if you want to retrieve more than one button state.

`CToolBarCtrl::IsButtonHidden`

Determines whether the specified button in a toolbar control is hidden.

BOOL IsButtonHidden(int nID) const;

Parameters

`CToolBarCtrl::IsButtonPressed`

Determines whether the specified button in a toolbar control is pressed.

BOOL IsButtonPressed(int nID) const;

Parameters

nID
Command identifier of the button in the toolbar.

Return Value

Nonzero if the button is pressed, otherwise zero.

Remarks

Consider calling GetState if you want to retrieve more than one button state.

`CToolBarCtrl::LoadImages`

Loads bitmaps into a toolbar control's image list.

void LoadImages(
    int iBitmapID,
    HINSTANCE hinst);

Parameters

iBitmapID
ID of a bitmap that contains the images to be loaded. To specify your own bitmap resource, set this parameter to the ID of a bitmap resource and set hInst to NULL. Your bitmap resource will be added to the image list as a single image. You can add standard, system-defined bitmaps by setting hinst to HINST_COMMCTRL and setting this parameter to one of the following IDs:

Bitmap ID	Description
`IDB_HIST_LARGE_COLOR`	Explorer bitmaps in large size
`IDB_HIST_SMALL_COLOR`	Explorer bitmaps in small size
`IDB_STD_LARGE_COLOR`	Standard bitmaps in large size
`IDB_STD_SMALL_COLOR`	Standard bitmaps in small size
`IDB_VIEW_LARGE_COLOR`	View bitmaps in large size
`IDB_VIEW_SMALL_COLOR`	View bitmaps in small size

hinst
Program instance handle to the calling application. This parameter can be HINST_COMMCTRL to load a standard image list.

Remarks

This member function implements the behavior of the Win32 message TB_LOADIMAGES, as described in the Windows SDK.

`CToolBarCtrl::MapAccelerator`

Maps an accelerator character to a toolbar button.

BOOL MapAccelerator(
    TCHAR chAccel,
    UINT* pIDBtn);

Parameters

chAccel
Accelerator character to be mapped. This character is the same character that is underlined in the button's text.

pIDBtn
A pointer to a UINT that receives the command identifier of the button that corresponds to the accelerator specified in chAccel.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the behavior of the Win32 message TB_MAPACCELERATOR, as described in the Windows SDK.

`CToolBarCtrl::MarkButton`

Sets the highlight state of a given button in a toolbar control.

BOOL MarkButton(
    int nID,
    BOOL fHighlight = TRUE);

Parameters

nID
The button identifier.

fHighlight
Specifies the highlight state to be set. By default, TRUE. If set to FALSE, the button is set to its default state.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message TB_MARKBUTTON, as described in the Windows SDK.

`CToolBarCtrl::MoveButton`

Moves a button from one index to another.

BOOL MoveButton(
    UINT nOldPos,
    UINT nNewPos);

Parameters

nOldPos
The zero-based index of the button to be moved.

nNewPos
The zero-based index of the button's destination.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message TB_MOVEBUTTON, as described in the Windows SDK.

`CToolBarCtrl::PressButton`

Presses or releases the specified button in a toolbar control.

BOOL PressButton(int nID, BOOL bPress = TRUE);

Parameters

nID
[in] Command identifier of the button to press or release.

bPress
[in] TRUE to press the specified button; FALSE to release the specified button. The default value is TRUE.

Return Value

TRUE if the method is successful; otherwise, FALSE.

Remarks

If you want to change more than one button state, consider calling SetState instead.

This method sends the TB_PRESSBUTTON message, which is described in the Windows SDK.

`CToolBarCtrl::ReplaceBitmap`

Replaces the existing bitmap in the current toolbar control with a new bitmap.

BOOL ReplaceBitmap(LPTBREPLACEBITMAP pReplaceBitmap);

Parameters

pReplaceBitmap
[in] Pointer to a TBREPLACEBITMAP structure that describes the bitmap to be replaced and the new bitmap.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the TB_REPLACEBITMAP message, which is described in the Windows SDK.

Example

The following code example replaces the bitmap for the standard toolbar with a different bitmap.

[!code-cppNVC_MFC_CToolBarCtrl_s1#2]

`CToolBarCtrl::RestoreState`

Restores the state of the toolbar control from the location in the registry specified by the parameters.

void RestoreState(
    HKEY hKeyRoot,
    LPCTSTR lpszSubKey,
    LPCTSTR lpszValueName);

Parameters

hKeyRoot
Identifies a currently open key in the registry or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszSubKey
Points to a NULL-terminated string containing the name of the subkey with which a value is associated. This parameter can be NULL or a pointer to an empty string. If the parameter is NULL, the value will be added to the key identified by the hKeyRoot parameter.

lpszValueName
Points to a string containing the name of the value to retrieve. If a value with this name isn't already present in the key, the function adds it to the key.

`CToolBarCtrl::SaveState`

Saves the state of the toolbar control in the location in the registry specified by the parameters.

void SaveState(
    HKEY hKeyRoot,
    LPCTSTR lpszSubKey,
    LPCTSTR lpszValueName);

Parameters

hKeyRoot
Identifies a currently open key in the registry or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszSubKey
Points to a NULL-terminated string containing the name of the subkey with which a value is associated. This parameter can be NULL or a pointer to an empty string. If the parameter is NULL, the value will be added to the key identified by the hKeyRoot parameter.

lpszValueName
Points to a string containing the name of the value to set. If a value with this name isn't already present in the key, the function adds it to the key.

`CToolBarCtrl::SetAnchorHighlight`

Sets the anchor highlight setting for a toolbar.

BOOL SetAnchorHighlight(BOOL fAnchor = TRUE);

Parameters

fAnchor
[in] Specifies if anchor highlighting is enabled or disabled. If this value is nonzero, anchor highlighting will be enabled. If this value is zero, anchor highlighting will be disabled

Return Value

The previous anchor setting. If highlighting was enabled, this value is nonzero. If highlighting wasn't enabled, this value is zero.

Remarks

This method implements the behavior of the Win32 message TB_SETANCHORHIGHLIGHT, as described in the Windows SDK.

`CToolBarCtrl::SetBitmapSize`

Sets the size of the actual bitmapped images to be added to a toolbar control.

BOOL SetBitmapSize(CSize size);

Parameters

size
Width and height, in pixels, of the bitmapped images.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This function must be called only before adding any bitmaps to the toolbar. If the application doesn't explicitly set the bitmap size, it defaults to 16 by 15 pixels.

`CToolBarCtrl::SetButtonInfo`

Sets the information for an existing button in a toolbar.

BOOL SetButtonInfo(
    int nID,
    TBBUTTONINFO* ptbbi);

Parameters

nID
The button identifier.

ptbbi
A pointer to a TBBUTTONINFO structure that receives the button information.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The member function implements the behavior of the Win32 message TB_SETBUTTONINFO, as described in the Windows SDK.

`CToolBarCtrl::SetButtonSize`

Sets the size of the buttons in the toolbar control.

BOOL SetButtonSize(CSize size);

Parameters

size
Width and height, in pixels, of the buttons.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The button size must always be at least as large as the bitmap size it encloses. This function must be called only before adding any bitmaps to the toolbar. If the application doesn't explicitly set the button size, it defaults to 24 by 22 pixels.

Example

See the example for CToolBar::GetToolBarCtrl.

`CToolBarCtrl::SetButtonStructSize`

Specifies the size of the TBBUTTON structure.

void SetButtonStructSize(int nSize);

Parameters

nSize
Size, in bytes, of the TBBUTTON structure.

Remarks

If you wanted to store extra data in the TBBUTTON structure, you could either derive a new structure from TBBUTTON, adding the members you needed, or create a new structure that contains a TBBUTTON structure as its first member. You would then call this function to tell the toolbar control the size of the new structure.

See CToolBarCtrl::AddButtons for more information on the TBBUTTON structure.

`CToolBarCtrl::SetButtonWidth`

Sets the minimum and maximum button widths in the toolbar control.

BOOL SetButtonWidth(
    int cxMin,
    int cxMax);

Parameters

cxMin
Minimum button width, in pixels. Toolbar buttons will never be narrower than this value.

cxMax
Maximum button width, in pixels. If button text is too wide, the control displays it with ellipsis points.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message TB_SETBUTTONWIDTH, as described in the Windows SDK.

`CToolBarCtrl::SetCmdID`

Sets the command identifier that will be sent to the owner window when the specified button is pressed.

BOOL SetCmdID(
    int nIndex,
    UINT nID);

Parameters

nIndex
The zero-based index of the button whose command ID is to be set.

nID
The command ID to set the selected button to.

Return Value

Returns nonzero if successful; otherwise zero.

`CToolBarCtrl::SetColorScheme`

Sets the color scheme of the current toolbar control.

void SetColorScheme(const COLORSCHEME* lpColorScheme);

Parameters

lpColorScheme
[in] Pointer to a COLORSCHEME structure that describes the highlight color and shadow color of the toolbar control.

Remarks

This method has no effect if a Windows Vista visual theme is set.

This method sends the TB_SETCOLORSCHEME message, which is described in the Windows SDK.

Example

The following code example sets the color scheme for the current toolbar control. The code example makes the left and top edges of each tool button red and the right and bottom edges blue. When the user presses the button, the button's red edges turn blue and its blue edges turn red.

[!code-cppNVC_MFC_CToolBarCtrl_s1#3]

`CToolBarCtrl::SetDisabledImageList`

Sets the image list that the toolbar control will use to display disabled buttons.

CImageList* SetDisabledImageList(CImageList* pImageList);

Parameters

pImageList
A pointer to a CImageList object containing the images to be used by the toolbar control to display disabled button images.

Return Value

A pointer to a CImageList object that was previously used by the toolbar control to display disabled button images.

Remarks

This member function implements the behavior of the Win32 message TB_SETDISABLEDIMAGELIST, as described in the Windows SDK. The MFC implementation of SetDisabledImageList uses a CImageList object containing the toolbar control's disabled button images, rather than a handle to an image list.

`CToolBarCtrl::SetDrawTextFlags`

Sets the flags in the Win32 function DrawText, which is used to draw the text in the specified rectangle, formatted according to how the flags are set.

DWORD SetDrawTextFlags(
    DWORD dwMask,
    DWORD dwDTFlags);

Parameters

dwMask
A combination of one or more of the DT_ flags, specified in the Win32 function DrawText, that indicates which bits in dwDTFlags will be used when drawing the text.

dwDTFlags
A combination of one or more of the DT_ flags, specified in the Win32 function DrawText, that indicate how the button text will be drawn. This value is passed to DrawText when the button text is drawn.

Return Value

A DWORD containing the previous text drawing flags.

Remarks

This member function implements the behavior of the Win32 message TB_SETDRAWTEXTFLAGS, as described in the Windows SDK. This member function sets the flags in the Win32 function DrawText, which draws text in the specified rectangle, formatted according to how the flags are set.

`CToolBarCtrl::SetExtendedStyle`

Sets the extended styles for a toolbar control.

DWORD SetExtendedStyle(DWORD dwExStyle);

Parameters

dwExStyle
A value specifying the new extended styles. This parameter can be a combination of the toolbar extended styles.

Return Value

A DWORD that represents the previous extended styles. For a list of styles, see Toolbar Extended Styles, in the Windows SDK.

Remarks

This member function implements the behavior of the Win32 message TB_SETEXTENDEDSTYLE, as described in the Windows SDK.

`CToolBarCtrl::SetHotImageList`

Sets the image list that the toolbar control will use to display "hot" buttons.

CImageList* SetHotImageList(CImageList* pImageList);

Parameters

pImageList
A pointer to a CImageList object containing the images to be used by the toolbar control to display hot button images.

Return Value

A pointer to a CImageList object that was previously used by the toolbar control to display hot button images.

Remarks

This member function implements the behavior of the Win32 message TB_SETHOTIMAGELIST, as described in the Windows SDK.

The MFC implementation of SetHotImageList uses a CImageList object containing the toolbar control's hot button images, rather than a handle to an image list. A hot button appears highlighted when the pointer is above it.

`CToolBarCtrl::SetHotItem`

Sets the hot item in a toolbar.

int SetHotItem(int nHot);

Parameters

nHot
The zero-based index number of the item that will be made hot. If this value is -1, none of the items will be hot.

Return Value

The index of the previous hot item, or -1 if there was no hot item.

Remarks

This member function implements the behavior of the Win32 message TB_SETHOTITEM, as described in the Windows SDK.

`CToolBarCtrl::SetImageList`

Sets the image list that the toolbar will use to display buttons that are in their default state.

CImageList* SetImageList(CImageList* pImageList);

Parameters

pImageList
A pointer to a CImageList object containing the images to be used by the toolbar control to display button images in their default state.

Return Value

A pointer to a CImageList object that was previously used by the toolbar control to display button images in their default state.

Remarks

This member function implements the behavior of the Win32 message TB_SETIMAGELIST, as described in the Windows SDK.

The MFC implementation of SetImageList uses a CImageList object containing the toolbar control's button images, rather than a handle to an image list.

`CToolBarCtrl::SetIndent`

Sets the indentation for the first button in a toolbar control.

BOOL SetIndent(int iIndent);

Parameters

iIndent
The value specifying the indentation, in pixels.

Return Value

Nonzero if successful; otherwise zero.

`CToolBarCtrl::SetInsertMark`

Sets the current insertion mark for the toolbar.

void SetInsertMark(TBINSERTMARK* ptbim);

Parameters

ptbim
A pointer to the TBINSERTMARK structure that contains the insertion mark.

Remarks

This member function implements the behavior of the Win32 message TB_SETINSERTMARK, as described in the Windows SDK.

`CToolBarCtrl::SetInsertMarkColor`

Sets the color used to draw the insertion mark for the toolbar.

COLORREF SetInsertMarkColor(COLORREF clrNew);

Parameters

clrNew
A COLORREF value that contains the new insertion mark color.

Return Value

A COLORREF value that contains the previous insertion mark color.

Remarks

This member function implements the behavior of the Win32 message TB_SETINSERTMARKCOLOR, as described in the Windows SDK.

`CToolBarCtrl::SetMaxTextRows`

Sets the maximum number of text rows displayed on a toolbar button.

BOOL SetMaxTextRows(int iMaxRows);

Parameters

iMaxRows
Maximum number of rows to be set.

Return Value

Nonzero if successful; otherwise zero.

`CToolBarCtrl::SetMetrics`

Sets the metrics of the CToolBarCtrl object.

void SetMetrics(LPTBMETRICS ptbm);

Parameters

ptbm
A pointer to the TBMETRICS structure of the CToolBarCtrl object.

Remarks

This member function emulates the functionality of the TB_SETMETRICS message, as described in the Windows SDK.

`CToolBarCtrl::SetOwner`

Sets the owner window for the toolbar control.

void SetOwner(CWnd* pWnd);

Parameters

pWnd
Pointer to the CWnd or CWnd-derived object that will be the new owner window for the toolbar control.

Remarks

The owner window is the window that receives notifications from the toolbar.

`CToolBarCtrl::SetPadding`

Sets the horizontal and vertical padding of the current toolbar control.

DWORD SetPadding(
    int nHorzPadding,
    int nVertPadding);

Parameters

nHorzPadding
[in] Specifies the horizontal padding of the toolbar control, in pixels.

nVertPadding
[in] Specifies the vertical padding of the toolbar control, in pixels.

Return Value

A DWORD whose low word contains the previous horizontal padding value, and whose high word contains the previous vertical padding value. The padding values are measured in pixels.

Remarks

This method sends the TB_SETPADDING message, which is described in the Windows SDK.

Example

The following code example sets the horizontal and vertical padding of the current toolbar control to 20 pixels.

[!code-cppNVC_MFC_CToolBarCtrl_s1#4]

`CToolBarCtrl::SetPressedImageList`

Sets the image list that the current toolbar control uses to represent buttons in the pressed state.

CImagelist* SetPressedImageList(
    int iImageID,
    CImageList* pImageList);

Parameters

iImageID
[in] The zero-based index of the image list. Set this parameter to zero if you use only one image list.

pImageList
[in] Pointer to a CImageList that contains the new image list.

Return Value

Pointer to a CImageList that contains the previous image list for the current control, or NULL if no such image list was set.

Remarks

This method sends the TB_SETPRESSEDIMAGELIST message, which is described in the Windows SDK.

Example

The following code example sets the pressed image list to be the same as the default image list.

[!code-cppNVC_MFC_CToolBarCtrl_s1#5]

`CToolBarCtrl::SetRows`

Asks the toolbar control to resize itself to the requested number of rows.

void SetRows(
    int nRows,
    BOOL bLarger,
    LPRECT lpRect);

Parameters

nRows
Requested number of rows.

bLarger
Tells whether to use more rows or fewer rows if the toolbar can't be resized to the requested number of rows.

lpRect
Points to the CRect object or RECT structure that will receive the new bounding rectangle of the toolbar.

Remarks

If the toolbar can't resize itself to the requested number or rows, it will resize itself to either the next larger or next smaller valid size, depending on the value of bLarger. If bLarger is TRUE, the new number of rows will be larger than the number requested. If bLarger is FALSE, the new number of rows will be smaller than the number requested.

A given number of rows is valid for the toolbar if the buttons can be arranged such that all of the rows have the same number of buttons (except perhaps the last row). For example, a toolbar that contains four buttons couldn't be sized to three rows because the last two rows would have to be shorter. If you attempted to size it to three rows, you would get four rows if bLarger was TRUE and two rows if bLarger was FALSE.

If there are separators in the toolbar, the rules for when a given number of rows is valid are more complicated. The layout is computed such that button groups (buttons with a separator before the first and the last button in the group) are never broken up on several rows unless the group can't fit on one row.

If a group doesn't fit on one row, the next group will start on the next row even if it would fit on the row where the large group ended. The purpose of this rule is to make the separation between large groups more noticeable. The resulting vertical separators are counted as rows.

Note also that the SetRows member function will always choose the layout that results in the smallest toolbar size. Creating a toolbar with the TBSTYLE_WRAPABLE style and then resizing the control will simply apply the method outlined above given the width of the control.

This function can only be called for toolbars that were created with the TBSTYLE_WRAPABLE style.

`CToolBarCtrl::SetState`

Sets the state for the specified button in a toolbar control.

BOOL SetState(
    int nID,
    UINT nState);

Parameters

nID
Command identifier of the button.

nState
State flags. It can be a combination of the values listed for button states in CToolBarCtrl::AddButtons.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This function is especially handy if you want to set more than one of the button states. To just set one state, use one of the following member functions: EnableButton, CheckButton, HideButton, Indeterminate, or PressButton.

`CToolBarCtrl::SetStyle`

Sets the styles for a toolbar control.

void SetStyle(DWORD dwStyle);

Parameters

dwStyle
A DWORD containing a combination of toolbar control styles, as described in the Windows SDK.

`CToolBarCtrl::SetToolTips`

Associates a tool tip control with a toolbar control.

void SetToolTips(CToolTipCtrl* pTip);

Parameters

pTip
Pointer to the CToolTipCtrl object.

`CToolBarCtrl::SetWindowTheme`

Sets the visual style of the CToolBarCtrl object.

HRESULT SetWindowTheme(LPCWSTR pszSubAppName);

Parameters

pszSubAppName
A pointer to a Unicode string that contains the toolbar visual style to set.

Return Value

The return value isn't used.

Remarks

This member function emulates the functionality of the TB_SETWINDOWTHEME message, as described in the Windows SDK.

Files

ctoolbarctrl-class.md

Latest commit

History

ctoolbarctrl-class.md

File metadata and controls

CToolBarCtrl Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Support for Internet Explorer Version 4.0 and Later

Inheritance Hierarchy

Requirements

CToolBarCtrl::AddBitmap

Parameters

Return Value

Remarks

CToolBarCtrl::AddButtons

Parameters

Return Value

Remarks

CToolBarCtrl::AddString

Parameters

Return Value

CToolBarCtrl::AddStrings

Parameters

Return Value

Remarks

CToolBarCtrl::AutoSize

Remarks

CToolBarCtrl::ChangeBitmap

Parameters

Return Value

Remarks

Example

CToolBarCtrl::CheckButton

Parameters

Return Value

Remarks

CToolBarCtrl::CommandToIndex

Parameters

Return Value

Remarks

CToolBarCtrl::Create

Parameters

Return Value

Remarks

CToolBarCtrl::CreateEx

Parameters

Return Value

Remarks

CToolBarCtrl::CToolBarCtrl

Remarks

CToolBarCtrl::Customize

Remarks

CToolBarCtrl::DeleteButton

Parameters

Return Value

Remarks

CToolBarCtrl::EnableButton

Parameters

Return Value

Remarks

CToolBarCtrl::GetAnchorHighlight

Return Value

Remarks

CToolBarCtrl::GetBitmap

Parameters

Return Value

Remarks

CToolBarCtrl::GetBitmapFlags

Return Value

Remarks

CToolBarCtrl::GetButton

Parameters

Return Value

CToolBarCtrl::GetButtonCount

Return Value

`CToolBarCtrl` Class

`CToolBarCtrl::AddBitmap`

`CToolBarCtrl::AddButtons`

`CToolBarCtrl::AddString`

`CToolBarCtrl::AddStrings`

`CToolBarCtrl::AutoSize`

`CToolBarCtrl::ChangeBitmap`

`CToolBarCtrl::CheckButton`

`CToolBarCtrl::CommandToIndex`

`CToolBarCtrl::Create`

`CToolBarCtrl::CreateEx`

`CToolBarCtrl::CToolBarCtrl`

`CToolBarCtrl::Customize`

`CToolBarCtrl::DeleteButton`

`CToolBarCtrl::EnableButton`

`CToolBarCtrl::GetAnchorHighlight`

`CToolBarCtrl::GetBitmap`

`CToolBarCtrl::GetBitmapFlags`

`CToolBarCtrl::GetButton`

`CToolBarCtrl::GetButtonCount`

`CToolBarCtrl::GetButtonInfo`

`CToolBarCtrl::GetButtonSize`

`CToolBarCtrl::GetButtonText`

`CToolBarCtrl::GetColorScheme`

`CToolBarCtrl::GetDisabledImageList`

`CToolBarCtrl::GetDropTarget`

`CToolBarCtrl::GetExtendedStyle`

`CToolBarCtrl::GetHotImageList`

`CToolBarCtrl::GetHotItem`

`CToolBarCtrl::GetImageList`

`CToolBarCtrl::GetInsertMark`

`CToolBarCtrl::GetInsertMarkColor`

`CToolBarCtrl::GetItemRect`

`CToolBarCtrl::GetMaxSize`

`CToolBarCtrl::GetMaxTextRows`

`CToolBarCtrl::GetMetrics`

`CToolBarCtrl::GetPadding`

`CToolBarCtrl::GetPressedImageList`

`CToolBarCtrl::GetRect`