Informacje o modelu obiektów tekstowych

Model obiektów tekstowych (TOM) definiuje zestaw interfejsów manipulowania tekstem, które są obsługiwane w różnym stopniu przez kilka rozwiązań tekstowych firmy Microsoft, w tym kontrolkę edycji sformatowanej. Ten temat zawiera ogólne omówienie rozwiązania TOM. Omówiono w nim następujące tematy.

• obiektów TOM w wersji 2
• Konwencje Interfejsu TOM
• Typ tomBool
• Konstrukcja matematyczna i dekompozycja
• tom RTF
• wyszukiwanie tekstu sformatowanego
• TOM ułatwień dostępu
  • interfejs z uruchomionej tabeli obiektów
  • interfejs z komunikatów okna
  • metody zorientowane na ułatwienia dostępu
• zestawy dopasowań znaków

Obiekty TOM w wersji 2

ToM w wersji 2 (TOM 2) rozszerza oryginalny model obiektu tekstowego; nowe interfejsy pochodzą ze starych. Zaktualizowany interfejs API TOM obejmuje obsługę nowych właściwości formatu znaków i akapitów, modelu tabeli, wielokrotnego zaznaczenia i obsługi obiektów wbudowanych na potrzeby obliczeń matematycznych i ruby.

Obiekt TOM 2 najwyższego poziomu jest definiowany przez interfejs ITextDocument2, który zawiera metody tworzenia i pobierania obiektów niższych w hierarchii obiektów. W przypadku prostego przetwarzania zwykłego tekstu można uzyskać obiekt ITextRange2 z obiektu ITextDocument2 i wykonać większość tych czynności. Jeśli musisz dodać formatowanie zaawansowanego tekstu, możesz uzyskać obiekty ITextFont2 i ITextPara2 z obiektu ITextRange2. ITextFont2 zapewnia programistyczny odpowiednik okna dialogowego format-czcionka w Microsoft Word, a ITextPara2 zapewnia odpowiednik okna dialogowego formatu akapitu w Wordzie.

Oprócz tych trzech obiektów niższego poziomu, TOM 2 ma obiekt zaznaczenia (ITextSelection2), który jest obiektem ITextRange2 z podświetleniem zaznaczenia i niektórymi metodami ukierunkowanymi na interfejs użytkownika.

Zakres i obiekty zaznaczenia obejmują metody zorientowane na ekran, które umożliwiają programom badanie tekstu widocznego na ekranie lub tekstu, który można przewijać na ekranie. Te możliwości ułatwiają na przykład dostęp do tekstu osobom z niedowidzącymi.

Każdy interfejs, który ma sufiks 2, dziedziczy po odpowiednim interfejsie bez sufiksu 2. Na przykład ITextDocument2 dziedziczy z ITextDocument.

Obiekty TOM 2 mają następującą hierarchię.

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

Obiekt ITextDocument2 opisuje jeden lub więcej ciągłych zakresów tekstu zwanych historiami. Scenariusze reprezentują różne części dokumentu, takie jak główny tekst dokumentu, nagłówki i stopki, przypisy dolne, adnotacje i podkładki do tekstu sformatowanego. Historia arkusza roboczego jest używana podczas tłumaczenia między wyrażeniami matematycznymi sformatowanymi liniowo a złożoną postacią. W przypadku zapisywania zawartości zakresu, który jest bieżącym źródłem kopiowania, jest również używany scenariusz w okienku tymczasowym, gdy zawartość ma zostać zmieniona.

Obiekt ITextRange2 jest definiowany przez przesunięcia pozycji początkowej i końcowej znaku oraz obiekt opowieści. Nie istnieje niezależnie od obiektu nadrzędnego, chociaż jego tekst można skopiować do schowka lub do innych obiektów docelowych. Obiekt zakresu tekstu różni się od arkusza kalkulacyjnego i innych obiektów zakresu, które są definiowane przez inne rodzaje przesunięć; na przykład położenie wiersza/kolumny lub grafiki (x, y). Obiekt zakresu tekstu może modyfikować się na różne sposoby, może zwracać duplikat samego siebie i można go polecenić, aby skopiować pozycje znaków początkowych i końcowych oraz wskaźnik historii do bieżącego zaznaczenia.

