Over tekstobjectmodel

Het Tekstobjectmodel (TOM) definieert een reeks tekstbewerkingsinterfaces die in verschillende mate door verschillende Microsoft-tekstoplossingen worden ondersteund, waaronder de Rich Edit Control. In dit onderwerp vindt u een algemeen overzicht van de TOM. Hierin worden de volgende onderwerpen besproken.

• TOM Versie 2-objecten
• TOM Interface-conventies
• Het type tomBool
• Wiskundige opbouw en afbouw
• TOM RTF
• Rtf-tekst zoeken
• TOM Accessibility
  • Interface van actieve objecttabel
  • Interface van vensterberichten
  • Toegankelijkheidsmethoden
• Tekensmatchsets

TOM Versie 2-objecten

TOM versie 2 (TOM 2) breidt het oorspronkelijke tekstobjectmodel uit; de nieuwe interfaces zijn afgeleid van de oude interfaces. De bijgewerkte TOM-API bevat ondersteuning voor nieuwe eigenschappen voor teken- en alineaopmaak, een tabelmodel, meerdere selecties en ondersteuning voor inlineobjecten voor wiskunde en ruby.

Het TOM 2-object op het hoogste niveau wordt gedefinieerd door de ITextDocument2-interface , met methoden voor het maken en ophalen van objecten lager in de objecthiërarchie. Voor eenvoudige verwerking van tekst zonder opmaak kunt u een ITextRange2-object verkrijgen van een ITextDocument2-object en daar de meeste mee doen. Als u rtf-tekstopmaak wilt toevoegen, kunt u ITextFont2 - en ITextPara2-objecten ophalen uit een ITextRange2-object . ITextFont2 biedt het programmeer-equivalent van het dialoogvenster Indeling-lettertype in Microsoft Word en ITextPara2 biedt het equivalent van het dialoogvenster Indeling-alinea in Word.

Naast deze drie objecten op een lager niveau heeft TOM 2 een selectieobject (ITextSelection2), een ITextRange2-object met selectiemarkeringen en enkele ui-georiënteerde methoden.

Het bereik en de selectieobjecten bevatten schermgeoriënteerde methoden waarmee programma's tekst op het scherm of tekst kunnen onderzoeken die naar het scherm kunnen worden geschoven. Deze mogelijkheden helpen bijvoorbeeld om tekst toegankelijk te maken voor mensen met slechtziendheid.

Elke interface met het 2-achtervoegsel wordt overgenomen van de bijbehorende interface zonder het 2-achtervoegsel. ITextDocument2 neemt bijvoorbeeld over van ITextDocument.

De TOM 2-objecten hebben de volgende hiërarchie.

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

Een ITextDocument2-object beschrijft een of meer aaneengesloten tekstbereiken die verhalen worden genoemd. Verhalen vertegenwoordigen verschillende delen van een document, zoals de hoofdtekst van het document, kop- en voetteksten, voetnoten, aantekeningen en scratchpads met tekst met opmaak. Een scratchpad-verhaal wordt gebruikt bij het vertalen tussen lineair opgemaakte wiskundige expressies en een ingebouwde vorm. Een scratchpad-verhaal wordt ook gebruikt wanneer de inhoud van een bereik, dat de huidige kopieerbron is, wordt opgeslagen als de inhoud op het punt staat te worden veranderd.

Een ITextRange2-object wordt gedefinieerd door de verschuivingen tussen de begin- en eindtekenpositie en een verhaalobject. Het bestaat niet onafhankelijk van het bovenliggende verhaalelement, hoewel de tekst kan worden gekopieerd naar het klembord of naar andere bestemmingen. Een tekstbereikobject verschilt van spreadsheets en andere bereikobjecten, die worden gedefinieerd door andere soorten offsets; Bijvoorbeeld rij-/kolom- of grafische positie (x, y). Een tekstbereikobject kan zichzelf op verschillende manieren wijzigen, een duplicaat van zichzelf retourneren, en het kan worden opgedragen om de begin- en eindpositie van tekens en de bijbehorende verhaalaanwijzer naar de huidige selectie te kopiëren.

