Interface ITextRange (tom.h)

Os objetos ITextRange são ferramentas avançadas de edição e associação de dados que permitem que um programa selecione texto em uma história e, em seguida, examine ou altere esse texto.

Herança

A interface ITextRange herda da interface IDispatch . ITextRange também tem estes tipos de membros:

Métodos

A interface ITextRange tem esses métodos.

ITextRange::CanEdit Determina se o intervalo especificado pode ser editado.
ITextRange::CanPaste Determina se um objeto de dados pode ser colado, usando um formato especificado, no intervalo atual.
ITextRange::ChangeCase Altera as letras maiúsculas e minúsculas nesse intervalo de acordo com o parâmetro Type.
ITextRange::Collapse Recolhe o intervalo de texto especificado em um ponto degenerado no início ou no final do intervalo.
ITextRange::Copy Copia o texto para um objeto de dados.
ITextRange::Cut Corta o texto simples ou avançado para um objeto de dados ou para a Área de Transferência, dependendo do parâmetro pVar.
ITextRange::D elete Imita as teclas DELETE e BACKSPACE, com e sem a tecla CTRL pressionada.
ITextRange::EndOf Move as extremidades desse intervalo para o final da última Unidade sobreposta no intervalo.
ITextRange::Expand Expande esse intervalo para que todas as unidades parciais que ele contém estejam completamente contidas.
ITextRange::FindText Pesquisa até Contagem de caracteres para o texto dado por bstr. A posição inicial e a direção também são especificadas por Contagem e os critérios correspondentes são dados por Sinalizadores.
ITextRange::FindTextEnd Pesquisa até Contagem de caracteres para a cadeia de caracteres, bstr, começando do cp Final do intervalo.
ITextRange::FindTextStart Pesquisa até Contagem de caracteres para a cadeia de caracteres, bstr, começando no cp Inicial do intervalo (cpFirst).
ITextRange::GetChar Obtém o caractere na posição inicial do intervalo.
ITextRange::GetDuplicate Obtém uma duplicata desse objeto de intervalo.
ITextRange::GetEmbeddedObject Recupera um ponteiro para o objeto inserido no início do intervalo especificado, ou seja, em cpFirst. O intervalo deve ser um ponto de inserção ou deve selecionar apenas o objeto inserido.
ITextRange::GetEnd Obtém a posição do caractere final do intervalo.
ITextRange::GetFont Obtém um objeto ITextFont com os atributos de caractere do intervalo especificado.
ITextRange::GetFormattedText Obtém um objeto ITextRange com o texto formatado do intervalo especificado.
ITextRange::GetIndex Recupera o índice de história do parâmetro Unit na posição de caractere Inicial do intervalo especificado.
ITextRange::GetPara Obtém um objeto ITextPara com os atributos de parágrafo do intervalo especificado.
ITextRange::GetPoint Recupera coordenadas de tela para a posição do caractere inicial ou final no intervalo de texto, juntamente com a posição da intra-linha.
ITextRange::GetStart Obtém a posição do caractere inicial do intervalo.
ITextRange::GetStoryLength Obtém a contagem de caracteres na história do intervalo.
ITextRange::GetStoryType Obtenha o tipo da história do intervalo.
ITextRange::GetText Obtém o texto sem formatação neste intervalo. A propriedade Text é a propriedade padrão da interface ITextRange.
ITextRange::InRange Determina se esse intervalo está dentro ou no mesmo texto de um intervalo especificado.
ITextRange::InStory Determina se a história desse intervalo é igual à história de um intervalo especificado.
ITextRange::IsEqual Determina se esse intervalo tem as mesmas posições de caractere e história que as de um intervalo especificado.
ITextRange::Move Move o ponto de inserção para frente ou para trás um número especificado de unidades. Se o intervalo não for descrigerado, o intervalo será recolhido para um ponto de inserção em ambas as extremidades, dependendo de Count e, em seguida, será movido.
ITextRange::MoveEnd Move a posição final do intervalo.
ITextRange::MoveEndUntil Move a extremidade do intervalo para a posição do caractere do primeiro caractere encontrado que está no conjunto de caracteres especificado por Cset, desde que o caractere seja encontrado dentro de Contagem de caracteres do final do intervalo.
ITextRange::MoveEndWhile Move o final do intervalo Contagem de caracteres ou apenas após todos os caracteres contíguos encontrados no conjunto de caracteres especificado por Cset, o que for menor.
ITextRange::MoveStart Move a posição inicial do intervalo o número especificado de unidades na direção especificada.
ITextRange::MoveStartUntil Move a posição inicial do intervalo a posição do primeiro caractere encontrado que está no conjunto de caracteres especificado por Cset, desde que o caractere seja encontrado dentro de Contagem de caracteres da posição inicial.
ITextRange::MoveStartWhile Move a posição inicial do intervalo contar caracteres ou apenas ultrapassar todos os caracteres contíguos encontrados no conjunto de caracteres especificado por Cset, o que for menor.
ITextRange::MoveUntil Pesquisa até Contagem de caracteres para o primeiro caractere no conjunto de caracteres especificado por Cset. Se um caractere for encontrado, o intervalo será recolhido a esse ponto. O início da pesquisa e a direção também são especificados por Count.
ITextRange::MoveWhile Começa em um final especificado de um intervalo e pesquisa enquanto os caracteres pertencem ao conjunto especificado por Cset e enquanto o número de caracteres é menor ou igual a Count.
ITextRange::P aste Cola o texto de um objeto de dados especificado.
ITextRange::ScrollIntoView Rola o intervalo especificado para a exibição.
ITextRange::Select Define as posições inicial e final e os valores de história da seleção ativa para as deste intervalo.
ITextRange::SetChar Define o caractere na posição inicial do intervalo.
ITextRange::SetEnd Define a posição final do intervalo.
ITextRange::SetFont Define os atributos de caractere desse intervalo como os do objeto ITextFont especificado.
ITextRange::SetFormattedText Define o texto formatado desse texto de intervalo para o texto formatado do intervalo especificado.
ITextRange::SetIndex Altera esse intervalo para a unidade especificada do texto.
ITextRange::SetPara Define os atributos de parágrafo desse intervalo como os do objeto ITextPara especificado.
ITextRange::SetPoint Altera o intervalo com base em um ponto especificado até (dependendo de Estender) o ponto (x, y) alinhado de acordo com Type.
ITextRange::SetRange Ajusta os pontos de extremidade de intervalo aos valores especificados.
ITextRange::SetStart Define a posição do caractere para o início desse intervalo.
ITextRange::SetText Define o texto nesse intervalo.
ITextRange::StartOf Move o intervalo para o início da primeira Unidade sobreposta no intervalo.

Comentários

Vários intervalos de texto podem ser ativos e trabalhar cooperativamente na mesma história e evoluir com a história. Por exemplo, se um intervalo de texto excluir o texto especificado antes de outro intervalo de texto, este último rastreará a alteração. Nesse sentido, os intervalos de texto são semelhantes aos indicadores do Microsoft Word, que também acompanham as alterações de edição. No entanto, os indicadores não podem editar texto, enquanto os intervalos de texto podem. Além disso, os intervalos permitem manipular o texto sem alterar a seleção ou a Área de Transferência, ambas valiosas para os usuários finais. A interface ITextSelection herda de ITextRange e adiciona alguns métodos e propriedades orientados à interface do usuário, conforme descrito na seção em ITextSelection.

Você pode examinar um intervalo de texto usando métodos baseados em posições de caractere. Especificamente, um intervalo de texto é caracterizado por:

• A primeira posição de caractere, cpFirst, que aponta para um ponto de inserção imediatamente antes do primeiro caractere (em relação ao início da história) no intervalo.
• A posição de limite , cpLim, que aponta para um ponto de inserção imediatamente após o último caractere no intervalo.

O primeiro caractere em uma história tem cpFirst = zero. Se um argumento cp tiver um valor maior que o número de caracteres na história, o número de caracteres na história será usado. Se um argumento cp for negativo, zero será usado. Para aqueles familiarizados com o Microsoft Visual Basic for Applications, chame a propriedade cpFirstStart e a propriedade cpLimEnd (embora a posição inicial de um intervalo também seja um fim).

Na figura a seguir, as posições de caractere são representadas pelas linhas que separam as letras. Os valores de posição de caractere correspondentes são fornecidos abaixo das linhas. O intervalo que começa em cpFirst = 5 e termina em cpLim = 7 contém a palavra de duas letras. Se esta figura ilustra o texto completo em uma história, o comprimento da história é 30.

O comprimento de um intervalo é fornecido por cpLim - cpFirst ou equivalentemente por End – Start. Um intervalo com comprimento zero é chamado de intervalo degenerado ou vazio e tem valores cp* iguais, ou seja, cpFirst = cpLim. Um exemplo de um intervalo degenerado é o ponto de inserção atual. Uma seleção não nula é um exemplo de um intervalo não indexador.

Suponha que o intervalo de 5 a 7 indicado por células sombreadas na figura anterior seja orientado a excluir seu texto (consulte Excluir), transformando-se assim em um ponto de inserção. O intervalo de 25 a 29 rastrearia automaticamente seu conteúdo, ou seja, o texto da palavra. A figura a seguir mostra o resultado.

Nessa figura, o intervalo de texto agora foi ajustado automaticamente para ter cpFirst = 23 e cpLim = 27. O proprietário do intervalo não precisa se preocupar em atualizar os valores de posição do caractere de intervalo em face da edição.

Os nomes dos métodos de movimentação indicam qual extremidade mover, mas observe que, se algum método tentar mover um intervalo para além do outro, ambas as extremidades serão movidas para a posição de destino. Como resultado, o ponto de inserção está na posição de destino. O conceito é que cpFirst e cpLim sempre têm que obedecer à condição fundamental

0 <= cpFirst<= cpLim<= # caracteres na história

ou equivalentemente para um intervalo r, 0 <= r. Start <= r. End <= r. StoryLength, que é o que você esperaria dos nomes dessas quantidades.

Outro recurso importante é que todas as histórias contêm um personagem CR final (0xD) indeletável no final. Portanto, até mesmo uma história vazia tem um único personagem, ou seja, o CR final. Um intervalo pode selecionar esse caractere, mas não pode se tornar um ponto de inserção além dele. Para ver como isso funciona, tente selecionar o CR final em um documento Word e pressione a tecla seta para a direita para recolhê-lo. A árvore de diretório será recolhida antes do CR final, mas o CR não pode ser excluído. O TOM (Modelo de Objeto de Texto) funciona da mesma maneira. Então, se r. Start <= r. End, em seguida , r. End <= (r. StoryLength – 1). Para obter uma discussão sobre como excluir um CR, consulte Excluir.

Alguns métodos dependem de um argumento Unit , que pode assumir os valores predefinidos listados na tabela a seguir.

Unidade	Valor	Significado
tomCharacter	1	Caractere.
tomWord	2	Word.
tomSentence	3	Frase.
tomParagraph	4	Parágrafo.
tomLine	5	Linha (em exibição).
tomStory	6	História.
tomScreen	7	Tela (como para PAGE UP/PAGE DOWN).
tomSection	8	Seção.
tomColumn	9	Coluna da tabela.
tomRow	10	Linha da tabela.
tomWindow	11	Superior esquerdo ou inferior direito da janela.
tomCell	12	Célula da tabela.
tomCharFormat	13	Execução de formatação de caractere constante.
tomParaFormat	14	Execução de formatação de parágrafo constante.
tomTable	15	Tabela.
tomObject	16	Objeto inserido.

 

A maioria dos valores unitários são autoexplicativos. No entanto, as descrições a seguir são fornecidas para maior clareza.

tomWord

A constante tomWord é um fim de parágrafo ou um intervalo de alfanuméricos ou pontuação, incluindo quaisquer espaços em branco a seguir. Para ter uma noção do tomWord na tela, watch como o cursor se move quando você pressiona CTRL+SETA PARA A DIREITA (—>) ou CTRL+SETA PARA A ESQUERDA (<—) em um documento Word.

tomSentence

