ホーム › UI.TabletPC › IInkRecognitionResult

IInkRecognitionResult

COMIDispatch (デュアル)

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IID3bc129a8-86cd-45ad-bde8-e0d32d61c16d継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

認識の結果を表します。手書きインクの認識結果は、IInkRecognitionResult オブジェクトとして返されます。

解説(Remarks)

IInkRecognitionAlternate オブジェクト (代替候補) は、この結果から作成されます。最良の候補 (トップの代替候補) が、結果内で既定として使用される候補です。ただし、IInkRecognitionResult オブジェクトのメソッドを使用して、結果内で使用する代替候補を指定できます。

ストロークのコレクションごとに認識結果が自動的に割り当てられると、システムのパフォーマンスが低下する可能性があります。そのため、既定では、結果はストロークのコレクションに関連付けられません。ストロークのコレクションに結果を割り当てるには、SetResultOnStrokes メソッドを呼び出す必要があります。

認識結果を永続化する唯一の方法は、SetResultOnStrokes を呼び出し、そのストロークのコレクションを InkDisp オブジェクトの CustomStrokes コレクションに追加することです。

すべての認識エンジンが TopConfidence プロパティを設定するわけではありません。認識エンジンによって設定されていないプロパティにアプリケーションがアクセスしようとすると、引数の例外がスローされます。

このインターフェースを実装するクラスを独自に定義した場合、その新しいクラスは Tablet PC アプリケーションプログラミングインターフェース (API) と正しく連携しません。

メモ Microsoft から提供されているラテン文字および東アジア言語の各種手書き認識エンジンは、認識結果として Unicode 値 0xFFFF を返すことがあります。これは、認識エンジンがインクの一部をどの有効な文字とも一致させられない場合に発生します。コードポイント 0xFFFF は UCS-2 としては有効ですが、UTF-8 では許可されていません。認識結果を UTF-8 に変換するアプリケーションでは、0xFFFF を 0xFFFD などの別のコードポイントに置き換える必要があります。

メソッド 7

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT get_TopString(LPWSTR* TopString)

TopAlternate プロパティの結果テキストを取得します。

TopString

LPWSTR*

out

最も信頼度の高い認識結果の文字列を受け取るポインタである。

解説(Remarks)

メモ ModifyTopAlternate メソッドの呼び出しによって TopAlternate プロパティが変化した場合、TopString プロパティの結果テキストも変化します。

vtbl 8 HRESULT get_TopAlternate(IInkRecognitionAlternate** TopAlternate)

認識結果のトップの代替候補を取得します。(IInkRecognitionResult.get_TopAlternate)

TopAlternate

IInkRecognitionAlternate**

out

最も信頼度の高い代替候補オブジェクトを受け取るポインタである。

解説(Remarks)

認識エンジンが認識結果を返すとき、認識の代替候補は信頼度の高い順に並べられます。最も信頼度の高い代替候補が、トップの代替候補として選択されます。

ModifyTopAlternate メソッドを使用すると、どの認識候補をトップの代替候補にするかを変更できます。

vtbl 9 HRESULT get_TopConfidence(InkRecognitionConfidence* TopConfidence)

認識結果のトップの代替候補を取得します。(IInkRecognitionResult.get_TopConfidence)

TopConfidence

InkRecognitionConfidence*

out

最上位候補の認識信頼度(強・中・弱)を受け取る InkRecognitionConfidence へのポインタである。

解説(Remarks)

Microsoft の認識エンジンのうち、信頼度をサポートしているのは Microsoft English (US) Handwriting Recognizer と Microsoft Gesture Recognizer だけです。サードパーティ製の認識エンジンでは、信頼度がサポートされる場合とされない場合があります。

メモ ModifyTopAlternate メソッドの呼び出しによって TopAlternate プロパティが変化した場合、TopConfidence プロパティも変化することがあります。

vtbl 10 HRESULT get_Strokes(IInkStrokes** Strokes)

オブジェクトに含まれるストロークのコレクション、またはオブジェクトの作成に使用されたストロークのコレクションを取得します。(IInkRecognitionResult.get_Strokes)

Strokes

IInkStrokes**

out

この認識結果の対象となったストロークコレクションを受け取るポインタである。

解説(Remarks)

このストロークのコレクションは、InkDisp オブジェクトに含まれるストロークのコピーである場合と、そのオブジェクトまたはコレクションの作成に使用されたストロークである場合があります。

メモ InkDisp オブジェクトの Strokes プロパティは、InkDisp オブジェクトが実際に扱っているコレクションそのものではなく、そのコピーを返します。つまり、このコレクションにストロークを追加または削除しても、InkDisp オブジェクトのストロークには影響しません。ストロークを追加または削除するには、AddStrokesAtRectangle、DeleteStroke、DeleteStrokes などの InkDisp のメソッドを使用してください。ただし、コレクション内の各ストロークは、元の IInkStrokeDisp オブジェクトへの参照です。

