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

ITextStoreACP

COM
IID28888fe3-c2a0-483a-a3ea-8cb1ce51ff3d継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ITextStoreACP インターフェイスはアプリケーションが実装し、TSF マネージャーが TSF のテキストストリームまたはテキストストア (text store) を操作するために使用します。

メソッド 26

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

vtbl 3 HRESULT AdviseSink(GUID* riid, IUnknown* punk, DWORD dwMask)

ITextStoreACP::AdviseSink メソッドは、ITextStoreACPSink インターフェイスによるアドバイズシンクを新規にインストールするか、既存のアドバイズシンクを変更します。シンクインターフェイスは punk パラメーターで指定します。

riidGUID*inシンクインターフェイスを指定します。
punkIUnknown*inシンクインターフェイスへのポインター。NULL は指定できません。
dwMaskDWORDinアドバイズシンクに通知するイベントを指定します。指定可能な値の詳細については、TS_AS_* 定数を参照してください。

戻り値

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

説明
S_OK
メソッドは成功しました。
CONNECT_E_ADVISELIMIT
シンクインターフェイスへのポインターを取得できませんでした。
E_INVALIDARG
指定されたシンクインターフェイスはサポートされていません。
E_UNEXPECTED
指定されたシンクオブジェクトを取得できませんでした。

解説(Remarks)

同じインターフェイス (punk パラメーターで表されるもの) を指定した 2 回目以降の呼び出しは、dwMask パラメーターの更新要求として扱われます。サーバーはこのような要求に応じてシンクに対し AddRef メソッドを呼び出してはなりません。

サーバーが保持する接続ポイントは 1 つだけです。最初のシンクオブジェクトが削除されるまで、2 つ目のシンクオブジェクトのアドバイズは失敗します。通知が不要になった場合、アプリケーションは ITextStoreACP::UnadviseSink メソッドを使用してシンクオブジェクトの登録を解除してください。

ITextStoreACPServices インターフェイスを取得するには、このメソッドを使用します。

CMyTextEditor ITextStoreACP


STDMETHODIMP CMyTextEditor::AdviseSink(REFIID riid, IUnknown *punk, DWORD dwMask)
{
        HRESULT         hr;
        IUnknown                *punkID;
        typedef struct
        {
        IUnknown                *punkID;
        ITextStoreACPSink       *pTextStoreACPSink;
        DWORD                   dwMask;
        }ADVISE_SINK, *PADVISE_SINK;    
        
        // Determine if the sink interface exists. 
        // Get the pointer to the IUnknown interface and check if the IUnknown 
        // pointer is the same as a pointer to an existing sink. 
        // If the sink exists, update the existing sink with the  
        // dwMask parameters passed to this method.      
        hr = QueryInterface(IID_IUnknown, (LPVOID*)&punkID);

        if(FAILED(hr))
        {
                hr = E_INVALIDARG;
        }       

        if(punkID == m_AdviseSink.punkID)
        {
                m_AdviseSink.dwMask = dwMask;
                hr = S_OK;
        }

        // If the sink does not exist, do the following: 
        // 1. Install a new sink. 
        // 2. Keep the pointer to the IUnknown interface to uniquely 
        //        identify this advise sink. 
        // 3. Set the dwMask parameter of this new sink to the dwMask  
        //    parameters passed to this method. 
        // 4. Increment the reference count. 
        // 5. Release the IUnknown pointer, since this pointer is no 
        //        longer required. 

        if(IsEqualIID(riid, IID_ITextStoreACPSink))
        {
                punk->QueryInterface(IID_ITextStoreACPSink,
                         (LPVOID*)&m_AdviseSink.pTextStoreACPSink);
                m_AdviseSink.punkID = punkID;
                m_AdviseSink.dwMask = dwMask;
                punkID->AddRef();
                punkID->Release();

                hr = S_OK;
        }
        return hr;
        
}
vtbl 4 HRESULT UnadviseSink(IUnknown* punk)

ITextStoreACP::UnadviseSink メソッドは、TSF マネージャーからの通知が不要になったことを示すためにアプリケーションが呼び出します。TSF マネージャーはシンクインターフェイスを解放し、通知を停止します。

punkIUnknown*inシンクオブジェクトへのポインター。NULL は指定できません。

戻り値

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

説明
S_OK
メソッドは成功しました。
CONNECT_E_NOCONNECTION
アクティブなシンクオブジェクトがありません。

解説(Remarks)

新しいシンクオブジェクトを登録する ITextStoreAnchor::AdviseSink メソッドの呼び出しは、必ずこのメソッドの呼び出しと対にしてください。既に登録済みのシンクの dwMask パラメーターを更新するだけの ITextStoreAnchor::AdviseSink メソッド呼び出しについては、ITextStoreAnchor::UnadviseSink メソッドの呼び出しは不要です。

たとえば、シンクオブジェクトを登録するために、アプリケーションはまず ITextStoreAnchor::AdviseSink メソッドを呼び出します。登録後、同じシンクオブジェクトで再度 ITextStoreAnchor::AdviseSink メソッドを呼び出して dwMask パラメーターを変更できます。シンクオブジェクトの登録を解除するには、ITextStoreAnchor::UnadviseSink メソッドを呼び出します。

punk パラメーターは、ITextStoreAnchor::AdviseSink メソッドに最初に渡したポインターと同一の COM アイデンティティを持つ必要があります。

vtbl 5 HRESULT RequestLock(DWORD dwLockFlags, HRESULT* phrSession)

ITextStoreACP::RequestLock メソッドは、ドキュメントを変更するためのドキュメントロックを提供する目的で TSF マネージャーが呼び出します。このメソッドは ITextStoreACPSink::OnLockGranted メソッドを呼び出してドキュメントロックを作成します。

