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
• Il tipo tomBool
• Aumento matematico e diminuzione
• TOM RTF
• ricerca di testo ricco
• TOM Accessibility
  • Interfaccia dalla Tabella degli Oggetti in Esecuzione
  • interfaccia dai messaggi della finestra
  • metodi orientati all'accessibilità
• insiemi 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 include metodi per la creazione e il recupero di oggetti inferiori nella gerarchia degli oggetti. Per una semplice elaborazione di testo normale, è possibile ottenere un oggetto ITextRange2 da un oggetto ITextDocument2 ed eseguire la maggior parte di tutto. Se è necessario aggiungere la formattazione RTF, è possibile ottenere gli 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. Viene utilizzato un processo di annotazione temporanea per la traduzione tra espressioni matematiche in formato lineare e forme sviluppate. Si utilizza una storia temporanea anche quando si salva il contenuto di un intervallo che è l'origine di copia corrente e il contenuto sta per essere modificato.

Un oggetto ITextRange2 è definito dagli offset di posizione iniziale e finale e da un oggetto story. Non esiste indipendentemente dalla storia principale, ma il suo 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é un oggetto ITextRange può sempre essere creato per rappresentare qualsiasi brano specifico. 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 le 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 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_RELEASED
• NOERROR (uguale a S_OK)
• S_FALSE

Tenere presente che se l'istanza di modifica associata a un oggetto TOM viene eliminata, ad esempio IntervalloDiTesto, l'oggetto TOM diventa inutile e tutti i relativi metodi restituiscono CO_E_RELEASED.

Oltre al HRESULT valori restituiti, 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 FALSEe tomTrue (-1) per TRUE.

Le costanti TOM vengono definite nel tipo di enumerazionetomConstants 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, tomTogglee tomUndefined. I valori tomTrue e tomFalse indicano vero e falso. 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 significa che i caratteri nell'intervallo hanno valori diversi (fornisce la casella di controllo grigia nelle finestre di dialogo delle proprietà).

Costruisci in su e costruisci in giù matematicamente

È 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, chiamata linearizzazione o riduzione, per convertire le versioni accumulate delle espressioni matematiche nuovamente in formato lineare. La funzionalità di compilazione matematica è utile quando è necessario esportare testo normale o per abilitare determinati tipi di modifica.

TOM RTF

Nell'interfaccia TOM, lo scambio di testo formattato può essere effettuato tramite set di chiamate di metodo esplicite o attraverso trasferimenti in formato Rich Text (RTF). In questa sezione vengono fornite tabelle di parole di controllo RTF per le proprietà di paragrafo e per le proprietà dei caratteri.

TOM RTF Parole di Controllo del Paragrafo

Parole di controllo del formato carattere RTF di TOM

Ricerca di testo arricchito

È possibile usare i metodi TOM per trovare testo RTF come definito da un intervallo di testo. La ricerca di testo ricco è spesso necessaria per l'elaborazione di testi, anche se non è mai stata soddisfatta in un "ciò che vedi è ciò che ottieni" (WYSIWYG) elaboratore di testi. Esiste chiaramente un dominio più ampio di corrispondenza di rich-text 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 sono al di là dell'ambito di questa sezione.

Uno degli scopi di questa funzionalità consiste nell'usare una finestra di dialogo Ricerca per definire il testo ricco 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 formattato desiderato dal documento nella finestra di dialogo Trova oppure inserirlo 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 in chiaro nella gamma di corrispondenza, denominata 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 valutazione confrontando 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 di punti di inserimento prip1 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 di ITextSelection e ITextRange. Questa sezione descrive i metodi utili per l'accessibilità e il modo in cui un programma può determinare il x, y posizione dello schermo di un oggetto .

Poiché i programmi di accessibilità basati sull'interfaccia utente funzionano in genere con lo schermo e il mouse, un problema comune consiste nel trovare l'interfaccia corrispondente ITextDocument 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 un'interfaccia ITextDocument e chiamare il metodo RangeFromPoint per ottenere un oggetto intervallo vuoto al cp 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 suo 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 dei messaggi della 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 Interface from Running Object Table, ottieni un HWND per la posizione dello schermo e quindi invii questo messaggio a tale HWND. Il messaggio EM_GETOLEINTERFACE è specifico dell'editor di testo avanzato 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. L'esempio di codice seguente 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.

Insiemi di abbinamenti 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 impostato. Gli indici sono definiti da intervalli Unicode o set di caratteri GetStringTypeEx . L'intervallo Unicode a partire da n e di lunghezza l (< 32768) viene assegnato 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 diGetStringTypeExvengono specificati dai valori per Ctype1, Ctype2e Ctype3e sono 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.