ITextServices

Text Object Model (TOM) を拡張し、ウィンドウレス動作のための追加機能を提供します。

ITextHost インターフェイスと組み合わせることで、ITextServices はウィンドウを作成することなく rich edit コントロールを使用する手段を提供します。

実装するタイミング

アプリケーションが ITextServices インターフェイスを実装することはありません。

使用するタイミング

アプリケーションは CreateTextServices 関数を呼び出して text services オブジェクトを作成できます。ITextServices ポインターを取得するには、CreateTextServices が返すプライベートな IUnknown ポインターに対して QueryInterface を呼び出します。その後、ITextServices のメソッドを呼び出して text services オブジェクトへメッセージを送信できます。

ウィンドウホストが、自身のウィンドウから送信されたメッセージを text services オブジェクトへ転送するために使用します。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次のいずれかの HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_OUTOFMEMORY	メモリ不足。NOERROR メッセージは処理され、何らかのアクションが実行されました。
S_FALSE	メッセージは処理されませんでした。通常、呼び出し元が(場合によっては DefWindowProc を呼び出して)自身でメッセージを処理すべきことを示します。
S_MSG_KEYIGNORED	メッセージは処理されましたが、キー入力に対するアクションは実行されませんでした。

この関数からは 2 つの戻り値が返される点に注意してください。ウィンドウプロシージャから返すべき戻り値は plresult です。ただし、場合によっては、返される LRESULT だけでは十分な情報が得られないことがあります。たとえば、コントロール間でのカーソル移動を実装する際には、キー入力(右矢印など)が処理されたものの無視された(たとえばキャレットが既にテキスト内の最も右の位置にある)かどうかを知ることが役立ちます。このような場合、追加の情報は返される HRESULT を通じて返されることがあります。

WM_CHAR および WM_KEYDOWN は、キーまたは文字が認識されたものの、現在の状態では効果がない場合に S_MSG_KEYIGNORED を返すべきです。たとえば、次のような場合に S_MSG_KEYIGNORED を返す必要があります。

• 挿入位置をドキュメントの先頭または末尾へ、あるいはそれを越えて移動しようとするキー入力で、既にそれぞれドキュメントの先頭または末尾にある場合。
• 既に最終行にあるときに挿入位置を次の行へ、あるいはそれ以降へ移動しようとするキー入力、または既に先頭行にあるときに前の行へ、あるいはそれ以前へ移動しようとするキー入力。
• WM_CHAR による文字の挿入で、挿入位置がコントロールの最大長を越えて移動することになるもの。

text services オブジェクトを描画します。

型: HRESULT

戻り値は通常 S_OK です。

このメソッドは text services オブジェクトをレンダリングします。OLE の対応する IViewObject::Draw メソッドと同じパラメーターに加えて、lprcUpdate と lViewId のパラメーターを受け取ります。ホストがインプレースアクティブ、非アクティブのいずれの状態でも使用できます。

lprcBounds パラメーターはレンダリング対象の矩形(クライアント矩形とも呼ばれます)を指定します。この矩形は、描画する text services オブジェクトのイメージ全体の位置と範囲を表します。これは hdcDraw の論理座標系で表現されます。lprcBounds が NULL の場合、コントロールはアクティブでなければなりません。この場合、text services オブジェクトはインプレースアクティブなビュー(すなわち、ホストに対して TxGetClientRect を呼び出して取得できるクライアント矩形)をレンダリングする必要があります。

lprcUpdate パラメーターが NULL でない場合、それは hdcDraw の論理座標系で、そのクライアント矩形内の更新対象の矩形を指定します。lprcUpdate が NULL の場合、クライアント矩形全体を描画する必要があります。

text services オブジェクトは適切なズーム倍率でレンダリングする必要があります。ズーム倍率は、クライアント矩形と TxGetExtent が返すネイティブサイズから求められます。ズーム倍率についての説明は TxGetExtent を参照してください。

OLE ホストと ITextServices::TxDraw(ITextServices::OnTxSetCursor および ITextServices::TxQueryHitPoint にも該当)に関する一般的な注意:

OLE ホストは、任意のレンダリング用デバイスコンテキストまたはクライアント矩形を用いて、いつでも ITextServices::TxDraw メソッドを呼び出せます。非アクティブな OLE オブジェクトは範囲(extent)のみを保持します。レンダリング先の矩形を取得するために、ホストは IViewObject::Draw メソッドを呼び出します。この矩形はそのメソッドの範囲内でのみ有効です。したがって、同じコントロールが、異なる矩形や異なるデバイスコンテキストで連続してレンダリングされることがあります。たとえば、画面上の異なるビューに同時に表示される場合などです。

