複合控制項全域函式

發行項
08/03/2024

這些函式支援建立對話框，以及建立、裝載和授權 ActiveX 控制件。

重要

下表所列的函式不能用於在 Windows 執行階段中執行的應用程式。

函式	描述
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]識別對話框範本。這個參數是 Null 終止字元字串的指標，指定對話框範本的名稱，或是指定對話框範本之資源識別碼的整數值。如果參數指定資源標識元，則其高序字必須是零，且低序字必須包含標識符。您可以使用 MAKEINTRESOURCE 巨集來建立此值。

hWndParent
[in]識別擁有對話框的視窗。

lpDialogProc
[in]指向對話框程式。如需對話框程式的詳細資訊，請參閱 DialogProc。

dwInitParam
[in]指定要傳遞至WM_INITDIALOG訊息之 lParam 參數中的對話框的值。

傳回值

其中一個標準 HRESULT 值。

備註

若要搭配包含 ActiveX 控件的對話框範本使用AtlAxDialogBox，請將有效的 CLSID、APPID 或 URL 字串指定為對話框資源的 CONTROL 區段文字欄位，以及 “AtlAxWin80” 作為相同區段下的類別名稱字段。下列示範有效的 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>"
使用中文件的參考，例如 "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、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>"
使用中文件的參考，例如 "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
成功建立自主物件之後，要連接到自主物件上 iidSink 所指定之連接點之接收物件的介面指標IUnknown。

傳回值

其中一個標準 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>"
使用中文件的參考，例如 "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>"
使用中文件的參考，例如 "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
成功建立自主物件之後，要連接到自主物件上 iidSink 所指定之連接點之接收物件的介面指標IUnknown。

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

參數

小時
[in]裝載控件之視窗的句柄。

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

傳回值

其中一個標準 HRESULT 值。

AtlAxGetControl

在考慮控制代碼的情況下，取得所指定視窗內包含之控制項的直接介面指標。

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

參數

小時
[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 之前，必須先呼叫此函式。在呼叫此函式之後，可以使用「AtlAxWin」 視窗類別來呼叫 CreateWindow 或 CreateWindowEx，如 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]對象預設來源介面之介面標識碼的指標。

pdwMajor
[out]包含來源介面定義之類型連結庫主要版本號碼的指標。

pdwMinor
[out]類型連結庫次要版本號碼的指標，其中包含來源介面的定義。

傳回值

標準 HRESULT 值。

備註

AtlGetObjectSourceInterface 可以提供預設來源介面的介面標識碼，以及描述該介面之類型連結庫的 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

參數

傳回值

備註

範例

另請參閱

意見反應

其他資源