複合コントロールのグローバル関数
これらの関数では、ダイアログ ボックスの作成、ActiveX コントロールの作成、ホスティング、およびライセンスのサポートが提供されます。
重要
次の表に示す関数は、Windows ランタイムで実行されるアプリケーションでは使用できません。
| 機能 | 説明 |
|---|---|
| AtlAxDialogBox | ユーザーが用意するダイアログ テンプレートからモーダル ダイアログ ボックスを作成します。 作成するダイアログ ボックスに、ActiveX コントロールを含めることができます。 |
| AtlAxCreateDialog | ユーザーが用意するダイアログ テンプレートからモードレス ダイアログ ボックスを作成します。 作成するダイアログ ボックスに、ActiveX コントロールを含めることができます。 |
| AtlAxCreateControl | ActiveX コントロールを作成して初期化し、指定されたウィンドウでホストします。 |
| AtlAxCreateControlEx | ActiveX を作成し、それを初期化して、指定したウィンドウ内でホストし、コントロールからインターフェイス ポインターを 1 つ以上取得します。 |
| AtlAxCreateControlLic | ライセンスされた ActiveX コントロールを作成して初期化し、指定されたウィンドウでホストします。 |
| AtlAxCreateControlLicEx | ライセンス対象の ActiveX を作成し、それを初期化して、指定したウィンドウ内でホストし、コントロールからインターフェイス ポインターを 1 つ以上取得します。 |
| 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
[入力] 実行可能ファイルにダイアログ ボックス テンプレートが含まれるモジュールのインスタンスを識別します。
lpTemplateName
[入力] ダイアログ ボックス テンプレートを識別します。 このパラメーターは、ダイアログ ボックス テンプレートの名前を指定する null 終端文字列へのポインター、またはダイアログ ボックス テンプレートのリソース識別子を指定する整数値のいずれかです。 このパラメーターにリソース識別子を指定する場合は、その上位ワードを 0 にして、下位ワードに識別子を含める必要があります。 この値は、MAKEINTRESOURCE マクロを使用して作成できます。
hWndParent
[入力] ダイアログ ボックスを所有するウィンドウを識別します。
lpDialogProc
[入力] ダイアログ ボックス プロシージャを指します。 ダイアログ ボックス プロシージャの詳細については、DialogProc に関するページをご覧ください。
dwInitParam
[入力] WM_INITDIALOG メッセージの lParam パラメーターに、ダイアログ ボックスに渡す値を指定します。
戻り値
標準 HRESULT 値のいずれか。
解説
ActiveX コントロールを含むダイアログ テンプレートで AtlAxDialogBox を使用するには、ダイアログ リソースの CONTROL セクションの text フィールドに有効な CLSID、APPID、または URL 文字列、さらに同じセクションの class name フィールドに "AtlAxWin80" を指定します。 以下に、有効な CONTROL セクションがどのように見えるかを示します。
CONTROL "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
"AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100
リソース スクリプトの編集の詳細については、「方法: リソースを作成する」を参照してください。 コントロール リソース定義ステートメントの詳細については、Windows SDK: SDK Tools の「共通コントロール パラメーター」を参照してください。
一般的なダイアログ ボックスの詳細については、Windows SDK の DialogBox と CreateDialogParam に関するページを参照してください。
AtlAxCreateDialog
ユーザーが用意するダイアログ テンプレートからモードレス ダイアログ ボックスを作成します。
ATLAPI_(HWND) AtlAxCreateDialog(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
パラメーター
Hinstance
[入力] 実行可能ファイルにダイアログ ボックス テンプレートが含まれるモジュールのインスタンスを識別します。
lpTemplateName
[入力] ダイアログ ボックス テンプレートを識別します。 このパラメーターは、ダイアログ ボックス テンプレートの名前を指定する null 終端文字列へのポインター、またはダイアログ ボックス テンプレートのリソース識別子を指定する整数値のいずれかです。 このパラメーターにリソース識別子を指定する場合は、その上位ワードを 0 にして、下位ワードに識別子を含める必要があります。 この値は、MAKEINTRESOURCE マクロを使用して作成できます。
hWndParent
[入力] ダイアログ ボックスを所有するウィンドウを識別します。
lpDialogProc
[入力] ダイアログ ボックス プロシージャを指します。 ダイアログ ボックス プロシージャの詳細については、DialogProc に関するページをご覧ください。
dwInitParam
[入力] 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>"など)Note
"MSHTML:"は HTML フラグメントの前に置いて、MSHTML ストリームであることを指定する必要があります。
hWnd
[入力] コントロールがアタッチされるウィンドウへのハンドル。
pStream
[入力] コントロールのプロパティを初期化するために使用されるストリームへのポインター。 NULL にすることができます。
ppUnkContainer
[出力] コンテナーの 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>"など)アクティブ ドキュメントへの参照 (
"file://\\\Documents\MyDoc.doc"など)HTML のフラグメント (
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"など)Note
"MSHTML:"は HTML フラグメントの前に置いて、MSHTML ストリームであることを指定する必要があります。
hWnd
[入力] コントロールがアタッチされるウィンドウへのハンドル。
pStream
[入力] コントロールのプロパティを初期化するために使用されるストリームへのポインター。 NULL にすることができます。
ppUnkContainer
[出力] コンテナーの IUnknown を受け取るポインターのアドレス。 NULL にすることができます。
ppUnkControl
[出力] 作成されたコントロールの 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>"など)Note
"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>"など)Note
"MSHTML:"は HTML フラグメントの前に置いて、MSHTML ストリームであることを指定する必要があります。
hWnd
コントロールがアタッチされるウィンドウへのハンドル。
pStream
コントロールのプロパティを初期化するために使用されるストリームへのポインター。 NULL にすることができます。
ppUnkContainer
コンテナーの IUnknown を受け取るポインターのアドレス。 NULL にすることができます。
ppUnkControl
[出力] 作成されたコントロールの 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
[入力] コントロールの IUnknown へのポインター。
hWnd
[入力] コントロールをホストするウィンドウへのハンドル。
ppUnkContainer
[出力] コンテナー オブジェクトの IUnknown へのポインターへのポインター。
戻り値
標準 HRESULT 値のいずれか。
解説
AtlAxCreateControlEx と AtlAxCreateControl を使用して、コントロールの作成とアタッチを同時に行います。
Note
AtlAxAttachControl を呼び出す前に、アタッチされるコントロール オブジェクトが正しく初期化されている必要があります。
AtlAxGetHost
ハンドルが与えられた指定のウィンドウに対するコンテナーへのダイレクト インターフェイス ポインターを取得します。
ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);
パラメーター
時
[入力] コントロールをホストしているウィンドウへのハンドル。
pp
[出力] コントロールのコンテナーの IUnknown。
戻り値
標準 HRESULT 値のいずれか。
AtlAxGetControl
ハンドルが与えられた指定のウィンドウ内に含まれるコントロールへのダイレクト インターフェイス ポインターを取得します。
ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);
パラメーター
時
[入力] コントロールをホストしているウィンドウへのハンドル。
pp
[出力] ホストされているコントロールの IUnknown。
戻り値
標準 HRESULT 値のいずれか。
AtlSetChildSite
この関数を呼び出して、子オブジェクトのサイトを親オブジェクトの IUnknown に設定します。
HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);
パラメーター
punkChild
[入力] 子の IUnknown インターフェイスへのポインター。
punkParent
[入力] 親の IUnknown インターフェイスへのポインター。
戻り値
標準の HRESULT 値。
AtlAxWinInit
この関数では、"AtlAxWin80" および "AtlAxWinLic80" ウィンドウ クラスに加えて、いくつかのカスタム ウィンドウ メッセージを登録すると、ATL のコントロール ホスティング コードが初期化されます。
ATLAPI_(BOOL) AtlAxWinInit();
戻り値
コントロール ホスティング コードの初期化が成功した場合は 0 以外。それ以外は FALSE。
解説
この関数は、ATL コントロール ホスティング API を使用する前に呼び出す必要があります。 この関数の呼び出しに続けて、"AtlAxWin" ウィンドウ クラスを、Windows SDK で説明されているように、CreateWindow または CreateWindowEx の呼び出しで使用できます。
AtlAxWinTerm
この関数では、"AtlAxWin80" および "AtlAxWinLic80" ウィンドウ クラスの登録を解除すると、ATL のコントロール ホスティング コードが初期化前の状態に戻されます。
inline BOOL AtlAxWinTerm();
戻り値
常に TRUE が返されます。
解説
Windows SDK で説明されているように、この関数から、UnregisterClass が呼び出されるだけです。
AtlAxWinInit を呼び出し、ホスト ウィンドウを作成する必要がなくなった場合に、この関数を呼び出して、既存のすべてのホスト ウィンドウが破棄された後にクリーンアップします。 この関数を呼び出さない場合、プロセスの終了時にウィンドウ クラスの登録が自動的に解除されます。
AtlGetObjectSourceInterface
オブジェクトの既定のソース インターフェイスに関する情報を取得します。
ATLAPI AtlGetObjectSourceInterface(
IUnknown* punkObj,
GUID* plibid,
IID* piid,
unsigned short* pdwMajor,
unsigned short* pdwMinor);
パラメーター
punkObj
[入力] 情報が返されるオブジェクトへのポインター。
plibid
[出力] ソース インターフェイスの定義を含むタイプ ライブラリの LIBID へのポインター。
piid
[出力] オブジェクトの既定のソース インターフェイスのインターフェイス ID へのポインター。
pdwMajor
[出力] ソース インターフェイスの定義を含むタイプ ライブラリのメジャー バージョン番号へのポインター。
pdwMinor
[出力] ソース インターフェイスの定義を含むタイプ ライブラリのマイナー バージョン番号へのポインター。
戻り値
標準の HRESULT 値。
解説
AtlGetObjectSourceInterface では、既定のソース インターフェイスのインターフェイス ID と、そのインターフェイスを記述するタイプ ライブラリの LIBID、メジャーバージョン番号、マイナー バージョン番号を提供できます。
Note
この関数で要求された情報を正常に取得するには、punkObj によって表されるオブジェクトが IDispatch を実装する (および IDispatch::GetTypeInfo を介して戻り値の型を返す) 必要があり、さらに IProvideClassInfo2 または IPersist のいずれかを実装する必要もあります。 ソース インターフェイスの型情報は、IDispatch の型情報と同じタイプ ライブラリ内にある必要があります。
例
次の例は、IDispEventImpl に渡すことができるテンプレート引数の数を必要最低限に減らすイベント シンク クラス CEasySink を定義する方法を示しています。 EasyAdvise と EasyUnadvise で、IDispEventImpl メンバーを初期化するのに AtlGetObjectSourceInterface が使用された後、DispEventAdvise または 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);
}
};
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示