テキスト オブジェクト モデルについて

テキスト オブジェクト モデル (TOM) は、リッチ エディット コントロールなど、いくつかの Microsoft テキスト ソリューションによってさまざまな程度でサポートされるテキスト操作インターフェイスのセットを定義します。 このトピックでは、TOM の概要について説明します。 ここでは、次のトピックについて説明します。

• TOM バージョン 2 オブジェクト
• TOM インターフェイス規則
• tomBool 型
• 数値演算のビルドアップとビルドダウン
• TOM RTF
• リッチ テキストの検索
• TOM アクセシビリティ
  • 実行中のオブジェクト テーブルからのインターフェイス
  • ウィンドウ メッセージからのインターフェイス
  • アクセシビリティ指向メソッド
• 文字パターングループ

TOM バージョン 2 オブジェクト

TOM バージョン 2 (TOM 2) は、元のテキスト オブジェクト モデルを拡張します。新しいインターフェイスは古いインターフェイスから派生します。 更新された TOM API には、新しい文字と段落の書式プロパティ、テーブル モデル、複数選択、数学と Ruby のインライン オブジェクトのサポートが含まれています。

最上位の TOM 2 オブジェクトは、オブジェクト階層の下位にあるオブジェクトを作成および取得するためのメソッドを持つ ITextDocument2 インターフェイスによって定義されます。 単純なプレーンテキスト処理の場合は、ITextDocument2 オブジェクトから ITextRange2 オブジェクトを取得し、それを使用してほとんどの処理を行うことができます。 リッチ テキストの書式設定を追加する必要がある場合は、ITextRange2 オブジェクトから ITextFont2 オブジェクトと ITextPara2 オブジェクトを取得できます。 ITextFont2 は、Microsoft Word の書式フォント ダイアログと同等のプログラミングを提供し、 ITextPara2 は Word の書式段落ダイアログと同等の機能を提供します。

これら 3 つの下位レベルのオブジェクトに加えて、TOM 2 には選択オブジェクト (ITextSelection2) があります。これは、選択の強調表示と一部の UI 指向メソッドを持つ ITextRange2 オブジェクトです。

範囲オブジェクトと選択オブジェクトには、画面上のテキストまたは画面にスクロールできるテキストをプログラムで調べることができる画面指向のメソッドが含まれます。 これらの機能は、視覚障害のあるユーザーがテキストにアクセスできるようにするのに役立ちます。

2 サフィックスを持つ各インターフェイスは、2 つのサフィックスを持たない対応するインターフェイスから継承されます。 たとえば、 ITextDocument2 は ITextDocument から継承します。

TOM 2 オブジェクトの階層は次のとおりです。

ITextDocument2         Top-level editing object
    ITextRange2        Primary text interface: a range of text
        ITextFont2     Character-attribute interface
        ITextPara2     Paragraph-attribute interface
        ITextRow       Table interface
    ITextSelection2    Screen highlighted text range
        ITextRange2    Selection inherits all range methods
    ITextDisplays      Displays collection (not yet defined)
    ITextStrings       Rich-text strings collection
    ITextStoryRanges2  Enumerator for stories in document

ITextDocument2 オブジェクトは、ストーリーと呼ばれる 1 つ以上の連続したテキスト範囲を表します。 ストーリーは、ドキュメントのメイン テキスト、ヘッダーとフッター、脚注、注釈、リッチ テキスト スクラッチ パッドなど、ドキュメントのさまざまな部分を表します。 スクラッチ パッド ストーリーは、線形形式の数式と組み込みフォームの間で翻訳するときに使用されます。 スクラッチ パッド ストーリーは、コンテンツが変更される現在のコピー ソースである範囲の内容を保存するときにも使用されます。

