Sobre o modelo de objeto de texto

O Text Object Model (TOM) define um conjunto de interfaces de manipulação de texto que são suportadas em diferentes graus por várias soluções de texto da Microsoft, incluindo o controle rich edit. Este tópico fornece uma visão geral de alto nível do TOM. Discute os seguintes tópicos.

• Objetos do TOM versão 2
• Convenções de Interface TOM
• O tipo tomBool
• Acúmulo e compilação de matemática
• TOM RTF
• Localizando rich text
• Acessibilidade TOM
  • Interface da tabela de objetos em execução
  • Interface de mensagens de janela
  • Métodos Orientados à Acessibilidade
• Conjuntos de correspondência de caracteres

Objetos do TOM versão 2

TOM versão 2 (TOM 2) estende o modelo de objeto de texto original; As novas interfaces são derivadas das antigas. A API TOM atualizada inclui suporte para novas propriedades de formato de caractere e parágrafo, um modelo de tabela, seleção múltipla e suporte a objetos embutidos para matemática e rubi.

O objeto TOM 2 de nível superior é definido pela interface ITextDocument2 , que tem métodos para criar e recuperar objetos inferiores na hierarquia de objetos. Para processamento simples de texto sem formatação, você pode obter um objeto ITextRange2 de um objeto ITextDocument2 e fazer quase tudo com isso. Se você precisar adicionar formatação rich-text, poderá obter objetos ITextFont2 e ITextPara2 de um objeto ITextRange2. ITextFont2 fornece o equivalente de programação da caixa de diálogo de fonte de formato do Microsoft Word e ITextPara2 fornece o equivalente da caixa de diálogo de parágrafo de formato do Word.

Além desses três objetos de nível inferior, o TOM 2 tem um objeto de seleção (ITextSelection2), que é um objeto ITextRange2 com realce de seleção e alguns métodos orientados à interface do usuário.

Os objetos de intervalo e seleção incluem métodos orientados à tela que permitem que os programas examinem o texto na tela ou o texto que pode ser rolado para a tela. Esses recursos ajudam a tornar o texto acessível a pessoas com deficiência visual, por exemplo.

Cada interface que tem o sufixo 2 herda da interface correspondente sem o sufixo 2. Por exemplo, ITextDocument2 herda de ITextDocument.

Os objetos TOM 2 têm a seguinte hierarquia.

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

Um objeto ITextDocument2 descreve um ou mais intervalos contíguos de texto chamados histórias. As matérias representam várias partes de um documento, como o texto principal do documento, cabeçalhos e rodapés, notas de rodapé, anotações e blocos de rascunho rich text. Uma história de bloco de rascunho é usada ao traduzir entre expressões matemáticas formatadas linearmente e um formulário construído. Uma história de bloco de rascunho também é usada ao salvar o conteúdo de um intervalo que é a fonte de cópia atual quando o conteúdo está prestes a ser alterado.

Um objeto ITextRange2 é definido por seus deslocamentos de posição de caractere inicial e final e um objeto story. Ele não existe independentemente de seu objeto de história pai, embora seu texto possa ser copiado para a área de transferência ou para outros destinos. Um objeto de intervalo de texto é diferente de planilha e outros objetos de intervalo, que são definidos por outros tipos de deslocamentos; por exemplo, posição de linha/coluna ou gráfico (x, y). Um objeto de intervalo de texto pode modificar-se de várias maneiras, pode retornar uma duplicata de si mesmo e pode ser ordenado a copiar suas posições de caracteres inicial e final e seu ponteiro de história para a seleção atual.

Um objeto de história explícito não é necessário, uma vez que um objeto ITextRange sempre pode ser criado para representar qualquer história específica. Em particular, o objeto ITextDocument pode criar um objeto ITextStoryRanges para enumerar as histórias no documento em termos de intervalos com valores de posição de caractere inicial e final que descrevem histórias completas (como 0 e tomForward).

Com um objeto ITextStoryRanges2, um objeto de história explícito não é necessário, já que cada história é descrita por um objeto ITextRange2. Em particular, o objeto ITextDocument2 pode criar um objeto ITextStoryRanges2 para enumerar as histórias no documento em termos de intervalos com valores de posição de caractere inicial e final que descrevem histórias completas (como 0 e tomForward).

A interface ITextRow juntamente com os métodos ITextRange::Move e ITextRange::Expand oferecem a capacidade de inserir, consultar e alterar tabelas.

Convenções de Interface TOM

Todos os métodos TOM retornam valores HRESULT . Em geral, os métodos TOM retornam os seguintes valores padrão.

