This documentation is archived and is not being maintained.

Implementing a Dialog Box 

There are two ways to add a dialog box to your ATL project: use the ATL Dialog Wizard or add it manually.

In the Add Class dialog box, select the ATL Dialog object to add a dialog box to your ATL project. Fill in the ATL Dialog Wizard as appropriate and click Finish. The wizard adds a class derived from CAxDialogImpl to your project. Open the Resource View from the View menu, locate your dialog, and double-click it to open it in the resource editor.


If your dialog box is derived from CAxDialogImpl, it can host both ActiveX and Windows controls. If you don't want the overhead of ActiveX control support in your dialog box class, use CSimpleDialog or CDialogImpl instead.

Message and event handlers can be added to your dialog class from Class View. For more information, see Adding an ATL Message Handler.

Implementing a dialog box is similar to implementing a window. You derive a class from either CAxDialogImpl, CDialogImpl, or CSimpleDialog and declare a message map to handle messages. However, you must also specify a dialog template resource ID in your derived class. Your class must have a data member called IDD to hold this value.


When you create a dialog box using the ATL Dialog Wizard, the wizard automatically adds the IDD member as an enum type.

CDialogImpl allows you to implement a modal or a modeless dialog box that hosts Windows controls. CAxDialogImpl allows you to implement a modal or a modeless dialog box that hosts both ActiveX and Windows controls.

To create a modal dialog box, create an instance of your CDialogImpl-derived (or CAxDialogImpl-derived) class and then call the DoModal method. To close a modal dialog box, call the EndDialog method from a message handler. To create a modeless dialog box, call the Create method instead of DoModal. To destroy a modeless dialog box, call DestroyWindow.

Sinking events is automatically done in CAxDialogImpl. Implement the dialog box's message handlers as you would the handlers in a CWindowImpl-derived class. If there is a message-specific return value, return it as an LRESULT. The returned LRESULT values are mapped by ATL for proper handling by the Windows dialog manager. For details, see the source code for CDialogImplBaseT::DialogProc in atlwin.h.

The following class implements a dialog box:

class CMyDialog : public CDialogImpl<CMyDialog>, ...
   enum { IDD = IDD_MYDIALOG };


   LRESULT OnInitDialog(UINT uMsg, WPARAM wParam, 
                        LPARAM lParam, BOOL& bHandled)
      // Do some initialization code
      return 1;