CDialogImpl Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CDialogImpl Class.
This class provides methods for creating a modal or modeless dialog box.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
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.
Members
Methods
| Create | Creates a modeless dialog box. |
| DestroyWindow | Destroys a modeless dialog box. |
| DoModal | Creates a modal dialog box. |
| EndDialog | Destroys a modal dialog box. |
CDialogImplBaseT Methods
| GetDialogProc | Returns the current dialog box procedure. |
| MapDialogRect | Maps the dialog-box units of the specified rectangle to screen units (pixels). |
| OnFinalMessage | Called after receiving the last message, typically WM_NCDESTROY. |
Static Functions
| DialogProc | Processes messages sent to the dialog box. |
| StartDialogProc | Called when the first message is received to process messages sent to the dialog box. |
Remarks
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.
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 about | See |
|---|---|
| Creating controls | ATL Tutorial |
| Using dialog boxes in ATL | ATL Window Classes |
| ATL Project Wizard | Creating an ATL Project |
| Dialog boxes | Dialog Boxes and subsequent topics in the Windows SDK |
Requirements
Header: atlwin.h
CDialogImpl::Create
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.
CDialogImpl::DestroyWindow
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.
CDialogImpl::DialogProc
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.
CDialogImpl::DoModal
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.
CDialogImpl::EndDialog
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.
Note
Do not call EndDialog to destroy a modeless dialog box. Call CWindow::DestroyWindow instead.
CDialogImpl::GetDialogProc
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.
CDialogImpl::MapDialogRect
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.
CDialogImpl::OnFinalMessage
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.
CDialogImpl::StartDialogProc
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.