• E_OUTOFMEMORY
• E_INVALIDARG
• E_NOTIMPL
• E_FILENOTFOUND
• E_ACCESSDENIED
• E_FAIL
• CO_E_RELEASED
• NOERROR (o mesmo que S_OK)
• S_FALSE

Lembre-se de que, se a instância de edição associada a um objeto TOM, como ITextRange , for excluída, o objeto TOM se tornará inútil e todos os seus métodos retornarão CO_E_RELEASED.

Além dos valores de retorno HRESULT , muitos métodos incluem parâmetros out, que são ponteiros usados para retornar valores. Para todas as interfaces, você deve verificar todos os parâmetros de ponteiro para garantir que eles sejam diferentes de zero antes de usá-los. Se você passar um valor nulo para um método que requer um ponteiro válido, o método retornará E_INVALIDARG. Ponteiros de saída opcionais com valores nulos são ignorados.

Use métodos com prefixos Get e Set para obter e definir propriedades. As variáveis booleanas usam tomFalse (0) para FALSE, e tomTrue (-1) para TRUE.

As constantes TOM são definidas no tipo de enumeração tomConstants e começam com o prefixo tom, por exemplo, tomWord.

O tipo tomBool

Muitos métodos TOM usam um tipo especial de variável chamado "tomBool" para atributos rich-text que têm estados binários. O tipo tomBool é diferente do tipo booleano porque pode ter quatro valores: tomTrue, tomFalse, tomToggle e tomUndefined. Os valores tomTrue e tomFalse indicam true e false. O valor tomToggle é usado para alternar uma propriedade. O valor tomUndefined , mais tradicionalmente chamado NINCH, é um valor especial sem entrada e sem alteração que funciona com longs, floats e COLORREFs. Para cadeias de caracteres, tomUndefined (ou NINCH) é representado pela cadeia de caracteres nula. Para operações de configuração de propriedade, o uso de tomUndefined não altera a propriedade de destino. Para operações de obtenção de propriedades, tomUndefined significa que os caracteres no intervalo têm valores diferentes (ele fornece a caixa de seleção cinza nas caixas de diálogo de propriedade).

Acúmulo e compilação de matemática

Você pode usar o método ITextRange2::BuildUpMath para converter expressões matemáticas formatadas linearmente em versões integradas. O método ITextRange2::Linearize faz a conversão oposta, chamada linearização ou build down, para converter versões compiladas de expressões matemáticas de volta ao formato linear. O recurso de compilação matemática é útil quando você precisa exportar texto sem formatação ou habilitar certos tipos de edição.

TOM RTF

No TOM, a troca de rich text pode ser realizada por conjuntos de chamadas de método explícitas ou por transferências de rich text no Rich Text Format (RTF). Esta seção fornece tabelas de palavras de controle RTF para propriedades de parágrafo e para propriedades de caractere.

Palavras de controle de parágrafo TOM RTF

Palavras de controle de formato de caractere TOM RTF

Localizando rich text

Você pode usar métodos TOM para localizar rich text conforme definido por um intervalo de texto. Encontrar esse rich text exatamente é muitas vezes necessário no processamento de texto, embora nunca tenha sido cumprido em um processador de texto "o que você vê é o que você obtém" (WYSIWYG). Há claramente um domínio maior de correspondência de rich text que permite que algumas propriedades de formatação de caracteres sejam ignoradas (ou incluam formatação de parágrafo e/ou conteúdo de objeto), mas tais generalizações estão além do escopo desta seção.

Uma finalidade para essa funcionalidade é usar uma caixa de diálogo Localizar rich text para definir o rich text que você deseja localizar em um documento. A caixa de diálogo seria implementada usando um controle de edição avançado e métodos TOM seriam usados para realizar a pesquisa através do documento. Você pode copiar o rich text desejado do documento para a caixa de diálogo Localizar ou inseri-lo e formatá-lo diretamente na caixa de diálogo Localizar .

O exemplo a seguir mostra como usar métodos TOM para localizar texto contendo combinações de formatação exata de caracteres. O algoritmo procura o texto sem formatação no intervalo de correspondência, que é chamado pr1. Se o texto sem formatação for encontrado, ele será apontado por um intervalo de avaliação, que é chamado pr2. Em seguida, dois intervalos de pontos de inserção (prip1 e prip2) são usados para percorrer o intervalo de avaliação comparando sua formatação de caracteres com a de pr1. Se corresponderem exatamente, o intervalo de entrada (dado por ppr) será atualizado para apontar para o texto do intervalo de avaliação e a função retornará a contagem de caracteres no intervalo correspondente. Dois objetos pf1 ITextFont e pf2, são usados na comparação de formatação de caracteres. Eles estão ligados às faixas prip1 de pontos de inserção 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;
}

