Developers Workshop to COM and ATL 3.0

ATL's Support for Dialog Box Development

With your current understanding of how ATL "does windows," you will find the process of building a dialog box is relatively trivial. ATL supplies a total of three dialog-based templates, each of which provides a different level of boilerplate functionality. Here is a high-level overview of each dialog template:

Working with CSimpleDialog<>

There are times when you need to display a dialog box with more flair than a simple call to MessageBox(), but less flair than a full-blown dialog used to gather user input. The classic example is an About box. You might need to fashion such a dialog, complete with your company logo, a few blocks of static text (tech support, URL, 800 number, and so on) but not much else. By this, I mean no user input is required beyond closing the dialog.

For these simple dialogs, ATL provides the aptly named CSimpleDialog<> template. The only required parameter for this template is the resource ID of the dialog template you have constructed using the Visual Studio resource editors. A second default parameter determines if the dialog should be centered on the screen. Once you create an instance of this class, you make a single call to DoModal(), and your dialog magically appears centered on the desktop.

Assume we have some function which is responsible for showing an About box for your ATL application, which we will call AboutBox(). To grab a dialog resource template, you simply go under the Insert | Resource menu selection and choose the type of dialog box you wish to insert into your project.

In Figure 13-6, we will insert a simple Dialog resource type to bring in a vanilla flavored box, with a default OK and Cancel button. Once you select New, you will be provided with a dialog template to which you may add whatever images or text you desire using the Visual Studio editing tools. Let's say you have built your About box, and assigned it the identifier IDD_ABOUTBOX. To launch this dialog using CSimpleDialog<>, just send it the dialog ID as your template parameter:

Figure 13-6: Inserting a new Dialog resource.

// Simple dialogs require no user input beyond dismissing the box. // Don't forget to include your project's resource file to get the definition // of IDD_ABOUTBOX. #include "resource.h" void CMyWindow::AboutBox() { CSimpleDialog< IDD_ABOUTBOX> dlg; dlg.DoModal(); }

Examining CSimpleDialog<>

The definition of CSimpleDialog<> makes a call to the API DialogBox() function within its implementation of DoModal(). Beyond this, a message map entry has been made for WM_INITDIALOG. This Windows message is sent just before the dialog is made visible to the end user. The default implementation simply centers the dialog on the screen. The final method of note is OnCloseCmd(), which closes the dialog using EndDialog(). This is a shared function called when a WM_COMMAND message is sent in response to the OK or Cancel button being clicked (with some help from COMMAND_RANGE_HANDLER):

// The definition of CSimpleDialog<>. template <WORD t_wDlgTemplateID, BOOL t_bCenter = TRUE> class CSimpleDialog : public CDialogImplBase { public: int DoModal(HWND hWndParent = ::GetActiveWindow()) { ... int nRet = ::DialogBox(_Module.GetResourceInstance(), MAKEINTRESOURCE(t_wDlgTemplateID), hWndParent, (DLGPROC)StartDialogProc); m_hWnd = NULL; return nRet; } BEGIN_MSG_MAP(thisClass) MESSAGE_HANDLER(WM_INITDIALOG, OnInitDialog) COMMAND_RANGE_HANDLER(IDOK, IDNO, OnCloseCmd) END_MSG_MAP() LRESULT OnInitDialog(UINT /*uMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/, BOOL& /*bHandled*/) { if(t_bCenter) CenterWindow(GetParent()); return TRUE; } LRESULT OnCloseCmd(WORD /*wNotifyCode*/, WORD wID, HWND /*hWndCtl*/, BOOL& /*bHandled*/) { ::EndDialog(m_hWnd, wID); return 0; } };

Now that we can display a dialog box with no user interaction, we are ready to examine how to create a more elaborate dialog box using CDialogImpl<>.