Mapping Messages to Functions

ClassView, WizardBar, or ClassWizard enable you to bind member functions of MFC classes (user-interface classes derived from the MFC library) to the messages generated by your application's resources. They use MFC message maps to create the binding.

Note   ClassWizard is not for use when mapping messages to ATL objects. Instead use ClassView or the WizardBar only.

When you use ClassView, WizardBar, or ClassWizard to create a new class derived from one of the framework classes, it automatically places a complete and functional class in the header (.h) and implementation (.cpp) files you specify. ClassWizard keeps track of the class's message-handling and data-exchange members, so that you can update the class at a later time.

Note   ClassWizard is only for use with MFC user-interface classes derived from CCmdTarget that handle messages or manage dialog box controls. To add a new class that does not handle messages, create the class directly in the text editor. (The exception to this rule is class CRecordset, for database support, which can be created with ClassWizard.)

To define a message handler with ClassView or WizardBar

1. From ClassView, right-click on a class and click Add Windows Message Handler on the shortcut menu.

   -or-

   From WizardBar's Class drop-down list, select a class, then click Add Windows Message Handler on the Action menu.

   The New Windows Message and Event Handler dialog box appears.

2. From the Class or Object to Handle list, select an item.

   The New Windows messages/events box displays a list of messages that you can add to the selected class or object. The Existing Windows message/event handlers box displays a list of messages already associated with the selected class or object. (Note that the Filter for messages available to class drop-down list allows you to select different sets of messages/events.)

Note   If the selected class is a dialog class, form view, or record view, then the New Windows Messages and Event Handlers box includes window messages but not menu commands. To map menu IDs to messages in a class, you need to determine which class should handle the message (for example, CView or CMainFrame). Choose that class in the WizardBar Class drop-down list, select the menu ID from the Filter drop-down list, then from the Action menu select Add Windows Message Handler.

For information on handling custom messages, see MFC Technical Note 6.

3. Select an item from the New Windows Messages and Event Handlers box, and click Add Handler to add the new handler function.

   WizardBar then adds a stub function to the class's implementation file. For example:

   // CChildFrame message handlers
   void CChildFrame::OnLButtonDblClk(UINT nFlags, 
         CPoint point) 
   {
      // TODO: Add your message handler code here
      // and/or call default
   
      CMDIChildWnd::OnLButtonDblClk(nFlags, point);
   }

Add and Edit performs the same function as Add Handler, except that after adding the message handler, Add and Edit navigates you to the file in which the message handler is implemented.

If you want to edit an existing message handler, or one you just added, select an item from Existing message/event handlers, and click Edit Existing to navigate to the file in which the message handler is implemented.

Quickly Adding Message Handlers for Dialog Box Controls

For dialog boxes in your project that are already associated with a class, you can take advantage of some shortcuts when creating message handlers. You can quickly create a handler for either the default control event, or for any applicable Windows message.

Note   ClassWizard and the WizardBar can not be used for adding message handlers to ATL objects. Add a new message handler using the ClassView method.

To quickly add the default message handler for a control

1. Open the dialog box resource that contains the control. (You can choose GoTo Dialog Editor from ClassView or WizardBar, or double-click the dialog resource from the ResourceView pane.)
   
   
2. Double-click the control whose default message you want to handle.
   
   
3. The Add Member Function dialog box appears, with the default handler selected (for example, BN_CLICKED for a push button), and a suggested event name (for example, OnOk).

   If the control already has a handler defined for it, double-clicking jumps you to the handler code in the Text editor.

4. Click OK to have WizardBar generate the declaration and stub function code for the new message handler function.

Note   You can disable this functionality by clearing the Double-click in dialog editor edits code checkbox on the Compatibility tab of the Options dialog (available from the Tools menu). In this case, double-clicking on a control opens the control's Properties page.

To quickly add a message handler for a control

