Informazioni sul modello a oggetti di testo

Text Object Model (TOM) definisce un set di interfacce di manipolazione del testo supportate in vari gradi da diverse soluzioni di testo Microsoft, incluso il controllo rich edit. Questo argomento offre una panoramica generale di TOM. Vengono illustrati gli argomenti seguenti.

• Oggetti TOM versione 2
• Convenzioni dell'interfaccia TOM
• Tipo tomBool
• Compilazione matematica e compilazione
• TOM RTF
• Ricerca di testo RTF
• Accessibilità TOM
  • Interfaccia dalla tabella degli oggetti in esecuzione
  • Interfaccia dai messaggi finestra
  • Metodi orientati all'accessibilità
• Set di corrispondenze di caratteri

Oggetti TOM versione 2

TOM versione 2 (TOM 2) estende il modello a oggetti di testo originale; le nuove interfacce sono derivate da quelle precedenti. L'API TOM aggiornata include il supporto per le nuove proprietà di formato carattere e paragrafo, un modello di tabella, una selezione multipla e il supporto di oggetti inline per matematica e ruby.

L'oggetto TOM 2 di primo livello è definito dall'interfaccia ITextDocument2 , che dispone di metodi per la creazione e il recupero di oggetti inferiori nella gerarchia degli oggetti. Per un'elaborazione semplice di testo normale, è possibile ottenere un oggetto ITextRange2 da un oggetto ITextDocument2 ed eseguire la maggior parte di tutto con questo. Se è necessario aggiungere la formattazione RTF, è possibile ottenere oggetti ITextFont2 e ITextPara2 da un oggetto ITextRange2. ITextFont2 fornisce l'equivalente di programmazione della finestra di dialogo formato-carattere di Microsoft Word e ITextPara2 fornisce l'equivalente della finestra di dialogo formato paragrafo di Word.

Oltre a questi tre oggetti di livello inferiore, TOM 2 ha un oggetto di selezione (ITextSelection2), che è un oggetto ITextRange2 con evidenziazione della selezione e alcuni metodi orientati all'interfaccia utente.

Gli oggetti intervallo e selezione includono metodi orientati allo schermo che consentono ai programmi di esaminare il testo sullo schermo o il testo che è possibile scorrere sullo schermo. Queste funzionalità consentono di rendere il testo accessibile alle persone con problemi di vista, ad esempio.

Ogni interfaccia con il suffisso 2 eredita dall'interfaccia corrispondente senza il suffisso 2. Ad esempio, ITextDocument2 eredita da ITextDocument.

Gli oggetti TOM 2 hanno la gerarchia seguente.

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

Un oggetto ITextDocument2 descrive uno o più intervalli contigui di testo denominati storie. Le storie rappresentano varie parti di un documento, ad esempio il testo principale del documento, le intestazioni e i piè di pagina, le note a piè di pagina, le annotazioni e i riquadri rtf. Per la conversione tra espressioni matematiche formattate in modo lineare e un modulo predefinito, viene usato un brano di riquadri scratch. Quando si salva il contenuto di un intervallo che rappresenta l'origine di copia corrente quando il contenuto sta per essere modificato, viene usato anche un brano di riquadri scratch.

Un oggetto ITextRange2 viene definito dagli offset iniziale e finale della posizione dei caratteri e da un oggetto story. Non esiste indipendentemente dal relativo oggetto brano padre, anche se il testo può essere copiato negli Appunti o in altre destinazioni. Un oggetto intervallo di testo è diverso dal foglio di calcolo e da altri oggetti intervallo, definiti da altri tipi di offset; ad esempio, riga/colonna o posizione grafica (x, y). Un oggetto intervallo di testo può modificare se stesso in vari modi, può restituire un duplicato di se stesso e può essere utilizzato per copiare le posizioni dei caratteri iniziali e finali e il puntatore del brano alla selezione corrente.

Non è necessario un oggetto story esplicito, poiché è sempre possibile creare un oggetto ITextRange per rappresentare qualsiasi brano specificato. In particolare, l'oggetto ITextDocument può creare un oggetto ITextStoryRanges per enumerare le storie nel documento in termini di intervalli con valori di posizione dei caratteri iniziale e finale che descrivono le storie complete (ad esempio, 0 e tomForward).

Con un oggetto ITextStoryRanges2, non è necessario un oggetto story esplicito, poiché ogni brano è descritto da un oggetto ITextRange2. In particolare, l'oggetto ITextDocument2 può creare un oggetto ITextStoryRanges2 per enumerare le storie nel documento in termini di intervalli con valori di posizione dei caratteri iniziale e finale che descrivono storie complete (ad esempio, 0 e tomForward).

L'interfaccia ITextRow insieme ai metodi ITextRange::Move e ITextRange::Expand consentono di inserire, eseguire query e modificare le tabelle.

Convenzioni dell'interfaccia TOM

Tutti i metodi TOM restituiscono valori HRESULT . In generale, i metodi TOM restituiscono i valori standard seguenti.

• E_OUTOFMEMORY
• E_INVALIDARG
• E_NOTIMPL
• E_FILENOTFOUND
• E_ACCESSDENIED
• E_FAIL
• CO_E_RELEAedizione Standard D
• NOERROR (uguale a S_OK)
• S_FALSE

Tenere presente che se l'istanza di modifica associata a un oggetto TOM come ITextRange viene eliminata, l'oggetto TOM diventa inutile e tutti i relativi metodi restituiscono CO_E_RELEAedizione Standard D.

Oltre ai valori restituiti HRESULT , molti metodi includono parametri out, che sono puntatori usati per restituire valori. Per tutte le interfacce, è necessario controllare tutti i parametri del puntatore per assicurarsi che siano diversi da zero prima di usarli. Se si passa un valore Null a un metodo che richiede un puntatore valido, il metodo restituisce E_INVALIDARG. I puntatori facoltativi con valori Null vengono ignorati.

Usare i metodi con prefissi Get e Set per ottenere e impostare le proprietà. Le variabili booleane usano tomFalse (0) per FAL edizione Standard e tomTrue (-1) per TRUE.

Le costanti TOM sono definite nel tipo di enumerazione tomConstants e iniziano con il prefisso tom, ad esempio tomWord.

Tipo tomBool

Molti metodi TOM usano un tipo speciale di variabile denominato "tomBool" per gli attributi RTF con stati binari. Il tipo tomBool è diverso dal tipo booleano perché può accettare quattro valori: tomTrue, tomFalse, tomToggle e tomUndefined. I valori tomTrue e tomFalse indicano true e false. Il valore tomToggle viene usato per attivare o disattivare una proprietà. Il valore tomUndefined , più tradizionalmente chiamato NINCH, è un valore speciale senza input, nessuna modifica che funziona con longs, float e COLORREFs. Per le stringhe, tomUndefined (o NINCH) è rappresentato dalla stringa null. Per le operazioni di impostazione delle proprietà, l'uso di tomUndefined non modifica la proprietà di destinazione. Per le operazioni di recupero delle proprietà, tomUndefined indica che i caratteri nell'intervallo hanno valori diversi (fornisce la casella di controllo grigia nelle finestre di dialogo delle proprietà).

Compilazione matematica e compilazione

È possibile usare il metodo ITextRange2::BuildUpMath per convertire espressioni matematiche formattate in modo lineare in versioni predefinite. Il metodo ITextRange2::Linearize esegue la conversione opposta, denominata linearizzazione o compilazione, per convertire le versioni predefinite delle espressioni matematiche in formato lineare. La funzionalità di compilazione matematica è utile quando è necessario esportare testo normale o per abilitare determinati tipi di modifica.

TOM RTF

In TOM, lo scambio RTF (Rich Text Format) può essere eseguito da set di chiamate di metodo esplicite o da trasferimenti di testo RTF (Rich Text Format). In questa sezione vengono fornite tabelle di parole di controllo RTF per le proprietà di paragrafo e per le proprietà dei caratteri.

Parole di controllo del paragrafo RTF TOM

Parole di controllo formato carattere RTF TOM

Ricerca di testo RTF

È possibile usare i metodi TOM per trovare testo RTF come definito da un intervallo di testo. La ricerca di testo rtf è spesso necessaria per l'elaborazione delle parole, anche se non è mai stata soddisfatta in un "quello che vedete è quello che si ottiene" (WYSIWYG) elaboratore di parole. Esiste chiaramente un dominio più ampio di corrispondenza rtf che consente di ignorare alcune proprietà di formattazione dei caratteri (o di includere la formattazione di paragrafo e/o il contenuto dell'oggetto), ma tali generalizzazioni non rientrano nell'ambito di questa sezione.

Uno degli scopi di questa funzionalità consiste nell'usare una finestra di dialogo Ricerca RTF per definire il testo RTF che si desidera individuare in un documento. La finestra di dialogo verrà implementata utilizzando un controllo di modifica avanzato e i metodi TOM verranno usati per eseguire la ricerca nel documento. È possibile copiare il testo RTF desiderato dal documento nella finestra di dialogo Trova oppure immetterlo e formattarlo direttamente nella finestra di dialogo Trova .

Nell'esempio seguente viene illustrato come usare i metodi TOM per trovare testo contenente combinazioni di formattazione esatta dei caratteri. L'algoritmo cerca il testo normale nell'intervallo di corrispondenze, denominato pr1. Se viene trovato il testo normale, viene indicato da un intervallo di prova, denominato pr2. Vengono quindi usati due intervalli di punti di inserimento (prip1 e prip2) per esaminare l'intervallo di prova confrontandone la formattazione dei caratteri con quella di pr1. Se corrispondono esattamente, l'intervallo di input (specificato da ppr) viene aggiornato in modo che punti al testo dell'intervallo di prova e la funzione restituisce il numero di caratteri nell'intervallo corrispondente. Due oggetti ITextFont, pf1 e pf2, vengono usati nel confronto di formattazione dei caratteri. Sono collegati agli intervalli prip1 di punti di inserimento e 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;
}

