Usar IUIAutomationTextRange para acceder a un intervalo de texto y manipularlo

En este tema se describe cómo usar las propiedades y métodos de la interfaz IUIAutomationTextRange para tener acceso y manipular el contenido textual de un control basado en texto.

¿Qué es un intervalo de texto?

El modelo de objetos de texto de Microsoft Automatización de la interfaz de usuario se basa en el concepto del intervalo de texto. Un intervalo de texto es un objeto que expone la interfaz IUIAutomationTextRange y representa un intervalo contiguo de texto en un control basado en texto. Cada intervalo de texto tiene un punto de conexión inicial y un extremo final, y todo el contenido textual entre los dos puntos de conexión se considera parte del intervalo. Un intervalo de texto cuyo punto de conexión inicial y extremo final se encuentran en la misma ubicación se denomina intervalo de texto degenerado (o vacío). Un intervalo de texto degenerado se usa para marcar una ubicación específica dentro del texto de un control, como la ubicación del punto de inserción de texto.

Adquisición de objetos de intervalo de texto

Las aplicaciones cliente adquieren objetos de intervalo de texto mediante las propiedades y métodos de la interfaz IUIAutomationTextPattern . La propiedad IUIAutomationTextRangePattern::D ocumentRange recupera un intervalo de texto que representa todo el contenido textual de un control basado en texto, mientras que otros métodos adquieren intervalos de texto que representan parte del contenido, como el texto seleccionado, el texto visible o un objeto incrustado en el texto.

Los métodos IUIAutomationTextRangePattern::GetVisibleRanges y GetSelection pueden recuperar matrices de objetos de intervalo de texto. Si un control está parcialmente oculto por una ventana superpuesta u otro objeto, GetVisibleRanges devuelve una matriz que contiene un objeto de intervalo de texto para cada línea de texto visible parcialmente. De forma similar, si un control basado en texto admite la selección de varios intervalos separados de texto, GetSelection devuelve una matriz que contiene un objeto de intervalo de texto para cada intervalo seleccionado.

El método IUIAutomationTextRangePattern::RangeFromChild permite a una aplicación cliente recuperar un intervalo de texto que incluya un objeto incrustado en el contenido textual. El cliente especifica el puntero de interfaz IUIAutomationElement de un objeto incrustado, como una imagen, una tabla o un hipervínculo, y el método devuelve un intervalo de texto que incluye el objeto. Sin embargo, si el objeto incrustado no tiene texto asociado, el método devuelve un intervalo de texto degenerado.

Una aplicación cliente puede usar el método IUIAutomationTextRangePattern::RangeFromPoint para recuperar un intervalo de texto para el texto visible o el objeto incrustado más cercano a las coordenadas de pantalla especificadas.

Seleccionar texto en un intervalo de texto

La interfaz IUIAutomationTextRange incluye varios métodos que permiten a una aplicación cliente controlar la selección de texto en un control basado en texto.

Las aplicaciones cliente pueden usar el método IUIAutomationTextRange::Select para seleccionar el texto correspondiente a un intervalo de texto y quitar la selección anterior, si existe, del control de texto. Al llamar a Select con un intervalo de texto degenerado, se mueve el punto de inserción a la ubicación del intervalo de texto sin seleccionar ningún texto.

Si un control admite la selección de varios intervalos de texto separados, un cliente puede usar los métodos IUIAutomationTextRange::AddToSelection y RemoveFromSelection para agregar intervalos de texto a la colección de intervalos de texto seleccionados y quitarlos de él. Si el control solo admite un intervalo de texto seleccionado a la vez, pero la operación de selección daría lugar a la selección de varios intervalos de texto separados, el método devuelve un error de E_INVALIDOPERATION , o extiende o trunca la selección actual. Una aplicación cliente puede detectar si un control admite la selección de uno o varios intervalos de texto, o ninguno en absoluto, comprobando la propiedad IUIAutomationTextPattern::SupportedTextSelection .

Si un control basado en texto admite inserciones de texto, al llamar a IUIAutomationTextRange::AddToSelection o RemoveFromSelection en un intervalo de texto degenerado en el control se mueve el punto de inserción, pero no se selecciona ningún texto.

Recuperar texto de un intervalo de texto

Las aplicaciones cliente pueden usar el método IUIAutomationTextRange::GetText para recuperar el texto sin formato de un intervalo de texto. El texto sin formato incluye todos los caracteres de control que se encuentran en el texto de origen, como retornos de carro y la marca Unicode de izquierda a derecha (LRM). El texto sin formato no incluye etiquetas de marcado como HTML que puedan estar presentes en el texto de origen. Además, los códigos de escape del texto de origen se convierten en los equivalentes de texto sin formato. Por ejemplo, " " se convierte en un carácter de espacio simple.

