CAxDialogImpl 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 CAxDialogImpl Class.
This class implements a dialog box (modal or modeless) that hosts ActiveX controls.
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 CAxDialogImpl : public CDialogImplBaseT<TBase>
Parameters
T
Your class, derived from CAxDialogImpl.
TBase
The base window class for CDialogImplBaseT.
Members
Public Methods
| Name | Description |
|---|---|
| CAxDialogImpl::AdviseSinkMap | Call this method to advise or unadvise all entries in the object's sink map event map. |
| CAxDialogImpl::Create | Call this method to create a modeless dialog box. |
| CAxDialogImpl::DestroyWindow | Call this method to destroy a modeless dialog box. |
| CAxDialogImpl::DoModal | Call this method to create a modal dialog box. |
| CAxDialogImpl::EndDialog | Call this method to destroy a modal dialog box. |
| CAxDialogImpl::GetDialogProc | Call this method to get a pointer to the DialogProc callback function. |
| CAxDialogImpl::GetIDD | Call this method to get the dialog template resource ID |
| CAxDialogImpl::IsDialogMessage | Call this method to determine whether a message is intended for this dialog box and, if it is, process the message. |
Protected Data Members
| Name | Description |
|---|---|
| CAxDialogImpl::m_bModal | A variable that exists only in debug builds and is set to true if the dialog box is modal. |
Remarks
CAxDialogImpl allows you to create a modal or modeless dialog box. CAxDialogImpl provides the dialog box procedure, which uses the default message map to direct messages to the appropriate handlers.
CAxDialogImpl derives from CDialogImplBaseT, which in turn derives from TBase (by default, CWindow) and CMessageMap.
Your class must define an IDD member that specifies the dialog template resource ID. For example, adding an ATL Dialog object using the Add Class dialog box automatically adds the following line to your class:
enum { IDD = IDD_MYDLG };
where MyDialog is the Short name entered in the ATL Dialog Wizard.
See Implementing a Dialog Box for more information.
Note that an ActiveX control on a modal dialog box created with CAxDialogImpl will not support accelerator keys. To support accelerator keys on a dialog box created with CAxDialogImpl, create a modeless dialog box and, using your own message loop, use CAxDialogImpl::IsDialogMessage after getting a message from the queue to handle an accelerator key.
For more information on CAxDialogImpl, see ATL Control Containment FAQ.
Inheritance Hierarchy
TBase
CWindowImplRoot
CDialogImplBaseT
CAxDialogImpl
Requirements
Header: atlwin.h
CAxDialogImpl::AdviseSinkMap
Call this method to advise or unadvise all entries in the object's sink map event map.
HRESULT AdviseSinkMap(bool bAdvise);
Parameters
bAdvise
Set to true if all sink entries are to be advised; false if all sink entries are to be unadvised.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
CAxDialogImpl::Create
Call this method to create 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.
dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.
RECT&
This parameter is not used. This parameter is passed in by CComControl.
Return Value
The handle to the newly created dialog box.
Remarks
This dialog box is automatically attached to the CAxDialogImpl object. To create a modal dialog box, call DoModal.
The second override is provided only so dialog boxes can be used with CComControl.
CAxDialogImpl::DestroyWindow
Call this method to destroy a modeless dialog box.
BOOL DestroyWindow();
Return Value
TRUE if the window is successfully destroyed; otherwise FALSE.
Remarks
Do not call DestroyWindow to destroy a modal dialog box. Call EndDialog instead.
CAxDialogImpl::DoModal
Call this method to create 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 CAxDialogImpl object.
To create a modeless dialog box, call Create.
CAxDialogImpl::EndDialog
Call this method to destroy a modal dialog box.
BOOL EndDialog(int nRetCode);
Parameters
nRetCode
[in] The value to be returned by DoModal.
Return Value
TRUE if the dialog box is destroyed; otherwise, FALSE.
Remarks
EndDialog must be called through the dialog box 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 DestroyWindow instead.
CAxDialogImpl::GetDialogProc
Call this method to get a pointer to the DialogProc callback function.
virtual DLGPROC GetDialogProc();
Return Value
Returns a pointer to the DialogProc callback function.
Remarks
The DialogProc function is an application-defined callback function.
CAxDialogImpl::GetIDD
Call this method to get the dialog template resource ID.
int GetIDD();
Return Value
Returns the dialog template resource ID.
CAxDialogImpl::IsDialogMessage
Call this method to determine whether a message is intended for this dialog box and, if it is, process the message.
BOOL IsDialogMessage(LPMSG pMsg);
Parameters
pMsg
Pointer to a MSG structure that contains the message to be checked.
Return Value
Returns TRUE if the message has been processed, FALSE otherwise.
Remarks
This method is intended to be called from within a message loop.
CAxDialogImpl::m_bModal
A variable that exists only in debug builds and is set to true if the dialog box is modal.
bool m_bModal;