CToolBar Class

Article
01/08/2013

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

class CToolBar : public CControlBar

Members

Public Constructors

Name	Description
CToolBar::CToolBar	Constructs a CToolBar object.

Public Methods

Name	Description
CToolBar::CommandToIndex	Returns the index of a button with the given command ID.
CToolBar::Create	Creates the Windows toolbar and attaches it to the CToolBar object.
CToolBar::CreateEx	Creates a CToolBar object with additional styles for the embedded CToolBarCtrl object.
CToolBar::GetButtonInfo	Retrieves the ID, style, and image number of a button.
CToolBar::GetButtonStyle	Retrieves the style for a button.
CToolBar::GetButtonText	Retrieves the text that will appear on a button.
CToolBar::GetItemID	Returns the command ID of a button or separator at the given index.
CToolBar::GetItemRect	Retrieves the display rectangle for the item at the given index.
CToolBar::GetToolBarCtrl	Allows direct access to the underlying common control.
CToolBar::LoadBitmap	Loads the bitmap containing bitmap-button images.
CToolBar::LoadToolBar	Loads a toolbar resource created with the resource editor.
CToolBar::SetBitmap	Sets a bitmapped image.
CToolBar::SetButtonInfo	Sets the ID, style, and image number of a button.
CToolBar::SetButtons	Sets button styles and an index of button images within the bitmap.
CToolBar::SetButtonStyle	Sets the style for a button.
CToolBar::SetButtonText	Sets the text that will appear on a button.
CToolBar::SetHeight	Sets the height of the toolbar.
CToolBar::SetSizes	Sets the sizes of buttons and their bitmaps.

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:

Create a toolbar resource.
Construct the CToolBar object.
Call the Create (or CreateEx) function to create the Windows toolbar and attach it to the CToolBar object.
Call LoadToolBar to load the toolbar resource.

Otherwise, follow these steps:

Construct the CToolBar object.
Call the Create (or CreateEx) function to create the Windows toolbar and attach it to the CToolBar object.
Call LoadBitmap to load the bitmap that contains the toolbar button images.
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.

Warning

CToolBar supports bitmaps with a maximum of 16 colors. When you load an image into a toolbar editor, Visual Studio automatically converts the image to a 16-color bitmap, if necessary, and displays a warning message if the image was converted. If you use an image with more than 16 colors (using an external editor to edit the image), the application might behave unexpectedly.

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.