Composite Control Global Functions
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 Composite Control Global Functions.
These functions provide support for creating dialog boxes, and for creating, hosting and licensing ActiveX controls.
Important
The functions listed in the following table cannot be used in applications that execute in the Windows Runtime.
| AtlAxDialogBox | Creates a modal dialog box from a dialog template provided by the user. The resulting dialog box can contain ActiveX controls. |
| AtlAxCreateDialog | Creates a modeless dialog box from a dialog template provided by the user. The resulting dialog box can contain ActiveX controls. |
| AtlAxCreateControl | Creates an ActiveX control, initializes it, and hosts it in the specified window. |
| AtlAxCreateControlEx | Creates an ActiveX control, initializes it, hosts it in the specified window, and retrieves an interface pointer (or pointers) from the control. |
| AtlAxCreateControlLic | Creates a licensed ActiveX control, initializes it, and hosts it in the specified window. |
| AtlAxCreateControlLicEx | Creates a licensed ActiveX control, initializes it, hosts it in the specified window, and retrieves an interface pointer (or pointers) from the control. |
| AtlAxAttachControl | Attaches a previously created control to the specified window. |
| AtlAxGetHost | Used to obtain a direct interface pointer to the container for a specified window (if any), given its handle. |
| AtlAxGetControl | Used to obtain a direct interface pointer to the control contained inside a specified window (if any), given its handle. |
| AtlSetChildSite | Initializes the IUnknown of the child site. |
| AtlAxWinInit | Initializes the hosting code for AxWin objects. |
| AtlAxWinTerm | Uninitializes the hosting code for AxWin objects. |
| AtlGetObjectSourceInterface | Returns information about the default source interface of an object. |
AtlAxDialogBox
Creates a modal dialog box from a dialog template provided by the user.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI_(int) AtlAxDialogBox(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
Parameters
hInstance
[in] Identifies an instance of the module whose executable file contains the dialog box template.
lpTemplateName
[in] Identifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent
[in] Identifies the window that owns the dialog box.
lpDialogProc
[in] Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.
Return Value
One of the standard HRESULT values.
Remarks
To use AtlAxDialogBox with a dialog template that contains an ActiveX control, specify a valid CLSID, APPID or URL string as the text field of the CONTROL section of the dialog resource, along with "AtlAxWin80" as the class name field under the same section. The following demonstrates what a valid CONTROL section might look like:
CONTROL "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
"AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100
For more information on editing resource scripts, see How to: Open a Resource Script File in Text Format. For more information on control resource-definition statements, see Common Control Parameters under Windows SDK*: SDK Tools*.
For more information on dialog boxes in general, refer to DialogBox and CreateDialogParam in the Windows SDK.
AtlAxCreateDialog
Creates a modeless dialog box from a dialog template provided by the user.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI_(HWND) AtlAxCreateDialog(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
Parameters
hInstance
[in] Identifies an instance of the module whose executable file contains the dialog box template.
lpTemplateName
[in] Identifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent
[in] Identifies the window that owns the dialog box.
lpDialogProc
[in] Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.
Return Value
One of the standard HRESULT values.
Remarks
The resulting dialog box can contain ActiveX controls.
See CreateDialog and CreateDialogParam in the Windows SDK.
AtlAxCreateControl
Creates an ActiveX control, initializes it, and hosts it in the specified window.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxCreateControl(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer);
Parameters
lpszName
A pointer to a string to be passed to the control. Must be formatted in one of the following ways:
A ProgID such as "MSCAL.Calendar.7"
A CLSID such as "{8E27C92B-1264-101C-8A2F-040224009C02}"
A URL such as "https://www.microsoft.com"
A reference to an Active document such as "file://\\Documents\MyDoc.doc"
A fragment of HTML such as "MSHTML:<HTML><BODY>This is a line of text</BODY></HTML>"
Note
"MSHTML:" must precede the HTML fragment so that it is designated as being an MSHTML stream.
hWnd
[in] Handle to the window that the control will be attached to.
pStream
[in] A pointer to a stream that is used to initialize the properties of the control. Can be NULL.
ppUnkContainer
[out] The address of a pointer that will receive the IUnknown of the container. Can be NULL.
Return Value
One of the standard HRESULT values.
Remarks
This global function gives you the same result as calling AtlAxCreateControlEx( lpszName, hWnd, pStream, NULL, NULL, NULL, NULL );.
To create a licensed ActiveX control, see AtlAxCreateControlLic.
AtlAxCreateControlEx
Creates an ActiveX control, initializes it, and hosts it in the specified window. An interface pointer and event sink for the new control can also be created.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxCreateControlEx(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
IUnknown** ppUnkControl,
REFIID iidSink = IID_NULL,
IUnknown* punkSink = NULL);
Parameters
lpszName
A pointer to a string to be passed to the control. Must be formatted in one of the following ways:
A ProgID such as "MSCAL.Calendar.7"
A CLSID such as "{8E27C92B-1264-101C-8A2F-040224009C02}"
A URL such as "https://www.microsoft.com"
A reference to an Active document such as "file://\\Documents\MyDoc.doc"
A fragment of HTML such as "MSHTML:<HTML><BODY>This is a line of text</BODY></HTML>"
Note
"MSHTML:" must precede the HTML fragment so that it is designated as being an MSHTML stream.
hWnd
[in] Handle to the window that the control will be attached to.
pStream
[in] A pointer to a stream that is used to initialize the properties of the control. Can be NULL.
ppUnkContainer
[out] The address of a pointer that will receive the IUnknown of the container. Can be NULL.
ppUnkControl
[out] The address of a pointer that will receive the IUnknown of the created control. Can be NULL.
iidSink
The interface identifier of an outgoing interface on the contained object.
punkSink
A pointer to the IUnknown interface of the sink object to be connected to the connection point specified by iidSink on the contained object after the contained object has been successfully created.
Return Value
One of the standard HRESULT values.
Remarks
AtlAxCreateControlEx is similar to AtlAxCreateControl but also allows you to receive an interface pointer to the newly created control and set up an event sink to receive events fired by the control.
To create a licensed ActiveX control, see AtlAxCreateControlLicEx.
AtlAxCreateControlLic
Creates a licensed ActiveX control, initializes it, and hosts it in the specified window.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxCreateControlLic(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
BSTR bstrLic = NULL);
Parameters
lpszName
A pointer to a string to be passed to the control. Must be formatted in one of the following ways:
A ProgID such as "MSCAL.Calendar.7"
A CLSID such as "{8E27C92B-1264-101C-8A2F-040224009C02}"
A URL such as "https://www.microsoft.com"
A reference to an Active document such as "file://\\Documents\MyDoc.doc"
A fragment of HTML such as "MSHTML:<HTML><BODY>This is a line of text</BODY></HTML>"
Note
"MSHTML:" must precede the HTML fragment so that it is designated as being an MSHTML stream.
hWnd
Handle to the window that the control will be attached to.
pStream
A pointer to a stream that is used to initialize the properties of the control. Can be NULL.
ppUnkContainer
The address of a pointer that will receive the IUnknown of the container. Can be NULL.
bstrLic
The BSTR containing the license for the control.
Return Value
One of the standard HRESULT values.
Example
See Hosting ActiveX Controls Using ATL AXHost for a sample of how to use AtlAxCreateControlLic.
AtlAxCreateControlLicEx
Creates a licensed ActiveX control, initializes it, and hosts it in the specified window. An interface pointer and event sink for the new control can also be created.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxCreateControlLicEx(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
IUnknown** ppUnkControl,
REFIID iidSink = IID_NULL,
IUnknown* punkSink = NULL,
BSTR bstrLic = NULL);
Parameters
lpszName
A pointer to a string to be passed to the control. Must be formatted in one of the following ways:
A ProgID such as "MSCAL.Calendar.7"
A CLSID such as "{8E27C92B-1264-101C-8A2F-040224009C02}"
A URL such as "https://www.microsoft.com"
A reference to an Active document such as "file://\\Documents\MyDoc.doc"
A fragment of HTML such as "MSHTML:<HTML><BODY>This is a line of text</BODY></HTML>"
Note
"MSHTML:" must precede the HTML fragment so that it is designated as being an MSHTML stream.
hWnd
Handle to the window that the control will be attached to.
pStream
A pointer to a stream that is used to initialize the properties of the control. Can be NULL.
ppUnkContainer
The address of a pointer that will receive the IUnknown of the container. Can be NULL.
ppUnkControl
[out] The address of a pointer that will receive the IUnknown of the created control. Can be NULL.
iidSink
The interface identifier of an outgoing interface on the contained object.
punkSink
A pointer to the IUnknown interface of the sink object to be connected to the connection point specified by iidSink on the contained object after the contained object has been successfully created.
bstrLic
The BSTR containing the license for the control.
Return Value
One of the standard HRESULT values.
Remarks
AtlAxCreateControlLicEx is similar to AtlAxCreateControlLic but also allows you to receive an interface pointer to the newly created control and set up an event sink to receive events fired by the control.
Example
See Hosting ActiveX Controls Using ATL AXHost for a sample of how to use AtlAxCreateControlLicEx.
AtlAxAttachControl
Attaches a previously created control to the specified window.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxAttachControl(
IUnknown* pControl,
HWND hWnd,
IUnknown** ppUnkContainer);
Parameters
pControl
[in] A pointer to the IUnknown of the control.
hWnd
[in] Handle to the window that will host the control.
ppUnkContainer
[out] A pointer to a pointer to the IUnknown of the container object.
Return Value
One of the standard HRESULT values.
Remarks
Use AtlAxCreateControlEx and AtlAxCreateControl to simultaneously create and attach a control.
Note
The control object being attached must be correctly initialized before calling AtlAxAttachControl.
AtlAxGetHost
Obtains a direct interface pointer to the container for a specified window (if any), given its handle.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);
Parameters
h
[in] A handle to the window that is hosting the control.
pp
[out] The IUnknown of the container of the control.
Return Value
One of the standard HRESULT values.
AtlAxGetControl
Obtains a direct interface pointer to the control contained inside a specified window given its handle.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);
Parameters
h
[in] A handle to the window that is hosting the control.
pp
[out] The IUnknown of the control being hosted.
Return Value
One of the standard HRESULT values.
AtlSetChildSite
Call this function to set the site of the child object to the IUnknown of the parent object.
Important
This function cannot be used in applications that execute in the Windows Runtime.
HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);
Parameters
punkChild
[in] A pointer to the IUnknown interface of the child.
punkParent
[in] A pointer to the IUnknown interface of the parent.
Return Value
A standard HRESULT value.
AtlAxWinInit
This function initializes ATL's control hosting code by registering the "AtlAxWin80" and "AtlAxWinLic80" window classes plus a couple of custom window messages.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI_(BOOL) AtlAxWinInit();
Return Value
Nonzero if the initialization of the control hosting code was successful; otherwise FALSE.
Remarks
This function must be called before using the ATL control hosting API. Following a call to this function, the "AtlAxWin" window class can be used in calls to CreateWindow or CreateWindowEx, as described in the Windows SDK.
AtlAxWinTerm
This function uninitializes ATL's control hosting code by unregistering the "AtlAxWin80" and "AtlAxWinLic80" window classes.
Important
This function cannot be used in applications that execute in the Windows Runtime.
inline BOOL AtlAxWinTerm();
Return Value
Always returns TRUE.
Remarks
This function simply calls UnregisterClass as described in the Windows SDK.
Call this function to clean up after all existing host windows have been destroyed if you called AtlAxWinInit and you no longer need to create host windows. If you don't call this function, the window class will be unregistered automatically when the process terminates.
AtlGetObjectSourceInterface
Call this function to retrieve information about the default source interface of an object.
Important
This function cannot be used in applications that execute in the Windows Runtime.
ATLAPI AtlGetObjectSourceInterface(
IUnknown* punkObj,
GUID* plibid,
IID* piid,
unsigned short* pdwMajor,
unsigned short* pdwMinor);
Parameters
punkObj
[in] A pointer to the object for which information is to be returned.
plibid
[out] A pointer to the LIBID of the type library containing the definition of the source interface.
piid
[out] A pointer to the interface ID of the object's default source interface.
pdwMajor
[out] A pointer to the major version number of the type library containing the definition of the source interface.
pdwMinor
[out] A pointer to the minor version number of the type library containing the definition of the source interface.
Return Value
A standard HRESULT value.
Remarks
AtlGetObjectSourceInterface can provide you with the interface ID of the default source interface, along with the LIBID and major and minor version numbers of the type library describing that interface.
Note
For this function to successfully retrieve the requested information, the object represented by punkObj must implement IDispatch (and return type information through IDispatch::GetTypeInfo) plus it must also implement either IProvideClassInfo2 or IPersist. The type information for the source interface must be in the same type library as the type information for IDispatch.
Example
The example below shows how you might define an event sink class, CEasySink, that reduces the number of template arguments that you can pass to IDispEventImpl to the bare essentials. EasyAdvise and EasyUnadvise use AtlGetObjectSourceInterface to initialize the IDispEventImpl members before calling DispEventAdvise or DispEventUnadvise.
template <UINT nID, class T>
class CEasySink : public IDispEventImpl<nID, T>
{
public:
HRESULT EasyAdvise(IUnknown* pUnk)
{
AtlGetObjectSourceInterface(pUnk,
&m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
return DispEventAdvise(pUnk, &m_iid);
}
HRESULT EasyUnadvise(IUnknown* pUnk)
{
AtlGetObjectSourceInterface(pUnk,
&m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
return DispEventUnadvise(pUnk, &m_iid);
}
};