class CModalDialog : public CDialog

The CModalDialog class provides modal dialog boxes. In this type of dialog box, the user must respond before any processing outside the dialog box is possible. This is untrue for modeless dialog boxes.

Except in the most trivial cases, such as an About dialog box, you must derive your own modal dialog class from CModalDialog.

In your derived class, you can add member variables and member functions to specify the behavior of the dialog box. Add member variables to store data entered by the user via the dialog box controls or to store data for display through the controls. Add member functions to set and get this data. Add message-handler member functions to process messages for the controls in the dialog box.

Like other classes derived from class CWnd, classes derived from CModalDialog need their own message maps. If you declare any message-handler member functions, you must also provide a message map that connects the Windows messages with your handlers.

Note:

The three most common functions, OnInitDialog, OnOK, and OnCancel, do not need message-map entries.

Create a modal dialog object by constructing it. To do this, create a dialog object using the CModalDialog constructor, as shown in the example below.

Once the dialog object has been constructed, call its DoModal member function to run the dialog box. For example, to construct a modal dialog object of class CMyModal and run the dialog box, use the following coding:

CMyModal myModalDlg;

myModalDlg.DoModal();

When the user clicks one of the dialog-box push buttons, such as OK or Cancel, the dialog box closes and it is removed from the screen.

After the user closes the dialog box, its member variables are accessed through the member functions that you defined to get information entered by the user.

For example, for a modal dialog box that has an editable text control, you can override the OnOK message-handler function in your derived modal dialog class so that when the user clicks the OK button, OnOK retrieves the text entered in the control and stores it in a data member of the dialog object. Later, after DoModal returns, you can call a member function of the dialog object to retrieve the stored text.

You are responsible for supplying the member variables and member functions needed to access the dialog's data. Declare them in the class you derive from CModalDialog.

CDialog::EndDialog is called automatically in OnOK and OnCancel when the user closes the dialog box.

If the dialog box requires some initialization, override the CDialog::OnInitDialog member function to perform the initialization. For example, if an edit field in the dialog box is to display a default value that the user can accept or replace, override OnInitDialog to initialize the default text in the edit field. OnInitDialog is called automatically while the dialog is being created before the dialog box appears on the screen.

See Also

CModalDialog::DoModal, CDialog::EndDialog, CWnd::MessageBox, CModalDialog::OnOK, CModalDialog::OnCancel, WM_INITDIALOG, WM_CLOSE, WM_SETFONT