ITfDocumentMgr

COM

IIDaa80e7f4-2021-11d2-93e0-0060b067b86e継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ITfDocumentMgr インターフェイスは TSF マネージャーによって実装され、アプリケーションまたはテキストサービスがテキストコンテキストを作成および管理するために使用します。このインターフェイスのインスタンスを取得するには、ITfThreadMgr::CreateDocumentMgr を呼び出します。

メソッド 6

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT CreateContext(DWORD tidOwner, DWORD dwFlags, IUnknown* punk, ITfContext** ppic, DWORD* pecTextStore)

ITfDocumentMgr::CreateContext メソッド

tidOwner	DWORD	in	クライアント識別子。アプリケーションの場合、この値は事前に呼び出した ITfThreadMgr::Activate から提供されます。テキストサービスの場合、この値はテキストサービスの ITfTextInputProcessor::Activate メソッドで提供されます。
dwFlags	DWORD	in	予約済みです。0 を指定してください。
punk	IUnknown*	in	ITextStoreACP または ITfContextOwnerCompositionSink インターフェイスをサポートするオブジェクトへのポインター。この値は NULL でもかまいません。
ppic	ITfContext**	out	コンテキストを受け取る ITfContext ポインターのアドレス。
pecTextStore	DWORD*	out	新しいコンテキストの編集クッキーを受け取る TfEditCookie 値へのポインター。この値はさまざまなメソッドでコンテキストを識別するために使用されます。

戻り値

このメソッドは次のいずれかの値を返します。

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	1 つ以上のパラメーターが無効です。
E_OUTOFMEMORY	メモリの割り当てエラーが発生しました。
E_FAIL	原因不明のエラーが発生しました。

解説(Remarks)

punk パラメーターへのすべての参照は、コンテキストが破棄されたとき、または ITfDocumentMgr::Pop メソッドによってコンテキストがスタックから取り除かれたときに解放されます。

vtbl 4 HRESULT Push(ITfContext* pic)

ITfDocumentMgr::Push メソッド

pic

ITfContext*

スタックに追加する ITfContext オブジェクトへのポインター。このオブジェクトは事前に呼び出した ITfDocumentMgr::CreateContext から取得します。

戻り値

このメソッドは次のいずれかの値を返します。

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pic が無効です。
TF_E_STACKFULL	コンテキストを格納する空き領域がスタックにありません。コンテキストスタックには 2 つまでという上限があります。
E_UNEXPECTED	このメソッドが ITfDocumentMgr::Pop の呼び出し中に呼び出されました。

解説(Remarks)

スタックに最初に追加されたコンテキストがメインのドキュメントコンテキストになります。

TSF マネージャーとテキストサービスは、スタックの最上位にあるコンテキストとのみやり取りします。通常、スタック上にはメインのドキュメントコンテキストだけが存在します。まれに、2 つ目のコンテキストをスタックに追加する必要が生じます。たとえば、テキストサービスが候補一覧などのモーダル UI を表示しなければならない場合です。この間、テキストサービスは自身のコンテキストをスタックに追加します。テキストサービスの UI が不要になると、テキストサービスはそのコンテキストをスタックから取り除きます。これによりメインのコンテキストが再びスタックの最上位に戻ります。この処理を簡潔にし、複数のモーダル UI が表示されるのを防ぐため、スタックに置けるコンテキストは最大 2 つに制限されています。

このメソッドを呼び出すと、インストールされているすべてのスレッドマネージャーイベントシンクの ITfThreadMgrEventSink::OnPushContext メソッドが呼び出されます。これがスタックに追加される最初のコンテキストである場合、インストールされているすべてのスレッドマネージャーイベントシンクの ITfThreadMgrEventSink::OnInitDocumentMgr メソッドも呼び出されます。

このコンテキストをコンテキストスタックから取り除くには、ITfDocumentMgr::Pop を呼び出す必要があります。

vtbl 5 HRESULT Pop(DWORD dwFlags)

ITfDocumentMgr::Pop メソッド

dwFlags

DWORD

この値が 0 の場合、スタックの最上位にあるコンテキストのみが取り除かれます。この値が TF_POPF_ALL の場合、すべてのコンテキストがスタックから取り除かれます。