vtbl 11 HRESULT AlternatesFromSelection(INT selectionStart, INT selectionLength, INT maximumAlternates, IInkRecognitionAlternates** AlternatesFromSelection)

selectionStart	INT	in	代替候補を取得する文字選択範囲の開始位置を指定する。
selectionLength	INT	in	代替候補を取得する文字選択範囲の長さを指定する。
maximumAlternates	INT	in	取得する代替候補の最大数を指定する。
AlternatesFromSelection	IInkRecognitionAlternates**	out	指定した選択範囲に対する代替候補のコレクションを受け取るポインタである。

vtbl 12 HRESULT ModifyTopAlternate(IInkRecognitionAlternate* Alternate)

指定した代替候補を使用して、認識結果のトップの代替候補を変更します。

Alternate

IInkRecognitionAlternate*

inoptional

トップの代替候補の変更に使用する IInkRecognitionAlternate。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値	説明
S_OK	成功しました。
TPC_E_NOT_RELEVANT	ラティスにデータが含まれていません。
E_POINTER	パラメーターに無効なポインターが含まれていました。
E_INVALIDARG	代替候補が既知の範囲と一致しないか、このラティスから取得されたものではありません。
E_INK_EXCEPTION	処理中に例外が発生しました。
E_OUTOFMEMORY	操作を完了するためのメモリを割り当てられません。

解説(Remarks)

既定では、認識結果の最良の結果文字列はトップの代替候補に対応します。ただし、このメソッドを使用すると、トップ以外の代替候補を結果内で使用するように指定できます。トップ以外の代替候補を選択することは、結果に関連付けられた代替候補のラティス内で別の経路を選択することを意味します。

認識結果の変更に使用できる代替候補を取得するには、AlternatesFromSelection メソッドを呼び出します。

メモ ModifyTopAlternate メソッドを呼び出すと、TopString プロパティと TopAlternate プロパティが変更されることがあります。

この関数で使用する代替候補は、文全体の中の 1 単語の候補にすることもできます。たとえば、"Hello World" に対して AlternatesFromSelection (0, 5) を使用して取得した代替候補は、単語の "Hello" の部分だけを変更し、"World" の部分はそのまま残します。

vtbl 13 HRESULT SetResultOnStrokes()

認識結果を、その結果の作成に使用されたストロークに割り当てます。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値	説明
S_OK	成功しました。
E_UNEXPECTED	パラメーターまたはプロパティの型が予期しないものです。
E_INK_EXCEPTION	処理中に例外が発生しました。

解説(Remarks)

すべての InkStrokes コレクションに認識結果が自動的に割り当てられると、システムのパフォーマンスが低下します。そのため、既定では、結果は InkStrokes コレクションに関連付けられません。InkStrokes コレクションに結果を割り当てるには、SetResultOnStrokes を呼び出す必要があります。InkStrokes コレクションの認識結果を取得するには、InkStrokes コレクションの IInkRecognitionResult プロパティを使用します。InkStrokes コレクションに結果を割り当てた後は、そのストロークを IInkCustomStrokes コレクションに格納できます。これらのカスタムストロークと IInkRecognitionResult は、永続化して後で取得できます。

ストロークのコレクションの認識結果を取得するには、RecognitionResult プロパティを使用します。

ストロークのコレクションに結果を割り当てた後は、そのストロークを IInkCustomStrokes コレクションに格納できます。これらのカスタムストロークと IInkRecognitionResult は、永続化して後で取得できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IInkRecognitionResult "{3BC129A8-86CD-45AD-BDE8-E0D32D61C16D}"
#usecom global IInkRecognitionResult IID_IInkRecognitionResult "{}"
#comfunc global IInkRecognitionResult_get_TopString            7 var
#comfunc global IInkRecognitionResult_get_TopAlternate         8 sptr
#comfunc global IInkRecognitionResult_get_TopConfidence        9 var
#comfunc global IInkRecognitionResult_get_Strokes              10 sptr
#comfunc global IInkRecognitionResult_AlternatesFromSelection  11 int,int,int,sptr
#comfunc global IInkRecognitionResult_ModifyTopAlternate       12 sptr
#comfunc global IInkRecognitionResult_SetResultOnStrokes       13
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IInkRecognitionResult "{3BC129A8-86CD-45AD-BDE8-E0D32D61C16D}"
#usecom global IInkRecognitionResult IID_IInkRecognitionResult "{}"
#comfunc global IInkRecognitionResult_get_TopString            7 sptr
#comfunc global IInkRecognitionResult_get_TopAlternate         8 sptr
#comfunc global IInkRecognitionResult_get_TopConfidence        9 sptr
#comfunc global IInkRecognitionResult_get_Strokes              10 sptr
#comfunc global IInkRecognitionResult_AlternatesFromSelection  11 int,int,int,sptr
#comfunc global IInkRecognitionResult_ModifyTopAlternate       12 sptr
#comfunc global IInkRecognitionResult_SetResultOnStrokes       13
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。