5. Open the dialog box resource that contains the control. (You can choose GoTo Dialog Editor from ClassView or WizardBar, or double-click the dialog resource from the ResourceView pane.)
   
   
6. From the WizardBar Members drop-down list, select an unimplemented (non-bold) message.

   The Add Member Function dialog appears, with a proposed name for that message handler (for example, OnKeydownTab1 for the TCN_KEYDOWN message on a tabbed dialog with an object ID of IDC_TAB1).

   Note   Selecting a bolded, or implemented message from the Messages list jumps you to that handler function in the Text editor.

7. Click OK to accept the default name for the handler, or rename it and then click OK.
   
   
8. WizardBar generates the function declaration and a stub function inside the dialog class, for example:

   afx_msg void OnKeydownTab1(NMHDR* pNMHDR, LRESULT* pResult);

   ……

   void CAboutDlg::OnSelchangeTab1(NMHDR* pNMHDR, LRESULT* pResult) 
   {
   // TODO: Add your control notification handler code here
   
   *pResult = 0;
   }
   

Default Control Events

To define a message handler with ClassWizard

Two shortcuts are available for:

• Defining message handlers for dialog buttons
  
  
• Defining member variables for dialog controls

1. On the View menu, click ClassWizard.

   ClassWizard appears and displays information about the currently selected class or the class you last edited with ClassWizard.

2. Click the Message Maps tab.
   
   
3. From the Class name drop-down list, select the class name of the user-interface component (such as a menu, accelerator, or dialog resource) you want to work with.

   ClassWizard displays information about the user-interface object that is currently selected.

4. In the Object IDs box, select the name of the user-interface object for which you want to define a message handler.
   
   
5. In the Messages box, select the message for which you want to define a handler. Click Add Function (or double-click the message name).

   Messages with handlers already defined are displayed in bold.

   Note   The messages you see in the Messages box are those most appropriate to your class. If your class is not associated with the resource that contains the command that you want to handle, set the focus on the resource (for example, a dialog), open ClassWizard, and then use the Class name drop-down list to switch to the class from which you want the message handled.

   In addition, you can change the set of messages you handle by selecting the Class Info tab and selecting a new set of messages in the Message filter box. For information on handling custom messages, see MFC Technical Note 6.

   Tip   Selecting a message displays a brief description of it at the bottom of the MFC ClassWizard dialog box.

   For messages that do not already have a predefined name for the handler function, the Add Member Function dialog box appears.

6. If the Add Member Function dialog box appears, type a name for the member function and click OK.

   -or-

   From the Add Member Function dialog box, click OK to accept the default name.

   Either action returns you to the ClassWizard Message Maps tab.

   The message name is now displayed in bold to show that a message handler has been defined. The name of the new message hander appears in the Member functions box.

7. At this point you have several options. You can:
   • Click Cancel to avoid updating your source code with the selected member functions.
     
     
   • Add more message handlers.
     
     
   • Click OK to update your source code with the selected member functions and close ClassWizard. You can return to ClassWizard any time during the development process.
     
     
   • Click Edit Code to jump to the definition of the function selected in the Member functions list just created by ClassWizard and begin defining the function's behavior.

   When you choose OK or Edit Code, ClassWizard updates your source code by:

   • Inserting a function declaration into the header file.
     
     
   • Inserting a complete, correct function definition with a skeletal implementation into the implementation file.
     
     
   • Updating the class's message map to include the new message-handling function.

For tips on adding message handlers to a class using ClassWizard, see Adding Functions with ClassWizard.

What do you want to know more about?

• What Message Types Are Associated with Which User-Interface Objects?
  
  
• Shortcut for Defining Message Handlers for Dialog Buttons
  
  
• Shortcut for Defining Member Variables for Dialog Controls
  
  
• Deleting a Message Handler
  
  
• Editing a Message Handler
  
  
• Defining a Message Handler for a Reflected Message
  
  
• Declaring a Variable Based on Your New Control Class
  
  
• Overriding a Virtual Function