关于文本对象模型

文本对象模型（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 格式段落对话框等效的编程。

除了这三个较低级别的对象外，TOM 2 还有一个选择对象（ITextSelection2），它是一个 ITextRange2 对象，其中突出显示了选定内容和一些面向 UI 的方法。

范围和选择对象包括面向屏幕的方法，这些方法使程序能够检查屏幕上的文本或可滚动到屏幕上的文本。 例如，这些功能有助于使视力受损的人能够访问文本。

具有 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 对象描述一个或多个称为故事的文本连续范围。 故事表示文档的各个部分，例如文档的主文本、页眉和页脚、脚注、批注和富文本暂存板。 在线性格式的数学表达式和内置窗体之间进行转换时，将使用暂存板故事。 当保存一个当前复制源的范围内容，而这些内容即将更改时，还会使用暂存板记录。

ITextRange2 对象由其开始和结束字符位置偏移量和故事对象定义。 它不与其父故事对象独立存在，尽管其文本可以复制到剪贴板或其他目标。 文本范围对象不同于电子表格和其他范围对象，这些对象由其他类型的偏移量定义：例如，行/列或图形位置（x，y）。 文本范围对象可以以各种方式修改自身，可以返回自身的重复项，并且可以命令复制其开始和结束字符位置以及指向当前所选内容的故事指针。

不需要显式情节对象，因为始终可以创建 ITextRange 对象来表示任何给定的故事。 具体而言， ITextDocument 对象可以创建 一个 ITextStoryRanges 对象，以范围来枚举文档中的故事，其中包含描述完整故事（如 0 和 tomForward）的起始和结束字符位置值。

使用 ITextStoryRanges2 对象时，不需要显式故事对象，因为每个故事都由 ITextRange2 对象描述。 具体而言，ITextDocument2 对象可以创建 ITextStoryRanges2 对象，以按起始和结束字符位置值的范围枚举文档中的所有完整的故事（如 0 和 tomForward）。

ITextRow 接口与 ITextRange：：Move 和 ITextRange：：Expand 方法一起提供插入、查询和更改表的功能。

TOM 接口约定

所有 TOM 方法都返回 HRESULT 值。 通常，TOM 方法返回以下标准值。

• E_OUTOFMEMORY
• E_INVALIDARG
• E_NOTIMPL
• E_FILENOTFOUND
• E_ACCESSDENIED（访问被拒绝）
• E_FAIL
• CO_E_RELEASED
• NOERROR （与S_OK相同）
• S_FALSE

请注意，如果删除与 TOM 对象（如 ITextRange ）关联的编辑实例，TOM 对象将变得无用，并且其所有方法都会返回CO_E_RELEASED。

除了 HRESULT 返回值之外，许多方法还包含 out 参数，这是用于返回值的指针。 对于所有接口，应检查所有指针参数，以确保在使用这些参数之前它们是非零的。 如果将 null 值传递给需要有效指针的方法，该方法将返回E_INVALIDARG。 忽略具有 null 值的可选 out 指针。

使用具有 Get 和 Set 前缀的方法来获取和设置属性。 布尔变量将 tomFalse （0） 用于 FALSE，将 tomTrue （-1） 用于 TRUE。

TOM 常量在 tomConstants 枚举类型中定义，以前缀 tom 开头，例如 tomWord。

tomBool 类型

许多 TOM 方法对具有二进制状态的富文本属性使用名为“tomBool”的特殊类型的变量。 tomBool 类型不同于 布尔 类型，因为它可以采用四个值：tomTrue、tomFalse、tomToggle 和 tomUndefined。 tomTrue 和 tomFalse 值指示 true 和 false。 tomToggle 值用于切换属性。 tomUndefined 值（更传统的称为 NINCH）是一种特殊的无输入、无更改值，适用于 longs、floats 和 COLORREFs。 对于字符串， tomUndefined （或 NINCH） 由 null 字符串表示。 对于属性设置作，使用 tomUndefined 不会更改目标属性。 在属性获取操作中，tomUndefined 表示范围内的字符具有不同的值（在属性对话框中显示为灰色复选框）。

数学递增和递减

可以使用 ITextRange2：：BuildUpMath 方法将线性格式的数学表达式转换为内置版本。 ITextRange2：：Linearize 方法执行相反的转换（称为线性化或向下生成）将数学表达式的内置版本转换回线性格式。 需要导出纯文本或启用某些类型的编辑时，数学生成功能非常有用。

TOM RTF

在 TOM 中，富文本交换可以通过一组显式方法调用或 RTF 中的富文本传输来实现。 本部分为段落属性和字符属性提供 RTF 控件单词的表。

TOM RTF 段落控制词

TOM RTF 字符格式控制词

查找富文本

可以使用 TOM 方法查找由一系列文本定义的富文本。 在文字处理中经常需要精确地找到如此丰富的文本，然而，它从未在“所见即所得”（WYSIWYG）文字处理器中实现过。 显然，有一个较大的格式文本匹配域，允许忽略某些字符格式属性（或包括段落格式和/或对象内容），但这种通用化超出了本部分的范围。

此功能的一个用途是使用富文本 “查找 ”对话框来定义要在文档中查找的富文本。 对话框将使用丰富的编辑控件实现，TOM 方法将用于通过文档执行搜索。 可以将所需的富文本从文档复制到 “查找” 对话框中，或者直接在 “查找” 对话框中输入并格式化。

以下示例演示如何使用 TOM 方法查找包含精确字符格式组合的文本。 该算法在匹配范围内搜索纯文本，并命名为 pr1。 如果找到纯文本，则由一个命名 pr2的试用范围指向它。 然后，使用两个插入点范围（prip1 和 prip2）遍历试验范围，将其字符格式与它的 pr1字符格式进行比较。 如果它们完全匹配，则输入范围（由 ppr给定）更新为指向试用范围的文本，并且该函数返回匹配区域中的字符计数。 两个 ITextFont 对象，pf1 和 pf2，用于字符格式比较。 它们连接到插入点范围 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 接口（在屏幕坐标中）。 以下部分提供了两种方法来确定正确的接口：

• 通过 running-object 表
• 通过 EM_GETOLEINTERFACE 消息，适用于有窗口的富文本编辑实例，前提是客户端位于同一进程空间（无需 封送 处理）

有关详细信息，请参阅 Microsoft Active Accessibility 规范。 从屏幕位置获取对象后，可以用于 ITextDocument 接口，并调用 RangeFromPoint 方法以获取与屏幕位置对应的 cp 处的空范围对象。

运行对象表的接口

正在运行的对象表 （ROT） 指示哪些对象实例处于活动状态。 通过查询此表，可以加速在对象正在运行时将客户端连接到对象的过程。 在程序可以通过正在运行的对象表 (ROT) 访问面向对象模型 (TOM) 接口之前，具有窗口的 TOM 实例需要使用标识符在 ROT 中注册。 你可以从一个包含其 HWND 十六进制值的字符串中构造一个标识符对象。 下面的代码示例演示如何执行此作。

// 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 方法可增强到达感兴趣的地方时的功能。 下表描述了最有用的方法。

字符匹配集合

ITextRange 中各种 Move* 方法的变体参数（如 MoveWhile 和 MoveUntil）可以采用显式字符串或字符匹配集 32 位索引。 索引由 Unicode 范围或 GetStringTypeEx 字符集定义。 索引 n + （l << 16） + 0x80000000提供从 n 和长度 l （<32768） 开始的 Unicode 范围。 例如，基本希腊文字母由 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 索引定义。