Map the Controls to Member Variables

Suggested Reading

• Using ClassWizard, Visual C++ User’s Guide
  
  
• CWnd::DoDataExchange, Microsoft Foundation Class Reference
  
  
• Defining Member Variables for DDX, Visual C++ Programmer’s Guide
  
  
• ClassWizard and Dialog Data Validation, Visual C++ Programmer’s Guide

Scribble must be able to retrieve the values that the user enters in the Thin Pen Width and Thick Pen Width boxes. MFC defines a mechanism that automates the process of gathering values from a dialog box; this mechanism is called a “data map.” In the same way that a message map binds a user-interface element with a member function, a data map binds a dialog-box control with a member variable. The value of the member variable reflects the status or the contents of the control. By adding entries to CPenWidthsDlg’s data map, you can retrieve the values entered in the Thin Pen Width and Thick Pen Width boxes.

For Scribble, the widths of the thin and thick pens must be between 1 and 20. You can enforce these conditions by using the automated data validation that data maps provide. If the user enters values that fall outside this range, the application displays a message box stating the legal range and allows the user to enter new values.

To map the controls of the Pen Widths dialog box to member variables

1. From the View menu, click ClassWizard and click the Member Variables tab.

   This tab, shown in the figure below, contains a list box displaying the mapping between controls and member variables.

2. In the Class name list, select CPenWidthsDlg.

   At the moment the box displays only the IDs for the controls because you haven’t yet specified which member variables the controls correspond to.

3. Select IDC_THIN_PEN_WIDTH and then click the Add Variable button.

   The Add Member Variable dialog box appears.

4. In the Member variable name box, specify m_nThinWidth as the variable name.
   
   
5. From the Variable type list box, click int.
   
   
6. Click OK to add the member variable to the class.

   Notice the changes in the MFC ClassWizard dialog box:

   • The member name and type you specified now appear in the Control IDs list.
     
     
   • Description reads “int with validation”.
     
     
   • Two new edit boxes (Minimum Value and Maximum Value) appear to receive the validation parameters appropriate for an integer. These correspond to the edit boxes you added to the dialog box resource.
7. In the Minimum Value and Maximum Value boxes, enter 1 and 20, respectively.
   
   
8. Repeat steps 3 through 7 for the control IDC_THICK_PEN_WIDTH. Specify m_nThickWidth as the member name, click int, and enter lower and upper limits of 1 and 20.
   
   
9. Click OK.

You’ve now completed the data map connecting the Pen Widths dialog box to the CPenWidthsDlg class. You can view the m_nThickWidth and m_nThinWidth member variables in ClassView under the CPenWidthsDlg class.

The Member Variables Tab

ClassWizard inserts declarations into the data map of PenWidthsDlg.h for the member variables you specified in the Add Member Variable dialog box.

ClassWizard also makes changes to PenWidthsDlg.cpp after you’ve mapped the controls to member variables. Examine these changes by opening PenWidthsDlg.cpp.

Notice that ClassWizard has initialized the member variables in the constructor and provided an implementation for DoDataExchange, which is a member function defined by CWnd (the base class of CDialog). The framework calls DoDataExchange whenever values have to be moved between the member variables in the class and the controls in the dialog box on screen (for example, when first displaying the dialog box on the screen or when the user closes the dialog box by clicking OK).

The DoDataExchange function is implemented using DDX and DDV function calls. A DDX (for Dialog Data eXchange) function specifies which control in the dialog box corresponds to a particular member variable and transfers the data between the two. A DDV (for Dialog Data Validation) function specifies the validation parameters for a particular member variable, ensuring that its value is legal. The DDX and DDV function calls shown in PenWidthsDlg.cpp reflect the mapping and validation parameters you specified with ClassWizard.

Notice that the DDV function call for a given member variable immediately follows the DDX function call for that variable. This is a rule you must follow if you choose to manually edit the contents of the data map.