ホーム › UI.TextServices › ITfProperty

ITfProperty

COM

📘 Microsoft Learn (日本語) · English

IIDe2449660-9542-11d2-bf46-00105a2799b5継承元ITfReadOnlyProperty自前メソッド開始 vtbl7

公式ドキュメント

ITfProperty インターフェイスは TSF マネージャーによって実装され、クライアント (アプリケーションまたはテキストサービス) がプロパティ値を変更するために使用します。

解説(Remarks)

このインターフェイスのインスタンスは、ITfContext::GetProperty や IEnumTfProperties::Next など、さまざまな方法で取得します。

メソッド 4

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

vtbl 7 HRESULT FindRange(DWORD ec, ITfRange* pRange, ITfRange** ppRange, TfAnchor aPos)

ITfProperty::FindRange メソッド

ec	DWORD	in	編集コンテキストを識別する編集クッキーを指定します。これは ITfDocumentMgr::CreateContext または ITfEditSession::DoEditSession から取得します。
pRange	ITfRange*	in	プロパティの範囲を取得する対象となる位置を含む ITfRange インターフェイスへのポインターです。その位置は、aPos の値に応じて、この範囲 (レンジ) の開始アンカーまたは終了アンカーのいずれかになります。
ppRange	ITfRange**	out	要求された範囲 (レンジ) オブジェクトを受け取る ITfRange インターフェイスポインターへのポインターです。
aPos	TfAnchor	in	pRange のどちらのアンカーを、プロパティの範囲を取得する位置として使用するかを指定する TfAnchor 値のいずれかを指定します。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
S_FALSE	pRange がプロパティに重なっておらず、隣接してもいません。ppRange は NULL を受け取ります。
E_INVALIDARG	1 つ以上のパラメーターが無効です。
E_OUTOFMEMORY	メモリの割り当てに失敗しました。
E_FAIL	原因不明のエラーが発生しました。
TF_E_NOLOCK	ec で識別される編集コンテキストが、読み取り専用ロックまたは読み取り/書き込みロックを保持していません。

解説(Remarks)

このメソッドは、プロパティの空でない値を持つテキストの範囲 (レンジ) を取得します。指定した位置にプロパティの値が存在しない場合、ppRange は NULL を受け取り、メソッドは S_FALSE を返します。次の例では、aPos が TF_ANCHOR_START の場合、返される範囲には "is" が含まれます。aPos が TF_ANCHOR_END の場合、範囲の終了位置にはプロパティが存在しないため、メソッドは S_FALSE を返します。


COLOR: RRRRR   RR          GGGGGGGG
TEXT:  this <a>is som</a>e colored text

aPos が TF_ANCHOR_START の場合、このメソッドは開始アンカーの直前で終了しているプロパティ範囲を無視します。同様に、aPos が TF_ANCHOR_END の場合、終了アンカーの直後で開始するプロパティ範囲を無視します。次の例では、aPos が TF_ANCHOR_START の場合、R の値を持つプロパティは開始アンカーの位置で終了し、G の値を持つプロパティが開始アンカーから始まるため、返される範囲には "some " ではなく "colored " が含まれます。aPos が TF_ANCHOR_END の場合も、返される範囲には "text" ではなく "colored " が含まれます。


COLOR:         RRRRR   GGGGGGGG    BBBB
TEXT:  this is some <a>colored </a>text

vtbl 8 HRESULT SetValueStore(DWORD ec, ITfRange* pRange, ITfPropertyStore* pPropStore)

ITfProperty::SetValueStore メソッド

ec	DWORD	in	編集コンテキストを識別する編集クッキーを指定します。これは ITfDocumentMgr::CreateContext または ITfEditSession::DoEditSession から取得します。
pRange	ITfRange*	in	プロパティ値を設定する対象の範囲 (レンジ) を含む ITfRange インターフェイスへのポインターです。このパラメーターに NULL を指定することはできません。pRange が空の場合、このメソッドは失敗します。
pPropStore	ITfPropertyStore*	in	プロパティデータを取得する ITfPropertyStore インターフェイスへのポインターです。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	1 つ以上のパラメーターが無効です。
E_FAIL	原因不明のエラーが発生しました。
TF_E_NOLOCK	ec で識別される編集コンテキストが、読み取り/書き込みロックを保持していません。

解説(Remarks)