通常、ITextServices::TxDraw に渡されるクライアント矩形とデバイスコンテキストはキャッシュすべきではありません。キャッシュすると text services オブジェクトが描画のたびに行を再計算せざるを得なくなり、パフォーマンスを低下させるためです。代わりに、text services オブジェクトは特定のクライアント矩形とデバイスコンテキストについて計算された情報(改行位置など)をキャッシュできます。ただし、次に ITextServices::TxDraw を呼び出す際には、キャッシュされた情報を使用する前にその有効性を確認し、必要に応じて更新された情報を再生成する必要があります。

また、コントロールがインプレースアクティブな場合は十分に注意してください。ITextServices::TxDraw はインプレースアクティブなビュー以外のビューをレンダリングするために呼び出されることがあるため、この問題はさらに複雑になります。言い換えると、ITextServices::TxDraw に渡されるクライアント矩形は、アクティブなもの(ITextServices::OnTxInPlaceActivate に渡され、ホストに対する TxGetClientRect を通じて取得されるもの)と同一とは限りません。

水平スクロールバーの情報を返します。

型: HRESULT

このメソッドは常に S_OK を返します。

垂直スクロールバーの状態情報を返します。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次のいずれかの HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_FAIL	原因不明のエラー。
E_INVALIDARG	1 つ以上の引数が無効です。

text services オブジェクトにカーソルを設定するよう通知します。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次の HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_INVALIDARG	1 つ以上の不正なパラメーターがあります。

text services オブジェクトは、この呼び出しの結果として正しいカーソルを判断するために再計測を行うことがあります。正しいカーソルは TxSetCursor を通じて設定されます。

lprcClient パラメーターは、マウスカーソルが位置しているコントロールのビューのクライアント矩形です。lprcClient パラメーターは、WM_SIZE メッセージと同様に、含まれるウィンドウのデバイス座標で表されます。これは最後にレンダリングされたビューとは限りません。さらに、コントロールがインプレースアクティブな場合、これは現在アクティブなビューとは限りません。そのため、text services オブジェクトはこの矩形を現在のキャッシュの値と照合し、行の再計算が必要かどうかを判断する必要があります。この計算にはズーム倍率を含める必要があります。ズーム倍率についての説明は TxGetExtent を参照してください。

このメソッドはコントロールのスクリーンビューに対してのみ呼び出されるべきです。したがってデバイスコンテキスト (DC) は渡されませんが、スクリーン DC であると想定してください。

詳細については、ITextServices::TxDraw の「解説」を参照してください。

指定した点が text services オブジェクトの矩形内にあるかどうかを判定します。

型: HRESULT

戻り値は HRESULT コードです。

このメソッドにより、ホストはテキスト上での透過ヒットテストを実装できます。

詳細については、ITextServices::TxDraw および ITextServices::OnTxSetCursor の「解説」セクションを参照してください。

このコントロールがインプレースアクティブであることを text services オブジェクトに通知します。

型: HRESULT

オブジェクトが正常にアクティブ化された場合、戻り値は S_OK です。

エラーによりオブジェクトをアクティブ化できなかった場合、戻り値は E_FAIL です。COM エラーコードの詳細については、Error Handling in COM を参照してください。

インプレースアクティブとは、埋め込みオブジェクトがインプレースで実行されていることを意味します(たとえば通常のコントロールや埋め込みでは、描画するウィンドウを持ちます)。対照的に、UI アクティブとは、オブジェクトが現在編集フォーカスを持っていることを意味します。たとえば、コンテナー上のメニューやツールバーなども、UI アクティブなコントロール/埋め込みの要素を含むことがあります。UI アクティブなコントロールは常に 1 つだけですが、インプレースアクティブなコントロールは多数存在し得ます。

UI アクティブ化はフォーカスの取得とは異なる点に注意してください。コントロールがフォーカスを取得または喪失することを text services オブジェクトに伝えるために、ホストは WM_SETFOCUS および WM_KILLFOCUS メッセージを送信します。また、ウィンドウレスホストは、これらのメッセージの wParam(フォーカスを失ったウィンドウ)として NULL を渡す点にも注意してください。

非アクティブ状態から UI アクティブ状態へ直接遷移する場合、ホストはまず ITextServices::OnTxInPlaceActivate を呼び出し、その後 ITextServices::OnTxUIActivate を呼び出す必要があります。

