复合控件全局函数

项目
04/03/2023

这些函数支持创建对话框，以及创建、托管和许可 ActiveX 控件。

重要

下表中列出的函数不能在 Windows 运行时执行的应用程序中使用。

Function	说明
AtlAxDialogBox	从用户提供的对话框模板创建模式对话框。生成的对话框可以包含 ActiveX 控件。
AtlAxCreateDialog	从用户提供的对话框模板创建无模式对话框。生成的对话框可以包含 ActiveX 控件。
AtlAxCreateControl	创建 ActiveX 控件，初始化它并在指定窗口中承载它。
AtlAxCreateControlEx	创建一个 ActiveX 控件，对其进行初始化，将其托管在指定的窗口中，并从控件中检索一个（或多个）接口指针。
AtlAxCreateControlLic	创建授权的 ActiveX 控件，初始化它并在指定窗口中承载它。
AtlAxCreateControlLicEx	创建一个许可的 ActiveX 控件，对其进行初始化，将其托管在指定的窗口中，并从控件中检索一个接口指针（或多个指针）。
AtlAxAttachControl	将以前创建的控件附加到指定窗口。
AtlAxGetHost	用于获取指向指定窗口（如果有）的容器的直接接口指针（在给定容器的句柄的情况下）。
AtlAxGetControl	用于获取指向指定窗口（如果有）中包含的控件的直接接口指针（在给定容器的句柄的情况下）。
AtlSetChildSite	初始化子站点的 `IUnknown`。
AtlAxWinInit	初始化 AxWin 对象的托管代码。
AtlAxWinTerm	取消初始化 AxWin 对象的托管代码。
AtlGetObjectSourceInterface	返回有关对象的默认源接口的信息。

要求

标头：atlhost.h

AtlAxDialogBox

从用户提供的对话框模板创建模式对话框。

