CToolBarCtrl

The CToolBarCtrl class provides the functionality of the Windows toolbar common control. This control (and therefore the CToolBarCtrl class) is available only to programs running under Windows 95 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 stings, 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 CToolBarCtrl: 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 CToolBarCtrl: 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 Control Topics and Using CToolBarCtrl in the Visual C++ Programmer’s Guide.

#include <afxcmn.h>

Class Members |  Base Class |  Hierarchy Chart

Samples   MFC Sample CMNCTRL1 |  MFC Sample MFCIE

See Also   CToolBar