Implementing a Dialog Box

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

Adding a Dialog Box with the ATL Object Wizard

In the ATL Object Wizard (Insert menu, New ATL Object command), highlight the miscellaneous category in the left pane, then double-click the Dialog object in the right pane to add a dialog box to your ATL project. Fill in the ATL Object Wizard Properties dialog box as appropriate and click OK. The ATL Object Wizard adds a class derived from CAxDialogImpl to your project, and opens the resource editor with your dialog box template.

Note   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 ClassView in the same way as to an MFC class. In ClassView, right-click the class and choose Add Windows Message Handler to open the New Windows Message and Event Handlers dialog box. For more information, see Adding a Message Handler.

To open the New Windows Message and Event Handlers dialog box from the dialog box template, right-click a control in the dialog box template and choose the Events command from the shortcut menu. In an ATL project, the dialog box class is highlighted in the Class or object to handle box; whereas, for an MFC project, the control is highlighted.

Adding a Dialog Box Manually

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.

Note   When you create a dialog box using the ATL Object 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.

If your dialog box object contains ActiveX controls, and you are handling events from these controls, you will need to advise and unadvise all ActiveX control interfaces. This can be done by adding the following line of code to your InitDialog function:

AtlAdviseSinkMap(pMyDlg, TRUE);

To unadvise any ActiveX controls, add the following line of code to your EndDialog function (or the function invoked upon termination of your dialog box object):

AtlAdviseSinkMap(pMyDlg, FALSE);

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.

Example

The following class implements a dialog box:

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

   BEGIN_MSG_MAP(CMyDialog)
      MESSAGE_HANDLER(WM_INITDIALOG, OnInitDialog)
   END_MSG_MAP()

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