ITextRange2 オブジェクトは、開始位置と終了位置のオフセットとストーリー オブジェクトによって定義されます。 テキストはクリップボードまたは他のターゲットにコピーできますが、親ストーリー オブジェクトとは独立して存在しません。 テキスト範囲オブジェクトは、他の種類のオフセットによって定義されるスプレッドシートや他の範囲オブジェクトとは異なります。たとえば、行/列やグラフィックスの位置 (x、y) などです。 テキスト範囲オブジェクトは、さまざまな方法で自身を変更し、それ自体の複製を返すことができます。また、開始位置と終了文字位置、および現在の選択範囲へのストーリー ポインターをコピーするようにコマンドを実行できます。

ITextRange オブジェクトは常に特定のストーリーを表すために作成できるため、明示的なストーリー オブジェクトは必要ありません。 特に、 ITextDocument オブジェクトは 、ITextStoryRanges オブジェクトを作成して、完全なストーリー (0、 tomForward など) を記述する開始文字と終了文字の位置値を持つ範囲の観点からドキュメント内のストーリーを列挙できます。

ITextStoryRanges2 オブジェクトでは、各ストーリーは ITextRange2 オブジェクトによって記述されるため、明示的なストーリー オブジェクトは必要ありません。 特に、 ITextDocument2 オブジェクトは 、ITextStoryRanges2 オブジェクトを作成して、完全なストーリー (0、 tomForward など) を記述する開始文字と終了文字の位置値を持つ範囲の観点からドキュメント内のストーリーを列挙できます。

ITextRange::Move メソッドおよび ITextRange::Expand メソッドと共に ITextRow インターフェイスを使用すると、テーブルの挿入、クエリ、変更を行うことができます。

TOM インターフェイス規則

すべての TOM メソッドは HRESULT 値を 返します。 一般に、TOM メソッドは次の標準値を返します。

• E_OUTOFMEMORY
• 無効な引数エラー (E_INVALIDARG)
• E_NOTIMPL
• E_FILENOTFOUND
• E_ACCESSDENIED (アクセス拒否)
• E_FAIL
• CO_E_RELEASED
• NOERROR (S_OKと同じ)
• S_FALSE

ITextRange などの TOM オブジェクトに関連付けられている編集インスタンスが削除されると、TOM オブジェクトは役に立たなくなり、そのすべてのメソッドはCO_E_RELEASEDを返します。

HRESULT 戻り値に加えて、多くのメソッドには、値を返すために使用されるポインターである out パラメーターが含まれています。 すべてのインターフェイスについて、すべてのポインター パラメーターをチェックして、使用する前に 0 以外であることを確認する必要があります。 有効なポインターを必要とするメソッドに null 値を渡すと、メソッドはE_INVALIDARGを返します。 null 値を持つ省略可能な out ポインターは無視されます。

Get プレフィックスと Set プレフィックスを持つメソッドを使用して、プロパティを取得および設定します。 ブール変数は FALSE の場合は tomFalse (0)、TRUE の場合は tomTrue (-1) を使用します。

TOM 定数は tomConstants 列挙型で定義され、プレフィックス tom ( tomWord など) で始まります。

tomBool 型

多くの TOM メソッドでは、バイナリ状態のリッチ テキスト属性に "tomBool" という特殊な型の変数が使用されています。 tomBool型はBoolean型とは異なり、tomTrue、tomFalse、tomToggle、tomUndefinedの4つの値を取ることができます。 tomTrue 値と tomFalse 値は true と false を示します。 tomToggle 値は、プロパティの切り替えに使用されます。 従来 NINCH と呼ばれる tomUndefined 値は、longs、floats、 COLORREFで動作する特別な入力なし、変更なし値です。 文字列の場合、 tomUndefined (または NINCH) は null 文字列で表されます。 プロパティ設定操作の場合、 tomUndefined を 使用してもターゲット プロパティは変更されません。 プロパティ取得操作の場合、 tomUndefined は、範囲内の文字の値が異なることを意味します (プロパティ ダイアログ ボックスの灰色のチェック ボックスが表示されます)。

数値演算のビルドアップとビルドダウン

ITextRange2::BuildUpMath メソッドを使用すると、線形形式の数式を組み込みバージョンに変換できます。 ITextRange2::Linearize メソッドは、線形化またはビルドダウンと呼ばれる逆の変換を実行して、組み込みバージョンの数式を線形形式に変換します。 数式のビルド ダウン機能は、プレーン テキストをエクスポートする必要がある場合や、特定の種類の編集を有効にする必要がある場合に便利です。

