ITextStoreACP
COM公式ドキュメント
ITextStoreACP インターフェイスはアプリケーションが実装し、TSF マネージャーが TSF のテキストストリームまたはテキストストア (text store) を操作するために使用します。
メソッド 26
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ITextStoreACP::AdviseSink メソッドは、ITextStoreACPSink インターフェイスによるアドバイズシンクを新規にインストールするか、既存のアドバイズシンクを変更します。シンクインターフェイスは punk パラメーターで指定します。
| riid | GUID* | in | シンクインターフェイスを指定します。 |
| punk | IUnknown* | in | シンクインターフェイスへのポインター。NULL は指定できません。 |
| dwMask | DWORD | in | アドバイズシンクに通知するイベントを指定します。指定可能な値の詳細については、TS_AS_* 定数を参照してください。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| シンクインターフェイスへのポインターを取得できませんでした。 | |
| 指定されたシンクインターフェイスはサポートされていません。 | |
| 指定されたシンクオブジェクトを取得できませんでした。 |
解説(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;
}
ITextStoreACP::UnadviseSink メソッドは、TSF マネージャーからの通知が不要になったことを示すためにアプリケーションが呼び出します。TSF マネージャーはシンクインターフェイスを解放し、通知を停止します。
| punk | IUnknown* | in | シンクオブジェクトへのポインター。NULL は指定できません。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| アクティブなシンクオブジェクトがありません。 |
解説(Remarks)
新しいシンクオブジェクトを登録する ITextStoreAnchor::AdviseSink メソッドの呼び出しは、必ずこのメソッドの呼び出しと対にしてください。既に登録済みのシンクの dwMask パラメーターを更新するだけの ITextStoreAnchor::AdviseSink メソッド呼び出しについては、ITextStoreAnchor::UnadviseSink メソッドの呼び出しは不要です。
たとえば、シンクオブジェクトを登録するために、アプリケーションはまず ITextStoreAnchor::AdviseSink メソッドを呼び出します。登録後、同じシンクオブジェクトで再度 ITextStoreAnchor::AdviseSink メソッドを呼び出して dwMask パラメーターを変更できます。シンクオブジェクトの登録を解除するには、ITextStoreAnchor::UnadviseSink メソッドを呼び出します。
punk パラメーターは、ITextStoreAnchor::AdviseSink メソッドに最初に渡したポインターと同一の COM アイデンティティを持つ必要があります。
ITextStoreACP::RequestLock メソッドは、ドキュメントを変更するためのドキュメントロックを提供する目的で TSF マネージャーが呼び出します。このメソッドは ITextStoreACPSink::OnLockGranted メソッドを呼び出してドキュメントロックを作成します。
| dwLockFlags | DWORD | in | 要求するロックの種類を指定します。
| ||||||||
| phrSession | HRESULT* | out | ロック要求が同期の場合、ロック要求の結果を示す ITextStoreAnchorSink::OnLockGranted メソッドからの HRESULT 値を受け取ります。 ロック要求が非同期で結果が TS_S_ASYNC の場合、ドキュメントは非同期ロックを取得します。ロック要求が非同期で結果が TS_E_SYNCHRONOUS の場合、ドキュメントを同期的にロックすることはできません。 |
戻り値
解説(Remarks)
このメソッドは ITextStoreACPSink::OnLockGranted メソッドを使用してドキュメントをロックします。アプリケーションは、ITextStoreACP::RequestLock メソッドの内部からドキュメントを変更したり、ITextStoreACPSink::OnTextChange メソッドで変更通知を送信したりしてはなりません。報告すべき保留中の変更がある場合、アプリケーションは非同期のロック要求にのみ応答できます。
アプリケーションに必要なコールバックは 1 回のみであるため、複数の ITextStoreACP::RequestLock メソッド呼び出しをキューに入れようとしてはなりません。ただし、呼び出し側が複数の読み取り要求と 1 つ以上の書き込み要求を行った場合、コールバックは書き込みアクセスで行う必要があります。
同期ロックの要求が成功した場合、その要求は非同期ロックの要求に優先します。同期ロックの要求が失敗した場合は、非同期ロックの要求に優先しません。未処理の非同期要求が存在する場合、実装はその要求に応答する必要があります。
ITextStoreACP::RequestLock メソッドが戻る前にロックが許可された場合、phrSession パラメーターは ITextStoreACPSink::OnLockGranted メソッドが返した HRESULT を受け取ります。呼び出しは成功したもののロックが後から許可される場合、phrSession パラメーターは TS_S_ASYNC フラグを受け取ります。ITextStoreACP::RequestLock が S_OK 以外を返した場合、phrSession パラメーターは無視してください。
呼び出し側は、このメソッドを再入的に呼び出してはなりません。ただし、読み取り専用ロックを保持している場合は例外で、非同期の書き込みロックを要求するために再入的に呼び出すことができます。この書き込みロックは、読み取り専用ロックの終了後に許可されます。
ドキュメントロックの詳細については、Document Locks を参照してください。
ITextStoreACP::GetStatus メソッドは、ドキュメントの状態を取得します。ドキュメントの状態は TS_STATUS 構造体で返されます。
| pdcs | TS_STATUS* | out | ドキュメントの状態を格納した TS_STATUS 構造体を受け取ります。NULL は指定できません。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| TS_STATUS パラメーターへのポインターが無効です。 |
ITextStoreACP::QueryInsert メソッドは、指定された開始文字位置と終了文字位置が有効かどうかを判定します。
| acpTestStart | INT | in | 挿入するテキストの開始アプリケーション文字位置。 |
| acpTestEnd | INT | in | 挿入するテキストの終了アプリケーション文字位置。選択されたテキストを置換するのではなく、ある一点に挿入する場合、この値は acpTextStart と等しくなります。 |
| cch | DWORD | in | 置換テキストの長さ。 |
| pacpResultStart | INT* | out | 挿入されたテキストの新しい開始アプリケーション文字位置を返します。このパラメーターが NULL の場合、指定された位置にテキストを挿入できません。この値はドキュメントの範囲外にはできません。 |
| pacpResultEnd | INT* | out | 挿入されたテキストの新しい終了アプリケーション文字位置を返します。このパラメーターが NULL の場合、pacpResultStart も NULL に設定され、指定された位置にテキストを挿入できません。この値はドキュメントの範囲外にはできません。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 原因不明のエラーが発生しました。 | |
| acpTestStart または acpTestEnd パラメーターが無効です。 |
解説(Remarks)
pacpResultStart と pacpResultEnd の値は、アプリケーションがドキュメントにテキストをどのように挿入するかによって異なります。pacpResultStart と pacpResultEnd が acpTextStart と同じ場合、挿入後にカーソルは挿入テキストの先頭に置かれます。pacpResultStart と pacpResultEnd が acpTextEnd と同じ場合、挿入後にカーソルは挿入テキストの末尾に置かれます。pacpResultStart と pacpResultEnd の差が挿入テキストの長さと等しい場合、挿入後に挿入テキストが選択表示されます。
ITextStoreACP::GetSelection メソッドは、ドキュメント内のテキスト選択範囲の文字位置を返します。このメソッドは複数のテキスト選択範囲をサポートします。呼び出し側は、このメソッドを呼び出す前にドキュメントの読み取り専用ロックを取得している必要があります。
| ulIndex | DWORD | in | 処理を開始するテキスト選択範囲を指定します。このパラメーターに TF_DEFAULT_SELECTION 定数を指定した場合、入力選択範囲から処理が開始されます。 |
| ulCount | DWORD | in | 返す選択範囲の最大数を指定します。 |
| pSelection | TS_SELECTION_ACP* | out | 選択されたテキストのスタイル、開始文字位置、終了文字位置を受け取ります。これらの値は TS_SELECTION_ACP 構造体に格納されます。 |
| pcFetched | DWORD* | out | 返された pSelection 構造体の数を受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 呼び出し側がドキュメントの読み取り専用ロックを保持していません。 | |
| ドキュメントに選択範囲がありません。 |
ITextStoreACP::SetSelection メソッドは、ドキュメント内のテキストを選択します。アプリケーションは、このメソッドを呼び出す前にドキュメントの読み取り/書き込みロックを取得している必要があります。
| ulCount | DWORD | in | pSelection に含まれるテキスト選択範囲の数を指定します。 |
| pSelection | TS_SELECTION_ACP* | in | TS_SELECTION_ACP 構造体により、選択するテキストのスタイル、開始文字位置、終了文字位置を指定します。 開始文字位置と終了文字位置が等しい場合、このメソッドはその文字位置にキャレットを配置します。ドキュメント内に同時に存在できるキャレットは 1 つだけです。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 原因不明のエラーが発生しました。 | |
| 指定された文字位置がドキュメント内のテキストの範囲を超えています。 | |
| 呼び出し側が読み取り/書き込みロックを保持していません。 |
ITextStoreACP::GetText メソッドは、指定された文字位置のテキストに関する情報を返します。このメソッドは表示テキストと非表示テキストを返し、テキストに埋め込みデータが付随しているかどうかを示します。
| acpStart | INT | in | 開始文字位置を指定します。 |
| acpEnd | INT | in | 終了文字位置を指定します。このパラメーターが -1 の場合、テキストストア内のすべてのテキストを返します。 |
| pchPlain | LPWSTR | out | プレーンテキストデータを受け取るバッファーを指定します。このパラメーターが NULL の場合、cchPlainReq パラメーターは 0 でなければなりません。 |
| cchPlainReq | DWORD | in | メソッドに渡すプレーンテキストの文字数を指定します。 |
| pcchPlainRet | DWORD* | out | プレーンテキストバッファーにコピーされた文字数を受け取ります。このパラメーターに NULL は指定できません。値が不要な場合でもパラメーターを指定してください。 |
| prgRunInfo | TS_RUNINFO* | out | TS_RUNINFO 構造体の配列を受け取ります。NULL にできるのは cRunInfoReq = 0 の場合のみです。 |
| cRunInfoReq | DWORD | in | テキストランバッファーのサイズを文字数で指定します。 |
| pcRunInfoRet | DWORD* | out | テキストランバッファーに書き込まれた TS_RUNINFO 構造体の数を受け取ります。このパラメーターに NULL は指定できません。 |
| pacpNext | INT* | out | 次の未読文字の文字位置を受け取ります。NULL は指定できません。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| acpStart または acpEnd パラメーターがドキュメントのテキストの範囲外です。 | |
| 呼び出し側がドキュメントの読み取り専用ロックを保持していません。 |
解説(Remarks)
このメソッドを使用する呼び出し側は、ITextStoreACP::RequestLock メソッドを呼び出してドキュメントの読み取り専用ロックを取得している必要があります。読み取り専用ロックがない場合、このメソッドは失敗し、TF_E_NOLOCK を返します。
また、アプリケーションは内部的な理由でメソッドの戻り値を切り詰めることがあります。呼び出し側は、必要な戻り値を得るために、返された文字数とテキストラン数を注意深く確認してください。戻り値が不完全な場合は、完全になるまでメソッドを繰り返し呼び出してください。
呼び出し側は、cRunInfoReq パラメーターを 0 に、prgRunInfo パラメーターを NULL に設定することで、プレーンテキストのみを要求できます。また、cchPlainReq パラメーターを 0 に、pchPlain パラメーターを NULL に設定することで、テキストランデータのみを要求できます。ただし、その場合でも pcchPlainRet には有効な非 NULL 値を指定する必要があります (このパラメーターを使用しない場合でも同様です)。
acpEnd が -1 の場合は、ストリームの末尾が指定されたものとして扱ってください。それ以外の場合、この値は 0 以上になります。
終了時、pacpNext には、戻り値で参照されなかったストリーム内の次の文字の文字位置を設定してください。呼び出し側は、複数回の ITextStoreACP::GetText 呼び出しでテキストを高速に走査するためにこれを使用します。
ITextStoreACP::SetText メソッドは、指定された文字位置にテキスト選択範囲を設定します。
| dwFlags | DWORD | in | TS_ST_CORRECTION の値が設定されている場合、テキストは既存の内容の変換 (訂正) であり、.wav ファイルのデータや言語識別子などの特別なテキストマークアップ情報 (メタデータ) が保持されます。保持するマークアップ情報の種類はクライアントが定義します。 | ||||||||
| acpStart | INT | in | 置換対象テキストの開始文字位置を指定します。 | ||||||||
| acpEnd | INT | in | 置換対象テキストの終了文字位置を指定します。値が 1 の場合、このパラメーターは無視されます。 | ||||||||
| pchText | LPWSTR | in | 置換テキストへのポインターを指定します。テキストの文字数は cch パラメーターで指定するため、文字列は NULL 終端である必要はありません。 | ||||||||
| cch | DWORD | in | 置換テキストの文字数を指定します。 | ||||||||
| pChange | TS_TEXTCHANGE* | out | 次のデータを持つ TS_TEXTCHANGE 構造体へのポインター。
|
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| acpStart または acpEnd パラメーターがドキュメントのテキストの範囲外です。 | |
| 呼び出し側が読み取り/書き込みロックを保持していません。 | |
| ドキュメントは読み取り専用です。内容を変更できません。 | |
|
リージョン境界をまたいでテキストを変更しようとしました。 |
解説(Remarks)
アプリケーションは、コンポジション (変換中の文字列) を開始する際、まず ITextStoreACP::InsertTextAtSelection を使用してください。ITextStoreACP::SetText は既存のコンポジション内でのみ使用します。SetText の呼び出し時にアクティブなコンポジションが存在しない場合、TSF マネージャーは SetText の呼び出しを包含するだけの短命なコンポジションを作成します。
acpStart と acpEnd の文字位置は、ドキュメントの範囲外にはできません。
アプリケーションは、このメソッドへの応答として ITextStoreACPSink::OnTextChange メソッドを呼び出してはなりません。
このメソッドは ITextStoreACP::SetSelection メソッドを呼び出して、変更対象のテキストを選択する必要があります。ITextStoreACP::SetSelection メソッドが正常に実行された後、このメソッドは ITextStoreACP::InsertTextAtSelection メソッドを呼び出して実際のテキスト変更を行います。
ITextStoreACP::GetFormattedText メソッドは、指定されたテキスト文字列に関する書式付きテキストデータを返します。呼び出し側は、このメソッドを呼び出す前にドキュメントの読み取り/書き込みロックを取得している必要があります。
| acpStart | INT | in | ドキュメント内で取得するテキストの開始文字位置を指定します。 |
| acpEnd | INT | in | ドキュメント内で取得するテキストの終了文字位置を指定します。値が 1 の場合、このパラメーターは無視されます。 |
| ppDataObject | IDataObject** | out | 書式付きテキストを格納した IDataObject オブジェクトへのポインターを受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 呼び出し側がドキュメントの読み取り/書き込みロックを保持していません。 |
埋め込みドキュメントを取得します。(ITextStoreACP.GetEmbedded)
| acpPos | INT | in | オブジェクトを取得する、ドキュメント内の文字位置を格納します。 | ||||||||
| rguidService | GUID* | in | 取得するオブジェクトの要求形式を定義する GUID 値を格納します。次のいずれかの値を指定できます。
| ||||||||
| riid | GUID* | in | 要求するインターフェイスの種類を指定します。 | ||||||||
| ppunk | IUnknown** | out | 要求されたインターフェイスを受け取る IUnknown ポインターへのポインター。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 1 つ以上のパラメーターが無効です。 | |
| アプリケーションは埋め込みオブジェクトをサポートしていません。 | |
| acpPos がドキュメント内にありません。 | |
| 要求されたインターフェイスの種類はサポートされていません。 | |
| 呼び出し側が読み取り専用ロックを保持していません。 | |
| acpPos に埋め込みオブジェクトがありません。 | |
| rguidService で指定されたサービスの種類はサポートされていません。 |
解説(Remarks)
呼び出し側は QueryInterface を使用して適切なインターフェイスを問い合わせる必要があります。対象となるインターフェイスには、埋め込みドキュメントやコントロールに関連する IOleObject、IDataObject、IViewObject、IPersistStorage、IOleCache、IDispatch などがあります。
指定されたオブジェクトをドキュメントに挿入できるかどうかを示す値を取得します。(ITextStoreACP.QueryInsertEmbedded)
| pguidService | GUID* | in | オブジェクトの種類へのポインター。NULL を指定できます。 |
| pFormatEtc | FORMATETC* | in | オブジェクトの形式データを格納した FORMATETC 構造体へのポインター。pguidService パラメーターが NULL の場合、このパラメーターに NULL は指定できません。 |
| pfInsertable | BOOL* | out | オブジェクトの種類をドキュメントに挿入できる場合は TRUE、挿入できない場合は FALSE を受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pFormatEtc パラメーターが NULL です。 |
解説(Remarks)
ドキュメントがサポートするクリップボード形式は、アプリケーションに依存します。
指定された文字位置に埋め込みオブジェクトを挿入します。(ITextStoreACP.InsertEmbedded)
| dwFlags | DWORD | in | TS_IE_CORRECTION でなければなりません。 |
| acpStart | INT | in | オブジェクトを挿入する開始文字位置を格納します。 |
| acpEnd | INT | in | オブジェクトを挿入する終了文字位置を格納します。 |
| pDataObject | IDataObject* | in | 挿入するオブジェクトに関するデータを格納した IDataObject インターフェイスへのポインター。 |
| pChange | TS_TEXTCHANGE* | out | 変更されたテキストに関するデータを受け取る TS_TEXTCHANGE 構造体へのポインター。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 1 つ以上のパラメーターが無効です。 | |
| アプリケーションは埋め込みオブジェクトをサポートしていません。 | |
| アプリケーションは pDataObject に含まれるデータ型をサポートしていません。 | |
| acpStart または acpEnd (あるいはその両方) がドキュメント内にありません。 | |
| 呼び出し側が読み取り/書き込みロックを保持していません。 |
ITextStoreACP::InsertTextAtSelection メソッドは、挿入点または選択範囲にテキストを挿入します。呼び出し側は、テキストを挿入する前にドキュメントの読み取り/書き込みロックを取得している必要があります。
| dwFlags | DWORD | in | pacpStart および pacpEnd パラメーターと TS_TEXTCHANGE 構造体がテキスト挿入の結果を格納するかどうかを指定します。 TF_IAS_NOQUERY と TF_IAS_QUERYONLY フラグは組み合わせられません。 | ||||||||
| pchText | LPWSTR | in | ドキュメントに挿入する文字列へのポインター。文字列は NULL 終端でもかまいません。 | ||||||||
| cch | DWORD | in | テキストの長さを指定します。 | ||||||||
| pacpStart | INT* | out | テキスト挿入が行われる開始アプリケーション文字位置へのポインター。 | ||||||||
| pacpEnd | INT* | out | テキスト挿入が行われる終了アプリケーション文字位置へのポインター。挿入点の場合、このパラメーターの値は pacpStart パラメーターの値と同じです。 | ||||||||
| pChange | TS_TEXTCHANGE* | out | 次のメンバーを持つ TS_TEXTCHANGE 構造体へのポインター。
|
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 呼び出し側がドキュメントのロックを保持していません。 | |
| pchText パラメーターが無効です。 |
解説(Remarks)
pacpStart および pacpEnd パラメーターの値は、クライアントアプリケーションがドキュメントにテキストをどのように挿入するかによって異なります。たとえば、テキスト挿入後にアプリケーションが挿入テキストの先頭にカーソルを設定する場合、pacpStart および pacpEnd パラメーターの値は TS_TEXTCHANGE 構造体の acpStart メンバーと同じになります。
アプリケーションは、このメソッドへの応答として ITextStoreACPSink::OnTextChange メソッドを呼び出してはなりません。
ITextStoreACP::InsertEmbeddedAtSelection メソッドは、挿入点または選択範囲に IDataObject オブジェクトを挿入します。このメソッドを呼び出すクライアントは、ドキュメントに IDataObject オブジェクトを挿入する前に読み取り/書き込みロックを取得している必要があります。
| dwFlags | DWORD | in | pacpStart および pacpEnd パラメーターと TS_TEXTCHANGE 構造体がオブジェクト挿入の結果を格納するかどうかを指定します。 TF_IAS_NOQUERY と TF_IAS_QUERYONLY フラグは組み合わせられません。 |
| pDataObject | IDataObject* | in | 挿入する IDataObject オブジェクトへのポインター。 |
| pacpStart | INT* | out | オブジェクト挿入が行われる開始アプリケーション文字位置へのポインター。 |
| pacpEnd | INT* | out | オブジェクト挿入が行われる終了アプリケーション文字位置へのポインター。挿入点の場合、このパラメーターの値は pacpStart パラメーターの値と同じになります。 |
| pChange | TS_TEXTCHANGE* | out | 次のメンバーを持つ TS_TEXTCHANGE 構造体へのポインター。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pchText パラメーターが無効です。 | |
| 呼び出し側がドキュメントのロックを保持していません。 |
解説(Remarks)
pacpStart および pacpEnd パラメーターの値は、クライアントアプリケーションがドキュメントにオブジェクトをどのように挿入するかによって異なります。たとえば、オブジェクト挿入後にアプリケーションがオブジェクトの先頭にカーソルを設定する場合、pacpStart および pacpEnd パラメーターの値は TS_TEXTCHANGE 構造体の acpStart メンバーと同じになります。
ドキュメントでサポートされている属性を取得します。(ITextStoreACP.RequestSupportedAttrs)
| dwFlags | DWORD | in | 後続の ITextStoreAnchor::RetrieveRequestedAttrs メソッド呼び出しがサポート対象の属性を含むかどうかを指定します。TS_ATTR_FIND_WANT_VALUE フラグを指定した場合、後続の ITextStoreAnchor::RetrieveRequestedAttrs 呼び出し後、既定の属性値は TS_ATTRVAL 構造体内の値になります。このパラメーターにその他のフラグを指定した場合、メソッドは属性がサポートされていることを確認するだけで、TS_ATTRVAL 構造体の varValue メンバーは VT_EMPTY に設定されます。 |
| cFilterAttrs | DWORD | in | 取得するサポート対象属性の数を指定します。 |
| paFilterAttrs | GUID* | in | 確認する属性を指定する TS_ATTRID データ型へのポインター。他の属性がサポートされている場合でも、メソッドは TS_ATTRID で指定された属性のみを返します。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 原因不明のエラーが発生しました。 | |
| 操作を完了するのに十分なメモリを割り当てられませんでした。 |
指定された文字位置のテキスト属性を取得します。(ITextStoreACP.RequestAttrsAtPosition)
| acpPos | INT | in | ドキュメント内のアプリケーション文字位置を指定します。 |
| cFilterAttrs | DWORD | in | 取得する属性の数を指定します。 |
| paFilterAttrs | GUID* | in | 確認する属性を指定する TS_ATTRID データ型へのポインター。 |
| dwFlags | DWORD | in | 0 でなければなりません。 |
戻り値
このメソッドに戻り値はありません。
指定された文字位置で遷移するテキスト属性を取得します。(ITextStoreACP.RequestAttrsTransitioningAtPosition)
| acpPos | INT | in | ドキュメント内のアプリケーション文字位置を指定します。 | ||||||
| cFilterAttrs | DWORD | in | 取得する属性の数を指定します。 | ||||||
| paFilterAttrs | GUID* | in | 確認する属性を指定する TS_ATTRID データ型へのポインター。 | ||||||
| dwFlags | DWORD | in | ITextStoreACP::RetrieveRequestedAttrs メソッドの呼び出しに対する属性を指定します。このパラメーターを設定しない場合、メソッドは指定位置で開始する属性を返します。このパラメーターに指定できるその他の値は次のとおりです。
|
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 |
解説(Remarks)
「This is italic text.」という文では、斜体属性は単語 italic の前で開始し、単語 text の後で終了します。
dwFlags に TS_ATTR_FIND_WANT_END フラグが設定されている場合、アンカー位置に終了遷移があるため、メソッドはテキスト「italic <anchor>normal」に対して斜体属性を返します。
ITextStoreACP::FindNextAttrTransition メソッドは、属性値の遷移が発生する文字位置を判定します。確認する属性はアプリケーションに依存します。
| acpStart | INT | in | 属性遷移の検索を開始する文字位置を指定します。 | ||||||
| acpHalt | INT | in | 属性遷移の検索を終了する文字位置を指定します。 | ||||||
| cFilterAttrs | DWORD | in | 確認する属性の数を指定します。 | ||||||
| paFilterAttrs | GUID* | in | 確認する属性を指定する TS_ATTRID データ型へのポインター。 | ||||||
| dwFlags | DWORD | in | 属性遷移を検索する方向を指定します。既定では、メソッドは前方に検索します。
| ||||||
| pacpNext | INT* | out | 属性遷移を確認する次の文字位置を受け取ります。 | ||||||
| pfFound | BOOL* | out | 属性遷移が見つかった場合はブール値 TRUE、見つからなかった場合は FALSE を受け取ります。 | ||||||
| plFoundOffset | INT* | out | 属性遷移の文字位置 (ACP 位置ではありません) を受け取ります。dwFlags に TS_ATTR_FIND_WANT_OFFSET フラグが設定されている場合は、acpStart から属性遷移までの文字オフセットを受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 指定された文字位置がドキュメント内のテキストの範囲を超えています。 |
解説(Remarks)
属性要求メソッドの呼び出しによって返された属性を取得します。(ITextStoreACP.RetrieveRequestedAttrs)
| ulCount | DWORD | in | 取得するサポート対象属性の数を指定します。 |
| paAttrVals | TS_ATTRVAL* | out | サポート対象の属性を受け取る TS_ATTRVAL 構造体へのポインター。この構造体のメンバーは、呼び出し元メソッドの dwFlags パラメーターによって異なります。 |
| pcFetched | DWORD* | out | サポート対象の属性の数を受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 |
ITextStoreACP::GetEndACP メソッドは、ドキュメント内の文字数を返します。
| pacp | INT* | out | ドキュメント内の最後の文字の文字位置に 1 を加えた値を受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| アプリケーションがこのメソッドを実装していません。これは通常、終了位置の算出に過大なリソースが必要であることを示します。終了位置が必要な場合は ITextStoreACP::GetText を使用して算出できますが、この操作もディスクから任意の大きさのメモリをページインする、メモリを多く消費する操作になる可能性があります。 | |
| 呼び出し側が読み取り専用ロックを保持していません。 |
ITextStoreACP::GetActiveView メソッドは、現在アクティブなビューを示す TsViewCookie データ型を返します。
| pvcView | DWORD* | out | 現在アクティブなビューを示す TsViewCookie データ型を受け取ります。 |
戻り値
このメソッドに戻り値はありません。
ITextStoreACP::GetACPFromPoint メソッドは、スクリーン座標の点をアプリケーション文字位置に変換します。
| vcView | DWORD | in | コンテキストのビューを指定します。 | ||||||
| ptScreen | POINT* | in | 点のスクリーン座標を格納した POINT 構造体へのポインター。 | ||||||
| dwFlags | DWORD | in | 文字の境界ボックスに対する点のスクリーン座標に基づいて、返す文字位置を指定します。既定では、返される文字位置は、点のスクリーン座標を含む文字の境界ボックスです。点が文字の境界ボックスの外にある場合、メソッドは NULL または TF_E_INVALIDPOINT を返します。このパラメーターのその他のビットフラグは次のとおりです。 これらのビットフラグは組み合わせられます。
| ||||||
| pacp | INT* | out | 点のスクリーン座標に対応する文字位置を受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| ptScreen パラメーターがいずれの文字の境界ボックス内にもありません。 | |
| アプリケーションがテキストレイアウトを算出していません。 |
解説(Remarks)
点 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
- 既定 -- pacp = 0 -- 点のスクリーン座標は文字位置 0 の文字の境界ボックス内にあります。
- GXFPF_ROUND_NEAREST -- pacp = 1 -- 点のスクリーン座標は、文字位置 1 の開始レンジ位置であるレンジ位置 1 に最も近いです。
- GXFPF_NEAREST -- pacp = 0 -- 点が文字位置 0 の文字の境界ボックス内にあるため、既定の動作になります。
- 既定 -- hr = TF_E_INVALIDPOINT -- 点のスクリーン座標は文字の境界ボックスの外にあります。
- GXFPF_ROUND_NEAREST -- hr = TF_E_INVALIDPOINT -- 点のスクリーン座標が文字の境界ボックスの外にあるため、既定の動作になります。
- GXFPF_NEAREST -- pacp = 1 -- 点のスクリーン座標に最も近い文字位置は文字位置 1 です。
ITextStoreACP::GetTextExt メソッドは、指定された文字位置のテキストの境界ボックスをスクリーン座標で返します。呼び出し側は、このメソッドを呼び出す前にドキュメントの読み取り専用ロックを取得している必要があります。
| vcView | DWORD | in | コンテキストのビューを指定します。 |
| acpStart | INT | in | ドキュメント内で取得するテキストの開始文字位置を指定します。 |
| acpEnd | INT | in | ドキュメント内で取得するテキストの終了文字位置を指定します。 |
| prc | RECT* | out | 指定された文字位置のテキストの境界ボックスをスクリーン座標で受け取ります。 |
| pfClipped | BOOL* | out | 境界ボックス内のテキストがクリップされているかどうかを示すブール値を受け取ります。このパラメーターが TRUE の場合、境界ボックスにはクリップされたテキストが含まれ、要求されたテキスト範囲全体は含まれません。要求された範囲が表示されていないため、境界ボックスがクリップされています。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
|
指定された開始文字位置と終了文字位置が等しいです。 |
| acpStart および acpEnd パラメーターで指定された範囲が、ドキュメントの先頭または末尾を超えています。 | |
| アプリケーションがテキストレイアウトを算出していません。 | |
| 呼び出し側がドキュメントの読み取り専用ロックを保持していません。 |
解説(Remarks)
ドキュメントウィンドウが最小化されている場合、または指定されたテキストが現在表示されていない場合、メソッドは prc パラメーターを {0,0,0,0} に設定して S_OK を返します。
ITextStoreACP::GetScreenExt メソッドは、テキストストリームが描画される表示面の境界ボックスのスクリーン座標を返します。
| vcView | DWORD | in | コンテキストのビューを指定します。 |
| prc | RECT* | out | ドキュメントの表示面の境界ボックスのスクリーン座標を受け取ります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 指定された vcView パラメーターが無効です。 |
解説(Remarks)
テキストが現在表示されていない場合 (たとえばドキュメントウィンドウが最小化されている場合)、prc パラメーターは { 0, 0, 0, 0 } に設定されます。
ITextStoreACP::GetWnd メソッドは、現在のドキュメントに対応するウィンドウのハンドルを返します。
| vcView | DWORD | in | 現在のドキュメントに対応する TsViewCookie データ型を指定します。 |
| phwnd | HWND* | out | 現在のドキュメントに対応するウィンドウのハンドルへのポインターを受け取ります。ドキュメントに対応するウィンドウハンドルがない場合、このパラメーターは NULL になることがあります。 |
戻り値
このメソッドは次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| TsViewCookie データ型が無効です。 |
解説(Remarks)
ドキュメントがメモリ内に存在するものの画面に表示されていない場合、またはドキュメントがウィンドウレスコントロールであり、そのコントロールがウィンドウレスコントロールの所有者のウィンドウハンドルを認識できない場合、ドキュメントには対応するウィンドウハンドルが存在しないことがあります。呼び出し側は、メソッドが成功した場合でも phwnd パラメーターが非 NULL の値を受け取ると想定してはなりません。呼び出し側は phwnd パラメーターとして NULL 値を受け取ることもあります。
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 指定が可能。#define global IID_ITextStoreACP "{28888FE3-C2A0-483A-A3EA-8CB1CE51FF3D}" #usecom global ITextStoreACP IID_ITextStoreACP "{}" #comfunc global ITextStoreACP_AdviseSink 3 sptr,sptr,int #comfunc global ITextStoreACP_UnadviseSink 4 sptr #comfunc global ITextStoreACP_RequestLock 5 int,sptr #comfunc global ITextStoreACP_GetStatus 6 sptr #comfunc global ITextStoreACP_QueryInsert 7 int,int,int,sptr,sptr #comfunc global ITextStoreACP_GetSelection 8 int,int,sptr,sptr #comfunc global ITextStoreACP_SetSelection 9 int,sptr #comfunc global ITextStoreACP_GetText 10 int,int,sptr,int,sptr,sptr,int,sptr,sptr #comfunc global ITextStoreACP_SetText 11 int,int,int,wstr,int,sptr #comfunc global ITextStoreACP_GetFormattedText 12 int,int,sptr #comfunc global ITextStoreACP_GetEmbedded 13 int,sptr,sptr,sptr #comfunc global ITextStoreACP_QueryInsertEmbedded 14 sptr,sptr,sptr #comfunc global ITextStoreACP_InsertEmbedded 15 int,int,int,sptr,sptr #comfunc global ITextStoreACP_InsertTextAtSelection 16 int,wstr,int,sptr,sptr,sptr #comfunc global ITextStoreACP_InsertEmbeddedAtSelection 17 int,sptr,sptr,sptr,sptr #comfunc global ITextStoreACP_RequestSupportedAttrs 18 int,int,sptr #comfunc global ITextStoreACP_RequestAttrsAtPosition 19 int,int,sptr,int #comfunc global ITextStoreACP_RequestAttrsTransitioningAtPosition 20 int,int,sptr,int #comfunc global ITextStoreACP_FindNextAttrTransition 21 int,int,int,sptr,int,sptr,sptr,sptr #comfunc global ITextStoreACP_RetrieveRequestedAttrs 22 int,sptr,sptr #comfunc global ITextStoreACP_GetEndACP 23 sptr #comfunc global ITextStoreACP_GetActiveView 24 sptr #comfunc global ITextStoreACP_GetACPFromPoint 25 int,sptr,int,sptr #comfunc global ITextStoreACP_GetTextExt 26 int,int,int,sptr,sptr #comfunc global ITextStoreACP_GetScreenExt 27 int,sptr #comfunc global ITextStoreACP_GetWnd 28 int,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。