dwLockFlagsDWORDin

要求するロックの種類を指定します。

意味
TS_LF_READ
ドキュメントは読み取り専用ロックを持ち、変更できません。
TS_LF_READWRITE
ドキュメントは読み取り/書き込みロックを持ち、変更できます。
TS_LF_SYNC
このフラグを他のフラグと組み合わせた場合、ドキュメントは同期ロックを持ちます。
phrSessionHRESULT*out

ロック要求が同期の場合、ロック要求の結果を示す ITextStoreAnchorSink::OnLockGranted メソッドからの HRESULT 値を受け取ります。

ロック要求が非同期で結果が TS_S_ASYNC の場合、ドキュメントは非同期ロックを取得します。ロック要求が非同期で結果が TS_E_SYNCHRONOUS の場合、ドキュメントを同期的にロックすることはできません。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_FAIL
原因不明のエラーが発生しました。

解説(Remarks)

このメソッドは ITextStoreACPSink::OnLockGranted メソッドを使用してドキュメントをロックします。アプリケーションは、ITextStoreACP::RequestLock メソッドの内部からドキュメントを変更したり、ITextStoreACPSink::OnTextChange メソッドで変更通知を送信したりしてはなりません。報告すべき保留中の変更がある場合、アプリケーションは非同期のロック要求にのみ応答できます。

アプリケーションに必要なコールバックは 1 回のみであるため、複数の ITextStoreACP::RequestLock メソッド呼び出しをキューに入れようとしてはなりません。ただし、呼び出し側が複数の読み取り要求と 1 つ以上の書き込み要求を行った場合、コールバックは書き込みアクセスで行う必要があります。

同期ロックの要求が成功した場合、その要求は非同期ロックの要求に優先します。同期ロックの要求が失敗した場合は、非同期ロックの要求に優先しません。未処理の非同期要求が存在する場合、実装はその要求に応答する必要があります。

ITextStoreACP::RequestLock メソッドが戻る前にロックが許可された場合、phrSession パラメーターは ITextStoreACPSink::OnLockGranted メソッドが返した HRESULT を受け取ります。呼び出しは成功したもののロックが後から許可される場合、phrSession パラメーターは TS_S_ASYNC フラグを受け取ります。ITextStoreACP::RequestLockS_OK 以外を返した場合、phrSession パラメーターは無視してください。

呼び出し側は、このメソッドを再入的に呼び出してはなりません。ただし、読み取り専用ロックを保持している場合は例外で、非同期の書き込みロックを要求するために再入的に呼び出すことができます。この書き込みロックは、読み取り専用ロックの終了後に許可されます。

ドキュメントロックの詳細については、Document Locks を参照してください。

vtbl 6 HRESULT GetStatus(TS_STATUS* pdcs)

ITextStoreACP::GetStatus メソッドは、ドキュメントの状態を取得します。ドキュメントの状態は TS_STATUS 構造体で返されます。

pdcsTS_STATUS*outドキュメントの状態を格納した TS_STATUS 構造体を受け取ります。NULL は指定できません。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
TS_STATUS パラメーターへのポインターが無効です。
vtbl 7 HRESULT QueryInsert(INT acpTestStart, INT acpTestEnd, DWORD cch, INT* pacpResultStart, INT* pacpResultEnd)

ITextStoreACP::QueryInsert メソッドは、指定された開始文字位置と終了文字位置が有効かどうかを判定します。

acpTestStartINTin挿入するテキストの開始アプリケーション文字位置。
acpTestEndINTin挿入するテキストの終了アプリケーション文字位置。選択されたテキストを置換するのではなく、ある一点に挿入する場合、この値は acpTextStart と等しくなります。
cchDWORDin置換テキストの長さ。
pacpResultStartINT*out挿入されたテキストの新しい開始アプリケーション文字位置を返します。このパラメーターが NULL の場合、指定された位置にテキストを挿入できません。この値はドキュメントの範囲外にはできません。
pacpResultEndINT*out挿入されたテキストの新しい終了アプリケーション文字位置を返します。このパラメーターが NULL の場合、pacpResultStartNULL に設定され、指定された位置にテキストを挿入できません。この値はドキュメントの範囲外にはできません。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_FAIL
原因不明のエラーが発生しました。
E_INVALIDARG
acpTestStart または acpTestEnd パラメーターが無効です。

解説(Remarks)

pacpResultStartpacpResultEnd の値は、アプリケーションがドキュメントにテキストをどのように挿入するかによって異なります。pacpResultStartpacpResultEndacpTextStart と同じ場合、挿入後にカーソルは挿入テキストの先頭に置かれます。pacpResultStartpacpResultEndacpTextEnd と同じ場合、挿入後にカーソルは挿入テキストの末尾に置かれます。pacpResultStartpacpResultEnd の差が挿入テキストの長さと等しい場合、挿入後に挿入テキストが選択表示されます。

vtbl 8 HRESULT GetSelection(DWORD ulIndex, DWORD ulCount, TS_SELECTION_ACP* pSelection, DWORD* pcFetched)

ITextStoreACP::GetSelection メソッドは、ドキュメント内のテキスト選択範囲の文字位置を返します。このメソッドは複数のテキスト選択範囲をサポートします。呼び出し側は、このメソッドを呼び出す前にドキュメントの読み取り専用ロックを取得している必要があります。