ATLAPI_(int) AtlAxDialogBox(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

参数

hInstance
[in] 标识其可执行文件包含对话框模板的模块实例。

lpTemplateName
[in] 标识对话框模板。此参数是指向指定对话框模板名称的以空字符结尾的字符串的指针，或者是指定对话框模板的资源标识符的整数值。如果参数指定了资源标识符，则其高位字必须为零，其低位字必须包含该标识符。你可以使用 MAKEINTRESOURCE 宏来创建此值。

hWndParent
[in] 标识拥有该对话框的窗口。

lpDialogProc
[in] 指向对话框过程。有关对话框过程的详细信息，请参阅 DialogProc。

dwInitParam
[in] 在 WM_INITDIALOG 消息的 lParam 参数中指定要传递到对话框的值。

返回值

标准 HRESULT 值之一。

备注

要将 AtlAxDialogBox 与包含 ActiveX 控件的对话框模板一起使用，请将有效的 CLSID、APPID 或 URL 字符串指定为对话框资源的 CONTROL 部分的文本字段，同时将“AtlAxWin80”指定为同一部分下的 class name 字段。下面演示了一个有效的 CONTROL 部分可能包含的内容：

CONTROL    "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
    "AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100

有关编辑资源脚本的更多信息，请参阅操作说明：创建资源。有关控制资源定义语句的详细信息，请参阅“Windows SDK：SDK 工具”中的通用控制参数。

有关对话框的更多信息，请参阅 Windows SDK 中的 DialogBox 和 CreateDialogParam。

AtlAxCreateDialog

从用户提供的对话框模板创建无模式对话框。

ATLAPI_(HWND) AtlAxCreateDialog(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

参数

hInstance
[in] 标识其可执行文件包含对话框模板的模块实例。

hWndParent
[in] 标识拥有该对话框的窗口。

lpDialogProc
[in] 指向对话框过程。有关对话框过程的详细信息，请参阅 DialogProc。

dwInitParam
[in] 在 WM_INITDIALOG 消息的 lParam 参数中指定要传递到对话框的值。

返回值

标准 HRESULT 值之一。

备注

生成的对话框可以包含 ActiveX 控件。

请参阅 Windows SDK 中的 CreateDialog 和 CreateDialogParam。

AtlAxCreateControl

创建 ActiveX 控件，初始化它并在指定窗口中承载它。

ATLAPI AtlAxCreateControl(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer);

参数

lpszName
指向要传递给控件的字符串的指针。必须采用以下方法之一进行格式化：

ProgID，例如 "MSCAL.Calendar.7"
CLSID，例如 "{8E27C92B-1264-101C-8A2F-040224009C02}"
URL，例如 "<https://www.microsoft.com>"
对 Active 文档的引用，例如 "file://\\\Documents\MyDoc.doc"
HTML 的片段，例如 "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

注意

"MSHTML:" 必须在 HTML 片段之前，以便将其指定为 MSHTML 流。

hWnd
[in] 控件将附加到的窗口的句柄。

pStream
[in] 指向用于初始化控件属性的流的指针。可以为 NULL。

ppUnkContainer
[out] 将接收容器的 IUnknown 的指针的地址。可以为 NULL。

返回值

标准 HRESULT 值之一。

注解

此全局函数产生的结果等同于你调用 AtlAxCreateControlEx（lpszName、hWnd、pStream、NULL、NULL、NULL、NULL）。

要创建许可的 ActiveX 控件，请参阅 AtlAxCreateControlLic。

AtlAxCreateControlEx

创建 ActiveX 控件，初始化它并在指定窗口中承载它。也可以创建新控件的接口指针和事件接收器。

ATLAPI AtlAxCreateControlEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL);

参数

lpszName
指向要传递给控件的字符串的指针。必须采用以下方法之一进行格式化：

ProgID，例如 "MSCAL.Calendar.7"
CLSID，例如 "{8E27C92B-1264-101C-8A2F-040224009C02}"
URL，例如 "<https://www.microsoft.com>"
对 Active 文档的引用，例如 "file://\\\Documents\MyDoc.doc"
HTML 的片段，例如 "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

注意

"MSHTML:" 必须在 HTML 片段之前，以便将其指定为 MSHTML 流。

hWnd
[in] 控件将附加到的窗口的句柄。

pStream
[in] 指向用于初始化控件属性的流的指针。可以为 NULL。

ppUnkContainer
[out] 将接收容器的 IUnknown 的指针的地址。可以为 NULL。

ppUnkControl
[out] 将接收所创建控件 IUnknown 的指针的地址。可以为 NULL。

iidSink
所包含对象的传出接口的接口标识符。

punkSink
一个指向接收器对象的 IUnknown 接口的指针，在被包含对象成功创建后，该接口即会连接到被包含对象上由 iidSink 指定的连接点。

返回值

标准 HRESULT 值之一。

注解

AtlAxCreateControlEx 与 AtlAxCreateControl 类似，但也允许你接收指向新创建控件的接口指针并设置事件接收器以接收控件触发的事件。

要创建许可的 ActiveX 控件，请参阅 AtlAxCreateControlLicEx。

AtlAxCreateControlLic

创建授权的 ActiveX 控件，初始化它并在指定窗口中承载它。

ATLAPI AtlAxCreateControlLic(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    BSTR bstrLic = NULL);

参数

lpszName
指向要传递给控件的字符串的指针。必须采用以下方法之一进行格式化：

ProgID，例如 "MSCAL.Calendar.7"
CLSID，例如 "{8E27C92B-1264-101C-8A2F-040224009C02}"
URL，例如 "<https://www.microsoft.com>"
对 Active 文档的引用，例如 "file://\\\Documents\MyDoc.doc"
HTML 的片段，例如 "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

注意

"MSHTML:" 必须在 HTML 片段之前，以便将其指定为 MSHTML 流。

hWnd
控件将附加到的窗口的句柄。

pStream
指向用于初始化控件属性的流的指针。可以为 NULL。

ppUnkContainer
将接收容器的 IUnknown 的指针的地址。可以为 NULL。

bstrLic
包含控件许可证的 BSTR。

返回值

标准 HRESULT 值之一。

示例

有关如何使用 AtlAxCreateControlLic 的示例，请参阅使用 ATL AXHost 托管 ActiveX 控件。

AtlAxCreateControlLicEx

创建授权的 ActiveX 控件，初始化它并在指定窗口中承载它。也可以创建新控件的接口指针和事件接收器。

ATLAPI AtlAxCreateControlLicEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL,
    BSTR bstrLic = NULL);

参数

lpszName
指向要传递给控件的字符串的指针。必须采用以下方法之一进行格式化：

ProgID，例如 "MSCAL.Calendar.7"
CLSID，例如 "{8E27C92B-1264-101C-8A2F-040224009C02}"
URL，例如 "<https://www.microsoft.com>"
对 Active 文档的引用，例如 "file://\\\Documents\MyDoc.doc"
HTML 的片段，例如 "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

注意

"MSHTML:" 必须在 HTML 片段之前，以便将其指定为 MSHTML 流。

hWnd
控件将附加到的窗口的句柄。

pStream
指向用于初始化控件属性的流的指针。可以为 NULL。

ppUnkContainer
将接收容器的 IUnknown 的指针的地址。可以为 NULL。

ppUnkControl
[out] 将接收所创建控件 IUnknown 的指针的地址。可以为 NULL。

iidSink
所包含对象的传出接口的接口标识符。

punkSink
一个指向接收器对象的 IUnknown 接口的指针，在被包含对象成功创建后，该接口即会连接到被包含对象上由 iidSink 指定的连接点。

bstrLic
包含控件许可证的 BSTR。

返回值

标准 HRESULT 值之一。

备注

AtlAxCreateControlLicEx 与 AtlAxCreateControlLic 类似，但也允许你接收指向新创建控件的接口指针并设置事件接收器以接收控件触发的事件。

示例

有关如何使用 AtlAxCreateControlLicEx 的示例，请参阅使用 ATL AXHost 托管 ActiveX 控件。

AtlAxAttachControl

将以前创建的控件附加到指定窗口。