TOM RTF

TOM では、リッチ テキスト交換は、明示的なメソッド呼び出しのセットまたはリッチ テキスト形式 (RTF) でのリッチ テキストの転送によって実現できます。 このセクションでは、段落プロパティと文字プロパティの RTF コントロール ワードの表を示します。

TOM RTF 段落コントロールワード

TOM RTF 文字書式制御語

リッチ テキストの検索

TOM メソッドを使用すると、テキストの範囲で定義されているリッチ テキストを検索できます。 このようなリッチテキストを正確に見つけることは、ワープロで必要になることがよくありますが、「WYSIWYG」（ウィジウィグ）型のワードプロセッサでは実現されたことはありません。 一部の文字書式プロパティを無視 (または段落の書式設定やオブジェクト コンテンツを含める) ことを可能にするリッチ テキスト 照合のより大きなドメインは明らかですが、このような一般化は、このセクションの範囲外です。

この機能の 1 つの目的は、 リッチ テキスト検索 ダイアログ ボックスを使用して、ドキュメント内で検索するリッチ テキストを定義することです。 ダイアログ ボックスは豊富な編集コントロールを使用して実装され、TOM メソッドを使用してドキュメントを検索します。 文書から目的のリッチ テキストを [検索] ダイアログ ボックスにコピーするか、[検索] ダイアログ ボックスで直接入力して書式設定することができます。

次の例は、TOM メソッドを使用して、正確な文字書式の組み合わせを含むテキストを検索する方法を示しています。 アルゴリズムは、 pr1という名前の一致範囲内のプレーン テキストを検索します。 プレーン テキストが見つかった場合は、pr2という名前の試行範囲によって指されます。 次に、2 つの挿入ポイント範囲 (prip1 と prip2) を使用して、文字の書式設定と pr1の文字書式を比較する試用範囲を確認します。 完全に一致する場合、入力範囲 ( ppr によって指定) が評価版範囲のテキストを指すように更新され、関数は一致した範囲内の文字数を返します。 文字書式の比較では、pf1 と pf2 の 2 つの ITextFont オブジェクトが使用されます。 これらは、 prip1 および prip2の挿入ポイント範囲にアタッチされます。

LONG FindRichText (
    ITextRange **ppr,             // Ptr to range to search
    ITextRange *pr1)              // Range with rich text to find
{
    BSTR        bstr;             // pr1 plain-text to search for
    LONG        cch;              // Text string count
    LONG        cch1, cch2;       // tomCharFormat run char counts
    LONG        cchMatch = 0;     // Nothing matched yet
    LONG        cp;               // Handy char position
    LONG        cpFirst1;         // pr1 cpFirst
    LONG        cpFirst2;         // pr2 cpFirst
    ITextFont  *    pf1, *pf      // Fonts corresponding to IPs prip1 and prip2
    ITextRange *pr2;              // Range duplicate to search with
    ITextRange *prip1, *prip      // Insertion points to walk pr1, pr2

    if (!ppr || !*ppr || !pr1)
        return E_INVALIDARG;

    // Initialize range and font objects used in search
    if ((*ppr)->GetDuplicate(&pr2)    != NOERROR ||
        pr1->GetDuplicate(&prip1)     != NOERROR ||
        pr2->GetDuplicate(&prip2)     != NOERROR ||
        prip1->GetFont(&pf1)          != NOERROR ||
        prip2->GetFont(&pf2)          != NOERROR ||
        pr1->GetText(&bstr)           != NOERROR )
    {
        return E_OUTOFMEMORY;
    }

    pr1->GetStart(&cpFirst1);

    // Keep searching till rich text is matched or no more plain-text hits
    while(!cchMatch && pr2->FindText(bstr, tomForward, 0, &cch) == NOERROR)
    {
        pr2->GetStart(&cpFirst2);                 // pr2 is a new trial range
        prip1->SetRange(cpFirst1, cpFirst1);      // Set up IPs to scan match
        prip2->SetRange(cpFirst2, cpFirst2);      //  and trial ranges

        while(cch > 0 &&
            pf1->IsEqual(pf2, NULL) == NOERROR)   // Walk match & trial ranges
        {                                         //  together comparing font
            prip1->GetStart(&cch1);               //  properties
            prip1->Move(tomCharFormat, 1, NULL);
            prip1->GetStart(&cp);
            cch1 = cp - cch1;                     // cch of next match font run

            prip2->GetStart(&cch2);
            prip2->Move(tomCharFormat, 1, NULL);
            prip2->GetStart(&cp);
            cch2 = cp - cch2;                      // cch of next trial font run

            if(cch1 < cch)                         // There is more to compare
            {
                if(cch1 != cch2)                   // Different run lengths:
                    break;                         //  no formatting match
                cch = cch - cch1;                  // Matched format run
            }
            else if(cch2 < cch)                    // Trial range format run too
                break;                             //  short

            else                                   // Both match and trial runs
            {                                      //  reach at least to match
                pr2->GetEnd(&cp);                  //  text end: rich-text match
                (*ppr)->SetRange(cpFirst2, cp)     // Set input range to hit
                cchMatch = cp - cpFirst2;          //  coordinates and return
                break;                             //  length of matched string
            }
        }
    }
    pr2->Release();
    prip1->Release();
    prip2->Release();
    pf1->Release();
    pf2->Release();
    SysFreeString(bstr);

    return cchMatch;
}

