Win32 API 日本語リファレンス
ホームUI.TabletPC › IInkStrokes

IInkStrokes

COMIDispatch (デュアル)
IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IIDf1f4c9d8-590a-4963-b3ae-1935671bb6f3継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

. (IInkStrokes)

メソッド 20

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

vtbl 7 HRESULT get_Count(INT* Count)

コレクションに含まれるオブジェクトまたはコレクションの数を取得します。(IInkStrokes.get_Count)

CountINT*outコレクションに含まれるストロークの個数を受け取るポインタである。
vtbl 8 HRESULT get__NewEnum(IUnknown** _NewEnum)
_NewEnumIUnknown**outコレクションを反復処理するための列挙子 (IEnumVARIANT) を受け取る IUnknown ポインタである。
vtbl 9 HRESULT get_Ink(IInkDisp** Ink)

ストロークのコレクションを保持する InkDisp オブジェクトを取得します。

InkIInkDisp**outこれらのストロークが属するインク オブジェクトを受け取るポインタである。
vtbl 10 HRESULT get_RecognitionResult(IInkRecognitionResult** RecognitionResult)

InkStrokes コレクションの IInkRecognitionResult オブジェクトを取得します。

RecognitionResultIInkRecognitionResult**outこのストローク コレクションに関連付けられた認識結果を受け取るポインタである。

解説(Remarks)

認識が実行されていない場合、または結果が永続化されていない場合、このプロパティの値は NULL になります。

vtbl 11 HRESULT ToString(LPWSTR* ToString)

ToString は Windows Vista 以降では使用できません。

ToStringLPWSTR*out

既定の認識エンジンがストロークのコレクションに対して認識を実行した後の、IInkRecognitionResult オブジェクトの TopAlternate プロパティの先頭の文字列。

BSTR データ型の詳細については、「Using the COM Library」を参照してください。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_FAIL
操作に失敗しました。
E_OUTOFMEMORY
メモリが不足しています。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
TPC_E_RECOGNIZER_NOT_REGISTERED
認識エンジンが 1 つもインストールされていないか、認識エンジンのレジストリキーが破損しているか、または使用中の環境が手書き認識をサポートしていません。

解説(Remarks)

ToString は手書き認識アプリケーションで使用すべきではありません。デバッグ目的でのみ使用してください。

次の場合、ToStringNULL を返します。

vtbl 12 HRESULT Item(INT Index, IInkStrokeDisp** Stroke)

InkStrokes コレクション内の指定したインデックスにある IInkStrokeDisp オブジェクトを取得します。

IndexINTin取得する IInkStrokeDisp オブジェクトの、0 から始まるインデックス。
StrokeIInkStrokeDisp**outこのメソッドが戻るときに、InkStrokes コレクション内の指定したインデックスにある IInkStrokeDisp オブジェクトへのポインターが格納されます。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_FAIL
不特定のエラーが発生しました。
CO_E_CLASSTRING
GUID の形式が無効です。
DISP_E_TYPEMISMATCH
パラメーターのいずれかが有効な VARIANT 型ではありません。
E_INVALIDARG
引数が無効です。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。
REGDB_CLASSNOTREG
型オブジェクトが登録されていません。
E_OUTOFMEMORY
操作を完了するためのメモリを割り当てられません。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
TPC_E_RECOGNIZER_NOT_REGISTERED
認識エンジンのレジストリキーが破損しているか、使用中の環境が手書き認識をサポートしていません。

解説(Remarks)

インデックスがコレクション内の既存のメンバーのいずれとも一致しない場合、エラーが発生します。

vtbl 13 HRESULT Add(IInkStrokeDisp* InkStroke)

既存の InkStrokes コレクションに、IInkStrokeDisp オブジェクトまたは InkStrokes コレクションを追加します。

InkStrokeIInkStrokeDisp*inoptionalInkStrokes コレクションに追加するストローク。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_OUTOFMEMORY
Stroke ハンドラーのヘルパーオブジェクトを割り当てられません。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_INK_INCOMPATIBLE_OBJECT
IInkStrokeDisp* が互換性のある IInkStrokeDisp オブジェクトを指していません。
E_INK_MISMATCHED_INK_OBJECT
追加しようとしている IInkStrokeDispInkDisp オブジェクトが、InkStrokes コレクションの InkDisp オブジェクトと一致しません。

解説(Remarks)

メモ ストロークは InkDisp オブジェクト内に既に存在している必要があり、別の InkDisp オブジェクトに属していてはなりません。また、このメソッドは InkDisp オブジェクトをコピーしたり変更したりするものではなく、単にこのストロークをコレクションに追加するだけです。
InkStrokes コレクションにストロークを 1 つ追加するには、このメソッドを使用します。ストロークのコレクションを別のコレクションに追加するには、AddStrokes メソッドを使用します。
vtbl 14 HRESULT AddStrokes(IInkStrokes* InkStrokes)

既存の Strokes コレクションに Strokes コレクションを追加します。

InkStrokesIInkStrokes*inoptionalストロークのコレクションに追加する、ストロークのコレクション。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_OUTOFMEMORY
Stroke ハンドラーのヘルパーオブジェクトを割り当てられません。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_INK_INCOMPATIBLE_OBJECT
IInkStrokes* が互換性のある InkDisp オブジェクトを指していません。
E_INK_MISMATCHED_INK_OBJECT
追加しようとしている InkStrokes コレクションの InkDisp オブジェクトは、追加先の InkStrokes コレクションの InkDisp オブジェクトと一致している必要があります。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。

解説(Remarks)

メモ このコレクションは InkDisp オブジェクト内に既に存在している必要があり、別の InkDisp オブジェクトに属していてはなりません。また、この操作は InkDisp オブジェクトをコピーしたり変更したりするものではなく、単にこのストロークのコレクションをコレクションに追加するだけです。
vtbl 15 HRESULT Remove(IInkStrokeDisp* InkStroke)

InkStrokes コレクションから IInkStrokeDisp オブジェクトを削除します。

InkStrokeIInkStrokeDisp*inoptional削除する IInkStrokeDisp

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_OUTOFMEMORY
IInkStrokeDisp ハンドラーのヘルパーオブジェクトを割り当てられません。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_INK_INCOMPATIBLE_OBJECT
IInkStroke* が有効な InkDisp Class オブジェクトを指していません。
E_INK_MISMATCHED_INK_OBJECT
InkStrokes コレクションの InkDisp オブジェクトと、この IInkStrokeDisp オブジェクトが一致しません。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。

解説(Remarks)

InkStrokes コレクションはインクデータへの参照の集合であり、実際のデータそのものではありません。このメソッドは、データのスナップショット (参照) からストロークのコレクションを削除するだけで、実際のインクデータは削除しません。実際のインクデータからコレクションを削除するには、DeleteStrokes メソッドを呼び出します。

Remove メソッドを呼び出すと、コレクション内のストロークの順序が変更されます。たとえば Strokes.Remove(Strokes.Item(0)) を呼び出すと、それまで Strokes.Item(1) だったものが Strokes.Item(0) になり、Strokes.Item(2) だったものが Strokes.Item(1) になる、というように繰り上がります。

vtbl 16 HRESULT RemoveStrokes(IInkStrokes* InkStrokes)

コレクションからストロークを削除します。

InkStrokesIInkStrokes*inoptionalコレクションから削除するストローク。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_OUTOFMEMORY
Stroke ハンドラーのヘルパーオブジェクトを割り当てられません。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_INK_INCOMPATIBLE_OBJECT
IInkStrokes* が有効な InkDisp オブジェクトを指していません。
E_INK_MISMATCHED_INK_OBJECT
InkStrokes コレクションの InkDisp オブジェクトと、指定された InkStrokes が一致しません。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。
vtbl 17 HRESULT ModifyDrawingAttributes(IInkDrawingAttributes* DrawAttrs)

InkStrokes コレクション内のすべてのストロークの描画属性を設定します。

DrawAttrsIInkDrawingAttributes*inoptionalコレクション内のすべてのストロークに適用する新しい描画属性。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。
vtbl 18 HRESULT GetBoundingBox(InkBoundingBoxMode BoundingBoxMode, IInkRectangle** BoundingBox)

InkDisp オブジェクト内のすべてのストローク、個々のストローク、または InkStrokes コレクションについて、インク空間座標での境界ボックスを取得します。

BoundingBoxModeInkBoundingBoxModein

省略可能。境界ボックスの計算に使用するストロークの特性を指定します。ストロークの特性を使用した境界ボックスの計算の詳細については、BoundingBoxMode 列挙型を参照してください。

GetBoundingBox メソッドの BoundingBoxMode パラメーターの既定値は -1 で、これはストロークのすべての特性を使用して境界ボックスを指定することを意味します。

BoundingBoxIInkRectangle**out

このメソッドが戻るときに、InkDisp オブジェクト、IInkStrokeDisp オブジェクト、または InkStrokes コレクションの境界ボックスを定義する四角形へのポインターが格納されます。

メモ IInkStrokeDisp オブジェクトの場合、返される境界ボックスはストロークの境界ボックスのコピーであるため、返された境界ボックスを変更してもストロークの位置には影響しません。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。
REGDB_CLASSNOTREG
InkRectangle オブジェクトが登録されていません。

解説(Remarks)

境界ボックスがペンの幅の影響を受ける場合、この幅は InkRenderer のビュー変換に合わせて適切にスケーリングされます。具体的には、ペンの幅にビュー変換の行列式の平方根を掛けます。

メモ Windows Vista 以降のバージョンでは、GetBoundingBox Method はストロークの幅を考慮しません。
メモ ペンの幅を明示的に設定していない場合、既定値は 53 です。正しい境界ボックスを求めるには、ペンの幅に行列式の平方根を掛ける必要があります。境界ボックスの高さと幅は、各方向にこの値の半分ずつ拡張されます。たとえば、ペンの幅が 53、行列式の平方根が 50、境界ボックスが (0, 0, 1000, 1000) の場合を考えます。各方向における境界ボックスへのペン幅の調整量は (53 * 50) / 2 として計算され、右辺と下辺はさらに 1 ずつ加算されます。その結果、描画される境界ボックスは (-1325, -1325, 2326, 2326) になります。
vtbl 19 HRESULT Transform(IInkTransform* Transform, VARIANT_BOOL ApplyOnPenWidth)

IInkStrokeDisp オブジェクトまたは InkStrokes コレクションに線形変換を適用します。線形変換では、拡大縮小、回転、平行移動、およびそれらの組み合わせを表現できます。(IInkStrokes.Transform)

TransformIInkTransform*inoptionalストロークに適用する変換。(これは InkTransform オブジェクトで、XFORM 構造体に対応します。) この変換はポイントとペンの幅の両方に適用されます (ApplyOnPenWidthVARIANT_TRUE の場合)。
ApplyOnPenWidthVARIANT_BOOLin省略可能。ストロークの InkDrawingAttributes におけるインクの幅にも変換を適用する場合は VARIANT_TRUE、それ以外の場合は VARIANT_FALSE。既定値は VARIANT_FALSE です。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_INVALIDARG
引数が無効です。
E_UNEXPECTED
予期しないパラメーターまたはプロパティの型です。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
vtbl 20 HRESULT ScaleToRectangle(IInkRectangle* Rectangle)

IInkStrokeDisp オブジェクトまたは InkStrokes コレクションを、指定した InkRectangle オブジェクトに収まるように拡大縮小します。(IInkStrokes.ScaleToRectangle)

RectangleIInkRectangle*inoptionalストロークまたはストロークのコレクションの拡大縮小先となる、インク空間内の InkRectangle。ストロークは、その境界ボックスがこの四角形に一致するように拡大縮小および平行移動されます。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
vtbl 21 HRESULT Move(FLOAT HorizontalComponent, FLOAT VerticalComponent)

IInkStrokeDisp オブジェクトまたは InkStrokes コレクションのインクに平行移動を適用します。(IInkStrokes.Move)

HorizontalComponentFLOATinビュー変換を X 方向に平行移動する距離 (インク空間座標)。
VerticalComponentFLOATinビュー変換を Y 方向に平行移動する距離 (インク空間座標)。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 22 HRESULT Rotate(FLOAT Degrees, FLOAT x, FLOAT y)

回転の中心点を基準に、度単位で指定した角度だけインクを回転します。(IInkStrokes.Rotate)

DegreesFLOATin時計回りに回転する角度 (度単位)。
xFLOATin省略可能。回転の中心となる点の x 座標 (インク空間座標)。既定値は原点です。
yFLOATin省略可能。回転の中心となる点の y 座標 (インク空間座標)。既定値は原点です。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
vtbl 23 HRESULT Shear(FLOAT HorizontalMultiplier, FLOAT VerticalMultiplier)

指定した水平方向および垂直方向の係数で、ストロークのインクをせん断します。(IInkStrokes.Shear)

HorizontalMultiplierFLOATinせん断の水平方向の係数。
VerticalMultiplierFLOATinせん断の垂直方向の係数。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。

解説(Remarks)

このメソッドで適用される変換が純粋なせん断となるのは、いずれか一方のパラメーターが 0 の場合だけです。原点にある四角形に適用した場合、shearY 係数が 0 のときは、四角形の高さの shearX 倍だけ下辺が水平方向に移動します。shearX 係数が 0 のときは、四角形の幅の shearY 倍だけ右辺が垂直方向に移動します。

メモ 両方のパラメーターが 0 以外の場合、結果は直感的でないことがあります。
せん断が可逆でない場合、このメソッドは例外をスローします。shearX パラメーターと shearY パラメーターの積が 1 に等しい場合、そのせん断は可逆ではありません。
vtbl 24 HRESULT ScaleTransform(FLOAT HorizontalMultiplier, FLOAT VerticalMultiplier)