ulIndexDWORDin処理を開始するテキスト選択範囲を指定します。このパラメーターに TF_DEFAULT_SELECTION 定数を指定した場合、入力選択範囲から処理が開始されます。
ulCountDWORDin返す選択範囲の最大数を指定します。
pSelectionTS_SELECTION_ACP*out選択されたテキストのスタイル、開始文字位置、終了文字位置を受け取ります。これらの値は TS_SELECTION_ACP 構造体に格納されます。
pcFetchedDWORD*out返された pSelection 構造体の数を受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_NOLOCK
呼び出し側がドキュメントの読み取り専用ロックを保持していません。
TS_E_NOSELECTION
ドキュメントに選択範囲がありません。
vtbl 9 HRESULT SetSelection(DWORD ulCount, TS_SELECTION_ACP* pSelection)

ITextStoreACP::SetSelection メソッドは、ドキュメント内のテキストを選択します。アプリケーションは、このメソッドを呼び出す前にドキュメントの読み取り/書き込みロックを取得している必要があります。

ulCountDWORDinpSelection に含まれるテキスト選択範囲の数を指定します。
pSelectionTS_SELECTION_ACP*in

TS_SELECTION_ACP 構造体により、選択するテキストのスタイル、開始文字位置、終了文字位置を指定します。

開始文字位置と終了文字位置が等しい場合、このメソッドはその文字位置にキャレットを配置します。ドキュメント内に同時に存在できるキャレットは 1 つだけです。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_FAIL
原因不明のエラーが発生しました。
TF_E_INVALIDPOS
指定された文字位置がドキュメント内のテキストの範囲を超えています。
TF_E_NOLOCK
呼び出し側が読み取り/書き込みロックを保持していません。
vtbl 10 HRESULT GetText(INT acpStart, INT acpEnd, LPWSTR pchPlain, DWORD cchPlainReq, DWORD* pcchPlainRet, TS_RUNINFO* prgRunInfo, DWORD cRunInfoReq, DWORD* pcRunInfoRet, INT* pacpNext)

ITextStoreACP::GetText メソッドは、指定された文字位置のテキストに関する情報を返します。このメソッドは表示テキストと非表示テキストを返し、テキストに埋め込みデータが付随しているかどうかを示します。

acpStartINTin開始文字位置を指定します。
acpEndINTin終了文字位置を指定します。このパラメーターが -1 の場合、テキストストア内のすべてのテキストを返します。
pchPlainLPWSTRoutプレーンテキストデータを受け取るバッファーを指定します。このパラメーターが NULL の場合、cchPlainReq パラメーターは 0 でなければなりません。
cchPlainReqDWORDinメソッドに渡すプレーンテキストの文字数を指定します。
pcchPlainRetDWORD*outプレーンテキストバッファーにコピーされた文字数を受け取ります。このパラメーターに NULL は指定できません。値が不要な場合でもパラメーターを指定してください。
prgRunInfoTS_RUNINFO*outTS_RUNINFO 構造体の配列を受け取ります。NULL にできるのは cRunInfoReq = 0 の場合のみです。
cRunInfoReqDWORDinテキストランバッファーのサイズを文字数で指定します。
pcRunInfoRetDWORD*outテキストランバッファーに書き込まれた TS_RUNINFO 構造体の数を受け取ります。このパラメーターに NULL は指定できません。
pacpNextINT*out次の未読文字の文字位置を受け取ります。NULL は指定できません。

戻り値

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

説明
S_OK
メソッドは成功しました。
TF_E_INVALIDPOS
acpStart または acpEnd パラメーターがドキュメントのテキストの範囲外です。
TF_E_NOLOCK
呼び出し側がドキュメントの読み取り専用ロックを保持していません。

解説(Remarks)

このメソッドを使用する呼び出し側は、ITextStoreACP::RequestLock メソッドを呼び出してドキュメントの読み取り専用ロックを取得している必要があります。読み取り専用ロックがない場合、このメソッドは失敗し、TF_E_NOLOCK を返します。

また、アプリケーションは内部的な理由でメソッドの戻り値を切り詰めることがあります。呼び出し側は、必要な戻り値を得るために、返された文字数とテキストラン数を注意深く確認してください。戻り値が不完全な場合は、完全になるまでメソッドを繰り返し呼び出してください。

呼び出し側は、cRunInfoReq パラメーターを 0 に、prgRunInfo パラメーターを NULL に設定することで、プレーンテキストのみを要求できます。また、cchPlainReq パラメーターを 0 に、pchPlain パラメーターを NULL に設定することで、テキストランデータのみを要求できます。ただし、その場合でも pcchPlainRet には有効な非 NULL 値を指定する必要があります (このパラメーターを使用しない場合でも同様です)。

acpEnd が -1 の場合は、ストリームの末尾が指定されたものとして扱ってください。それ以外の場合、この値は 0 以上になります。

終了時、pacpNext には、戻り値で参照されなかったストリーム内の次の文字の文字位置を設定してください。呼び出し側は、複数回の ITextStoreACP::GetText 呼び出しでテキストを高速に走査するためにこれを使用します。

vtbl 11 HRESULT SetText(DWORD dwFlags, INT acpStart, INT acpEnd, LPWSTR pchText, DWORD cch, TS_TEXTCHANGE* pChange)

ITextStoreACP::SetText メソッドは、指定された文字位置にテキスト選択範囲を設定します。

dwFlagsDWORDinTS_ST_CORRECTION の値が設定されている場合、テキストは既存の内容の変換 (訂正) であり、.wav ファイルのデータや言語識別子などの特別なテキストマークアップ情報 (メタデータ) が保持されます。保持するマークアップ情報の種類はクライアントが定義します。
acpStartINTin置換対象テキストの開始文字位置を指定します。
acpEndINTin置換対象テキストの終了文字位置を指定します。値が 1 の場合、このパラメーターは無視されます。
pchTextLPWSTRin置換テキストへのポインターを指定します。テキストの文字数は cch パラメーターで指定するため、文字列は NULL 終端である必要はありません。
cchDWORDin置換テキストの文字数を指定します。
pChangeTS_TEXTCHANGE*out