Er is geen expliciet verhaalobject nodig, omdat er altijd een ITextRange-object kan worden gemaakt om een bepaald verhaal weer te geven. Met name het ITextDocument-object kan een ITextStoryRanges-object maken om de verhalen in het document op te sommen in termen van bereiken met begin- en eindpositiewaarden waarmee volledige verhalen worden beschreven (zoals 0 en tomForward).

Met een ITextStoryRanges2-object is een expliciet verhaalobject niet nodig, omdat het verhaal wordt beschreven door een ITextRange2-object . In het bijzonder kan het ITextDocument2-object een ITextStoryRanges2-object maken om de verhalen in het document op te sommen in termen van bereiken met begin- en eindpositiewaarden waarmee volledige verhalen (zoals 0 en tomForward) worden beschreven.

De ITextRow-interface samen met de methoden ITextRange::Move en ITextRange::Expand bieden de mogelijkheid om tabellen in te voegen, op te vragen en te wijzigen.

TOM Interface-conventies

Alle TOM-methoden retourneren HRESULT-waarden . Over het algemeen retourneren de TOM-methoden de volgende standaardwaarden.

• E_OUTOFMEMORY
• E_INVALIDARG
• E_NOTIMPL
• E_FILENOTFOUND (Bestand niet gevonden)
• E_ACCESSDENIED
• E_FAIL
• CO_E_RELEASED
• NOERROR (hetzelfde als S_OK)
• S_FALSE

Houd er rekening mee dat als het bewerkingsexemplaar dat is gekoppeld aan een TOM-object, zoals ITextRange , wordt verwijderd, het TOM-object nutteloos wordt en alle methoden CO_E_RELEASED retourneren.

Naast de HRESULT-retourwaarden bevatten veel methoden parameters, die pointers zijn die worden gebruikt om waarden te retourneren. Voor alle interfaces moet u alle aanwijzerparameters controleren om ervoor te zorgen dat ze niet-nul zijn voordat u ze gebruikt. Als u een null-waarde doorgeeft aan een methode waarvoor een geldige aanwijzer is vereist, retourneert de methode E_INVALIDARG. Optionele aanwijzers met null-waarden worden genegeerd.

Gebruik methoden met de voorvoegsels Get en Set om eigenschappen op te halen en in te stellen. Booleaanse variabelen gebruiken tomFalse (0) voor FALSE en tomTrue (-1) voor TRUE.

TOM-constanten worden gedefinieerd in het opsommingstype tomConstants en beginnen met het voorvoegsel tom, bijvoorbeeld tomWord.

Het type tomBool

Veel TOM-methoden gebruiken een speciaal type variabele met de naam 'tomBool' voor rich-text-kenmerken met binaire statussen. Het type tomBool verschilt van het Booleaanse type omdat het vier waarden kan aannemen: tomTrue, tomFalse, tomToggle en tomUndefined. De waarden tomTrue en tomFalse geven waar en onwaar aan. De waarde tomToggle wordt gebruikt om een eigenschap in te schakelen. De tomUndefined-waarde , traditioneel NINCH genoemd, is een speciale no-input, no-change waarde die werkt met longs, floats en COLORREFs. Voor tekenreeksen wordt tomUndefined (of NINCH) vertegenwoordigd door de null-tekenreeks. Voor bewerkingen voor het instellen van eigenschappen wijzigt het gebruik van tomUndefined de doeleigenschap niet. Voor het ophalen van eigenschappen betekent tomUndefined dat de tekens in het bereik verschillende waarden hebben (het geeft het grijsgekleurde selectievakje in eigenschapsdialoogvensters).

Mathematische opbouw en afbouw

U kunt de methode ITextRange2::BuildUpMath gebruiken om lineair opgemaakte wiskundige expressies te converteren naar ingebouwde versies. De methode ITextRange2::Linearize voert de tegenovergestelde conversie uit, linearisatie of build down genoemd, om ingebouwde versies van wiskundige expressies weer te converteren naar lineaire indeling. De wiskundige opbouwfunctie is handig wanneer u tekst zonder opmaak wilt exporteren of bepaalde typen bewerkingen wilt inschakelen.

TOM RTF

In TOM kan uitwisseling van opgemaakte tekst worden uitgevoerd door sets van expliciete methode-aanroepen of door overdrachten in Rich Text Formaat (RTF). Deze sectie bevat tabellen met RTF-besturingswoorden voor alinea-eigenschappen en voor tekeneigenschappen.

TOM RTF-alinearegelwoorden

Besturingselementwoorden voor TOM RTF-tekenopmaak

Rtf-tekst zoeken

U kunt TOM-methoden gebruiken om tekst met opmaak te zoeken, zoals gedefinieerd door een tekstbereik. Het exact vinden van dergelijke rijk opgemaakte tekst is vaak nodig in tekstverwerking, hoewel dit nooit is vervuld in een "Wat U Ziet Is Wat U Krijgt" (WYSIWYG) tekstverwerker. Er is duidelijk een groter domein van rich-text matching waarmee bepaalde tekenopmaakeigenschappen kunnen worden genegeerd (of om alineaopmaak en/of objectinhoud op te nemen), maar dergelijke generalisaties vallen buiten het bereik van deze sectie.

Een doel van deze functionaliteit is het gebruik van een dialoogvenster Zoeken om de rich-text die u in een document wilt lokaliseren op te geven. Het dialoogvenster zou worden geïmplementeerd met behulp van een uitgebreid besturingselement voor bewerken en TOM-methoden worden gebruikt om de zoekopdracht door het document uit te voeren. U kunt de gewenste tekst met opmaak uit het document kopiëren naar het dialoogvenster Zoeken of deze rechtstreeks invoeren en opmaken in het dialoogvenster Zoeken .

In het volgende voorbeeld ziet u hoe u TOM-methoden gebruikt om tekst te zoeken die combinaties van exacte tekenopmaak bevat. Het algoritme zoekt naar de tekst zonder opmaak in het overeenkomende bereik, genaamd pr1. Als gewone tekst wordt gevonden, wordt deze toegewezen aan een testbereik met de naam pr2. Vervolgens worden twee invoegpuntbereiken (prip1 en prip2) gebruikt om het proefbereik te doorlopen, waarbij de tekenopmaak wordt vergeleken met die van pr1. Als deze exact overeenkomen, wordt het invoerbereik (gegeven door ppr) bijgewerkt om te verwijzen naar de tekst van het proefbereik en retourneert de functie het aantal tekens in het overeenkomende bereik. Twee ITextFont-objectenpf1 en pf2worden gebruikt in de vergelijking van tekenopmaak. Ze zijn gekoppeld aan de invoegpuntbereiken prip1 en 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 Accessibility

TOM biedt ondersteuning voor toegankelijkheid via de ITextSelection - en ITextRange-interfaces . In deze sectie worden methoden beschreven die handig zijn voor toegankelijkheid en hoe een programma de positie van het x- , y-scherm van een object kan bepalen.

Aangezien toegankelijkheidsprogramma's op basis van de gebruikersinterface doorgaans met het scherm en de muis werken, is het belangrijk om de bijbehorende ITextDocument-interface te vinden voor de huidige muislocatie (in schermcoördinaten). De volgende secties bevatten twee manieren om de juiste interface te bepalen:

• Via de tabel van actieve objecten
• Via het EM_GETOLEINTERFACE bericht, dat werkt voor windowed rich edit-instanties, zolang de client zich in dezelfde procesomgeving bevindt (er is geen marshaling nodig)