Obiekt jawnej historii nie jest potrzebny, ponieważ obiekt ITextRange można zawsze utworzyć w celu reprezentowania dowolnego scenariusza. W szczególności obiekt ITextDocument może utworzyć obiekt ITextStoryRanges, aby wyliczyć historie w dokumencie pod względem zakresów z wartościami położenia znaku początkowego i końcowego, które opisują kompletne historie (takie jak 0 i tomForward).

W przypadku obiektuITextStoryRanges2 obiektnie jest wymagany, ponieważ każdy scenariusz jest opisywany przez obiekt ITextRange2. W szczególności obiekt ITextDocument2 może utworzyć obiekt ITextStoryRanges2, aby wyliczyć historie w dokumencie pod względem zakresów z wartościami położenia znaku początkowego i końcowego, które opisują pełne historie (takie jak, 0 i tomForward).

Interfejs ITextRow wraz z metodami ITextRange::Move i ITextRange::Expand umożliwia wstawianie, zapytania i modyfikację tabel.

Konwencje interfejsu TOM

Wszystkie metody TOM zwracają wartości HRESULT. Ogólnie rzecz biorąc, metody TOM zwracają następujące wartości standardowe.

• E_OUTOFMEMORY
• E_INVALIDARG
• E_NOTIMPL
• E_FILENOTFOUND
• E_ACCESSDENIED
• E_FAIL
• CO_E_RELEASED
• NOERROR (taki sam jak S_OK)
• S_FALSE

Należy pamiętać, że jeśli wystąpienie edycji skojarzone z obiektem TOM, takim jak ITextRange zostanie usunięte, obiekt TOM stanie się bezużyteczny, a wszystkie jego metody zwracają CO_E_RELEASED.

Oprócz wartości zwracanych HRESULT wiele metod zawiera parametry out, które są wskaźnikami używanymi do zwracania wartości. Dla wszystkich interfejsów należy sprawdzić wszystkie parametry wskaźnika, aby upewnić się, że nie są onezerowe przed ich użyciem. Jeśli przekażesz wartość null do metody wymagającej prawidłowego wskaźnika, metoda zwróci E_INVALIDARG. Opcjonalne wskaźniki z wartościami null są ignorowane.

Użyj metod z prefiksami Get i Set, aby pobrać i ustawić właściwości. Zmienne logiczne używają tomFalse (0) dla FALSEi tomTrue (-1) dla TRUE.

Stałe TOM są definiowane w typie wyliczeniowym tomConstants i zaczynają się od prefiksu tom, na przykład tomWord.

Typ tomBool

Wiele metod TOM używa specjalnego typu zmiennej o nazwie "tomBool" dla atrybutów tekstu sformatowanego, które mają stany binarne. Typ tomBool różni się od typu logicznego, ponieważ może przyjmować cztery wartości: tomTrue, tomFalse, tomTogglei tomUndefined. Wartości tomTrue i tomFalse wskazują wartości true i false. Wartość tomToggle służy do przełączania właściwości. Wartość tomUndefined, która jest tradycyjnie nazywana NINCH, jest specjalną wartością braku danych wejściowych, bez zmian, która działa z długościami, zmiennoprzecinkami i COLORREFs. W przypadku ciągów tomUndefined (lub NINCH) jest reprezentowany przez ciąg o wartości null. W przypadku operacji ustawień właściwości użycie tomUndefined nie zmienia właściwości docelowej. W przypadku operacji pobierania właściwości tomUndefined oznacza, że znaki w zakresie mają różne wartości (daje szare pole wyboru w oknach dialogowych właściwości).

Budowanie Matematyczne i Spadek Matematyczny

Możesz użyć metody ITextRange2::BuildUpMath, aby przekonwertować wyrażenia matematyczne sformatowane liniowo na wbudowane wersje. Metoda ITextRange2::Linearize wykonuje odwrotną konwersję, nazywaną linearizacją lub redukowaniem, w celu przekształcenia bardziej złożonych wersji wyrażeń matematycznych na format liniowy. Funkcja kompilowania matematycznego jest przydatna, gdy trzeba wyeksportować zwykły tekst lub włączyć niektóre typy edycji.

