CDialogImpl Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This class provides methods for creating a modal or modeless dialog box.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

 
template <class T,  
    class TBase = CWindow>  
    class ATL_NO_VTABLE CDialogImpl : public CDialogImplBaseT<TBase>  
 

Parameters

T
Your class, derived from CDialogImpl.

TBase
The base class of your new class. The default base class is CWindow.

Methods

CreateCreates a modeless dialog box.
DestroyWindowDestroys a modeless dialog box.
DoModalCreates a modal dialog box.
EndDialogDestroys a modal dialog box.

CDialogImplBaseT Methods

GetDialogProcReturns the current dialog box procedure.
MapDialogRectMaps the dialog-box units of the specified rectangle to screen units (pixels).
OnFinalMessageCalled after receiving the last message, typically WM_NCDESTROY.

Static Functions

DialogProcProcesses messages sent to the dialog box.
StartDialogProcCalled when the first message is received to process messages sent to the dialog box.

With CDialogImpl you can create a modal or modeless dialog box. CDialogImpl provides the dialog box procedure, which uses the default message map to direct messages to the appropriate handlers.

The base class destructor ~CWindowImplRoot ensures that the window is gone before destroying the object.

CDialogImpl derives from CDialogImplBaseT, which in turn derives from CWindowImplRoot.

System_CAPS_ICON_note.jpg Note

Your class must define an IDD member that specifies the dialog template resource ID. For example, the ATL Project Wizard automatically adds the following line to your class:

   enum { IDD = IDD_MYDLG };

where MyDlg is the Short name entered in the wizard's Names page.

For more information aboutSee
Creating controlsATL Tutorial
Using dialog boxes in ATLATL Window Classes
ATL Project WizardCreating an ATL Project
Dialog boxesDialog Boxes and subsequent topics in the Windows SDK

Header: atlwin.h

Creates a modeless dialog box.

HWND Create(HWND hWndParent, LPARAM dwInitParam = NULL);
HWND Create(HWND hWndParent, RECT&, LPARAM dwInitParam = NULL);

Parameters

hWndParent
[in] The handle to the owner window.

RECT& rect
[in] A RECT structure specifying the dialog's size and position.

dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Value

The handle to the newly created dialog box.

Remarks

This dialog box is automatically attached to the CDialogImpl object. To create a modal dialog box, call DoModal. The second override above is used only with CComControl.

Destroys a modeless dialog box.

BOOL DestroyWindow();

Return Value

TRUE if the dialog box was successfully destroyed; otherwise FALSE.

Remarks

Returns TRUE if the dialog box was successfully destroyed; otherwise FALSE.

This static function implements the dialog box procedure.

 
static LRESULT CALLBACK DialogProc(
    HWND hWnd,  
    UINT uMsg,  
    WPARAM wParam,  
    LPARAM lParam);

 

Parameters

hWnd
[in] The handle to the dialog box.

uMsg
[in] The message sent to the dialog box.

wParam
[in] Additional message-specific information.

lParam
[in] Additional message-specific information.

Return Value

TRUE if the message is processed; otherwise, FALSE.

Remarks

DialogProc uses the default message map to direct messages to the appropriate handlers.

You can override DialogProc to provide a different mechanism for handling messages.

Creates a modal dialog box.

INT_PTR DoModal(
  HWND hWndParent = ::GetActiveWindow(), 
  LPARAM dwInitParam = NULL);

Parameters

hWndParent
[in] The handle to the owner window. The default value is the return value of the GetActiveWindow Win32 function.

dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Value

If successful, the value of the nRetCode parameter specified in the call to EndDialog. Otherwise, -1.

Remarks

This dialog box is automatically attached to the CDialogImpl object.

To create a modeless dialog box, call Create.

Destroys a modal dialog box.

BOOL EndDialog(int nRetCode);

Parameters

nRetCode
[in] The value to be returned by CDialogImpl::DoModal.

Return Value

TRUE if the dialog box is destroyed; otherwise, FALSE.

Remarks

EndDialog must be called through the dialog procedure. After the dialog box is destroyed, Windows uses the value of nRetCode as the return value for DoModal, which created the dialog box.

System_CAPS_ICON_note.jpg Note

Do not call EndDialog to destroy a modeless dialog box. Call CWindow::DestroyWindow instead.

Returns DialogProc, the current dialog box procedure.

virtual WNDPROC GetDialogProc(); 

Return Value

The current dialog box procedure.

Remarks

Override this method to replace the dialog procedure with your own.

Converts (maps) the dialog-box units of the specified rectangle to screen units (pixels).

BOOL MapDialogRect(LPRECT lpRect); 

Parameters

lpRect
Points to a CRect object or RECT structure that is to receive the client coordinates of the update that encloses the update region.

Return Value

Nonzero if the update succeeds; 0 if the update fails. To get extended error information, call GetLastError.

Remarks

The function replaces the coordinates in the specified RECT structure with the converted coordinates, which allows the structure to be used to create a dialog box or position a control within a dialog box.

Called after receiving the last message (typically WM_NCDESTROY).

virtual void OnFinalMessage(HWND hWnd); 

Parameters

hWnd
[in] A handle to the window being destroyed.

Remarks

Note that if you want to automatically delete your object upon the window destruction, you can call delete this; here.

Called only once, when the first message is received, to process messages sent to the dialog box.

static LRESULT CALLBACK StartDialogProc(
    HWND hWnd,  
    UINT uMsg,  
    WPARAM wParam,  
    LPARAM lParam); 

Parameters

hWnd
[in] The handle to the dialog box.

uMsg
[in] The message sent to the dialog box.

wParam
[in] Additional message-specific information.

lParam
[in] Additional message-specific information.

Return Value

The window procedure.

Remarks

After the initial call to StartDialogProc, DialogProc is set as a dialog procedure, and further calls go there.

BEGIN_MSG_MAP
Class Overview

Show: