Información general sobre TextPattern y objetos incrustados

2011-08-10

Nota
Esta documentación está dirigida a desarrolladores de .NET Framework que desean usar las clases administradas de UI Automation definidas en el espacio de nombres System.Windows.Automation. Para obtener información actualizada sobre UI Automation, vea Windows Automation API: UI Automation.

En este tema se describe cómo la Microsoft UI Automation expone los objetos incrustados, o elementos secundarios, dentro de un contenedor o documento de texto.

En UI Automation un objeto incrustado es cualquier elemento que tiene límites no textuales; por ejemplo, una imagen, un hipervínculo, una tabla o un tipo de documento como una hoja de cálculo de Microsoft Excel o un archivo de Microsoft Windows Media. Esta definición difiere de la estándar, según la cual se crea un elemento en una aplicación y se incrusta, o vincula, en otra. Si el objeto se puede editar o no dentro de su aplicación original es irrelevante en el contexto de UI Automation.

Este tema contiene las secciones siguientes.

Objetos incrustados y el árbol de automatización de la interfaz de usuario
Exponer objetos incrustados mediante TextPattern y TextPatternRange
Escenarios comunes
Temas relacionados

Objetos incrustados y el árbol de automatización de la interfaz de usuario

Los objetos incrustados se tratan como elementos individuales dentro de la vista de control del árbol de UI Automation. Se exponen como elementos secundarios del contenedor de texto para que se pueda tener acceso a ellos a través del mismo patrón que otros controles de UI Automation.

Ejemplo de contenedor de texto con objetos de tabla, imagen e hipervínculo incrustados

Tabla incrustada con imagen en un contenedor de texto

Ejemplo de vista de contenido para una parte del contenedor de texto anterior

Vista de contenido del ejemplo anterior

Exponer objetos incrustados mediante TextPattern y TextPatternRange

Cuando se combinan, la clase TextPattern del patrón de control y la clase TextPatternRange exponen métodos y propiedades que facilitan la navegación y la consulta de objetos incrustados.

El contenido textual (o texto interno) de un contenedor de texto y un objeto incrustado, como un hipervínculo o celda de tabla, se expone como una secuencia de texto continua única en la vista del control y en la vista de contenido del árbol de UI Automation; se omiten los límites del objeto. Si un cliente de automatización de la interfaz de usuario recupera el texto para narrarlo, interpretarlo o analizarlo de alguna manera, debería comprobarse si el intervalo de texto incluye casos especiales, como una tabla con contenido textual u otros objetos incrustados. Para ello, se puede llamar a GetChildren para obtener un AutomationElement para cada objeto incrustado y después a RangeFromChild para obtener un intervalo de texto para cada elemento. El proceso se realiza de forma recursiva hasta que se ha recuperado todo el contenido textual.

Ejemplo de secuencia de texto con objetos incrustados y sus tramos de intervalo

Intervalos de texto ocupados por objetos incrustados.

Cuando es necesario atravesar el contenido de un intervalo de texto, debe realizarse una serie de pasos en segundo plano para que el método Move se ejecute correctamente.

El intervalo de texto está normalizado; es decir, el intervalo de texto se contrae en un intervalo degenerado en el extremo Start, por lo que el extremo End resulta superfluo. Este paso es necesario para evitar la ambigüedad en las situaciones en las que un intervalo de texto abarca los límites de TextUnit; por ejemplo, "{La dirección U}RL https://www.microsoft.com está incrustada en el texto", donde "{" y "}" son los extremos del intervalo de texto.
El intervalo resultante se mueve hacia atrás en la propiedad DocumentRange, hasta el comienzo del límite de TextUnit solicitado.
El intervalo se mueve hacia atrás o hacia adelante en la propiedad DocumentRange según el número solicitado de límites de TextUnit.
Después se expande el intervalo desde un estado de intervalo degenerado y se mueve el extremo End en un límite de TextUnit solicitado.

Ejemplos de cómo ajustar un intervalo de texto para Move() y ExpandToEnclosingUnit()

Ajustes de intervalo mediante Move & ExpandToEnclosingUnit

Escenarios comunes

En las secciones siguientes se presentan ejemplos de los escenarios más comunes con objetos incrustados.

Leyenda para los ejemplos mostrados:

{ = Start

} = End

Hipervínculo

Ejemplo 1: intervalo de texto que contiene un hipervínculo de texto incrustado

