ITfIntegratableCandidateListUIElement
COM公式ドキュメント
テキストサービスや IME (Input Method Editor) が UI レス モードの動作を調整できるようにします。
解説(Remarks)
ITfIntegratableCandidateListUIElement インターフェイスは、Windows 8 の検索ボックスのような IME 統合コントロールにおいて、より優れた UI とキーボード操作の体験を実現するために UI レス モードの動作を調整する目的で、テキストサービスや IME (Input Method Editor) が実装します。このインターフェイスは、IME 言語での UI とキーボード操作をより洗練させたいアプリケーションが使用します。
ITfIntegratableCandidateListUIElement インターフェイス ポインターは、ITfUIElementSink のコールバック関数の dwUIElementId パラメーターを使用して ITfUIElementMgr から取得した ITfUIElement インターフェイス ポインターに対して QueryInterface を呼び出すことで取得できます。
ITfIntegratableCandidateListUIElement インターフェイスは省略可能なインターフェイスであり、UI レス モードでの UI の表示方法をより細かく制御する必要があるテキストサービスや IME が実装します。アプリケーションは、オートコンプリートや検索候補のように、洗練された特定用途向けの入力コントロールを実装するために利用できます。
ITfIntegratableCandidateListUIElement インターフェイスは、ITfUIElement、ITfCandidateListUIElement、ITfCandidateListUIElementBehavior の各インターフェイスを実装するクラスと同じクラスに実装してください。これらのインターフェイスは連携して動作し、アプリケーションがテキストサービスや IME に代わって候補一覧の UI を描画しつつ、IME 固有の UI カスタマイズやキーボード操作の動作も実現できる、完全に統合された体験を作り出します。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
統合スタイルを設定します。
| guidIntegrationStyle | GUID | in | 必要とするキーボード統合体験の種類。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| テキストサービスがその統合スタイルをサポートしています。 | |
| テキストサービスがその統合スタイルをサポートしていません。 |
解説(Remarks)
アプリケーションがキーボード統合された体験を必要とする場合、必要な統合体験の種類を示す GUID を設定できます。テキストサービスがその統合スタイルをサポートしている場合は S_OK を返してください。サポートしていない場合は E_NOTIMPL を返してください。このメソッドが呼び出されると、テキストサービスは ITfCandidateListUIElement オブジェクトの有効期間中 (たとえば ITfUIElementSink::EndUIElement が呼び出されるまで)、キーボード操作への応答を調整することがあります。
選択スタイルを取得します。
| ptfSelectionStyle | TfIntegratableCandidateListSelectionStyle* | out | 選択スタイルを指定する値。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 |
解説(Remarks)
アクティブな選択スタイルは通常、矢印キーで選択を変更できることを示します。暗黙的な選択スタイルは、既定の選択キーがその項目を選ぶことを示します。アプリケーションが選択スタイルの変更をサポートしている場合、このメソッドは UpdateUIElement メソッドが呼び出されたときに呼び出してください。
キー押下を処理します。
| wParam | WPARAM | in | キーの仮想キー コードを指定します。このパラメーターの詳細については、WM_KEYDOWN の wParam パラメーターを参照してください。 |
| lParam | LPARAM | in | キーのリピート回数、スキャン コード、拡張キー フラグ、コンテキスト コード、直前のキー状態フラグ、遷移状態フラグを指定します。このパラメーターの詳細については、WM_KEYDOWN の lParam パラメーターを参照してください。 |
| pfEaten | BOOL* | out | キー イベントが処理された場合は TRUE、それ以外の場合は FALSE。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 |
解説(Remarks)
OnKeyDown メソッドを使用すると、アプリケーションは、特定の統合スタイルにおいて指定したキーをテキストサービスが処理したいかどうかを問い合わせることができます。OnKeyDown メソッドの動作は統合スタイルによって異なる場合があります。テキストサービスが *pfEaten=TRUE を返した場合、アプリケーションはそのキーに対して何も処理してはいけません。FALSE が返された場合、アプリケーションはそのキーに応じて独自の処理を行えます。
GUID_INTEGRATIONSTYLE_SEARCHBOX ({E6D1BD11-82F7-4903-AE21-1A6397CDE2EB}) を使用すると、ユーザーが体感上のキーボード フォーカスを検索ボックスから候補一覧へ移動して検索候補を選べるキーボード操作体験を実装できます。テキストサービスは、検索側が処理する前に VK_UP や VK_DOWN などのキーを処理し、内部状態を変更できます。
候補番号を表示するかどうかを指定します。
| pfShow | BOOL* | out | 候補番号を表示する場合は TRUE、それ以外の場合は FALSE。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 |
現在ユーザーに表示されている値で、現在のコンポジションを確定します。
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 |
解説(Remarks)
FinalizeExactCompositionString メソッドを使用すると、アプリケーションはテキストサービスに対して、先頭候補への自動変換を行わずに、現在ユーザーに表示されているとおりの値で現在のコンポジションを確定するよう指示できます。これにより、アプリケーションは文字列を変更することなく、候補一覧より下にある候補へフォーカスを移動できます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ITfIntegratableCandidateListUIElement "{C7A6F54F-B180-416F-B2BF-7BF2E4683D7B}" #usecom global ITfIntegratableCandidateListUIElement IID_ITfIntegratableCandidateListUIElement "{}" #comfunc global ITfIntegratableCandidateListUIElement_SetIntegrationStyle 3 int #comfunc global ITfIntegratableCandidateListUIElement_GetSelectionStyle 4 var #comfunc global ITfIntegratableCandidateListUIElement_OnKeyDown 5 sptr,sptr,var #comfunc global ITfIntegratableCandidateListUIElement_ShowCandidateNumbers 6 var #comfunc global ITfIntegratableCandidateListUIElement_FinalizeExactCompositionString 7 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ITfIntegratableCandidateListUIElement "{C7A6F54F-B180-416F-B2BF-7BF2E4683D7B}" #usecom global ITfIntegratableCandidateListUIElement IID_ITfIntegratableCandidateListUIElement "{}" #comfunc global ITfIntegratableCandidateListUIElement_SetIntegrationStyle 3 int #comfunc global ITfIntegratableCandidateListUIElement_GetSelectionStyle 4 sptr #comfunc global ITfIntegratableCandidateListUIElement_OnKeyDown 5 sptr,sptr,sptr #comfunc global ITfIntegratableCandidateListUIElement_ShowCandidateNumbers 6 sptr #comfunc global ITfIntegratableCandidateListUIElement_FinalizeExactCompositionString 7 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。