次のデータを持つ TS_TEXTCHANGE 構造体へのポインター。

意味
acpStart
テキストがドキュメントに挿入される前の開始アプリケーション文字位置。
acpOldEnd
テキストがドキュメントに挿入される前の終了位置。挿入点の場合、この値は acpStart と同じです。この値が acpStart と異なる場合、テキスト挿入前にテキストが選択されていたことを意味します。
acpNewEnd
テキスト挿入後の終了位置。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_INVALIDPOS
acpStart または acpEnd パラメーターがドキュメントのテキストの範囲外です。
TS_E_NOLOCK
呼び出し側が読み取り/書き込みロックを保持していません。
TS_E_READONLY
ドキュメントは読み取り専用です。内容を変更できません。
TS_E_REGION
リージョン境界をまたいでテキストを変更しようとしました。

解説(Remarks)

アプリケーションは、コンポジション (変換中の文字列) を開始する際、まず ITextStoreACP::InsertTextAtSelection を使用してください。ITextStoreACP::SetText は既存のコンポジション内でのみ使用します。SetText の呼び出し時にアクティブなコンポジションが存在しない場合、TSF マネージャーは SetText の呼び出しを包含するだけの短命なコンポジションを作成します。

acpStartacpEnd の文字位置は、ドキュメントの範囲外にはできません。

アプリケーションは、このメソッドへの応答として ITextStoreACPSink::OnTextChange メソッドを呼び出してはなりません。

このメソッドは ITextStoreACP::SetSelection メソッドを呼び出して、変更対象のテキストを選択する必要があります。ITextStoreACP::SetSelection メソッドが正常に実行された後、このメソッドは ITextStoreACP::InsertTextAtSelection メソッドを呼び出して実際のテキスト変更を行います。

vtbl 12 HRESULT GetFormattedText(INT acpStart, INT acpEnd, IDataObject** ppDataObject)

ITextStoreACP::GetFormattedText メソッドは、指定されたテキスト文字列に関する書式付きテキストデータを返します。呼び出し側は、このメソッドを呼び出す前にドキュメントの読み取り/書き込みロックを取得している必要があります。

acpStartINTinドキュメント内で取得するテキストの開始文字位置を指定します。
acpEndINTinドキュメント内で取得するテキストの終了文字位置を指定します。値が 1 の場合、このパラメーターは無視されます。
ppDataObjectIDataObject**out書式付きテキストを格納した IDataObject オブジェクトへのポインターを受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_NOLOCK
呼び出し側がドキュメントの読み取り/書き込みロックを保持していません。
vtbl 13 HRESULT GetEmbedded(INT acpPos, GUID* rguidService, GUID* riid, IUnknown** ppunk)

埋め込みドキュメントを取得します。(ITextStoreACP.GetEmbedded)

acpPosINTinオブジェクトを取得する、ドキュメント内の文字位置を格納します。
rguidServiceGUID*in

取得するオブジェクトの要求形式を定義する GUID 値を格納します。次のいずれかの値を指定できます。

意味
GUID_TS_SERVICE_DATAOBJECT
オブジェクトを IDataObject オブジェクトとして取得します。
GUID_TS_SERVICE_ACCESSIBLE
オブジェクトを Accessible オブジェクトとして取得します。
GUID_TS_SERVICE_ACTIVEX
オブジェクトを ActiveX オブジェクトとして取得します。
riidGUID*in要求するインターフェイスの種類を指定します。
ppunkIUnknown**out要求されたインターフェイスを受け取る IUnknown ポインターへのポインター。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
1 つ以上のパラメーターが無効です。
E_NOTIMPL
アプリケーションは埋め込みオブジェクトをサポートしていません。
TF_E_INVALIDPOS
acpPos がドキュメント内にありません。
TS_E_NOINTERFACE
要求されたインターフェイスの種類はサポートされていません。
TS_E_NOLOCK
呼び出し側が読み取り専用ロックを保持していません。
TS_E_NOOBJECT
acpPos に埋め込みオブジェクトがありません。
TS_E_NOSERVICE
rguidService で指定されたサービスの種類はサポートされていません。

解説(Remarks)

呼び出し側は QueryInterface を使用して適切なインターフェイスを問い合わせる必要があります。対象となるインターフェイスには、埋め込みドキュメントやコントロールに関連する IOleObjectIDataObjectIViewObjectIPersistStorageIOleCacheIDispatch などがあります。

vtbl 14 HRESULT QueryInsertEmbedded(GUID* pguidService, FORMATETC* pFormatEtc, BOOL* pfInsertable)

指定されたオブジェクトをドキュメントに挿入できるかどうかを示す値を取得します。(ITextStoreACP.QueryInsertEmbedded)

pguidServiceGUID*inオブジェクトの種類へのポインター。NULL を指定できます。
pFormatEtcFORMATETC*inオブジェクトの形式データを格納した FORMATETC 構造体へのポインター。pguidService パラメーターが NULL の場合、このパラメーターに NULL は指定できません。
pfInsertableBOOL*outオブジェクトの種類をドキュメントに挿入できる場合は TRUE、挿入できない場合は FALSE を受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
pFormatEtc パラメーターが NULL です。

解説(Remarks)

ドキュメントがサポートするクリップボード形式は、アプリケーションに依存します。

vtbl 15 HRESULT InsertEmbedded(DWORD dwFlags, INT acpStart, INT acpEnd, IDataObject* pDataObject, TS_TEXTCHANGE* pChange)

指定された文字位置に埋め込みオブジェクトを挿入します。(ITextStoreACP.InsertEmbedded)

