CToolBar Class

Control bars that have a row of bitmapped buttons and optional separators.

class CToolBar : public CControlBar

Remarks

The buttons can act like pushbuttons, check-box buttons, or radio buttons. CToolBar objects are usually embedded members of frame-window objects derived from the class CFrameWnd or CMDIFrameWnd.

CToolBar::GetToolBarCtrl, a member function new to MFC 4.0, allows you to take advantage of the Windows common control's support for toolbar customization and additional functionality. CToolBar member functions give you most of the functionality of the Windows common controls; however, when you call GetToolBarCtrl, you can give your toolbars even more of the characteristics of Windows 95/98 toolbars. When you call GetToolBarCtrl, it will return a reference to a CToolBarCtrl object. See CToolBarCtrl for more information about designing toolbars using Windows common controls. For more general information about common controls, see Common Controls in the Windows SDK.

Visual C++ provides you with two methods to create a toolbar. To create a toolbar resource using the Resource Editor, follow these steps:

1. Create a toolbar resource.

2. Construct the CToolBar object.

3. Call the Create (or CreateEx) function to create the Windows toolbar and attach it to the CToolBar object.

4. Call LoadToolBar to load the toolbar resource.

Otherwise, follow these steps:

1. Construct the CToolBar object.

2. Call the Create (or CreateEx) function to create the Windows toolbar and attach it to the CToolBar object.

3. Call LoadBitmap to load the bitmap that contains the toolbar button images.

4. Call SetButtons to set the button style and associate each button with an image in the bitmap.

All the button images in the toolbar are taken from one bitmap, which must contain one image for each button. All images must be the same size; the default is 16 pixels wide and 15 pixels high. Images must be side by side in the bitmap.

The SetButtons function takes a pointer to an array of control IDs and an integer that specifies the number of elements in the array. The function sets each button's ID to the value of the corresponding element of the array and assigns each button an image index, which specifies the position of the button's image in the bitmap. If an array element has the value ID_SEPARATOR, no image index is assigned.

The order of the images in the bitmap is typically the order in which they are drawn on the screen, but you can use the SetButtonInfo function to change the relationship between image order and drawing order.

All buttons in a toolbar are the same size. The default is 24 x 22 pixels, in accordance with Windows Interface Guidelines for Software Design. Any additional space between the image and button dimensions is used to form a border around the image.

Each button has one image. The various button states and styles (pressed, up, down, disabled, disabled down, and indeterminate) are generated from that one image. Although bitmaps can be any color, you can achieve the best results with images in black and shades of gray.

Toolbar buttons imitate pushbuttons by default. However, toolbar buttons can also imitate check-box buttons or radio buttons. Check-box buttons have three states: checked, cleared, and indeterminate. Radio buttons have only two states: checked and cleared.

To set an individual button or separator style without pointing to an array, call GetButtonStyle to retrieve the style, and then call SetButtonStyle instead of SetButtons. SetButtonStyle is most useful when you want to change a button's style at run time.

To assign text to appear on a button, call GetButtonText to retrieve the text to appear on the button, and then call SetButtonText to set the text.

To create a check-box button, assign it the style TBBS_CHECKBOX or use a CCmdUI object's SetCheck member function in an ON_UPDATE_COMMAND_UI handler. Calling SetCheck turns a pushbutton into a check-box button. Pass SetCheck an argument of 0 for unchecked, 1 for checked, or 2 for indeterminate.

To create a radio button, call a CCmdUI object's SetRadio member function from an ON_UPDATE_COMMAND_UI handler. Pass SetRadio an argument of 0 for unchecked or nonzero for checked. In order to provide a radio group's mutually exclusive behavior, you must have ON_UPDATE_COMMAND_UI handlers for all of the buttons in the group.

For more information on using CToolBar, see the article MFC Toolbar Implementation and Technical Note 31: Control Bars.

Requirements

Header: afxext.h

See Also

Tasks

CTRLBARS Sample: Illustrates Custom Control Bars

DLGCBR32 Sample: Demonstrates Adding a Status Bar and Toolbar to Dialog Boxes

DOCKTOOL Sample: Demonstrates Dockable Toolbars

Reference

CControlBar Class

Hierarchy Chart

CToolBarCtrl Class

CControlBar Class

CToolBar::Create

CToolBar::LoadBitmap

CToolBar::SetButtons

CCmdUI::SetCheck

CCmdUI::SetRadio

Other Resources

CToolBar Members