Designing and Creating Dialog BoxesThis section describes dialog box architecture and the types of dialog boxes, and how to design,
build, and test a dialog box.
First, you will learn how to add controls to a dialog box resource using the Dialog editor. Then you will be introduced to the primary properties of most of the controls found in dialog boxes. Finally, you will learn how to test dialog boxes during development.
This section includes the following topics:
Dialog Box Architecture
Before building dialog boxes, you need to understand how they work. Data for dialog boxes comes from three sources: a dialog box resource
, a dialogbox object
, and a
document object. To see an illustration of the dialog box architecture, click this icon.
The purposes of the dialog box resource, dialog box object, and document object can be described as follows:
® A dialog box is a graphical object that gets data from, and gives data to, the user. This graphical interface is created from a dialog box template provided by Developer Studio. When you finish adding controls to this template, it becomes the dialog box resource that Windows uses to draw the dialog box on the screen. When you create the resource using the Dialog editor, the dialog box resource is available to your application at run time.
® A dialog box object provides a place to put default values for controls in the dialog box. The dialog box class is created in ClassWizard. Objects of the dialog box class enable communication between the dialog box and the application.
® The document object is a general term that describes a place in memory from which a dialog box draws data. For example, the data that populates the Summary Information dialog box of a word-processing file (such as the file name and author) comes from a document object. In this case, it is the file that the user is editing. Similarly, in dialog boxes that display Help topics, the document object is the Help file itself.
This expert point of view explains how dialog boxes work
Types of Dialog Boxes
You can design and create two types of dialog boxes:
modal and
modeless.
Modal Dialog Boxes
When using modal dialog boxes, the user needs to perform an action in the dialog box before continuing to use the application. For example, a File Open dialog box closes only after the user performs an action, such as selecting a file name and clicking OK. The user is then returned to the application. From the system's point of view, starting a modal dialog box is like making a function call: the caller (or application) waits until something is returned by the called function (dialog box) before taking the next action.
Modeless Dialog Boxes
In contrast, when the user invokes modeless dialog boxes, the dialog boxes remain on the screen and allow user interaction with the application. A find-and-replace dialog box is a typical modeless dialog box. From the system's point of view, a modeless dialog box is a second process that needs to be supported.
Note Most of the initial work to create a dialog box is the same for modal and modeless types. However, you will need to write additional code for a modeless dialog box to enable reciprocal communication with its parent application. This course covers the creation of modal dialog boxes only. For information about creating modeless dialog boxes, search for "modeless dialog boxes" in Visual C++ Help.
Creating a Dialog Box
The dialog box template provided by Developer Studio creates the basic interface for a dialog box. By default, the template provides a window with a caption, a
Close button, and
OK and
Cancel buttons. You can remove or alter these controls and add more controls to the template to complete the functionality of the dialog box. This template, with the changes you make, becomes the basis for the dialog box resource that your application uses.
To create a simple dialog box template in a project
1. On the Insert menu, click Resource.
2. In the Insert Resource dialog box, click Dialog, and then click New.
When you create a dialog box resource, it is assigned a unique symbol name to be used by the operating system, an ID value, and a caption. You can modify these in the Dialog Properties property sheet.
Adding Controls
A control is any item, usually visual in nature, that can be placed in a dialog box to provide functionality to the user. For example, edit controls provide the user with text strings; groups of option (or radio) buttons provide the user with mutually exclusive choices.
From the application's perspective, controls are actually child windows of the dialog box window. Controls communicate with the parent dialog box through event-notification messages. This illustration shows a list of the standard controls.
By default, the Controls toolbar is displayed while the Dialog editor is open. You can use the toolbar to add controls to the dialog box template.
On the Layout menu, the Dialog editor provides layout tools for aligning, sizing, spacing, and positioning controls. You can also use these layout tools for testing the template. To copy and paste controls from other dialog boxes, you can use the Cut, Copy, and Paste commands.
To add a control to a dialog box template
1. On the Controls toolbar, click the control you want to place in the template, and then drag the control to the dialog box template.
You can resize the control by dragging any of the handles on the control. Move the control by dragging it to the location you want on the template.
2. To see the property sheet for the new control, right-click the control and click Properties.
Control Properties
The properties associated with a control determine the behavior and appearance of the control. The control ID, also a property of the control, helps identify the control when
events occur that the control needs to handle.
To set the properties of a control, use the property sheet associated with that control. To access the property sheet, right-click the control and click Properties on the shortcut menu. To see the property sheet for the Edit control, click this icon.
For information about individual control options, see Visual C++ Help.
To set properties for controls
1. While in the Dialog editor, right-click the control for which you want to set properties.
2. Click Properties on the shortcut menu.
3. Set the properties you want for the control.
To keep the property sheet on top while you edit a control's properties, click the Keep Visible button (pushpin) in the upper-left corner of the property sheet.
Setting Tab Order and Grouping Controls
Once you place controls in a dialog box template, you can define the order in which the
focus moves from one control to the next when the user presses the TAB key. You can also organize the controls into logical or functional groups.
Tab Order
Tab order is the order in which the controls in a dialog box receive focus when the user presses the TAB key (or in some cases, an arrow key).
When the user presses the tab key, the system looks for the next control in the tab order that has the Tab stop property set.
To set the tab order of controls
1. In the Dialog editor, press CTRL+D, or click Tab Order on the Layout menu.
A numbered tag is placed beside each control in the dialog box. These numbers show the tab order for the controls.
2. To change the tab order, click the controls in the sequence of the tab order you want.
3. Press ESC or CTRL+D when you are finished.
To see an illustration of the default tab order for a sample dialog box, click this icon.
Control Groups
Microsoft Visual C++ offers a tool for arranging controls according to function, called the Group Box control. Grouping controls makes it easier for a user to understand the structure of a dialog box.
A control often used in group boxes is the radio button. Groups of radio buttons offer the user one choice within a group of mutually exclusive options. For example, radio buttons are used to allow users to set paragraphs either left, right, or justified in a word processor.
When you use the Group Box control, however, you are only telling the user which controls are logically related. At design time, you must also specify in Windows which controls are logically grouped. You can do this by setting the Tab stop and Group properties on the General tab of the property sheet for the control.
To create a control group
1. To indicate the beginning of a group, select the Group check box on the property sheet of the first control in the group.
2. For all other controls in the group, clear the Group checkbox.
3. To signal the end of the group or the beginning of the next group, select the Group property of the next control in the tab order, even if it is a stand-alone control.
Testing the Dialog Box
While you're constructing a dialog box, you will want to see how the dialog box will function for the user. Microsoft Visual C++ provides a test mechanism. In test mode, controls are activated and accept user input in the standard manner.
Shortcut keys and tab order are enabled as well. However, programmatic responses to user actions are not enabled.
To test a dialog box
1. In the Dialog editor, press CTRL+T, or click the Test button on the Dialog toolbar.
2. Test the dialog box features you want to see.
3. Press CTRL+T or click the Test button again to exit test mode.
To see the location of the Test button, click this icon.
Implementing the Dialog Box Class
This section describes how to create a dialog box class, how to add and initialize
member variables, and how to add code to handle user input.
To make a dialog box functional, you must create a dialog box class and develop the code that implements the controls in the dialog box. The dialog box class is used by Windows to create space in memory for the dialog box.
The following illustration is a schematic diagram of a dialog box resource, a dialog box object, and a document object. The dialog box resource has two controls that have been set to their default values: the color of the phrase and the phrase itself in the Edit control. The dialog box is built from the resource and the object code; the results appear on the screen. To see the illustration, click this icon.
This section includes the following topics:
Creating the Dialog Box Class
The first step in implementing a dialog box is to create a dialog box class.
To create a dialog box class
1. Save the dialog box template that you have created.
2. With your new dialog box open in the Dialog editor, press CTRL+W to invoke ClassWizard.
3. On the Message Maps tab, click Add Class, and then choose New from the drop-down list.
To see an illustration of the New Class dialog box, click this icon.
4. Under Class information, type in a name for the new class, and select CDialog as the base class.
5. Verify that the dialog ID is the same ID as your dialog box template ID.
Note It is important to verify that the dialog box ID of the new class and the ID of the template are the same. These IDs tell the dialog box class which resource to check before building the window, filling the controls with their default values, and showing the dialog box on the screen.
Adding and Initializing Member Variables
Once you have created a dialog box class, you must add and initialize the member variables. In this section, you will learn how to do just that.
This section includes the following topics:
Adding Member Variables
Once you have created a dialog box class, add member variables to hold the initial values of the various controls. Two categories of member variables serve different purposes, described in this table.
Category Description
Values Value member variables are used to initialize and hold the value of the control. They can be of a variety of data types, depending on the type of control. For example, the value of an edit control may be a
CString or an
int. The value of a check box is a
BOOL.
Controls Control member variables are objects that correspond to a control's type. They are generally used when interaction with a control goes beyond extracting its data. For example, when you use a list box control, you create a control variable of type CListBox. This enables you to use the CListBox member function on that control. This includes initializing the list box or extracting more than one string when Multiselect is enabled.
To add a member variable for a control
1. In ClassWizard, click the Member Variables tab.
2. In the Control IDs list box, select the ID for the control that you want to initialize.
3. Click Add Variable.
The Add Member Variable dialog box appears.
To see an illustration of the Add Member Variable dialog box, click this icon.
4. Assign a name to the variable, select a variable category, and then select a variable type for the member variable.
5. Click OK.
ClassWizard generates a class declaration and definitions for each member function in the designated header and implementation files, and adds the variable to your project.
ClassWizard also adds the member variables to the declaration of the new dialog box class, and adds code in the constructor to initialize these members to a default value, normally zero or NULL.
Initializing Member Variables
To complete the process of implementing a dialog box class, you need to initialize the member variables. There are two methods for initializing member variables:
® Initializing member variables in the constructor for the dialog box object
® Initializing member variables after the dialog box object is created
Initializing in the Constructor
Most simple controls are initialized in the constructor for the dialog box object. Examples of simple controls are the edit controls that use variables of the value category. For edit controls, the ClassWizard inserts a block into the constructor. You add statements after this block to change the initializations performed by the ClassWizard. The following example code shows this initialization:
CColorPhraseDlg::CColorPhraseDlg(CWnd* pParent /*=NULL*/)
: CDialog(CColorPhraseDlg::IDD, pParent)
{
//{{AFX_DATA_INIT(CColorPhraseDlg)
m_color = -1;
m_phrase = _T("");
//}}AFX_DATA_INIT
}
Initializing After You Create the Dialog Box Object
Members of a dialog box class are public by default. Consequently, they can be initialized by the object that creates and invokes the dialog box. The following example code shows how to do this:
void CDialog1View::OnModifyShowdialog()
{
CColorPhraseDlg dlg;
CDialog1Doc* pDoc = GetDocument();
ASSERT_VALID(pDoc);
// Load the dialog box's members before displaying
// it.
dlg.m_phrase = pDoc->GetPhrase();
dlg.m_color = RgbToInt(pDoc->GetColor());
...
}
Exchanging and Validating Dialog Box Input
Once you have used ClassWizard to associate data members in your dialog box class with specific controls in your dialog box, and have initialized the data members with default values for the controls, you need to add code to handle user input. In this section, you will learn how to add data exchange and data validation to your dialog boxes.
The following illustration shows what the MFC framework provides for data exchange and validation versus what you must provide. It also builds on earlier descriptions of the relationships between dialog box resources, dialog box objects, and document objects. To see the illustration, click this icon.
This expert point of view explains how dialog data exchange (DDX) and dialog data validation (DDV) are implemented.
This section includes the following topics:
Dialog Data Exchange
When your code makes the call to display the dialog box by using
DoModal, dialog data exchange (DDX) transfers the initial default values into the controls in the dialog box. When the user clicks
OK and closes the dialog box, DDX stores the values from the controls in the dialog box in the corresponding dialog box object members. If the user clicks
Cancel, DDX does not occur.
Dialog Data Validation
When adding member variables to the dialog class, in many cases you have the option to specify some validation criteria. At run time, when data is copied to the member variables, the dialog data validation (DDV) functions of
DoDataExchange are also called. If validation fails, an error message box appears. Focus returns to the last control for which a corresponding DDV function was called, indicating to the user that the information contained in the control is invalid.
ClassWizard does most of the basic DDV work for you. It inserts the statements to verify that an edit box string does not exceed a given length, or that an integer is within a specified range. For more complex validation capabilities, you need to write additional code. For example, you need to write the code to determine whether an edit box is empty.
Implementing Exchange and Validation
DDX and DDV are handled by the function DoDataExchange, which is called by UpdateData. UpdateData takes either True or False as a parameter.
® UpdateData(FALSE) copies the member variables from the dialog class object to the controls in the dialog box.
® UpdateData(TRUE) copies data from the controls in the dialog box to the member variables of the dialog class object.
If you don't call UpdateData with a parameter, the default is True.
You call UpdateData whenever data transfer is appropriate. For example, use the UpdateData function from the Apply button of a modeless dialog box, with True as the argument.
The DoDataExchange routine can contain many DDX and DDV routines. However, if a DDV routine exists, it must follow immediately after its associated DDX routine in the data map.
Note ClassWizard edits DDX and DDV routines placed between the lines //{{AFX_DATA_MAP(CMyDialog) and //}}AFX_DATA_MAP. Add any custom DDX and DDV routines outside these special comments.
This sample code demonstrates the data exchange and validation of a single CString member variable, m_phrase.
void CMyDlg::DoDataExchange(CDataExchange* pDX)
{
CDialog::DoDataExchange(pDX);
//{{AFX_DATA_MAP(CColorPhraseDlg)
DDX_Text(pDX, IDC_PHRASE, m_phrase);
DDV_MaxChars(pDX, m_phrase, 50);
//}}AFX_DATA_MAP
}
Note If a validation fails, the system returns to the dialog box, queries which control was involved in the exchange, sets the focus to that control, and indicates that the validation has failed.
A. Radio buttons
B. Static text controls
C. Up-down (spin) controls
D. All controls
A. A new class is automatically generated for the parent dialog box.
B. A new CControl-derived class is created and an instance of this class is embedded in the parent dialog class.
C. A new member variable is created in the parent dialog class.
D. ClassWizard generates no source code, but maintains this information in the project’s .clw file.
A. DDX and DDV occur when the user clicks OK.
B. The developer can force DDX and DDV by calling CWnd::DoDataExchange.
C. The developer cannot extend DDX and DDV.
D. DDX and DDV are mutually exclusive; only one can be performed for each control. 