ITfProperty::SetValue で設定したプロパティ値は、その値が対象とするテキストが変更されると破棄されます。テキストが変更されたときのプロパティ値の扱いを制御するには、ITfProperty::SetValueStore を使用してください。

ITfProperty::SetValue で設定した値はシリアル化されますが、VT_UNKNOWN 型の値はシリアル化されません。VT_UNKNOWN 型のプロパティ値をシリアル化する必要がある場合は、代わりに ITfProperty::SetValueStore を使用してください。

同じ型のプロパティ値どうしが重なり合うことはサポートされていません。

vtbl 9 HRESULT SetValue(DWORD ec, ITfRange* pRange, VARIANT* pvarValue)

ITfProperty::SetValue メソッド

ec	DWORD	in	編集コンテキストを識別する編集クッキーを指定します。これは ITfDocumentMgr::CreateContext または ITfEditSession::DoEditSession から取得します。
pRange	ITfRange*	in	プロパティ値を設定する対象の範囲 (レンジ) を含む ITfRange インターフェイスへのポインターです。このパラメーターに NULL を指定することはできません。pRange が空の場合、このメソッドは失敗します。
pvarValue	VARIANT*	in	新しいプロパティ値を格納する VARIANT 構造体へのポインターです。サポートされる型は VT_I4、VT_UNKNOWN、VT_BSTR、VT_EMPTY のみです。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	1 つ以上のパラメーターが無効です。
E_OUTOFMEMORY	メモリの割り当てに失敗しました。
E_FAIL	原因不明のエラーが発生しました。
TF_E_NOLOCK	ec で識別される編集コンテキストが、読み取り/書き込みロックを保持していません。
TF_E_READONLY	編集コンテキストが読み取り専用です。
TF_E_NOTOWNEDRANGE	TSF マネージャーがその範囲 (レンジ) を所有していません。

解説(Remarks)

このメソッドで設定したプロパティ値は、その値が対象とするテキストが変更されると破棄されます。テキスト編集に対する値の挙動を独自に制御するには、ITfProperty::SetValueStore を使用してください。

このメソッドで設定した値はシリアル化されますが、VT_UNKNOWN 型の値はシリアル化されません。VT_UNKNOWN 型のプロパティ値をシリアル化する必要がある場合は、代わりに ITfProperty::SetValueStore を使用してください。

同じ型のプロパティ値どうしが重なり合うことはサポートされていません。

vtbl 10 HRESULT Clear(DWORD ec, ITfRange* pRange)

ITfProperty::Clear メソッド

ec	DWORD	in	編集コンテキストを識別する編集クッキーを指定します。これは ITfDocumentMgr::CreateContext または ITfEditSession::DoEditSession から取得します。
pRange	ITfRange*	in	プロパティをクリアする対象の範囲 (レンジ) を含む ITfRange インターフェイスへのポインターです。このパラメーターが NULL の場合、編集コンテキスト全体にわたるこのプロパティのすべての値がクリアされます。

戻り値

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

値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pRange が無効です。
TF_E_NOLOCK	ec で識別される編集コンテキストが、読み取り/書き込みロックを保持していません。
TF_E_READONLY	編集コンテキストが読み取り専用です。
TF_E_NOTOWNEDRANGE	TSF マネージャーがその範囲 (レンジ) を所有していません。

解説(Remarks)

コンテキストが破棄される直前にこのメソッドを呼び出す必要はありません。TSF マネージャーは、コンテキストがコンテキストスタックから削除されるときにすべてのプロパティをクリアします。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITfProperty "{E2449660-9542-11D2-BF46-00105A2799B5}"
#usecom global ITfProperty IID_ITfProperty "{}"
#comfunc global ITfProperty_FindRange      7 int,sptr,sptr,int
#comfunc global ITfProperty_SetValueStore  8 int,sptr,sptr
#comfunc global ITfProperty_SetValue       9 int,sptr,var
#comfunc global ITfProperty_Clear          10 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ITfProperty "{E2449660-9542-11D2-BF46-00105A2799B5}"
#usecom global ITfProperty IID_ITfProperty "{}"
#comfunc global ITfProperty_FindRange      7 int,sptr,sptr,int
#comfunc global ITfProperty_SetValueStore  8 int,sptr,sptr
#comfunc global ITfProperty_SetValue       9 int,sptr,sptr
#comfunc global ITfProperty_Clear          10 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。