dwFlagsDWORDinTS_IE_CORRECTION でなければなりません。
acpStartINTinオブジェクトを挿入する開始文字位置を格納します。
acpEndINTinオブジェクトを挿入する終了文字位置を格納します。
pDataObjectIDataObject*in挿入するオブジェクトに関するデータを格納した IDataObject インターフェイスへのポインター。
pChangeTS_TEXTCHANGE*out変更されたテキストに関するデータを受け取る TS_TEXTCHANGE 構造体へのポインター。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
1 つ以上のパラメーターが無効です。
E_NOTIMPL
アプリケーションは埋め込みオブジェクトをサポートしていません。
TS_E_FORMAT
アプリケーションは pDataObject に含まれるデータ型をサポートしていません。
TS_E_INVALIDPOS
acpStart または acpEnd (あるいはその両方) がドキュメント内にありません。
TS_E_NOLOCK
呼び出し側が読み取り/書き込みロックを保持していません。
vtbl 16 HRESULT InsertTextAtSelection(DWORD dwFlags, LPWSTR pchText, DWORD cch, INT* pacpStart, INT* pacpEnd, TS_TEXTCHANGE* pChange)

ITextStoreACP::InsertTextAtSelection メソッドは、挿入点または選択範囲にテキストを挿入します。呼び出し側は、テキストを挿入する前にドキュメントの読み取り/書き込みロックを取得している必要があります。

dwFlagsDWORDin

pacpStart および pacpEnd パラメーターと TS_TEXTCHANGE 構造体がテキスト挿入の結果を格納するかどうかを指定します。

TF_IAS_NOQUERYTF_IAS_QUERYONLY フラグは組み合わせられません。

意味
0
テキストの挿入が行われ、pacpStart および pacpEnd パラメーターにテキスト挿入の結果が格納されます。このフラグを使用する場合、TS_TEXTCHANGE 構造体を設定する必要があります。
TF_IAS_NOQUERY
テキストが挿入され、pacpStart および pacpEnd パラメーターの値は NULL にできます。TS_TEXTCHANGE 構造体は設定する必要があります。テキスト挿入の結果を確認するには、このフラグを使用します。
TF_IAS_QUERYONLY
テキストは挿入されず、pacpStart および pacpEnd パラメーターの値にテキスト挿入の結果が格納されます。これらのパラメーターの値は、アプリケーションがドキュメントへのテキスト挿入をどのように実装しているかによって異なります。詳細については「解説」を参照してください。実際にテキストを挿入せずにテキスト挿入の結果を確認するには、このフラグを使用します。このフラグを使用する場合、TS_TEXTCHANGE 構造体を設定する必要はありません。
pchTextLPWSTRinドキュメントに挿入する文字列へのポインター。文字列は NULL 終端でもかまいません。
cchDWORDinテキストの長さを指定します。
pacpStartINT*outテキスト挿入が行われる開始アプリケーション文字位置へのポインター。
pacpEndINT*outテキスト挿入が行われる終了アプリケーション文字位置へのポインター。挿入点の場合、このパラメーターの値は pacpStart パラメーターの値と同じです。
pChangeTS_TEXTCHANGE*out

次のメンバーを持つ TS_TEXTCHANGE 構造体へのポインター。

意味
acpStart
テキストがドキュメントに挿入される前の開始アプリケーション文字位置。
acpOldEnd
テキストがドキュメントに挿入される前の終了アプリケーション文字位置。挿入点の場合、この値は acpStart と同じです。この値が acpStart と異なる場合、テキスト挿入前にテキストが選択されていたことを意味します。
acpNewEnd
テキスト挿入後の終了位置。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_NOLOCK
呼び出し側がドキュメントのロックを保持していません。
E_INVALIDARG
pchText パラメーターが無効です。

解説(Remarks)

pacpStart および pacpEnd パラメーターの値は、クライアントアプリケーションがドキュメントにテキストをどのように挿入するかによって異なります。たとえば、テキスト挿入後にアプリケーションが挿入テキストの先頭にカーソルを設定する場合、pacpStart および pacpEnd パラメーターの値は TS_TEXTCHANGE 構造体の acpStart メンバーと同じになります。

アプリケーションは、このメソッドへの応答として ITextStoreACPSink::OnTextChange メソッドを呼び出してはなりません。

vtbl 17 HRESULT InsertEmbeddedAtSelection(DWORD dwFlags, IDataObject* pDataObject, INT* pacpStart, INT* pacpEnd, TS_TEXTCHANGE* pChange)

ITextStoreACP::InsertEmbeddedAtSelection メソッドは、挿入点または選択範囲に IDataObject オブジェクトを挿入します。このメソッドを呼び出すクライアントは、ドキュメントに IDataObject オブジェクトを挿入する前に読み取り/書き込みロックを取得している必要があります。

dwFlagsDWORDin

pacpStart および pacpEnd パラメーターと TS_TEXTCHANGE 構造体がオブジェクト挿入の結果を格納するかどうかを指定します。

TF_IAS_NOQUERYTF_IAS_QUERYONLY フラグは組み合わせられません。

意味
0
テキストの挿入が行われ、pacpStart および pacpEnd パラメーターにテキスト挿入の結果が格納されます。このフラグを使用する場合、TS_TEXTCHANGE 構造体を設定する必要があります。
TF_IAS_NOQUERY
テキストが挿入され、pacpStart および pacpEnd パラメーターの値は NULL にできます。TS_TEXTCHANGE 構造体は設定する必要があります。テキスト挿入の結果が不要な場合は、このフラグを使用します。
TF_IAS_QUERYONLY
テキストは挿入されず、pacpStart および pacpEnd パラメーターの値にテキスト挿入の結果が格納されます。これらのパラメーターの値は、アプリケーションがドキュメントへのテキスト挿入をどのように実装しているかによって異なります。詳細については「解説」を参照してください。

