Update Scribble’s Clear All Menu Item

This topic presents the steps you will take to update the Clear All menu item on Scribble’s Edit menu. The update command is handled by the document object, which has the necessary information on whether there are any strokes in the current drawing to clear.

Recall how you used WizardBar to create a starter handler for the Edit menu’s Clear All command earlier in this lesson, in the topic Bind Scribble’s Clear All Command to Its Handler Code; then you filled in the handler code. In this topic you’ll use WizardBar to create a starter handler for the update command, which you’ll then fill in with Scribble-specific code.

To add an update handler for Scribble’s Clear All menu

1. Using WizardBar, open ScribbleDoc.cpp in the text editor.
   
   
2. In the WizardBar Filter combo box, select ID_EDIT_CLEAR_ALL.
   
   
3. Click the action button arrow on the right end of WizardBar and click Add Windows Message Handler.
   
   
4. In the New Windows messages to handle box, select UPDATE_COMMAND_UI. Click Add and Edit.

   The Add Member Function dialog box appears, displaying a suggested name for the handler.

5. Click OK to accept the name OnUpdateEditClearAll.

   WizardBar creates the function template for OnUpdateEditClearAll at the end of the file.

6. Replace the //TODO comment text with the following code:

   // Enable the user-interface object (menu item or tool- 
   // bar button) if the document is non-empty, i.e., has 
   // at least one stroke.
   pCmdUI->Enable( !m_strokeList.IsEmpty( ) );
   

7. Save your work.

The OnUpdateEditClearAll handler takes one argument, a pointer to a CCmdUI object that contains information about the Clear All menu item on Scribble’s Edit menu.

The pointer to a CCmdUI object, pCmdUI, is used to access a CCmdUI member function, Enable. Enable takes one Boolean argument. In this code, the expression !m_strokeList.IsEmpty( ) evaluates to nonzero if the document has at least one stroke to clear. If the expression evaluates to zero (no strokes), the menu item is disabled (and dimmed or grayed).

Note   When the user opens a menu, the update handlers for all items on the menu are called before the user sees the menu displayed. Thus it’s important not to perform a lot of processing in your update handlers.

When you added the update command handler for the Clear All menu item, ClassWizard wrote the following message-map entry in the document’s message map in ScribbleDoc.cpp:

   ON_UPDATE_COMMAND_UI( ID_EDIT_CLEAR_ALL, OnUpdateEditClearAll )

The ON_UPDATE_COMMAND_UI macro resembles the ON_COMMAND macro for the OnEditClearAll message handler.

In addition, ClassWizard added a new member function declaration for OnUpdateEditClearAll to the CScribbleDoc class definition in ScribbleDoc.h. The function declaration looks like this:

afx_msg void OnUpdateEditClearAll( CCmdUI* pCmdUI );