CDialog Class
The base class used for displaying dialog boxes on the screen.
class CDialog : public CWnd
Members
Public Constructors
Name |
Description |
|---|---|
Constructs a CDialog object. |
Public Methods
Name |
Description |
|---|---|
Initializes the CDialog object. Creates a modeless dialog box and attaches it to the CDialog object. |
|
Creates a modeless dialog box from a dialog-box template in memory (not resource-based). |
|
Calls a modal dialog box and returns when done. |
|
Closes a modal dialog box. |
|
Gets the ID of the default pushbutton control for a dialog box. |
|
Moves the focus to a specified dialog-box control in the dialog box. |
|
Creates a modal dialog box from a dialog-box template in memory (not resource-based). The parameters are stored until the function DoModal is called. |
|
Converts the dialog-box units of a rectangle to screen units. |
|
Moves the focus to the next dialog-box control in the dialog box. |
|
Override to augment dialog-box initialization. |
|
Override to specify the font that a dialog-box control is to use when it draws text. |
|
Moves the focus to the previous dialog-box control in the dialog box. |
|
Changes the default pushbutton control for a dialog box to a specified pushbutton. |
|
Sets a context-sensitive help ID for the dialog box. |
Protected Methods
Name |
Description |
|---|---|
Override to perform the Cancel button or ESC key action. The default closes the dialog box and DoModal returns IDCANCEL. |
|
Override to perform the OK button action in a modal dialog box. The default closes the dialog box and DoModal returns IDOK. |
Remarks
Dialog boxes are of two types: modal and modeless. A modal dialog box must be closed by the user before the application continues. A modeless dialog box allows the user to display the dialog box and return to another task without canceling or removing the dialog box.
A CDialog object is a combination of a dialog template and a CDialog-derived class. Use the dialog editor to create the dialog template and store it in a resource, then use the Add Class wizard to create a class derived from CDialog.
A dialog box, like any other window, receives messages from Windows. In a dialog box, you are particularly interested in handling notification messages from the dialog box's controls since that is how the user interacts with your dialog box. Use the Properties window to select which messages you wish to handle and it will add the appropriate message-map entries and message-handler member functions to the class for you. You only need to write application-specific code in the handler member functions.
If you prefer, you can always write message-map entries and member functions manually.
In all but the most trivial dialog box, you add member variables to your derived dialog class to store data entered in the dialog box's controls by the user or to display data for the user. You can use the Add Variable wizard to create member variables and associate them with controls. At the same time, you choose a variable type and permissible range of values for each variable. The code wizard adds the member variables to your derived dialog class.
A data map is generated to automatically handle the exchange of data between the member variables and the dialog box's controls. The data map provides functions that initialize the controls in the dialog box with the proper values, retrieve the data, and validate the data.
To create a modal dialog box, construct an object on the stack using the constructor for your derived dialog class and then call DoModal to create the dialog window and its controls. If you wish to create a modeless dialog, call Create in the constructor of your dialog class.
You can also create a template in memory by using a DLGTEMPLATE data structure as described in the Windows SDK. After you construct a CDialog object, call CreateIndirect to create a modeless dialog box, or call InitModalIndirect and DoModal to create a modal dialog box.
The exchange and validation data map is written in an override of CWnd::DoDataExchange that is added to your new dialog class. See the DoDataExchange member function in CWnd for more on the exchange and validation functionality.
Both the programmer and the framework call DoDataExchange indirectly through a call to CWnd::UpdateData.
The framework calls UpdateData when the user clicks the OK button to close a modal dialog box. (The data is not retrieved if the Cancel button is clicked.) The default implementation of OnInitDialog also calls UpdateData to set the initial values of the controls. You typically override OnInitDialog to further initialize controls. OnInitDialog is called after all the dialog controls are created and just before the dialog box is displayed.
You can call CWnd::UpdateData at any time during the execution of a modal or modeless dialog box.
If you develop a dialog box by hand, you add the necessary member variables to the derived dialog-box class yourself, and you add member functions to set or get these values.
A modal dialog box closes automatically when the user presses the OK or Cancel buttons or when your code calls the EndDialog member function.
When you implement a modeless dialog box, always override the OnCancel member function and call DestroyWindow from within it. Don't call the base class CDialog::OnCancel, because it calls EndDialog, which will make the dialog box invisible but will not destroy it. You should also override PostNcDestroy for modeless dialog boxes in order to delete this, since modeless dialog boxes are usually allocated with new. Modal dialog boxes are usually constructed on the frame and do not need PostNcDestroy cleanup.
For more information on CDialog, see:
Knowledge Base article Q262954 : HOWTO: Create a Resizeable Dialog Box with Scroll Bars
Inheritance Hierarchy
CDialog
Requirements
Header: afxwin.h