実際にテキストを挿入せずにテキスト挿入の結果を確認する場合 (たとえば、選択範囲を折りたたむ、あるいは調整した結果を予測する場合) に、このフラグを使用します。このフラグを使用する場合、TS_TEXTCHANGE 構造体を設定する必要はありません。

pDataObjectIDataObject*in挿入する IDataObject オブジェクトへのポインター。
pacpStartINT*outオブジェクト挿入が行われる開始アプリケーション文字位置へのポインター。
pacpEndINT*outオブジェクト挿入が行われる終了アプリケーション文字位置へのポインター。挿入点の場合、このパラメーターの値は pacpStart パラメーターの値と同じになります。
pChangeTS_TEXTCHANGE*out

次のメンバーを持つ TS_TEXTCHANGE 構造体へのポインター。

意味
acpStart
オブジェクトがドキュメントに挿入される前の開始アプリケーション文字位置。
acpOldEnd
オブジェクトがドキュメントに挿入される前の終了アプリケーション文字位置。挿入点の場合、この値は acpStart と同じです。この値が acpStart と異なる場合、オブジェクト挿入前にテキストが選択されていたことを意味します。
acpNewEnd
オブジェクト挿入後の終了アプリケーション文字位置。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
pchText パラメーターが無効です。
TS_E_NOLOCK
呼び出し側がドキュメントのロックを保持していません。

解説(Remarks)

pacpStart および pacpEnd パラメーターの値は、クライアントアプリケーションがドキュメントにオブジェクトをどのように挿入するかによって異なります。たとえば、オブジェクト挿入後にアプリケーションがオブジェクトの先頭にカーソルを設定する場合、pacpStart および pacpEnd パラメーターの値は TS_TEXTCHANGE 構造体の acpStart メンバーと同じになります。

vtbl 18 HRESULT RequestSupportedAttrs(DWORD dwFlags, DWORD cFilterAttrs, GUID* paFilterAttrs)

ドキュメントでサポートされている属性を取得します。(ITextStoreACP.RequestSupportedAttrs)

dwFlagsDWORDin後続の ITextStoreAnchor::RetrieveRequestedAttrs メソッド呼び出しがサポート対象の属性を含むかどうかを指定します。TS_ATTR_FIND_WANT_VALUE フラグを指定した場合、後続の ITextStoreAnchor::RetrieveRequestedAttrs 呼び出し後、既定の属性値は TS_ATTRVAL 構造体内の値になります。このパラメーターにその他のフラグを指定した場合、メソッドは属性がサポートされていることを確認するだけで、TS_ATTRVAL 構造体の varValue メンバーは VT_EMPTY に設定されます。
cFilterAttrsDWORDin取得するサポート対象属性の数を指定します。
paFilterAttrsGUID*in確認する属性を指定する TS_ATTRID データ型へのポインター。他の属性がサポートされている場合でも、メソッドは TS_ATTRID で指定された属性のみを返します。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_FAIL
原因不明のエラーが発生しました。
E_OUTOFMEMORY
操作を完了するのに十分なメモリを割り当てられませんでした。
vtbl 19 HRESULT RequestAttrsAtPosition(INT acpPos, DWORD cFilterAttrs, GUID* paFilterAttrs, DWORD dwFlags)

指定された文字位置のテキスト属性を取得します。(ITextStoreACP.RequestAttrsAtPosition)

acpPosINTinドキュメント内のアプリケーション文字位置を指定します。
cFilterAttrsDWORDin取得する属性の数を指定します。
paFilterAttrsGUID*in確認する属性を指定する TS_ATTRID データ型へのポインター。
dwFlagsDWORDin0 でなければなりません。

戻り値

このメソッドに戻り値はありません。

vtbl 20 HRESULT RequestAttrsTransitioningAtPosition(INT acpPos, DWORD cFilterAttrs, GUID* paFilterAttrs, DWORD dwFlags)

指定された文字位置で遷移するテキスト属性を取得します。(ITextStoreACP.RequestAttrsTransitioningAtPosition)

acpPosINTinドキュメント内のアプリケーション文字位置を指定します。
cFilterAttrsDWORDin取得する属性の数を指定します。
paFilterAttrsGUID*in確認する属性を指定する TS_ATTRID データ型へのポインター。
dwFlagsDWORDin

ITextStoreACP::RetrieveRequestedAttrs メソッドの呼び出しに対する属性を指定します。このパラメーターを設定しない場合、メソッドは指定位置で開始する属性を返します。このパラメーターに指定できるその他の値は次のとおりです。

意味
TS_ATTR_FIND_WANT_END
指定されたアプリケーション文字位置で終了する属性を取得します。
TS_ATTR_FIND_WANT_VALUE
属性に加えて属性の値も取得します。属性値は、ITextStoreACP::RetrieveRequestedAttrs メソッドの呼び出し時に TS_ATTRVAL 構造体の varValue メンバーに格納されます。

戻り値

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

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

解説(Remarks)

「This is italic text.」という文では、斜体属性は単語 italic の前で開始し、単語 text の後で終了します。

dwFlagsTS_ATTR_FIND_WANT_END フラグが設定されている場合、アンカー位置に終了遷移があるため、メソッドはテキスト「italic <anchor>normal」に対して斜体属性を返します。

vtbl 21 HRESULT FindNextAttrTransition(INT acpStart, INT acpHalt, DWORD cFilterAttrs, GUID* paFilterAttrs, DWORD dwFlags, INT* pacpNext, BOOL* pfFound, INT* plFoundOffset)

ITextStoreACP::FindNextAttrTransition メソッドは、属性値の遷移が発生する文字位置を判定します。確認する属性はアプリケーションに依存します。