Si un objeto incrustado abarca un intervalo de texto, el texto sin formato incluye el texto interno del objeto, pero no el texto alternativo (la propiedad name del objeto incrustado). Para obtener más información, vea Cómo Automatización de la interfaz de usuario expone objetos incrustados.

El método IUIAutomationTextRange::FindText busca un intervalo de texto para una cadena determinada y, si se encuentra, devuelve un nuevo intervalo de texto que abarca la cadena.

Recuperar atributos de texto de un intervalo de texto

Los atributos de texto determinan el estilo de formato del texto en un control basado en texto e incluyen elementos como el color de primer plano, el estilo de viñeta, el tamaño de fuente, etc. Automatización de la interfaz de usuario admite una serie de atributos de texto y define un identificador para cada atributo admitido. Una aplicación cliente puede consultar un intervalo de texto para el valor de un atributo de texto determinado especificando un identificador de atributo en una llamada al método IUIAutomationTextRange::GetAttributeValue , junto con un puntero a una estructura VARIANT que recibe el valor del atributo. Para obtener información detallada sobre cada atributo de texto que Automatización de la interfaz de usuario admite, vea Identificadores de atributos de texto.

El valor recuperado por GetAttributeValue representa el valor del atributo en todo el intervalo de texto. Si todo el texto del intervalo comparte el mismo valor para el atributo especificado, GetAttributeValue devuelve ese valor. Sin embargo, si el valor del atributo varía en el intervalo de texto, GetAttributeValue devuelve un puntero IUnknown a un objeto de token estático denominado objeto ReservedMixedAttribute . Para detectar si el valor de un atributo varía en un intervalo de texto, una aplicación cliente debe comparar los resultados de GetAttributeValue con el objeto ReservedMixedAttribute recuperado de la propiedad IUIAutomation::ReservedMixedAttributeValue .

No es necesario un control basado en texto para admitir todos los atributos de texto Automatización de la interfaz de usuario. Si un cliente llama al método IUIAutomationTextRange::GetAttributeValue y pasa el identificador de un atributo no admitido, el método devuelve un puntero IUnknown a un objeto de token estático denominado Objeto ReservedNotSupported . Para detectar si se admite un atributo determinado, una aplicación cliente debe comparar los resultados de GetAttributeValue con el objeto ReservedNotSupported recuperado de la propiedad IUIAutomation::ReservedNotSupportedValue .

Las aplicaciones cliente pueden usar el método IUIAutomationTextRange::FindAttribute para buscar un intervalo de texto que tenga un atributo de texto determinado. Si se encuentra, el método devuelve un nuevo intervalo de texto que abarca el texto coincidente. Tenga en cuenta que FindAttribute devuelve un intervalo de texto para el texto coincidente, incluso si el texto no está visible.

Recuperar objetos incrustados de un intervalo de texto

Un intervalo de texto puede incluir objetos incrustados como tablas, imágenes, hipervínculos, etc. Una aplicación cliente puede recuperar una colección de todos los objetos incrustados de un intervalo llamando al método IUIAutomationTextRange::GetChildren . Los objetos incrustados que se superponen con el intervalo, pero que no están completamente incluidos en ella, también se incluyen en la colección. Si el intervalo no contiene objetos incrustados, GetChildren recupera una colección vacía.

Aunque depende del proveedor del control basado en texto, el método GetChildren normalmente no devuelve ningún elemento secundario de los elementos incrustados. Por ejemplo, si un intervalo de texto contiene una tabla que tiene una serie de celdas secundarias , el método GetChildren normalmente devuelve solo el elemento table y no los elementos de celda.

Por motivos de rendimiento o arquitectura, Es posible que GetChildren no pueda recuperar objetos IUIAutomationElement para todos los objetos incrustados de un intervalo de texto. En su lugar, el proveedor podría devolver una colección que incluye elementos virtualizados. Para obtener más información, vea Trabajar con elementos virtualizados.

Manipular un intervalo de texto

La interfaz IUIAutomationTextRange proporciona varios métodos para manipular y navegar por intervalos de texto en un control basado en texto. Los métodos IUIAutomationTextRange::Move, MoveEndpointByUnit y ExpandToEnclosingUnit mueven un intervalo de texto o uno de sus extremos por la unidad de texto especificada, como carácter, palabra, párrafo, etc. Para obtener más información, vea Automatización de la interfaz de usuario Unidades de texto.

A pesar de su nombre, el método ExpandToEnclosingUnit no expande necesariamente un intervalo de texto. En su lugar, "normaliza" un intervalo de texto moviendo los puntos de conexión para que el intervalo abarque exactamente la unidad de texto especificada. El intervalo se expande si es menor que la unidad especificada o se acorta si es mayor que la unidad especificada. En el diagrama siguiente se muestra cómo ExpandToEnclosingUnit normaliza un intervalo de texto moviendo los puntos de conexión del intervalo.

