The Toolbar

A toolbar consists of a number of horizontally (or vertically) arranged graphical buttons that might be clustered in groups. The programming interface determines the grouping. The graphical images for the buttons are stored in a single bitmap that is attached to the application's resource file. When a button is clicked, it sends a command message, as do menus and keyboard accelerators. An update command UI message handler is used to update the button's state, which in turn is used by the application framework to modify the button's graphical image.

The Toolbar Bitmap

Each button on a toolbar appears to have its own bitmap, but actually a single bitmap serves the entire toolbar. The toolbar bitmap has a tile, 15 pixels high and 16 pixels wide, for each button. The application framework supplies the button borders, and it modifies those borders, together with the button's bitmap tile color, to reflect the current button state. Figure 14-1 shows the relationship between the toolbar bitmap and the corresponding toolbar.

Figure 14-1. A toolbar bitmap and an actual toolbar.

The toolbar bitmap is stored in the file Toolbar.bmp in the application's \res subdirectory. The bitmap is identified in the resource script (RC) file as IDR_MAINFRAME. You don't edit the toolbar bitmap directly; instead you use Visual C++'s special toolbar-editing facility.

Button States

Each button can assume the following states.

State	Meaning
0	Normal, unpressed state.
TBSTATE_CHECKED	Checked (down) state.
TBSTATE_ENABLED	Available for use. Button is grayed and unavailable if this state is not set.
TBSTATE_HIDDEN	Not visible.
TBSTATE_INDETERMINATE	Grayed.
TBSTATE_PRESSED	Currently selected (pressed) with the mouse.
TBSTATE_WRAP	Line break follows the button.

A button can behave in either of two ways: it can be a pushbutton, which is down only when currently selected by the mouse, or it can be a check box button, which can be toggled up and down with mouse clicks. All buttons in the standard application framework toolbar are pushbuttons.

The Toolbar and Command Messages

When the user clicks a toolbar button with the mouse, a command message is generated. This message is routed like the menu command messages you saw in Chapter 13. Most of the time, a toolbar button matches a menu option. In the standard application framework toolbar, for example, the Disk button is equivalent to the File Save menu option because both generate the ID_FILE_SAVE command. The object receiving the command message doesn't need to know whether the message was produced by a click on the toolbar or by a selection from the menu.

A toolbar button doesn't have to mirror a menu item. If you don't provide the equivalent menu item, however, you are advised to define a keyboard accelerator for the button so that the user can activate the command with the keyboard or with a keyboard macro product for Microsoft Windows. You can use ClassWizard to define command and update command UI message handlers for toolbar buttons, whether or not they have corresponding menu items.

A toolbar has an associated bitmap resource and, in the RC file, a companion TOOLBAR resource that defines the menu commands associated with the buttons. Both the bitmap and the TOOLBAR resource have the same ID, typically IDR_MAINFRAME. The text of the AppWizard-generated TOOLBAR resource is shown below:

IDR_MAINFRAME TOOLBAR DISCARDABLE  16, 15 BEGIN     BUTTON      ID_FILE_NEW     BUTTON      ID_FILE_OPEN     BUTTON      ID_FILE_SAVE         SEPARATOR     BUTTON      ID_EDIT_CUT     BUTTON      ID_EDIT_COPY     BUTTON      ID_EDIT_PASTE         SEPARATOR     BUTTON      ID_FILE_PRINT     BUTTON      ID_APP_ABOUT END

The SEPARATOR constants serve to group the buttons by inserting corresponding spaces on the toolbar. If the number of toolbar bitmap panes exceeds the number of resource elements (excluding separators), the extra buttons are not displayed.

When you edit the toolbar with the resource editor, you're editing both the bitmap resource and the TOOLBAR resource. You select a button image, and then you double-click on the left panel to edit the properties, including the button's ID.

Toolbar Update Command UI Message Handlers

Remember from Chapter 13 that update command UI message handlers are used to disable or add check marks to menu items. These same message handlers apply to toolbar buttons. If your update command UI message handler calls the CCmdUI::Enable member function with a FALSE parameter, the corresponding button is set to the disabled (grayed) state and no longer responds to mouse clicks.

On a menu item, the CCmdUI::SetCheck member function displays a check mark. For the toolbar, the SetCheck function implements check box buttons. If the update command UI message handler calls SetCheck with a parameter value of 1, the button is toggled to the down (checked) state; if the parameter is 0, the button is toggled up (unchecked).

If the SetCheck parameter value is 2, the button is set to the indeterminate state. This state looks like the disabled state, but the button is still active and its color is a bit brighter.

The update command UI message handlers for a pop-up menu are called only when the menu is painted. The toolbar is displayed all the time, so when are its update command UI message handlers called? They're called during the application's idle processing, so the buttons can be updated continuously. If the same handler covers a menu item and a toolbar button, it is called both during idle processing and when the pop-up menu is displayed.