acpStartINTin属性遷移の検索を開始する文字位置を指定します。
acpHaltINTin属性遷移の検索を終了する文字位置を指定します。
cFilterAttrsDWORDin確認する属性の数を指定します。
paFilterAttrsGUID*in確認する属性を指定する TS_ATTRID データ型へのポインター。
dwFlagsDWORDin

属性遷移を検索する方向を指定します。既定では、メソッドは前方に検索します。

意味
TS_ATTR_FIND_BACKWARDS
メソッドは後方に検索します。
TS_ATTR_FIND_WANT_OFFSET
plFoundOffset パラメーターが、acpStart から属性遷移までの文字オフセットを受け取ります。
pacpNextINT*out属性遷移を確認する次の文字位置を受け取ります。
pfFoundBOOL*out属性遷移が見つかった場合はブール値 TRUE、見つからなかった場合は FALSE を受け取ります。
plFoundOffsetINT*out属性遷移の文字位置 (ACP 位置ではありません) を受け取ります。dwFlagsTS_ATTR_FIND_WANT_OFFSET フラグが設定されている場合は、acpStart から属性遷移までの文字オフセットを受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_INVALIDPOS
指定された文字位置がドキュメント内のテキストの範囲を超えています。

解説(Remarks)

注意 アプリケーションが ITextStoreACP::FindNextAttrTransition を実装していない場合、ITfReadOnlyProperty::EnumRangesE_FAIL で失敗します。
vtbl 22 HRESULT RetrieveRequestedAttrs(DWORD ulCount, TS_ATTRVAL* paAttrVals, DWORD* pcFetched)

属性要求メソッドの呼び出しによって返された属性を取得します。(ITextStoreACP.RetrieveRequestedAttrs)

ulCountDWORDin取得するサポート対象属性の数を指定します。
paAttrValsTS_ATTRVAL*outサポート対象の属性を受け取る TS_ATTRVAL 構造体へのポインター。この構造体のメンバーは、呼び出し元メソッドの dwFlags パラメーターによって異なります。
pcFetchedDWORD*outサポート対象の属性の数を受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
vtbl 23 HRESULT GetEndACP(INT* pacp)

ITextStoreACP::GetEndACP メソッドは、ドキュメント内の文字数を返します。

pacpINT*outドキュメント内の最後の文字の文字位置に 1 を加えた値を受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_NOTIMPL
アプリケーションがこのメソッドを実装していません。これは通常、終了位置の算出に過大なリソースが必要であることを示します。終了位置が必要な場合は ITextStoreACP::GetText を使用して算出できますが、この操作もディスクから任意の大きさのメモリをページインする、メモリを多く消費する操作になる可能性があります。
TS_E_NOLOCK
呼び出し側が読み取り専用ロックを保持していません。
vtbl 24 HRESULT GetActiveView(DWORD* pvcView)

ITextStoreACP::GetActiveView メソッドは、現在アクティブなビューを示す TsViewCookie データ型を返します。

pvcViewDWORD*out現在アクティブなビューを示す TsViewCookie データ型を受け取ります。

戻り値

このメソッドに戻り値はありません。

vtbl 25 HRESULT GetACPFromPoint(DWORD vcView, POINT* ptScreen, DWORD dwFlags, INT* pacp)

ITextStoreACP::GetACPFromPoint メソッドは、スクリーン座標の点をアプリケーション文字位置に変換します。

vcViewDWORDinコンテキストのビューを指定します。
ptScreenPOINT*in点のスクリーン座標を格納した POINT 構造体へのポインター。
dwFlagsDWORDin

文字の境界ボックスに対する点のスクリーン座標に基づいて、返す文字位置を指定します。既定では、返される文字位置は、点のスクリーン座標を含む文字の境界ボックスです。点が文字の境界ボックスの外にある場合、メソッドは NULL または TF_E_INVALIDPOINT を返します。このパラメーターのその他のビットフラグは次のとおりです。

これらのビットフラグは組み合わせられます。

意味
GXFPF_ROUND_NEAREST
点のスクリーン座標が文字の境界ボックスに含まれる場合、返される文字位置は、点のスクリーン座標に最も近い境界エッジになります。
GXFPF_NEAREST
点のスクリーン座標が文字の境界ボックスに含まれない場合、最も近い文字位置が返されます。
pacpINT*out点のスクリーン座標に対応する文字位置を受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_INVALIDPOINT
ptScreen パラメーターがいずれの文字の境界ボックス内にもありません。
TS_E_NOLAYOUT
アプリケーションがテキストレイアウトを算出していません。

解説(Remarks)

Point 1 is in character bounding box and point 2 is outside the character bounding box. 点 1 のスクリーン座標は文字位置 0 の文字の境界ボックス内にあるため、既定の場合、または dwFlags パラメーターに GXFPF_NEAREST を設定した場合、pacp パラメーターは 0 になります。点 1 に対して dwFlags パラメーターに GXFPF_ROUND_NEAREST を設定した場合、点 1 のスクリーン座標はレンジ位置 1 に最も近いため、pacp パラメーターは 1 になります。レンジ位置 1 は、文字位置 1 の開始レンジ位置です。

点 2 のスクリーン座標については、点 2 が文字の境界ボックスの外にあるため、既定の場合、または dwFlags パラメーターに GXFPF_NEAREST を設定した場合、メソッドは TF_E_INVALIDPOINT を返します。dwFlags パラメーターに GXFPF_ROUND_NEAREST を設定した場合、点 2 のスクリーン座標に最も近い文字位置は文字位置 1 であるため、pacp パラメーターは 1 になります。

点 1

点 2
vtbl 26 HRESULT GetTextExt(DWORD vcView, INT acpStart, INT acpEnd, RECT* prc, BOOL* pfClipped)

