IAnchor

COM

IID0feb7e34-5a60-4356-8ef7-abdec2ff7cf8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IAnchor インターフェイスは TSF マネージャーによって実装されます。Microsoft Active Accessibility のクライアントは、IAnchor アンカーオブジェクトを使用して、テキストストリーム内のテキスト範囲(レンジ)を区切ります。

メソッド 11

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

vtbl 3 HRESULT SetGravity(TsGravity gravity)

IAnchor::SetGravity メソッド

gravity

TsGravity

アンカーの新しい gravity(前方または後方)を指定する TsGravity 列挙型の値を格納します。

戻り値

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

値	説明
S_OK	メソッドは成功しました。

vtbl 4 HRESULT GetGravity(TsGravity* pgravity)

IAnchor::GetGravity メソッドは、IAnchor オブジェクト内のアンカーの gravity を取得します。

pgravity

TsGravity*

out

アンカーの gravity を示す TsGravity 値を受け取るポインターです。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pgravity ポインターが無効です。

vtbl 5 HRESULT IsEqual(IAnchor* paWith, BOOL* pfEqual)

IAnchor::IsEqual メソッドは、テキストストリーム内の 2 つのアンカーを評価し、アンカー位置が等しいかどうかを示すブール値を返します。

paWith	IAnchor*	in	主アンカーと比較するアンカーを指定します。2 つのアンカー位置が等しいかどうかを判定するために使用します。
pfEqual	BOOL*	out	2 つのアンカーが同じ位置にあるかどうかを示すブール値です。TRUE の場合、2 つのアンカーは同じ位置にあります。FALSE の場合、2 つのアンカーは同じ位置にはありません。

戻り値

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

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

解説(Remarks)

アンカーは常に文字と文字の間、またはリージョン(領域)と領域の間に位置します。2 つのアンカーが同じ文字の間、すなわちテキストストリーム内の同じオフセットにあり、かつ同じ領域内にある場合、IAnchor::IsEqual は TRUE を返します。それ以外の場合は FALSE を返します。

IAnchor::Compare にも IAnchor::IsEqual と同じ機能が含まれています。ただし、IAnchor::IsEqual はより限定的であるため、サーバー側でより効率的に実装できます。

vtbl 6 HRESULT Compare(IAnchor* paWith, INT* plResult)

IAnchor::Compare メソッドは、テキストストリーム内の 2 つのアンカーの相対位置を比較します。

paWith

IAnchor*

主アンカーと比較するアンカーオブジェクトです。2 つのアンカーの相対位置を判定するために使用します。

plResult

INT*

out

2 つのアンカーの位置を比較した結果です。

値	意味
-1	主アンカーは、テキストストリーム内で paWith より前に位置しています。
0	主アンカーは paWith と同じ位置にあります。
+1	主アンカーは、テキストストリーム内で paWith より後ろに位置しています。

戻り値

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

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

解説(Remarks)

*plResult に 0 が返されるのは、2 つのアンカーが同一の領域内にある場合のみです。アンカーの位置には領域と領域の間の空間も含まれます。2 つのアンカーが同じ位置にあるかどうかだけを判定したい場合は、IAnchor::IsEqual の方が効率的です。

vtbl 7 HRESULT Shift(DWORD dwFlags, INT cchReq, INT* pcch, IAnchor* paHaltAnchor)

IAnchor::Shift メソッドは、テキストストリーム内でアンカーを前方または後方に移動します。

dwFlags

DWORD

アンカーの実際の移動を回避するために使用するビットフィールドです。

値	意味
TS_SHIFT_COUNT_ONLY	アンカーは移動しません。このフラグが設定されていない場合(dwFlags = 0)、アンカーは他のパラメーターの設定に従って移動します。

cchReq

INT

テキストストリーム内でアンカーを移動する文字数です。

pcch

INT*

out

テキストストリーム内で実際に移動した文字数です。メソッドが失敗した場合、pcch には 0 が設定されます。

paHaltAnchor

IAnchor*

移動を阻止するアンカーへの参照です。移動の阻止を行わない場合は NULL を設定します。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_FAIL	移動に失敗しました。
E_INVALIDARG	入力パラメーターの値が無効です。
E_NOTIMPL	dwFlags パラメーターの値は、このメソッドでは実装されていません。

解説(Remarks)

cchReq および pcch パラメーターは負の値(テキストストリーム内での後方への移動)にも、正の値(前方への移動)にもなり得ます。ドキュメントの先頭または末尾に達した場合、領域の境界に達した場合、または paHaltAnchor に移動を阻止するアンカーが指定された場合、実際に移動する文字数は cchReq より少なくなることがあります。

paHaltAnchor に移動を阻止するアンカーが指定されている場合、アプリケーションは paHaltAnchor が示す位置で移動を打ち切ります。paHaltAnchor が移動の対象となるテキストの範囲内にない場合、移動には関係しないため無視されます。

たとえば、paHaltAnchor が参照するアンカーがストリーム内で対象のアンカーの 8 文字先にあるときに、クライアントが Shift (0, 10, pcch, paHaltAnchor) を呼び出した場合、戻り時にはアンカーは 8 文字だけ移動しています。paHaltAnchor が参照するアンカーが移動対象の現在のアンカーと等しい場合、Shift はアンカーをまったく移動せずに成功を返します。この場合、pcch は 0 になります。

アンカーの移動は、ドキュメントの先頭または末尾に達したときと同様に、常に領域の境界で阻止されます。これは、戻り時に実際の移動量 pcch の絶対値が要求した移動量 cchReq の絶対値より小さくなることで示されます。この場合、クライアントは IAnchor::ShiftRegion を使用して、アンカーを隣接する領域へ移動できます。