ITextServices::OnTxInPlaceActivate は、アクティブ化されるビューのクライアント矩形をパラメーターとして受け取ります。この矩形は、含まれるウィンドウのクライアント座標で与えられます。これはホストに対して TxGetClientRect を呼び出して取得されるものと同じです。

このコントロールがインプレースアクティブでなくなったことを text services オブジェクトに通知します。

型: HRESULT

戻り値は常に S_OK です。

インプレースアクティブ化とは、埋め込みオブジェクトがインプレースで実行されていることを指します(たとえば通常のコントロールや埋め込みでは、描画するウィンドウを持ちます)。対照的に、UI アクティブとは、オブジェクトが現在編集フォーカスを持っていることを意味します。具体的には、コンテナー上のメニューやツールバーなども、UI アクティブなコントロール/埋め込みの要素を含むことがあります。UI アクティブなコントロールは常に 1 つだけですが、インプレースアクティブなコントロールは同時に多数存在し得ます。

UI アクティブ化はフォーカスの取得とは異なる点に注意してください。コントロールがフォーカスを取得または喪失することを text services オブジェクトに知らせるために、ホストは WM_SETFOCUS および WM_KILLFOCUS メッセージを送信します。また、ウィンドウレスホストは、これらのメッセージの wParam(フォーカスを失ったウィンドウ)として NULL を渡す点にも注意してください。

UI アクティブ状態から非アクティブ状態へ遷移する場合、ホストはまず ITextServices::OnTxUIDeactivate を呼び出し、その後 ITextServices::OnTxInPlaceDeactivate を呼び出す必要があります。

コントロールが UI アクティブになったことを text services オブジェクトに通知します。

型: HRESULT

このメソッドは常に S_OK を返します。

アクティブ化の詳細な説明については、ITextServices::OnTxInPlaceActivate を参照してください。

コントロールが UI アクティブでなくなったことを text services オブジェクトに通知します。

型: HRESULT

このメソッドは常に S_OK を返します。

非アクティブ化の詳細な説明については、ITextServices::OnTxInPlaceActivate を参照してください。

コントロール内のすべての Unicode プレーンテキストを BSTR として返します。

      *</b>

型: HRESULT

テキストが出力引数に正常に返された場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次のいずれかの HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_INVALIDARG	無効な BSTR ポインターが渡されました。
E_OUTOFMEMORY	テキストのコピー用のメモリを割り当てられませんでした。

ホスト(呼び出し元)が、返された BSTR の所有権を取得します。

プレーンテキストデータを取得する他の方法として、WM_GETTEXT や Text Object Model (TOM) の GetText メソッドの使用があります。

コントロールにテキストが存在しない場合、BSTR は割り当てられ、その中に 0x000D が返されます。

返されるテキストは、必ずしも null 終端されているとは限りません。

コントロール内のすべてのテキストを設定します。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次の HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_FAIL	テキストを更新できませんでした。

このメソッドは注意して使用する必要があります。本質的に、text services オブジェクトを新しいデータで再初期化します。取り消し(undo)情報を含め、以前のデータおよび書式情報はすべて失われます。

以前のデータがクリップボードにコピーされている場合、そのデータは破棄される前に(OleFlushClipboard を通じて)クリップボードへ完全にレンダリングされます。

このメソッドは Undo をサポートしません。

テキストを設定する代替手段として、WM_SETTEXT と SetText の 2 つがあります。

ターゲット x 位置、すなわちキャレットの現在の水平位置を取得します。

型: HRESULT

キャレットの x 位置が返された場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次の HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_FAIL	選択範囲がありません。
E_INVALIDARG	入力引数が無効です。

ITextServices::OnTxSetCursor と組み合わせることで、このメソッドはキャレットを上下に移動する際に水平方向のキャレット位置を維持できます。この機能は、フォーム内でキャレットを移動する際に役立ちます。

ターゲットのキャレット位置は、ディスプレイ上の x 座標として表現されます。これは、他のコントロールが必ずしも列位置について同じ属性を共有しているとは限らないためです。

text services のクライアント矩形を基準として、最初に表示される行のベースライン位置をピクセル単位で取得します。これにより、コントロールをベースラインで整列できます。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次の HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_NOTIMPL	実装されていません。

コントロールのサイズを変更して、そのコンテンツに適切に収まるようにします。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

text services がオブジェクトをアクティブ化できなかった場合、戻り値は次のいずれかの HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_FAIL	正しいサイズを判断できません。
E_INVALIDARG	1 つ以上の引数が無効です。
E_OUTOFMEMORY	メモリ不足。