ITextStoreACP::GetTextExt メソッドは、指定された文字位置のテキストの境界ボックスをスクリーン座標で返します。呼び出し側は、このメソッドを呼び出す前にドキュメントの読み取り専用ロックを取得している必要があります。

vcViewDWORDinコンテキストのビューを指定します。
acpStartINTinドキュメント内で取得するテキストの開始文字位置を指定します。
acpEndINTinドキュメント内で取得するテキストの終了文字位置を指定します。
prcRECT*out指定された文字位置のテキストの境界ボックスをスクリーン座標で受け取ります。
pfClippedBOOL*out境界ボックス内のテキストがクリップされているかどうかを示すブール値を受け取ります。このパラメーターが TRUE の場合、境界ボックスにはクリップされたテキストが含まれ、要求されたテキスト範囲全体は含まれません。要求された範囲が表示されていないため、境界ボックスがクリップされています。

戻り値

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

説明
S_OK
メソッドは成功しました。
TS_E_INVALIDARG
指定された開始文字位置と終了文字位置が等しいです。
TS_E_INVALIDPOS
acpStart および acpEnd パラメーターで指定された範囲が、ドキュメントの先頭または末尾を超えています。
TS_E_NOLAYOUT
アプリケーションがテキストレイアウトを算出していません。
TS_E_NOLOCK
呼び出し側がドキュメントの読み取り専用ロックを保持していません。

解説(Remarks)

ドキュメントウィンドウが最小化されている場合、または指定されたテキストが現在表示されていない場合、メソッドは prc パラメーターを {0,0,0,0} に設定して S_OK を返します。

vtbl 27 HRESULT GetScreenExt(DWORD vcView, RECT* prc)

ITextStoreACP::GetScreenExt メソッドは、テキストストリームが描画される表示面の境界ボックスのスクリーン座標を返します。

vcViewDWORDinコンテキストのビューを指定します。
prcRECT*outドキュメントの表示面の境界ボックスのスクリーン座標を受け取ります。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
指定された vcView パラメーターが無効です。

解説(Remarks)

テキストが現在表示されていない場合 (たとえばドキュメントウィンドウが最小化されている場合)、prc パラメーターは { 0, 0, 0, 0 } に設定されます。

vtbl 28 HRESULT GetWnd(DWORD vcView, HWND* phwnd)

ITextStoreACP::GetWnd メソッドは、現在のドキュメントに対応するウィンドウのハンドルを返します。

vcViewDWORDin現在のドキュメントに対応する TsViewCookie データ型を指定します。
phwndHWND*out現在のドキュメントに対応するウィンドウのハンドルへのポインターを受け取ります。ドキュメントに対応するウィンドウハンドルがない場合、このパラメーターは NULL になることがあります。

戻り値

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

説明
S_OK
メソッドは成功しました。
E_INVALIDARG
TsViewCookie データ型が無効です。

解説(Remarks)

ドキュメントがメモリ内に存在するものの画面に表示されていない場合、またはドキュメントがウィンドウレスコントロールであり、そのコントロールがウィンドウレスコントロールの所有者のウィンドウハンドルを認識できない場合、ドキュメントには対応するウィンドウハンドルが存在しないことがあります。呼び出し側は、メソッドが成功した場合でも phwnd パラメーターが非 NULL の値を受け取ると想定してはなりません。呼び出し側は phwnd パラメーターとして NULL 値を受け取ることもあります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITextStoreACP "{28888FE3-C2A0-483A-A3EA-8CB1CE51FF3D}"
#usecom global ITextStoreACP IID_ITextStoreACP "{}"
#comfunc global ITextStoreACP_AdviseSink                           3 var,sptr,int
#comfunc global ITextStoreACP_UnadviseSink                         4 sptr
#comfunc global ITextStoreACP_RequestLock                          5 int,var
#comfunc global ITextStoreACP_GetStatus                            6 var
#comfunc global ITextStoreACP_QueryInsert                          7 int,int,int,var,var
#comfunc global ITextStoreACP_GetSelection                         8 int,int,var,var
#comfunc global ITextStoreACP_SetSelection                         9 int,var
#comfunc global ITextStoreACP_GetText                              10 int,int,var,int,var,var,int,var,var
#comfunc global ITextStoreACP_SetText                              11 int,int,int,wstr,int,var
#comfunc global ITextStoreACP_GetFormattedText                     12 int,int,sptr
#comfunc global ITextStoreACP_GetEmbedded                          13 int,var,var,sptr
#comfunc global ITextStoreACP_QueryInsertEmbedded                  14 var,var,var
#comfunc global ITextStoreACP_InsertEmbedded                       15 int,int,int,sptr,var
#comfunc global ITextStoreACP_InsertTextAtSelection                16 int,wstr,int,var,var,var
#comfunc global ITextStoreACP_InsertEmbeddedAtSelection            17 int,sptr,var,var,var
#comfunc global ITextStoreACP_RequestSupportedAttrs                18 int,int,var
#comfunc global ITextStoreACP_RequestAttrsAtPosition               19 int,int,var,int
#comfunc global ITextStoreACP_RequestAttrsTransitioningAtPosition  20 int,int,var,int
#comfunc global ITextStoreACP_FindNextAttrTransition               21 int,int,int,var,int,var,var,var
#comfunc global ITextStoreACP_RetrieveRequestedAttrs               22 int,var,var
#comfunc global ITextStoreACP_GetEndACP                            23 var
#comfunc global ITextStoreACP_GetActiveView                        24 var
#comfunc global ITextStoreACP_GetACPFromPoint                      25 int,var,int,var
#comfunc global ITextStoreACP_GetTextExt                           26 int,int,int,var,var
#comfunc global ITextStoreACP_GetScreenExt                         27 int,var
#comfunc global ITextStoreACP_GetWnd                               28 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。