Si el intervalo de texto comienza al principio de una unidad de texto y termina al principio de, o antes, el siguiente límite de unidad de texto, el extremo final se mueve al siguiente límite de unidad de texto (vea 1 y 2 en la ilustración anterior).

Si el intervalo de texto comienza al principio de una unidad de texto y termina en, o después, el siguiente límite de unidad, el extremo final permanece o se mueve hacia atrás al siguiente límite de unidad después del punto de conexión inicial (vea 3 y 4 en la ilustración anterior). Si hay más de un límite de unidad de texto entre los extremos inicial y final, el extremo final se mueve hacia atrás al siguiente límite de unidad después del punto de conexión inicial, lo que da como resultado un intervalo de texto que es una unidad de texto de longitud.

Si el intervalo de texto se inicia en medio de una unidad de texto, el punto de conexión inicial se mueve hacia atrás al principio de la unidad de texto y el extremo final se mueve hacia delante o hacia atrás, según sea necesario, al siguiente límite de unidad después del punto de conexión inicial (vea 5 a 8 en la ilustración anterior).

Cuando se llama al método IUIAutomationTextRange::Move , el proveedor normaliza el intervalo de texto por la unidad de texto especificada. A continuación, el proveedor mueve el intervalo hacia atrás o hacia delante por el número especificado de unidades de texto. Al mover el intervalo, el proveedor omite los límites de los objetos incrustados en el texto. (Sin embargo, el propio límite de unidad puede verse afectado por la existencia de un objeto incrustado). En el diagrama siguiente se muestra cómo el método Move mueve un intervalo de texto, una unidad por unidad, entre objetos incrustados y límites de unidad de texto.

El método IUIAutomationTextRange::MoveEndpointByUnit mueve uno de los puntos de conexión hacia delante o hacia atrás por la unidad de texto especificada. En la ilustración siguiente se muestra cómo avanza un punto de conexión.

El método IUIAutomationTextRange::MoveEndpointByRange permite a una aplicación cliente establecer un punto de conexión de un intervalo de texto en la misma ubicación que el extremo especificado de un segundo intervalo de texto.

Desplazamiento de un intervalo de texto a la vista

El método IUIAutomationTextRange::ScrollIntoView desplaza un intervalo de texto para que el texto esté visible en la ventanilla del control basado en texto. Al llamar a ScrollIntoView, un cliente puede especificar si el texto debe alinearse con la parte superior o inferior de la ventanilla.

Recuperar el elemento envolvente de un intervalo de texto

Una aplicación cliente puede usar el método IUIAutomationTextRange::GetEnclosingElement para recuperar el puntero de la interfaz IUIAutomation del elemento más interno que incluye un intervalo de texto. El elemento envolvente suele ser el proveedor de texto que proporciona el intervalo de texto. Sin embargo, si el proveedor de texto admite elementos secundarios como tablas o hipervínculos, el elemento envolvente podría ser un descendiente del proveedor de texto.

Comparación y clonación de intervalos de texto

La interfaz IUIAutomationTextRange incluye dos métodos para comparar intervalos de texto. El método IUIAutomationTextRange::Compare compara los puntos de conexión inicial y final de dos intervalos de texto y devuelve TRUE si ambos extremos son los mismos. El método IUIAutomationTextRange::CompareEndpoints compara el punto de conexión inicial o final de los dos intervalos. El valor devuelto es cero si los puntos de conexión son iguales, o un valor positivo o negativo que indica las posiciones relativas de los dos puntos de conexión.

Las aplicaciones cliente pueden usar el método IUIAutomationTextRange::Clone para crear una copia exacta del intervalo de texto. El nuevo intervalo de texto se puede manipular independientemente del intervalo de texto original.

Recuperación de anotaciones

Un intervalo de texto puede incluir anotaciones si el control basado en texto los admite. Hay muchos tipos diferentes de anotaciones. El archivo de encabezado UIAutomationClient.h define un conjunto de valores constantes con nombre que identifican los tipos de anotaciones que Automatización de la interfaz de usuario admite. Para obtener más información, vea Identificadores de tipo de anotación.

Algunos tipos de anotaciones se representan mediante un elemento de automatización que admite el patrón de control Annotation (interfaz IUIAutomationAnnotationPattern ). Otros tipos de anotaciones se exponen a través del patrón de control TextRange . Por ejemplo, un proveedor podría exponer un indicador simple de error ortográfico haciendo que el método IUIAutomationTextRange::GetAttributeValue devuelva un atributo de texto AnnotationTypes de AnnotationType_SpellingError y un valor NULL para el atributo de texto AnnotationObjects .

Recuperar tipos de anotaciones de un intervalo de texto

