ホーム › UI.TextServices › ITfCandidateList

ITfCandidateList

COM

IIDa3ad50fb-9bdb-49e3-a843-6c76520fbf5d継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ITfCandidateList インターフェイスはテキストサービスによって実装され、TSF マネージャーまたはクライアント (アプリケーションや他のテキストサービス) が候補文字列オブジェクトを取得および操作するために使用します。

解説(Remarks)

テキストサービスがテキストをコンテキストに挿入する前に解釈する必要がある場合、その解釈が複数存在することがあります。音声入力がその例です。話された単語が "there" である場合、"their" や "they're" という解釈も考えられます。テキストサービスは最も適切なテキストを挿入しますが、誤りが生じる可能性は残ります。テキストの再変換とは、挿入されたテキストに対する代替テキストをユーザーが選択できるようにする処理です。この代替テキストのオブジェクトを候補 (candidate) と呼びます。

メソッド 4

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

vtbl 3 HRESULT EnumCandidates(IEnumTfCandidates** ppEnum)

ITfCandidateList::EnumCandidates メソッド

ppEnum

IEnumTfCandidates**

out

列挙子オブジェクトを受け取る IEnumTfCandidates インターフェイスポインターへのポインター。呼び出し元は、このインターフェイスが不要になった時点で解放する必要があります。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	ppEnum が無効です。
E_OUTOFMEMORY	メモリの割り当てに失敗しました。

vtbl 4 HRESULT GetCandidate(DWORD nIndex, ITfCandidateString** ppCand)

ITfCandidateList::GetCandidate メソッド

nIndex	DWORD	in	取得する候補文字列の 0 から始まるインデックスを指定します。
ppCand	ITfCandidateString**	out	候補文字列オブジェクトを受け取る ITfCandidateString インターフェイスポインターへのポインター。呼び出し元は、このインターフェイスが不要になった時点で解放する必要があります。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_FAIL	nIndex が無効です。
E_INVALIDARG	ppCand が無効です。
E_OUTOFMEMORY	メモリの割り当てに失敗しました。

vtbl 5 HRESULT GetCandidateNum(DWORD* pnCnt)

ITfCandidateList::GetCandidateNum メソッド

pnCnt

DWORD*

out

候補一覧に含まれる候補文字列オブジェクトの数を受け取る ULONG 値へのポインター。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pnCnt が無効です。

vtbl 6 HRESULT SetResult(DWORD nIndex, TfCandidateResult imcr)

ITfCandidateList::SetResult メソッド

nIndex	DWORD	in	結果を設定する候補文字列の 0 から始まるインデックスを指定します。imcr に CAND_CANCELED が指定されている場合、このパラメーターは無視されます。
imcr	TfCandidateResult	in	再変換操作の結果を指定する TfCandidateResult の値のいずれかを指定します。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_FAIL	不特定のエラーが発生しました。

解説(Remarks)

一般的な再変換操作は、次のような手順で構成されます。

候補の一覧を取得し、ダイアログボックスでユーザーに表示します。
ユーザーが候補を選択した時点で、ダイアログボックスを閉じる前に、新しく選択された候補のインデックスと CAND_SELECTED を指定して ITfCandidateList::SetResult を呼び出します。
別の候補が選択された場合は、新しく選択された候補のインデックスと CAND_SELECTED を指定して ITfCandidateList::SetResult を再度呼び出します。
ユーザーが新しい候補を確定した場合は、現在選択されている候補のインデックスと CAND_FINALIZED を指定して ITfCandidateList::SetResult を呼び出します。
ユーザーがダイアログをキャンセルした場合は、インデックス 0 と CAND_CANCELED を指定して ITfCandidateList::SetResult を呼び出します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITfCandidateList "{A3AD50FB-9BDB-49E3-A843-6C76520FBF5D}"
#usecom global ITfCandidateList IID_ITfCandidateList "{}"
#comfunc global ITfCandidateList_EnumCandidates   3 sptr
#comfunc global ITfCandidateList_GetCandidate     4 int,sptr
#comfunc global ITfCandidateList_GetCandidateNum  5 var
#comfunc global ITfCandidateList_SetResult        6 int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ITfCandidateList "{A3AD50FB-9BDB-49E3-A843-6C76520FBF5D}"
#usecom global ITfCandidateList IID_ITfCandidateList "{}"
#comfunc global ITfCandidateList_EnumCandidates   3 sptr
#comfunc global ITfCandidateList_GetCandidate     4 int,sptr
#comfunc global ITfCandidateList_GetCandidateNum  5 sptr
#comfunc global ITfCandidateList_SetResult        6 int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。