CToolBarCtrl Class

  • Article

Provides the functionality of the Windows toolbar common control.

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 is 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 which 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 cannot retrieve strings from the toolbar.

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

  1. Construct the CToolBarCtrl object.

  2. 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.

  3. Identify how you want the buttons on the toolbar displayed:

  4. Add button structures to the toolbar by calling AddButtons.

  5. If you want tool tips for a toolbar button in an owner window that is not 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.

  6. 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 are not 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

See Also

Reference

CWnd Class

Hierarchy Chart

CToolBar Class

Concepts

MFC Sample CMNCTRL1

MFC Sample MFCIE