Accessibilità TOM

TOM offre supporto per l'accessibilità tramite le interfacce ITextSelection e ITextRange. Questa sezione descrive i metodi utili per l'accessibilità, nonché il modo in cui un programma può determinare la posizione dello schermo x, y di un oggetto.

Poiché i programmi di accessibilità basati sull'interfaccia utente funzionano in genere con lo schermo e il mouse, un problema comune è trovare l'interfaccia ITextDocument corrispondente per la posizione corrente del mouse (nelle coordinate dello schermo). Le sezioni seguenti illustrano due modi per determinare l'interfaccia appropriata:

• Tramite la tabella degli oggetti in esecuzione
• Tramite il messaggio di EM_GETOLEINTERFACE , che funziona per le istanze di modifica avanzate finestrate, a condizione che il client si trova nello stesso spazio di processo (non è necessario effettuare il marshalling )

Per altre informazioni, vedere la specifica Microsoft Active Accessibility. Dopo aver ottenuto un oggetto da una posizione dello schermo, è possibile usare per un'interfaccia ITextDocument e chiamare il metodo RangeFromPoint per ottenere un oggetto intervallo vuoto in corrispondenza della posizione dello schermo corrispondente alla posizione dello schermo.

Interfaccia dalla tabella degli oggetti in esecuzione

Una tabella di oggetti in esecuzione (ROT) indica quali istanze dell'oggetto sono attive. Eseguendo una query su questa tabella, è possibile accelerare il processo di connessione di un client a un oggetto quando l'oggetto è già in esecuzione. Prima che i programmi possano accedere alle interfacce TOM tramite la tabella degli oggetti in esecuzione, un'istanza TOM con una finestra deve registrarsi in ROT usando un moniker. Si costruisce il moniker da una stringa contenente il valore esadecimale del relativo HWND. Nell'esempio di codice seguente viene illustrato come eseguire questa operazione.

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

Interfaccia dai messaggi finestra

Il messaggio EM_GETOLEINTERFACE fornisce un altro modo per ottenere un'interfaccia IUnknown per un oggetto in una determinata posizione dello schermo. Come descritto in Interfaccia da Tabella oggetti in esecuzione, si ottiene un HWND per la posizione dello schermo e quindi si invia questo messaggio a tale HWND. Il messaggio EM_GETOLEINTERFACE è specifico della modifica avanzata e restituisce un puntatore a un'interfaccia IRichEditOle nella variabile gestita da lParam.

Suggerimento Se viene restituito un puntatore (assicurarsi di impostare l'oggetto su cui lParam punta a null prima di inviare il messaggio), è possibile chiamare il relativo metodo IUnknown::QueryInterface per ottenere un'interfaccia ITextDocument. Il seguente esempio di codice illustra questo approccio.

    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
    }

Metodi orientati all'accessibilità

Alcuni metodi TOM sono particolarmente utili per spostarsi sullo schermo, mentre altri metodi TOM migliorano ciò che si può fare quando si arriva a luoghi di interesse. Nella tabella seguente vengono descritti i metodi più utili.

Set di corrispondenze di caratteri

Il parametro variant dei vari metodi Move* in ITextRange, ad esempio MoveWhile e MoveUntil, può accettare una stringa esplicita o un indice a 32 bit del set di corrispondenze di caratteri. Gli indici sono definiti da intervalli Unicode o da set di caratteri GetStringTypeEx. L'intervallo Unicode a partire da n e di lunghezza l (< 32768) è dato dall'indice n + (l << 16) + 0x80000000. Ad esempio, le lettere greche di base sono definite da CR_Greek = 0x805f0370 e i caratteri ASCII stampabili sono definiti da CR_ASCIIPrint = 0x805e0020. Inoltre, i metodi MoveWhile e MoveUntil consentono di ignorare rapidamente un intervallo di caratteri in qualsiasi set di caratteri GetStringTypeEx o in un intervallo di caratteri che non si trova in uno di questi set di caratteri.

I set GetStringTypeEx vengono specificati dai valori per Ctype1, Ctype2 e Ctype3 e vengono definiti come segue.

In particolare, Ctype1 può essere qualsiasi combinazione di quanto segue.

I tipi Ctype2 supportano il layout corretto del testo Unicode. Gli attributi di direzione vengono assegnati in modo che l'algoritmo di layout bidirezionale standardizzato da Unicode produa risultati accurati. Questi tipi si escludono a vicenda. Per altre informazioni sull'uso di questi attributi, vedere The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison-Wesley Publishing Company: 1991, 1992.

I tipi Ctype3 devono essere segnaposto per le estensioni ai tipi POSIX necessari per l'elaborazione di testo generale o per le funzioni della libreria C standard.

Un Edit Development Kit (EDK) può includere definizioni di indice pVar per gli intervalli seguenti descritti nello standard Unicode.