TOM アクセシビリティ

TOM では、 ITextSelection インターフェイスと ITextRange インターフェイスを介したアクセシビリティ サポートが提供されます。 このセクションでは、アクセシビリティに役立つメソッドと、プログラムがオブジェクトの x、 y 画面の位置を決定する方法について説明します。

UI ベースのアクセシビリティ プログラムは通常、画面とマウスで動作するため、一般的な懸念事項は、現在のマウス位置 (画面座標) に対応する ITextDocument インターフェイスを見つけることです。 次のセクションでは、適切なインターフェイスを決定する 2 つの方法について説明します。

• 実行中のオブジェクト テーブルを使用する
• クライアントが同じプロセス空間に存在する場合は、ウィンドウ化されたリッチエディット インスタンスに対して機能する EM_GETOLEINTERFACE メッセージを使用します ( マーシャリング は必要ありません)

詳細については、Microsoft Active Accessibility 仕様を参照してください。 画面位置からオブジェクトを取得した後、 ITextDocument インターフェイスに使用し、 RangeFromPoint メソッドを呼び出して、画面の位置に対応する cp で空の範囲オブジェクトを取得できます。

実行中のオブジェクト テーブルからのインターフェイス

実行中のオブジェクト テーブル (ROT) は、アクティブなオブジェクト インスタンスを示します。 このテーブルに対してクエリを実行すると、オブジェクトが既に実行されているときに、クライアントをオブジェクトに接続するプロセスを高速化できます。 実行中のオブジェクト テーブルを介してプログラムから TOM インターフェイスにアクセスするには、ウィンドウがある TOM インスタンスをモニカーを使用して ROT に登録する必要があります。 モニカーは、 その HWND の 16 進値を含む文字列から構築します。 次のコード サンプルは、これを行う方法を示しています。

// This TOM implementation code is executed when a new windowed 
// instance starts up. 
// Variables with leading underscores are members of this class.

HRESULT hr;
OLECHAR szBuf[10];            // Place to put moniker
MONIKER *pmk;

hr = StringCchPrintf(szBuff, 10, "%x", _hwnd);
if (FAILED(hr))
{
    //
    // TODO: write error handler
    //
}
CreateFileMoniker(szBuf, &pmk);
OleStdRegisterAsRunning(this, pmk, &_dwROTcookie);
....................
 
// Accessibility Client: 
//    Find hwnd for window pointed to by mouse cursor.

GetCursorPos(&pt);
hwnd = WindowFromPoint(pt);