TOM RTF

W programie TOM wymiana tekstu sformatowanego może odbywać się za pomocą zestawów jawnych wywołań metod lub transferów tekstu sformatowanego w formacie RTF (Rich Text Format). Ta sekcja zawiera tabele wyrazów kontrolek RTF dla właściwości akapitu i właściwości znaków.

Elementy sterujące akapitem RTF TOM

Kontrolne wyrazy formatu znaków RTF TOM

Znajdowanie tekstu z formatowaniem

Metody TOM umożliwiają znajdowanie tekstu sformatowanego, jak definiuje zakres tekstu. Znalezienie takiego wzbogaconego tekstu jest często potrzebne w przetwarzaniu tekstu, chociaż nigdy nie udało się tego osiągnąć w edytorze tekstu typu "to, co widzisz, jest tym, co dostajesz" (WYSIWYG). Istnieje wyraźnie większa domena dopasowywania tekstu sformatowanego, która umożliwia ignorowanie niektórych właściwości formatowania znaków (lub uwzględnianie formatowania akapitu i/lub zawartości obiektu), ale takie uogólnienia wykraczają poza zakres tej sekcji.

Jednym z celów tej funkcji jest użycie tekstu sformatowanego w oknie dialogowym Znajdowanie w celu zdefiniowania tekstu sformatowanego, który chcesz zlokalizować w dokumencie. Okno dialogowe zostanie zaimplementowane przy użyciu rozbudowanej kontrolki edycji, a metody TOM będą używane do przeprowadzania wyszukiwania w dokumencie. Możesz skopiować żądany sformatowany tekst z dokumentu do okna dialogowego Znajdź lub wprowadzić go i sformatować bezpośrednio w oknie dialogowym Znajdź.

W poniższym przykładzie pokazano, jak używać metod TOM do znajdowania tekstu zawierającego kombinacje dokładnego formatowania znaków. Algorytm wyszukuje zwykły tekst w zakresie dopasowania o nazwie pr1. Jeśli zostanie znaleziony zwykły tekst, jest wskazywany przez zakres próbny o nazwie pr2. Następnie dwa zakresy punktów wstawiania (prip1 i prip2) są używane do przemierzania zakresu próbnego, porównując jego formatowanie znaków z tym, które ma pr1. Jeśli są one dokładnie zgodne, zakres danych wejściowych (podany przez ppr) jest aktualizowany tak, aby wskazywał tekst zakresu próbnego, a funkcja zwraca liczbę znaków w dopasowanym zakresie. Dwa obiekty ITextFont, pf1 i pf2, są używane w porównaniu formatowania znaków. Są one dołączone do zakresów punktów wstawiania prip1 i 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;
}

Ułatwienia dostępu TOM

TOM zapewnia obsługę ułatwień dostępu za pośrednictwem interfejsów ITextSelection i ITextRange. W tej sekcji opisano metody, które są przydatne dla ułatwień dostępu, a także sposób, w jaki program może określić x, y położenie ekranu obiektu.

Ponieważ programy ułatwień dostępu oparte na interfejsie użytkownika zwykle działają z ekranem i myszą, typowym problemem jest znalezienie odpowiedniego interfejsu ITextDocument dla bieżącej lokalizacji myszy (we współrzędnych ekranu). W poniższych sekcjach przedstawiono dwa sposoby określania odpowiedniego interfejsu:

• za pośrednictwem tabeli running-object
• Za pośrednictwem komunikatu EM_GETOLEINTERFACE, który działa w przypadku okiennych wystąpień edycji wzbogaconej, pod warunkiem, że klient znajduje się w tej samej przestrzeni procesów (nie jest wymagana żadna marshaling)

Aby uzyskać więcej informacji, zobacz specyfikację Microsoft Active Accessibility. Po uzyskaniu obiektu z pozycji ekranu można użyć interfejsu ITextDocument i wywołać metodę RangeFromPoint, aby uzyskać pusty obiekt zakresu w cp odpowiadającym pozycji ekranu.