{La dirección URL https://www.microsoft.com está incrustada en el texto}.

Método al que se llama	Resultado
GetText	Devuelve la cadena "La dirección URL https://www.microsoft.com está incrustada en el texto".
GetEnclosingElement	Devuelve el AutomationElement más profundo que engloba el intervalo de texto, en este caso, el AutomationElement que representa al propio proveedor de texto.
GetChildren	Devuelve un AutomationElement que representa el control de hipervínculo.
RangeFromChild donde AutomationElement es el objeto devuelto por el método GetChildren anterior.	Devuelve el intervalo que representa "http://www.microsoft.com".

Ejemplo 2: intervalo de texto que incluye parcialmente un hipervínculo de texto incrustado

La dirección URL http://{} está incrustada en el texto.

Método al que se llama	Resultado
GetText	Devuelve la cadena "www".
GetEnclosingElement	Devuelve el AutomationElement más profundo que engloba el intervalo de texto, en este caso, el control de hipervínculo.
GetChildren	Devuelve null, ya que el intervalo de texto no incluye la cadena de la dirección URL completa.

Ejemplo 3: intervalo de texto que incluye parcialmente el contenido de un contenedor del texto. El contenedor de texto tiene un hipervínculo de texto incrustado que no forma parte del intervalo de texto.

{La dirección URL} está incrustada en el texto.

Método al que se llama	Resultado
GetText	Devuelve la cadena "La dirección URL".
GetEnclosingElement	Devuelve el AutomationElement más profundo que engloba el intervalo de texto, en este caso, el AutomationElement que representa al propio proveedor de texto.
Move con parámetros de (TextUnit.Word, 1).	Desplaza el tramo del intervalo de texto hasta "http", ya que el texto del hipervínculo se compone de palabras sueltas. En este caso, el hipervínculo no se trata como un solo objeto. La dirección URL {http} está incrustada en el texto.

GetText

Devuelve la cadena "La dirección URL".

GetEnclosingElement

Devuelve el AutomationElement más profundo que engloba el intervalo de texto, en este caso, el AutomationElement que representa al propio proveedor de texto.

Move con parámetros de (TextUnit.Word, 1).

Desplaza el tramo del intervalo de texto hasta "http", ya que el texto del hipervínculo se compone de palabras sueltas. En este caso, el hipervínculo no se trata como un solo objeto.

La dirección URL {http} está incrustada en el texto.

Imagen

Ejemplo 1: intervalo de texto que contiene una imagen incrustada

{La imagen Ejemplo de imagen incrustada está incrustada en el texto}.

Método al que se llama	Resultado
GetText	Devuelve la cadena "La está incrustada en el texto". No se puede esperar que el texto ALT asociado a la imagen se incluya en la secuencia de texto.
GetEnclosingElement	Devuelve el AutomationElement más profundo que engloba el intervalo de texto, en este caso, el AutomationElement que representa al propio proveedor de texto.
GetChildren	Devuelve un AutomationElement que representa el control de imagen.
RangeFromChild donde AutomationElement es el objeto devuelto por el método GetChildren anterior.	Devuelve el intervalo degenerado que representa "".

Ejemplo 2: intervalo de texto que incluye parcialmente el contenido de un contenedor del texto. El contenedor de texto tiene una imagen incrustada que no forma parte del intervalo de texto.

{La imagen} Ejemplo de imagen incrustada está incrustada en el texto.

Método al que se llama	Resultado
GetText	Devuelve la cadena "La imagen".
GetEnclosingElement	Devuelve el AutomationElement más profundo que engloba el intervalo de texto, en este caso, el AutomationElement que representa al propio proveedor de texto.
Move con parámetros de (TextUnit.Word, 1).	Desplaza el tramo del intervalo de texto hasta "está". Dado que sólo los objetos incrustados basados en texto se consideran parte de la secuencia de texto, la imagen de este ejemplo no afecta a Move o a su valor devuelto (1 en este caso).

Tabla

Tabla usada para los ejemplos

Celda con imagen	Celda con texto
	X
	Y
Imagen para Z	Z

Ejemplo de imagen incrustada

Ejemplo de imagen incrustada 2

Ejemplo de imagen incrustada 3

Imagen para Z

Ejemplo 1: obtener el contenedor del texto a partir del contenido de una celda.

Método al que se llama	Resultado
GetItem con los parámetros (0,0)	Devuelve el AutomationElement que representa el contenido de la celda de la tabla; en este caso, el elemento es un control de texto.
RangeFromChild donde AutomationElement es el objeto devuelto por el método GetItem anterior.	Devuelve el intervalo que incluye la imagen .
GetEnclosingElement para el objeto devuelto por el método RangeFromChild anterior.	Devuelve el AutomationElement que representa la celda de la tabla; en este caso, el elemento es un control de texto que admite TableItemPattern.
GetEnclosingElement para el objeto devuelto por el método GetEnclosingElement anterior.	Devuelve el AutomationElement que representa la tabla.
GetEnclosingElement para el objeto devuelto por el método GetEnclosingElement anterior.	Devuelve el AutomationElement que representa al propio proveedor de texto.

Ejemplo 2: obtener el contenido de texto de una celda.

Método al que se llama	Resultado
GetItem con parámetros de (1,1).	Devuelve el AutomationElement que representa el contenido de la celda de la tabla; en este caso, el elemento es un control de texto.
RangeFromChild donde AutomationElement es el objeto devuelto por el método GetItem anterior.	Devuelve "Y".