A constante tomSentence descreve uma cadeia de caracteres de texto que termina com um ponto de interrogação, ponto de interrogação ou ponto de exclamação e é seguida por um ou mais caracteres de espaço em branco ASCII (9 a 0xd e 0x20) ou o separador de parágrafo Unicode (0x2029). O espaço em branco à direita faz parte da frase. A última frase de uma história não precisa ter um ponto de interrogação, ponto de interrogação ou ponto de exclamação. O início de uma história se qualifica como o início de uma tomSentence, mesmo que a cadeia de caracteres lá não se qualifique como uma frase gramaticalmente. Outras frases devem seguir um fim de frase e não podem começar com um ponto de interrogação, ponto de interrogação ou ponto de exclamação.

tomParagraph

A constante tomParagraph é uma cadeia de caracteres de texto terminada por uma marca de fim de parágrafo (CRLF, CR, VT (para SHIFT+ENTER), LF, FF ou 0x2029). Os mecanismos TOM sempre têm uma marca de fim de parágrafo indeletável no final de uma história. Assim, todas as histórias tom automaticamente têm pelo menos um tomWord, um tomSentence e um tomParagraph.

tomLine

A constante tomLine corresponde a uma linha de texto em uma exibição, desde que uma exibição esteja associada ao intervalo. Se nenhuma exibição estiver associada a um intervalo, tomLine será tratado como tomParagraph. Uma seleção tem automaticamente uma exibição e um intervalo que é duplicado (consulte GetDuplicate). Outros intervalos podem não ter uma exibição, dependendo do mecanismo e do contexto TOM.

Os métodos que movem uma ou ambas as extremidades em termos de Unidade, como Move, MoveEnd e MoveStart, dependem do argumento Count assinado. Exceto pelos comandos de movimento geométrico ITextSelection , se Count for maior que zero, as extremidades a serem movidas serão movidas para frente (no final da história) e, se Count for menor que zero, as extremidades serão movidas para trás (para o início). O valor padrão de Count para esses métodos Move é 1. Esses métodos tentam mover Unidades de Contagem, mas o movimento nunca está além dos fins da história.

Métodos que movem uma ou ambas as extremidades correspondendo a cadeias de caracteres ou padrões de cadeia de caracteres, como MoveWhile, MoveEndWhile e MoveStartWhile, podem se mover para um número máximo de caracteres fornecidos pelo argumento Count assinado. Se Count for maior que zero, as extremidades a serem movidas serão movidas para frente e, se Count for menor que zero, as extremidades serão movidas para trás. Dois valores especiais de Contagem , tomForward e tomBackward, são definidos. Esses valores têm a garantia de chegar ao final e ao início da história, respectivamente. O valor padrão de Count é tomForward.

Em Métodos Move* que transformam um intervalo não descritivo em um degenerado, como Move, MoveWhile e MoveUntil, cpFirst será alterado se Count for negativo e cpLim for alterado se Count for positivo. Após esse movimento, a outra extremidade do intervalo também é movida para o novo local. Consulte os métodos individuais para obter informações de contagem mais específicas. Para intervalos não descritivos, os métodos MoveStart, MoveEnd, MoveStartWhile, MoveEndWhile, MoveStartUntil e MoveEndUntil movem a posição inicial (Start) ou a posição final (End).

Para selecionar uma unidade que corresponda a um intervalo contíguo, como tomWord, tomSentence e tomParagraph, use o método MoveEnd . Para selecionar uma unidade que corresponda a um intervalo não contíguo, como tomObject, use o método EndOf , pois o próximo objeto pode ocorrer após texto intermediário substancial, se for o caso. Para selecionar uma unidade tomCell, o intervalo deve estar dentro de uma tabela.

Exemplos e explicação adicionais dos argumentos Count e Unit a seguir. Observe que os mecanismos TOM podem não dar suporte a todas as unidades na tabela acima. Por exemplo, os controles de edição avançada não oferecem os conceitos das seções, mas retornam E_NOTIMPL quando determinado tomSection. No entanto, se um mecanismo TOM der suporte a uma unidade, ele terá o valor de índice fornecido na tabela.

Os aplicativos normalmente não implementam a interface ITextRange . Soluções de texto da Microsoft, como controles de edição avançada, implementam ITextRange como parte de sua implementação tom.

Os aplicativos podem recuperar um ponteiro ITextRange chamando o método Range .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	tom.h

Confira também

Conceitual

IDispatch

Modelo de objeto de texto

Usando o modelo de objeto text