ATLAPI AtlAxAttachControl(
    IUnknown* pControl,
    HWND hWnd,
    IUnknown** ppUnkContainer);

参数

pControl
[in] 指向控件的 IUnknown 的指针。

hWnd
[in] 将托管控件的窗口的句柄。

ppUnkContainer
[out] 一个指针，指向容器对象的 IUnknown 的指针。

返回值

标准 HRESULT 值之一。

备注

使用 AtlAxCreateControlEx 和 AtlAxCreateControl 同时创建和附加控件。

注意

在调用 AtlAxAttachControl 之前必须正确初始化所要附加的控件对象。

AtlAxGetHost

获取指向指定窗口（如果有）的容器的直接接口指针（在给定容器的句柄的情况下）。

ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);

参数

h
[in] 托管控件的窗口的句柄。

pp
[out] 控件的容器的 IUnknown。

返回值

标准 HRESULT 值之一。

AtlAxGetControl

获取指向包含在指定窗口内的控件的直接接口指针（在给定控件的句柄的情况下）。

ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);

参数

h
[in] 托管控件的窗口的句柄。

pp
[out] 被托管的控件的 IUnknown。

返回值

标准 HRESULT 值之一。

AtlSetChildSite

调用此函数可将子对象的站点设置为父对象的 IUnknown。

HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);

参数

punkChild
[in] 一个指针，指向子级的 IUnknown 接口。

punkParent
[in] 一个指针，指向父级的 IUnknown 接口。

返回值

标准 HRESULT 值。

AtlAxWinInit

此函数通过注册“AtlAxWin80”和“AtlAxWinLic80”窗口类以及一些自定义窗口消息来初始化 ATL 的控件承载代码。

ATLAPI_(BOOL) AtlAxWinInit();

返回值

如果控件托管代码的初始化成功，则为非零；否则为 FALSE。

注解

在使用 ATL 控件托管 API 之前必须调用此函数。调用此函数后，可以在调用 CreateWindow 或 CreateWindowEx 时使用“AtlAxWin”窗口类，如 Windows SDK 中所述。

AtlAxWinTerm

此函数通过注销“AtlAxWin80”和“AtlAxWinLic80”窗口类来取消初始化 ATL 的控件承载代码。

inline BOOL AtlAxWinTerm();

返回值

始终返回 TRUE。

备注

此函数仅调用 UnregisterClass，如 Windows SDK 中所述。

如果你调用了 AtlAxWinInit 并且不再需要创建主机窗口，则在所有现有主机窗口都被销毁后调用此函数进行清理。如果不调用该函数，则进程终止后窗口类将被自动注销。

AtlGetObjectSourceInterface

调用此函数可检索有关对象的默认源接口的信息。

ATLAPI AtlGetObjectSourceInterface(
    IUnknown* punkObj,
    GUID* plibid,
    IID* piid,
    unsigned short* pdwMajor,
    unsigned short* pdwMinor);

参数

punkObj
[in] 一个指针，指向要为其返回信息的对象。

plibid
[out] 一个指针，指向包含源接口定义的类型库的 LIBID。

piid
[out] 一个指针，指向对象默认源接口的接口 ID。

pdwMajor
[out] 一个指针，指向包含源接口定义的类型库的主要版本号。

pdwMinor
[out] 一个指针，指向包含源接口定义的类型库的次要版本号。

返回值

标准 HRESULT 值。

注解

AtlGetObjectSourceInterface 可以为你提供默认源接口的接口 ID，以及描述该接口的类型库的 LIBID 和主要和次要版本号。

注意

要使此函数成功检索请求的信息，由 punkObj 表示的对象必须实现 IDispatch（并通过 IDispatch::GetTypeInfo 返回类型信息），而且它还必须实现 IProvideClassInfo2 或 IPersist。源接口的类型信息必须与 IDispatch 的类型信息在同一个类型库中。

示例

下面的示例展示了如何定义一个事件接收器类 CEasySink，此类可以将能够传递给 IDispEventImpl 的模板参数数量减少到最基本数量。 EasyAdvise 和 EasyUnadvise 在调用 DispEventAdvise 或 DispEventUnadvise 之前，使用 AtlGetObjectSourceInterface 初始化 IDispEventImpl 成员。

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);
   }
};

另请参阅

函数
 复合控件宏

通过

复合控件全局函数

要求

AtlAxDialogBox

参数

返回值

备注

AtlAxCreateDialog

参数

返回值

备注

AtlAxCreateControl

参数

返回值

注解

AtlAxCreateControlEx

参数

返回值

注解

AtlAxCreateControlLic

参数

返回值

示例

AtlAxCreateControlLicEx

参数

返回值

备注

示例

AtlAxAttachControl

参数

返回值

备注

AtlAxGetHost

参数

返回值

AtlAxGetControl

参数

返回值

AtlSetChildSite

参数

返回值

AtlAxWinInit

返回值

注解

AtlAxWinTerm

返回值

备注

AtlGetObjectSourceInterface

参数

返回值

注解

示例

另请参阅

反馈

其他资源