О текстовой объектной модели

Объектная модель текста (TOM) определяет набор интерфейсов обработки текста, которые поддерживаются в различных уровнях несколькими текстовыми решениями Майкрософт, включая элемент управления расширенными изменениями. В этом разделе представлен общий обзор TOM. В ней рассматриваются следующие темы.

• Объекты TOM версии 2
• Соглашения об интерфейсе TOM
• Тип tomBool
• Математические сборки и сборка вниз
• TOM RTF
• Поиск форматированного текста
• Специальные возможности TOM
  • Интерфейс из запущенной таблицы объектов
  • Интерфейс из сообщений окна
  • Специальные методы
• Наборы совпадений символов

Объекты TOM версии 2

TOM версии 2 (TOM 2) расширяет исходную текстовую объектную модель; новые интерфейсы являются производными от старых. Обновленный API TOM включает поддержку новых свойств формата символов и абзаца, табличную модель, несколько выделения и встроенную поддержку объектов для математических и ruby.

Объект TOM 2 верхнего уровня определяется интерфейсом ITextDocument2 , который имеет методы для создания и извлечения объектов ниже в иерархии объектов. Для простой обработки обычного текста можно получить объект ITextRange2 из объекта ITextDocument2 и сделать все с этим. Если необходимо добавить форматирование форматированного текста, можно получить объекты ITextFont2 и ITextPara2 из объекта ITextRange2. ITextFont2 предоставляет эквивалент программирования диалогового окна форматирования Microsoft Word, а ITextPara2 — эквивалент диалогового окна формата Word.

Помимо этих трех объектов нижнего уровня, TOM 2 имеет объект выбора (ITextSelection2), который является объектом 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 описывает один или несколько смежных диапазонов текста, называемых историями. Истории представляют различные части документа, такие как основной текст документа, верхние и нижние колонтитулы, сноски, заметки и сносы, а также колонтитулы с форматированным текстом. История с нуля используется при переводе между линейно отформатированными математическими выражениями и созданной формой. История с нуля также используется при сохранении содержимого диапазона, который является текущим источником копирования при изменении содержимого.

Объект 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, многие методы включают параметры, которые являются указателями, используемыми для возврата значений. Для всех интерфейсов следует проверка все параметры указателя, чтобы убедиться, что они не являются ненулевой, прежде чем использовать их. При передаче значения NULL методу, требующего допустимого указателя, метод возвращает E_INVALIDARG. Необязательные указатели с значениями NULL игнорируются.

Используйте методы с префиксами Get и Set для получения и задания свойств. Логические переменные используют tomFalse (0) для FALSE и tomTrue (-1) для TRUE.

Константы TOM определяются в типе перечисления tomConstants и начинаются с префикса тома, например tomWord.

Тип tomBool

Многие методы TOM используют специальный тип переменной с именем tomBool для атрибутов форматированного текста, имеющих двоичные состояния. Тип tomBool отличается от логического типа, так как он может принимать четыре значения: tomTrue, tomFalse, tomToggle и tomUndefined. Значения tomTrue и tomFalse указывают значение true и false. Значение tomToggle используется для переключения свойства. Значение tomUndefined , более традиционно называемое NINCH, — это специальное значение no-input, no-change, которое работает с длинными, плавающими и 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) обновляется до точки в тексте пробного диапазона, а функция возвращает количество символов в сопоставленном диапазоне. Два объекта pf1 ITextFont и 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 объекта.

Так как программы специальных возможностей на основе пользовательского интерфейса обычно работают с экраном и мышью, часто волнует поиск соответствующего интерфейса ITextDocument для текущего расположения мыши (в координатах экрана). В следующих разделах представлены два способа определения правильного интерфейса:

• В таблице запускаемых объектов
• Через сообщение EM_GETOLEINTERFACE, которое работает для экземпляров расширенных возможностей редактирования окна, если клиент находится в том же пространстве процесса (маршалинг не требуется)

Дополнительные сведения см. в спецификации Microsoft Active Accessibility. Получив объект из положения экрана, можно использовать для интерфейса ITextDocument и вызвать метод RangeFromPoint, чтобы получить пустой объект диапазона в cp, соответствующий положению экрана.

Интерфейс из запущенной таблицы объектов

Запущенная таблица объектов (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 имеет широкий характер редактирования и возвращает указатель на интерфейс IRichEditOle в переменной, адресованной lParam.

Совет, если возвращается указатель (не забудьте задать объект, которому 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 улучшают то, что можно сделать при поступлении в интересующие места. В следующей таблице описаны наиболее полезные методы.

Наборы совпадений символов

Параметр варианта различных методов Move* в ITextRange, таких как MoveTime и MoveUntil, может принимать явную строку или 32-разрядный индекс сопоставления символов. Индексы определяются диапазонами Юникода или наборами символов GetStringTypeEx. Диапазон Юникода начиная с n и длины l (< 32768) получает индекс n + (l << 16) + 0x80000000. Например, базовые греческие буквы определяются CR_Greek = 0x805f0370 и печатными символами ASCII определяются CR_ASCIIPrint = 0x805e0020. Кроме того, методы MoveTime и MoveUntil позволяют быстро обойти диапазон символов в любом наборе символов GetStringTypeEx или в диапазоне символов, не входящих в один из этих наборов символов.

Наборы GetStringTypeEx задаются значениями для Ctype1, Ctype2 и Ctype3 и определяются следующим образом.

В частности, Ctype1 может быть любым сочетанием следующего.

Типы Ctype2 поддерживают правильный макет текста Юникода. Атрибуты направления назначаются таким образом, чтобы алгоритм двунаправленного макета, стандартизированный Юникодом, выдает точные результаты. Эти типы являются взаимоисключающими. Дополнительные сведения об использовании этих атрибутов см. в разделе "Стандарт Юникода: кодировка символов по всему миру", тома 1 и 2, addison-Wesley Publishing Company: 1991, 1992.

Типы Ctype3 предназначены для заполнителей для расширений типов POSIX, необходимых для общей обработки текста или стандартных функций библиотекИ C.

Пакет средств разработки для редактирования (EDK) может включать определения индекса pVar для следующих диапазонов, описанных в Стандарте Юникода.