指定した水平方向および垂直方向の係数を、変換またはインクに適用します。(IInkStrokes.ScaleTransform)

HorizontalMultiplierFLOATin変換において水平方向を拡大縮小する係数。
VerticalMultiplierFLOATin変換において垂直方向を拡大縮小する係数。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。

解説(Remarks)

IInkStrokeDisp クラスおよび InkStrokes クラスでは、このメソッドはストローク内のポイントを原点を基準に拡大縮小します。したがって、HorizontalMultiplier パラメーターが 2.0 の場合、ストロークは幅が 2 倍になるとともに、原点からの水平方向の距離も 2 倍になります。ストロークの相対位置を制御するには、このメソッドを Move メソッドと組み合わせて使用します。

vtbl 25 HRESULT Clip(IInkRectangle* Rectangle)

IInkStrokeDisp オブジェクトまたは InkStrokes コレクションのうち、四角形の外側にある部分を削除します。(IInkStrokes.Clip)

RectangleIInkRectangle*inoptionalこの四角形の外側にあるストロークの部分がクリップされます。四角形はインク空間座標で指定します。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_POINTER
パラメーターに無効なポインターが含まれていました。
REGDB_CLASSNOTREG
InkDisp オブジェクトが登録されていません。
E_INVALIDARG
クリップ用の四角形が無効です。
E_INK_EXCEPTION
メソッド内で例外が発生しました。
E_FAIL
不特定のエラーが発生しました。

解説(Remarks)

InkDisp オブジェクトの場合、四角形と交差するすべてのストロークは交点で分割されます。四角形の外側にあるストロークの部分は、すべて InkDisp オブジェクトから削除されます。このメソッドは、ストロークが四角形と交差する位置に新しいポイントを追加することがあります。InkDisp オブジェクトに対して Clip メソッドを呼び出した後、InkDisp オブジェクトのストロークコレクション内にあるストロークの ID は一意であることが保証されますが、その他の情報が保持されることは保証されません。

このメソッドは、クリップの際にペンの幅を考慮しません。クリップされるのは実際のインクデータ (ストロークデータ) のみです。

IInkStrokeDisp オブジェクトまたは InkStrokes コレクションの場合、Clip メソッドは親の InkDisp オブジェクトを更新します。InkDisp オブジェクトからインクが削除されると、その InkDisp オブジェクトに対して定義されている IInkStrokeDisp オブジェクトや InkStrokes コレクションが無効になる場合があります。

インクデータの詳細については、「Ink Data」を参照してください。

vtbl 26 HRESULT RemoveRecognitionResult()

InkStrokes コレクションに関連付けられている RecognitionResult を削除します。

戻り値

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

戻り値 説明
S_OK
成功しました。
E_INK_EXCEPTION
メソッド内で例外が発生しました。

解説(Remarks)

InkStrokes コレクションに認識結果を設定するには、SetResultOnStrokes メソッドを使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IInkStrokes "{F1F4C9D8-590A-4963-B3AE-1935671BB6F3}"
#usecom global IInkStrokes IID_IInkStrokes "{48F491BC-240E-4860-B079-A1E94D3D2C86}"
#comfunc global IInkStrokes_get_Count                7 var
#comfunc global IInkStrokes_get__NewEnum             8 sptr
#comfunc global IInkStrokes_get_Ink                  9 sptr
#comfunc global IInkStrokes_get_RecognitionResult    10 sptr
#comfunc global IInkStrokes_ToString                 11 var
#comfunc global IInkStrokes_Item                     12 int,sptr
#comfunc global IInkStrokes_Add                      13 sptr
#comfunc global IInkStrokes_AddStrokes               14 sptr
#comfunc global IInkStrokes_Remove                   15 sptr
#comfunc global IInkStrokes_RemoveStrokes            16 sptr
#comfunc global IInkStrokes_ModifyDrawingAttributes  17 sptr
#comfunc global IInkStrokes_GetBoundingBox           18 int,sptr
#comfunc global IInkStrokes_Transform                19 sptr,int
#comfunc global IInkStrokes_ScaleToRectangle         20 sptr
#comfunc global IInkStrokes_Move                     21 float,float
#comfunc global IInkStrokes_Rotate                   22 float,float,float
#comfunc global IInkStrokes_Shear                    23 float,float
#comfunc global IInkStrokes_ScaleTransform           24 float,float
#comfunc global IInkStrokes_Clip                     25 sptr
#comfunc global IInkStrokes_RemoveRecognitionResult  26
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。