Puede recuperar una lista de los tipos de anotaciones que están presentes en un intervalo de texto mediante el método IUIAutomationTextRange::GetAttributeValue . Al llamar al método , especifique un identificador de atributo de texto de UIA_AnnotationTypesAttributeId y un puntero a un parámetro de tipo VARIANT. Cuando el método devuelve, el parámetro VARIANT contiene una lista de identificadores de tipo de anotación, uno para cada tipo de anotación en el intervalo de texto. Para obtener más información, vea Identificadores de tipo de anotación.

Recuperar todas las anotaciones de un intervalo de texto

Para recuperar las anotaciones de un intervalo de texto, llame al método IUIAutomationTextRange::GetAttributeValue , especificando un identificador de atributo de texto de UIA_AnnotationObjectsAttributeId y un puntero a un parámetro de tipo VARIANT. Cuando el método devuelve, el parámetro VARIANT contiene una interfaz IUIAutomationElementArray que representa una matriz de elementos de automatización, una para cada anotación del intervalo de texto. La propiedad IUIAutomationElementArray::Length indica el número de elementos de la matriz y el método IUIAutomationElementArray::GetElement recupera la interfaz IUIAutomationElement para un elemento determinado.

Recuperar información sobre una anotación determinada

Para recuperar información sobre una anotación determinada, primero recupere la interfaz IUIAutomationElement para el elemento de anotación como se describe en la sección anterior. A continuación, recupere la interfaz IUIAutomationAnnotationPattern para la anotación llamando al método IUIAutomationElement::GetCurrentPatternAs con un identificador de patrón de control de UIA_AnnotationPatternId, un identificador de interfaz de IID_IUIAutomationAnnotationPattern y la dirección de una variable que recibe el puntero IUIAutomationAnnotation para la anotación. Consulte las propiedades de la interfaz IUIAutomationAnnotation para recuperar el nombre y el identificador de tipo de anotación, el nombre del autor de la anotación, la fecha y hora de la anotación, y la interfaz IUIAutomationElement para el elemento anotado.

Recuperación del texto de destino de anotación

Normalmente, una anotación se aplica a algún subconjunto del texto de un intervalo de texto. Después de recuperar la interfaz IUIAutomationElement para una anotación, puede pasar la interfaz al método IUIAutomationTextRange2::RangeFromAnnotation para recuperar un intervalo de texto que contiene el texto que es el destino de la anotación.

Recuperar estilos visuales

Un proveedor implementa el patrón de control Styles para describir un elemento de interfaz de usuario que tiene un estilo específico, un color de relleno, un patrón de relleno o una forma. Esto resulta especialmente útil cuando se describen los elementos de un documento, que suelen tener estos estilos. Estilos como este a menudo llevan información útil para los clientes con discapacidades; por ejemplo, los estilos pueden describir una determinada cadena como título de un documento o un determinado objeto de diagrama de flujo como un diamante o un círculo.

Puede usar el método IUIAutomationTextRange::GetAttributeValue para recuperar los nombres e identificadores de los estilos visuales que se usan en un intervalo de texto. Use el atributo de texto UIA_StyleNameAttributeId para recuperar los nombres de estilo y UIA_StyleIdAttributeId para recuperar los identificadores de estilo.

Un control basado en texto que admite estilos visuales puede implementar el patrón de control Estilos para permitir que los clientes accedan a información sobre un estilo visual usado por el control. Los clientes acceden al patrón de control Styles a través de la interfaz IUIAutomationStylesPattern . Puede recuperar esta interfaz llamando al método IUIAutomationElement::GetCurrentPattern o GetCurrentPatternAs , especificando UIA_StylesPatternId como identificador de patrón de control.

La interfaz IUIAutomationStylesPattern incluye propiedades y métodos que proporcionan la siguiente información sobre un estilo visual:

• Nombre del estilo visual, como "Normal" o "Título 1".
• Identificador del estilo visual. Para obtener más información, vea Identificadores de estilo.
• Color usado para rellenar el control basado en texto.
• Color del patrón usado para rellenar el control basado en texto.
• Forma del control basado en texto.
• Las propiedades extendidas; es decir, una lista de nombres y valores de estilo específicos del control.

Invocar menús contextuales desde intervalos de texto

A partir de Windows 8.1, los intervalos de texto pueden admitir la interfaz IUIAutomationTextRange2. Esta interfaz admite el método ShowContextMenu . Puede llamar a este método para invocar cualquier menú contextual asociado a un intervalo de texto. El escenario para esto es la autocorrección de intervalos de texto o selección candidata de IME. En estos casos, aparece un menú contextual que admite la interacción del usuario.

Temas relacionados

Patrones de control Text y TextRange

Automatización de la interfaz de usuario compatibilidad con contenido textual

Trabajar con controles basados en texto