Acessibilidade TOM

O TOM fornece suporte de acessibilidade por meio das interfaces ITextSelection e ITextRange. Esta seção descreve métodos que são úteis para acessibilidade, bem como como um programa pode determinar a posição da tela x, y de um objeto.

Como os programas de acessibilidade baseados em interface do usuário geralmente funcionam com a tela e o mouse, uma preocupação comum é encontrar a interface ITextDocument correspondente para o local atual do mouse (em coordenadas de tela). As seções a seguir apresentam duas maneiras de determinar a interface adequada:

• Através da tabela de objeto em execução
• Através da mensagem EM_GETOLEINTERFACE, que funciona para instâncias de edição avançada em janelas, desde que o cliente esteja no mesmo espaço de processo (não é necessário empacotamento)

Para obter mais informações, consulte a especificação Microsoft Active Accessibility. Depois de obter um objeto de uma posição de tela, você pode usar para uma interface ITextDocument e chamar o método RangeFromPoint para obter um objeto de intervalo vazio no cp correspondente à posição da tela.

Interface da tabela de objetos em execução

Uma tabela de objeto em execução (ROT) informa quais instâncias de objeto estão ativas. Ao consultar essa tabela, você pode acelerar o processo de conexão de um cliente a um objeto quando o objeto já estiver em execução. Antes que os programas possam acessar interfaces TOM por meio da tabela de objetos em execução, uma instância TOM com uma janela precisa se registrar no ROT usando um moniker. Você constrói o moniker a partir de uma cadeia de caracteres que contém o valor hexadecimal de seu HWND. O exemplo de código a seguir mostra como fazer isso.

// 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 de mensagens de janela

A mensagem EM_GETOLEINTERFACE fornece outra maneira de obter uma interface IUnknown para um objeto em uma determinada posição de tela. Conforme descrito em Interface de Executando Tabela de Objetos, você obtém um HWND para a posição da tela e, em seguida, envia essa mensagem para esse HWND. A mensagem EM_GETOLEINTERFACE é rica específica de edição e retorna um ponteiro para uma interface IRichEditOle na variável endereçada por lParam.

Dica Se um ponteiro for retornado (certifique-se de definir o objeto para o qual lParam aponta como null antes de enviar a mensagem), você poderá chamar seu método IUnknown::QueryInterface para obter uma interface ITextDocument. O exemplo de código a seguir ilustra essa abordagem.

    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
    }

Métodos Orientados à Acessibilidade

Alguns métodos TOM são particularmente úteis para navegar pela tela, enquanto outros métodos TOM aprimoram o que você pode fazer quando chega a locais de interesse. A tabela a seguir descreve os métodos mais úteis.

Conjuntos de correspondência de caracteres

O parâmetro variante dos vários métodos Move* em ITextRange, como MoveWhile e MoveUntil, pode ter uma cadeia de caracteres explícita ou um índice de 32 bits de conjunto de correspondência de caracteres. Os índices são definidos por intervalos Unicode ou conjuntos de caracteres GetStringTypeEx. O intervalo Unicode começando em n e de comprimento l ( 32768) é dado pelo índice n + (<l< <16) + 0x80000000. Por exemplo, letras gregas básicas são definidas por CR_Greek = 0x805f0370 e caracteres ASCII imprimíveis são definidos por CR_ASCIIPrint = 0x805e0020. Além disso, os métodos MoveWhile e MoveUntil permitem que você ignore rapidamente uma extensão de caracteres em qualquer conjunto de caracteres GetStringTypeEx ou em uma extensão de caracteres que não esteja em nenhum desses conjuntos de caracteres.

Os conjuntos GetStringTypeEx são especificados pelos valores para Ctype1, Ctype2 e Ctype3 e são definidos da seguinte maneira.

Especificamente, Ctype1 pode ser qualquer combinação dos seguintes.

Os tipos Ctype2 suportam o layout adequado do texto Unicode. Os atributos de direção são atribuídos para que o algoritmo de layout bidirecional padronizado pelo Unicode produza resultados precisos. Esses tipos são mutuamente exclusivos. Para obter mais informações sobre o uso desses atributos, consulte The Unicode Standard: Worldwide Character Encoding, Volumes 1 e 2, Addison-Wesley Publishing Company: 1991, 1992.

Os tipos Ctype3 destinam-se a ser espaços reservados para extensões para os tipos POSIX necessários para o processamento de texto geral ou para as funções padrão da biblioteca C.

Um Edit Development Kit (EDK) pode incluir definições de índice pVar para os seguintes intervalos descritos no padrão Unicode.