The buttons on a toolbar correspond to commands, just as the items on a menu do. Although you can add a toolbar to your application with AppWizard, you still need to use a little programming polish to make things just right. This is because every application is different and AppWizard can create only the most generally useful toolbar for most applications. When you create your own toolbars, you will probably want to add or delete buttons to support your application’s unique command set.

For example, when you create a standard AppWizard application with a toolbar, AppWizard creates the toolbar shown in Figure 7.1. This toolbar provides buttons for the commonly used commands in the File and Edit menus, as well as a button for displaying the About dialog box. What if your application doesn’t support these commands? It’s up to you to modify the default toolbar to fit your application.

FIG. 7.1 The default toolbar provides buttons for commonly used commands.

Create a multiple document interface application with a toolbar by choosing File, New; selecting the Project tab; highlighting MFC AppWizard (exe); naming the application Tool; and accepting the defaults in every dialog box. If you like, you can click the Finish button in step 1 to speed up the process. AppWizard provides a docking toolbar by default. Build and run the application, and you should see a toolbar of your own, just like Figure 7.1.

Before moving on, play with this toolbar a little. On the View menu, you can toggle whether the toolbar is displayed. Turn it off and then on again. Now click and hold on the toolbar between buttons and pull it down into the working area of your application. Let it go, and it’s a floating palette. Drag it around and drop it at the bottom of the application or one of the sides—it will dock against any side of the main window. Watch the tracking rectangle change shape to show you it will dock if you drop it. Drag it back off again so that it’s floating and close it by clicking the small x in the upper-right corner. Bring it back with the View menu and notice that it comes back right where you left it. All this functionality is yours free from AppWizard and MFC.

The first step in modifying the toolbar is to delete buttons you no longer need. To do this, first select the ResourceView tab to display your application’s resources by clicking on the + next to Tool Resources. Click the + next to Toolbar and double-click the IDR_MAINFRAME toolbar resource to edit it, as shown in Figure 7.2. (The Graphics and Colors palettes, shown floating in Figure 7.2, are docked by default. You can move them around by grabbing the wrinkles at the top.)

FIG. 7.2 Use the toolbar editor to customize your application’s toolbar.

After you have the toolbar editor on the screen, deleting buttons is as easy as dragging the unwanted buttons from the toolbar. Place your mouse pointer on the button, hold down the left mouse button, and drag the unwanted button away from the toolbar. When you release the mouse button, the toolbar button disappears. In the Tool application, delete all the buttons except the Help button with a yellow question mark. Figure 7.3 shows the edited toolbar with only the Help button remaining. The single blank button template is only a starting point for the next button you want to create. If you leave it blank, it doesn’t appear in the final toolbar.

FIG. 7.3 This edited toolbar has only a single button left (not counting the blank button template).

Adding buttons to a toolbar is a two-step process: First you draw the button’s icon, and then you match the button with its command. To draw a new button, first click the blank button template in the toolbar. The blank button appears enlarged in the edit window, as shown in Figure 7.4.

FIG. 7.4 Click the button template to open it in the button editor.

Suppose you want to create a toolbar button that draws a red circle in the application’s window. Draw a red circle on the blank button with the Ellipse tool, and you’ve created the button’s icon. Open the properties box and give the button an appropriate ID, such as ID_CIRCLE in this case.

Now you need to define the button’s description and ToolTip. The description appears in the application’s status bar. In this case, a description of "Draws a red circle in the window" might be good. The ToolTip appears whenever the user leaves the mouse pointer over the button for a second or two, acting as a reminder of the button’s purpose. A ToolTip of Circle would be appropriate for the circle button. Type these two text strings into the Prompt box. The description comes first, followed by the newline character (\n) and the ToolTip, as shown in Figure 7.5.

FIG. 7.5 After drawing the button, specify its properties.

You’ve now defined a command ID for your new toolbar button. Usually, you use the command ID of an existing menu item already connected to some code. In these cases, simply choose the existing command ID from the drop-down box, and your work is done. The prompt is taken from the properties of the menu item, and the message handler has already been arranged for the menu item. You will already be handling the menu item, and that code will handle the toolbar click, too. In this application, the toolbar button doesn’t mirror a menu item, so you will associate the ID with a message-handler function that MFC automatically calls when the user clicks the button.

To do this, follow these steps:

NOTE: If you haven’t defined a message-response function for a toolbar button, or if there is no instance of the class that catches the message, MFC disables the button when you run the application. For example, if the message is caught by the document or view in an MDI application and there is no open document, the button is disabled. The same is true for menu commands—in fact, for all intents and purposes, toolbar buttons are menu commands.

FIG. 7.6 You can use ClassWizard to catch messages from your toolbar buttons.

NOTE: Ordinarily, toolbar buttons duplicate menu commands, providing a quicker way for the user to select commonly used commands in the menus. In that case, the menu item and the toolbar button both represent the exact same command, and you give both the same ID. Then the same message-response function is called, whether the user selects the command from the menu bar or the toolbar.

If you compile and run the application now, you will see the window shown in Figure 7.7. In the figure, you can see the new toolbar button, as well as its ToolTip and description line. The toolbar looks sparse in this example, but you can add as many buttons as you like.

You can create as many buttons as you need; just follow the same procedure for each. After you have created the buttons, you’re through with the toolbar resources and ready to write the code that responds to the buttons. For example, in the previous example, a circle button was added to the toolbar, and a message-response function, called OnCircle(), was added to the program. MFC calls that message-response function whenever the user clicks the associated button. However, right now, that function doesn’t do anything, as shown in Listing 7.1.

FIG. 7.7 The new toolbar button shows its ToolTip and description.

Although the circle button is supposed to draw a red circle in the window, you can see that the OnCircle() function is going to need a little help accomplishing that task. Add the lines shown in Listing 7.2 to the function so that the circle button will do what it’s supposed to do, as shown in Figure 7.8. This drawing code makes a brush, selects it into the DC, draws an ellipse with it, and then restores the old brush.

In most cases, after you have created your toolbar resource and associated its buttons with the appropriate command IDs, you don’t need to bother any more with the toolbar. The code generated by AppWizard creates the toolbar for you, and MFC takes care of calling the buttons’ response functions for you. However, at times you might want to change the toolbar’s default behavior or appearance in some way. In those cases, you can call on the CToolBar class’s member functions, which are listed in Table 7.1 along with their descriptions. The toolbar is accessible from the CMainFrame class as the m_wndToolBar member variable. Usually, you change the toolbar behavior in CMainFrame::OnCreate().

FIG. 7.8 After adding code to OnCircle(), the new toolbar button actually does something.

Normally, you don’t need to call the toolbar’s methods, but you can achieve some unusual results when you do. This toolbar resulted from a call to the toolbar object’s SetHeight() member function. The CToolbar class member functions enables you to perform this sort of toolbar trickery, but use them with great cautions.