最初の 4 つのパラメーターは、ITextServices::TxDraw の対応するパラメーターと同様で、同じ情報を与えます。行を再計算する必要がある場合は、ITextServices::TxDraw と同じ方法でこれらの値を使用してください。

pwidth および pheight パラメーターは入出力パラメーターです。ホストは、テキストオブジェクトの自然な範囲の暫定的な幅と高さを渡します。text services オブジェクトはこれらの値を現在のキャッシュ状態と比較し、異なる場合は行を再計算します。その後、dwMode で指定されたとおりに自然なサイズを計算して返します。

テキストコントロールのドロップターゲットを取得します。

型: HRESULT

メソッドがドロップターゲットを正常に取得した場合、戻り値は S_OK です。

COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_OUTOFMEMORY	ドロップターゲットを作成できませんでした。

ホスト(呼び出し元)は、RegisterDragDrop または RevokeDragDrop を呼び出す責任、および完了時に返されたドロップターゲットに対して Release を呼び出す責任を負います。

コントロールのプロパティ(ビットで表される)を設定します。

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。

メソッドが失敗した場合、戻り値は次の HRESULT コードです。COM エラーコードの詳細については、Error Handling in COM を参照してください。

リターンコード	説明
E_NOTIMPL	実装されていません。

クライアント矩形は、text services オブジェクトが描画と管理を担当する矩形です。ホストはその領域の描画を text services オブジェクトに依存します。text services オブジェクトは、その矩形の外側の領域を描画したり無効化したりしてはなりません。さらに、カーソルがこの矩形の上にあるとき、ホストはマウスメッセージを text services オブジェクトへ転送します。この矩形は、含まれるウィンドウのクライアント座標で表されます。

ビューインセットは、クライアント矩形とビュー矩形の間の各辺のスペースの量です。ビュー矩形(書式設定矩形とも呼ばれます)は、テキストを書式設定する矩形です。詳細については、TxGetViewInset を参照してください。

backstyle は、クライアント矩形の背景のスタイルです。TXTBACK_TRANSPARENT または TXTBACK_SOLID のいずれかになります。TXTBACKSTYLE を参照してください。

スクロールバープロパティは、スクロールバーの変更、すなわちどのスクロールバーが存在するか、スクロールが不可能なときにスクロールバーを非表示にするか無効にするか、および挿入位置がクライアント矩形から外れたときに自動スクロールを有効にするかどうかを示します。

text services が使用しているキャッシュされた描画論理サイズ(存在する場合)を返します。通常、これは ITextServices::TxDraw や ITextServices::OnTxSetCursor などで最後に使用されたクライアント矩形のサイズになりますが、保証されるわけではありません。

型: HRESULT

メソッドが成功した場合、戻り値は HRESULT コードです。

このメソッドにより、ホストはキャッシュされた描画サイズ情報を保持する必要や、同期を維持する必要から解放されます。

#define global IID_ITextServices "{}"
#usecom global ITextServices IID_ITextServices "{}"
#comfunc global ITextServices_TxSendMessage           3 int,sptr,sptr,var
#comfunc global ITextServices_TxDraw                  4 int,int,sptr,var,sptr,sptr,var,var,var,sptr,int,int
#comfunc global ITextServices_TxGetHScroll            5 var,var,var,var,var
#comfunc global ITextServices_TxGetVScroll            6 var,var,var,var,var
#comfunc global ITextServices_OnTxSetCursor           7 int,int,sptr,var,sptr,sptr,var,int,int
#comfunc global ITextServices_TxQueryHitPoint         8 int,int,sptr,var,sptr,sptr,var,int,int,var
#comfunc global ITextServices_OnTxInPlaceActivate     9 var
#comfunc global ITextServices_OnTxInPlaceDeactivate   10
#comfunc global ITextServices_OnTxUIActivate          11
#comfunc global ITextServices_OnTxUIDeactivate        12
#comfunc global ITextServices_TxGetText               13 var
#comfunc global ITextServices_TxSetText               14 wstr
#comfunc global ITextServices_TxGetCurTargetX         15 var
#comfunc global ITextServices_TxGetBaseLinePos        16 var
#comfunc global ITextServices_TxGetNaturalSize        17 int,sptr,sptr,var,int,var,var,var
#comfunc global ITextServices_TxGetDropTarget         18 sptr
#comfunc global ITextServices_OnTxPropertyBitsChange  19 int,int
#comfunc global ITextServices_TxGetCachedSize         20 var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。