關於文字物件模型

文字物件模型 （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) 代表 假，並將 tomTrue (-1) 用於 真。

TOM 常數定義於 tomConstants 列舉類型中，並以前綴 tom開頭，例如 tomWord。

tomBool 類型

許多 TOM 方法會針對具有二進位狀態的 RTF 屬性使用稱為 「tomBool」 的特殊變數類型。 tomBool 類型與 布爾值 類型不同，因為它可能需要四個值：tomTrue、tomFalse、tomToggle和 tomUndefined。 tomTrue 和 tomFalse 的值表示真假。 tomToggle 值可用來切換屬性。 tomUndefined 值，傳統上稱為 NINCH，是一種特殊的無輸入、無變更值，適用於長整數、浮點數和 COLORREF。 對於字串，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 介面（在螢幕座標中）。 下列各節提供兩種方式來判斷適當的介面：

• 透過執行中的物件數據表
• 透過適用於窗口豐富編輯實例的 EM_GETOLEINTERFACE 訊息，前提是客戶端位於相同的進程空間中（不需要 封送處理）

如需詳細資訊，請參閱 Microsoft Active Accessibility 規格。 從螢幕位置取得對象之後，您可以使用 ITextDocument 介面，並呼叫 RangeFromPoint 方法，以取得與螢幕位置相對應之 cp 的空白範圍物件。

來自執行中對象數據表的介面

執行中的物件數據表 （ROT） 會指出哪些物件實例為使用中。 藉由查詢此資料表，您可以在物件已經在執行時，加速將客戶端連接到物件。 在程式可以透過執行中的對象數據表存取 TOM 介面之前，具有視窗的 TOM 實例必須使用 Moniker 在 ROT 中註冊。 您可以從字串建構Moniker，其中包含其 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* 方法的 variant 參數，例如 MoveWhile 和 MoveUntil，可以使用明確的字串或字符比對集的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) 可以包含 pVar 索引定義，適用於 Unicode 標準中描述的以下範圍。