Zie de Microsoft Active Accessibility-specificatie voor meer informatie. Nadat u een object op een schermpositie hebt verkregen, kunt u deze gebruiken voor een ITextDocument-interface en de RangeFromPoint-methode aanroepen om een leeg bereikobject op te halen op de cp die overeenkomt met de schermpositie.

Interface van actieve objecttabel

Een actieve objecttabel (ROT) vertelt welke objectexemplaren actief zijn. Door een query uit te voeren op deze tabel, kunt u het proces van het verbinden van een client met een object versnellen wanneer het object al wordt uitgevoerd. Voordat programma's toegang hebben tot TOM-interfaces via de actieve objecttabel, moet een TOM-exemplaar met een venster zich registreren in rot met behulp van een moniker. U construeert de moniker van een string die de hexadecimale waarde van de HWND bevat. In het volgende codevoorbeeld ziet u hoe u dit doet.

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

Interface van vensterberichten

Het EM_GETOLEINTERFACE bericht biedt een andere manier om een IUnknown-interface te verkrijgen voor een object op een bepaalde schermpositie. Zoals beschreven in interface van de actieve objecttabel, krijgt u een HWND voor de schermpositie en verzendt u dit bericht naar die HWND. Het EM_GETOLEINTERFACE bericht is uitgebreid voor bewerken en retourneert een aanwijzer naar een IRichEditOle-interface in de variabele die door lParam wordt geadresseerd.

Fooi Als een aanwijzer wordt geretourneerd (zorg ervoor dat u het object instelt waarop lParam verwijst naar null voordat u het bericht verzendt), kunt u de methode IUnknown::QueryInterface aanroepen om een ITextDocument-interface te verkrijgen. Het volgende codevoorbeeld illustreert deze benadering.

    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
    }

Toegankelijkheidsmethoden

Sommige TOM-methoden zijn met name handig om door het scherm te navigeren, terwijl andere TOM-methoden verbeteren wat u kunt doen wanneer u op nuttige plaatsen aankomt. In de volgende tabel worden de nuttigste methoden beschreven.

Karaktersets

De variantparameter van de verschillende Move*-methoden in ITextRange, zoals MoveWhile en MoveUntil, kan een expliciete tekenreeks of een tekenovereenkomstset 32-bits index aannemen. De indexen worden gedefinieerd door Unicode-reeksen of GetStringTypeEx-tekensets. Het Unicode-bereik vanaf n en lengte l (< 32768) wordt gegeven door de index n + (l << 16) + 0x80000000. Eenvoudige Griekse letters worden bijvoorbeeld gedefinieerd door CR_Greek = 0x805f0370 en afdrukbare ASCII-tekens worden gedefinieerd door CR_ASCIIPrint = 0x805e0020. Bovendien kunt u met de methoden MoveWhile en MoveUntil snel een reeks tekens in een GetStringTypeEx-tekenset overslaan, of in een reeks tekens die zich niet in een van deze tekensets bevinden.

De GetStringTypeEx-sets worden opgegeven door de waarden voor Ctype1, Ctype2 en Ctype3 en worden als volgt gedefinieerd.

Ctype1 kan een combinatie van het volgende zijn.

De Ctype2-typen ondersteunen de juiste indeling van Unicode-tekst. De richtingkenmerken worden toegewezen, zodat het algoritme voor de indeling in twee richtingen dat is gestandaardiseerd door Unicode nauwkeurige resultaten produceert. Deze typen sluiten elkaar wederzijds uit. Zie De Unicode-standaard: Worldwide Character Encoding, Volumes 1 en 2, Addison-Wesley Publishing Company: 1991, 1992 voor meer informatie over het gebruik van deze kenmerken.

De Ctype3-typen zijn bedoeld als tijdelijke aanduidingen voor extensies voor de POSIX-typen die vereist zijn voor algemene tekstverwerking of voor de standaard-C-bibliotheekfuncties.

Een Edit Development Kit (EDK) kan pVar-indexdefinities bevatten voor de volgende reikwijdtes die worden beschreven in de Unicode-standaard.