vtbl 8 HRESULT ShiftTo(IAnchor* paSite)

IAnchor::ShiftTo メソッドは、現在のアンカーを別のアンカーと同じ位置に移動します。

paSite

IAnchor*

現在のアンカーの移動先となる位置にあるアンカーです。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_FAIL	paSite アンカーへの IAnchor インターフェイスポインターを取得できなかったか、操作を安全に完了するにはメモリが不足しています。
E_INVALIDARG	paSite が無効です。

解説(Remarks)

通常、このメソッドの実装は、同等の IAnchor::Shift 操作よりも効率的です。

vtbl 9 HRESULT ShiftRegion(DWORD dwFlags, TsShiftDir dir, BOOL* pfNoRegion)

IAnchor::ShiftRegion メソッド

dwFlags

DWORD

非表示テキストの周辺でのアンカーの再配置を制御する、またはアンカーの実際の再配置を回避するために使用するビットフィールドです。

値	意味
TS_SHIFT_COUNT_HIDDEN	非表示テキストの領域の境界を含め、次の領域の境界までアンカーを移動することを指定します。設定されていない場合、アンカーは隣接する非表示テキストを越えて、表示テキストの領域が見つかるまで移動します。
TS_SHIFT_COUNT_ONLY	アンカーは移動しません。

dir

TsShiftDir

アンカーの移動先となる隣接領域を指定する TsShiftDir 値のいずれかを格納します。

値	意味
TS_SD_BACKWARD	テキスト範囲の直前にある領域へアンカーを移動することを指定します。
TS_SD_FORWARD	テキスト範囲の直後にある領域へアンカーを移動することを指定します。

pfNoRegion

BOOL*

out

アンカーの移動が行われたかどうかを示すブール値です。

値	意味
TRUE	移動に失敗し、アンカーは再配置されませんでした。
FALSE	移動に成功しました。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_FAIL	移動に失敗しました。
E_INVALIDARG	入力パラメーターの値が無効です。

vtbl 10 HRESULT SetChangeHistoryMask(DWORD dwMask)

このメソッドは実装されていません。

dwMask

DWORD

使用しません。

戻り値

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

値	説明
E_NOTIMPL	このメソッドは実装されていません。

vtbl 11 HRESULT GetChangeHistory(ANCHOR_CHANGE_HISTORY_FLAGS* pdwHistory)

IAnchor::GetChangeHistory メソッドは、アンカーの直前または直後で発生した削除の履歴を取得します。

pdwHistory

ANCHOR_CHANGE_HISTORY_FLAGS*

out

アンカーの直前または直後で削除が発生したことを示すビットフィールドフラグです。次の値の一方または両方が設定されます。

値	意味
TS_CH_PRECEDING_DEL	アンカーの直前のテキストが削除されました。
TS_CH_FOLLOWING_DEL	アンカーの直後のテキストが削除されました。

戻り値

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

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

解説(Remarks)

アンカーに隣接する位置で削除が発生した場合は、pdwHistory の変更フラグを設定する必要があります。

変更フラグは、IAnchor::ClearChangeHistory の呼び出しによってクリアされるまで設定されたままになります。

vtbl 12 HRESULT ClearChangeHistory()

IAnchor::ClearChangeHistory メソッドは、アンカーの変更履歴フラグをクリアします。

戻り値

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

値	説明
S_OK	メソッドは成功しました。

解説(Remarks)

アプリケーションは、この呼び出しを受け取った後にアンカーの変更履歴フラグをクリアする必要があります。変更履歴フラグは IAnchor::GetChangeHistory によって設定されたものです。

vtbl 13 HRESULT Clone(IAnchor** ppaClone)

IAnchor::Clone メソッドは、現在のアンカーと同じ位置、同じ gravity を持つ新しいアンカーオブジェクトを生成します。

ppaClone

IAnchor**

out

現在のアンカーと同一の、新しいアンカーオブジェクトです。

戻り値

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

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

解説(Remarks)

複製されたアンカーでは、変更履歴と変更履歴マスクの両方がクリアされます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IAnchor "{0FEB7E34-5A60-4356-8EF7-ABDEC2FF7CF8}"
#usecom global IAnchor IID_IAnchor "{}"
#comfunc global IAnchor_SetGravity            3 int
#comfunc global IAnchor_GetGravity            4 var
#comfunc global IAnchor_IsEqual               5 sptr,var
#comfunc global IAnchor_Compare               6 sptr,var
#comfunc global IAnchor_Shift                 7 int,int,var,sptr
#comfunc global IAnchor_ShiftTo               8 sptr
#comfunc global IAnchor_ShiftRegion           9 int,int,var
#comfunc global IAnchor_SetChangeHistoryMask  10 int
#comfunc global IAnchor_GetChangeHistory      11 var
#comfunc global IAnchor_ClearChangeHistory    12
#comfunc global IAnchor_Clone                 13 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IAnchor "{0FEB7E34-5A60-4356-8EF7-ABDEC2FF7CF8}"
#usecom global IAnchor IID_IAnchor "{}"
#comfunc global IAnchor_SetGravity            3 int
#comfunc global IAnchor_GetGravity            4 sptr
#comfunc global IAnchor_IsEqual               5 sptr,sptr
#comfunc global IAnchor_Compare               6 sptr,sptr
#comfunc global IAnchor_Shift                 7 int,int,sptr,sptr
#comfunc global IAnchor_ShiftTo               8 sptr
#comfunc global IAnchor_ShiftRegion           9 int,int,sptr
#comfunc global IAnchor_SetChangeHistoryMask  10 int
#comfunc global IAnchor_GetChangeHistory      11 sptr
#comfunc global IAnchor_ClearChangeHistory    12
#comfunc global IAnchor_Clone                 13 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。