戻り値

このメソッドは次のいずれかの値を返します。

値	説明
S_OK	メソッドは成功しました。
E_FAIL	スタックが空であるか、TF_POPF_ALL フラグを指定せずにこのメソッドが呼び出され、スタック上にコンテキストが 1 つしかありません。
E_UNEXPECTED	このメソッドが別の ITfDocumentMgr::Pop の呼び出し中に呼び出されました。
E_INVALIDARG	dwFlags が無効です。

解説(Remarks)

このメソッドは、対応する ITfDocumentMgr::Push の呼び出しと同じスレッドから呼び出す必要があります。

スタックに最初に追加されたコンテキストがプライマリコンテキストになります。プライマリコンテキストは TF_POPF_ALL フラグを使用しない限りスタックから取り除けません。ドキュメントの終了処理を行う際は、TF_POPF_ALL フラグを指定してこのメソッドを呼び出してください。これにより、ドキュメントマネージャーはコンテキストスタックからすべてのコンテキストを取り除き、テキストサービスの UI を終了させます。それ以外の場面では TF_POPF_ALL フラグを使用しないでください。

このメソッドを呼び出すと、インストールされているすべてのスレッドマネージャーイベントシンクの ITfThreadMgrEventSink::OnPopContext メソッドが呼び出されます。最後のコンテキストがスタックから取り除かれた場合、インストールされているすべてのスレッドマネージャーイベントシンクの ITfThreadMgrEventSink::OnUninitDocumentMgr メソッドも呼び出されます。

vtbl 6 HRESULT GetTop(ITfContext** ppic)

ITfDocumentMgr::GetTop メソッド

ppic

ITfContext**

out

コンテキストを受け取る ITfContext ポインターのアドレス。

戻り値

このメソッドは次のいずれかの値を返します。

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	ppic が無効です。
E_OUTOFMEMORY	メモリの割り当てエラーが発生しました。

vtbl 7 HRESULT GetBase(ITfContext** ppic)

ITfDocumentMgr::GetBase メソッド

ppic

ITfContext**

out

コンテキストを受け取る ITfContext ポインターのアドレス。

戻り値

このメソッドは次のいずれかの値を返します。

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	ppic が無効です。
E_OUTOFMEMORY	メモリの割り当てエラーが発生しました。

vtbl 8 HRESULT EnumContexts(IEnumTfContexts** ppEnum)

ITfDocumentMgr::EnumContexts メソッド

ppEnum

IEnumTfContexts**

out

列挙子を受け取る IEnumTfContexts ポインターのアドレス。

戻り値

このメソッドは次のいずれかの値を返します。

値	説明
S_OK	メソッドは成功しました。
E_OUTOFMEMORY	メモリの割り当てエラーが発生しました。
E_FAIL	列挙子を初期化できません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_ITfDocumentMgr "{AA80E7F4-2021-11D2-93E0-0060B067B86E}"
#usecom global ITfDocumentMgr IID_ITfDocumentMgr "{}"
#comfunc global ITfDocumentMgr_CreateContext  3 int,int,sptr,sptr,var
#comfunc global ITfDocumentMgr_Push           4 sptr
#comfunc global ITfDocumentMgr_Pop            5 int
#comfunc global ITfDocumentMgr_GetTop         6 sptr
#comfunc global ITfDocumentMgr_GetBase        7 sptr
#comfunc global ITfDocumentMgr_EnumContexts   8 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ITfDocumentMgr "{AA80E7F4-2021-11D2-93E0-0060B067B86E}"
#usecom global ITfDocumentMgr IID_ITfDocumentMgr "{}"
#comfunc global ITfDocumentMgr_CreateContext  3 int,int,sptr,sptr,sptr
#comfunc global ITfDocumentMgr_Push           4 sptr
#comfunc global ITfDocumentMgr_Pop            5 int
#comfunc global ITfDocumentMgr_GetTop         6 sptr
#comfunc global ITfDocumentMgr_GetBase        7 sptr
#comfunc global ITfDocumentMgr_EnumContexts   8 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。