Interfejs z uruchomionej tabeli obiektów

Uruchomiona tabela obiektów (ROT) informuje, jakie wystąpienia obiektów są aktywne. Wykonując zapytanie względem tej tabeli, można przyspieszyć proces łączenia klienta z obiektem, gdy obiekt jest już uruchomiony. Zanim programy będą mogły uzyskiwać dostęp do interfejsów TOM za pośrednictwem uruchomionej tabeli obiektów (ROT), wystąpienie TOM z oknem musi zarejestrować się w tabeli ROT przy użyciu monikera. Skonstruujesz moniker z ciągu zawierającego wartość szesnastkową HWND. Poniższy przykładowy kod pokazuje, jak to zrobić.

// 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
}

Interfejs z komunikatów okna

Komunikat EM_GETOLEINTERFACE umożliwia uzyskanie interfejsu IUnknown dla obiektu na danej pozycji ekranu. Jak opisano w Interface from Running Object Table, otrzymujesz HWND dla położenia ekranu, a następnie wysyłasz ten komunikat do tego HWND. Komunikat EM_GETOLEINTERFACE jest specyficzny dla edytorów typu "rich edit" i zwraca wskaźnik do interfejsu IRichEditOle umieszczonego w zmiennej wskazanej przez lParam.

Wskazówka Jeśli zostanie zwrócony wskaźnik (upewnij się, że obiekt, na który lParam wskazuje, jest ustawiony na null przed wysłaniem komunikatu), możesz wywołać metodę IUnknown::QueryInterface, aby uzyskać interfejs ITextDocument. Poniższy przykładowy kod ilustruje to podejście.

    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
    }

Metody zorientowane na ułatwienia dostępu

Niektóre metody TOM są szczególnie przydatne do poruszania się po ekranie, podczas gdy inne metody TOM zwiększają możliwości, które można zrobić po dotarciu do interesujących cię miejsc. W poniższej tabeli opisano najbardziej przydatne metody.

Zestawy dopasowań znakowych

Wariant parametru w różnych metodach Move* w ITextRange, takich jak MoveWhile i MoveUntil, może przyjmować jawny ciąg znaków lub indeks 32-bitowy zgodny z zestawem dopasowania znaków. Indeksy są definiowane przez zakresy Unicode lub zestawy znaków GetStringTypeEx. Zakres Unicode rozpoczynający się od n i długości l (< 32768) jest podawany przez indeks n + (l << 16) + 0x80000000. Na przykład podstawowe greckie litery są definiowane przez CR_Greek = 0x805f0370 i drukowalne znaki ASCII są definiowane przez CR_ASCIIPrint = 0x805e0020. Ponadto metody MoveWhile i MoveUntil umożliwiają szybkie obejście zakresu znaków w dowolnym zestawie znaków GetStringTypeEx lub w zakresie znaków, które nie są w żadnym z tych zestawów znaków.

Zestawy GetStringTypeEx są określane przez wartości Ctype1, Ctype2i Ctype3i są zdefiniowane w następujący sposób.

W szczególności Ctype1 może być dowolną kombinacją poniższych.

Typy Ctype2 obsługują prawidłowy układ tekstu Unicode. Atrybuty kierunku są przypisywane tak, aby algorytm układu dwukierunkowego ustandaryzowany przez Unicode zapewniał dokładne wyniki. Te typy wykluczają się wzajemnie. Aby uzyskać więcej informacji na temat używania tych atrybutów, zobacz Standard Unicode: Kodowanie znaków na całym świecie, woluminy 1 i 2, Addison-Wesley Publishing Company: 1991, 1992.

Typy Ctype3 mają być symbolami zastępczymi rozszerzeń typów POSIX wymaganych do ogólnego przetwarzania tekstu lub standardowych funkcji biblioteki C.

Zestaw Edit Development Kit (EDK) może zawierać pVar definicje indeksów dla następujących zakresów opisanych w standardzie Unicode.