// Look in ROT (running object table) for an object attached to hwnd

hr = StringCchPrintf(szBuff, 10, "%x", hwnd);
if (FAILED(hr))
{
    //
    // TODO: write error handler
    //
}
CreateFileMoniker(szBuf, &pmk);
CreateBindContext(0, &pbc);
pmk->BindToObject(pbc, NULL, IID_ITextDocument, &pDoc);
pbc->Release();

if( pDoc )
{
    pDoc->RangeFromPoint(pt.x, pt.y, &pRange);
    // ...now do whatever with the range pRange
}

ウィンドウ メッセージからのインターフェイス

EM_GETOLEINTERFACE メッセージは、特定の画面位置にあるオブジェクトの IUnknown インターフェイスを取得する別の方法を提供します。 「 実行中のオブジェクト テーブルからのインターフェイス」で説明されているように、画面位置の HWND を取得し、その HWND にこのメッセージを送信します。 EM_GETOLEINTERFACE メッセージは、リッチ エディット固有であり、lParam によってアドレス指定された変数内の IRichEditOle インターフェイスへのポインターを返します。

ヒント ポインタが返される場合は (lParam が指すオブジェクトをメッセージを送信する前に null に設定してください)、IUnknown::QueryInterface メソッドを呼び出して ITextDocument インターフェースを取得することが可能です。 次のコード サンプルに、この方法を示します。

    HWND    hwnd;
    ITextDocument *pDoc;
    ITextRange *pRange;
    POINT    pt;
    IUnknown *pUnk = NULL;
    
    GetCursorPos(&pt);
    hwnd = WindowFromPoint(pt);
    SendMessage(hwnd, EM_GETOLEINTERFACE, 0, (LPARAM)&pUnk);
    if(pUnk && 
        pUnk->QueryInterface(IID_ITextDocument, &pDoc) == NOERROR)
    {
        pDoc->RangeFromPoint(pt.x, pt.y, &pRange);
        //  ... continue with rest of program
    }

アクセシビリティ指向メソッド

一部の TOM メソッドは画面内を移動するのに特に役立ちますが、他の TOM メソッドは、関心のある場所に到着したときに実行できる操作を強化します。 次の表では、最も便利な方法について説明します。

キャラクターマッチセット

MoveWhile や MoveUntil など、ITextRange のさまざまな Move* メソッドのバリアント パラメーターは、明示的な文字列または文字一致セットの 32 ビット インデックスを受け取ることができます。 インデックスは、Unicode 範囲または GetStringTypeEx 文字セットによって定義されます。 n および長さ l (< 32768) から始まる Unicode 範囲は、インデックス n + (l << 16) + 0x80000000で指定されます。 たとえば、基本的なギリシャ文字は CR_Greek = 0x805f0370 で定義され、印刷可能な ASCII 文字は CR_ASCIIPrint = 0x805e0020 で定義されます。 さらに、 MoveWhile メソッドと MoveUntil メソッドを使用すると、 GetStringTypeEx 文字セットまたはこれらの文字セットに含まれていない文字のスパンで、一連の文字をすばやくバイパスできます。

GetStringTypeEx セットは、Ctype1、Ctype2、および Ctype3 の値で指定され、次のように定義されます。

具体的には、 Ctype1 は、以下の任意の組み合わせとすることができる。

Ctype2 型は、Unicode テキストの適切なレイアウトをサポートします。 方向属性が割り当てられ、Unicode によって標準化された双方向レイアウト アルゴリズムによって正確な結果が生成されます。 これらの型は相互に排他的です。 これらの属性の使用方法の詳細については、「 Unicode 標準: ワールドワイド文字エンコード、ボリューム 1 および 2、Addison-Wesley パブリッシング カンパニー: 1991、1992」を参照してください。

Ctype3 型は、一般的なテキスト処理または標準の C ライブラリ関数に必要な POSIX 型の拡張のためのプレースホルダーです。

開発キットの編集 (EDK) には、Unicode 標準で説明されている次の範囲の pVar インデックス定義を含めることができます。