Propiedades de UI Automation para clientes

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 esta introducción se presentan las propiedades de la UI Automation tal y como se exponen en las aplicaciones cliente de Automatización de la interfaz de usuario.

Las propiedades de los objetos AutomationElement contienen información sobre los elementos de la user interface (UI), normalmente controles. Las propiedades de un elemento AutomationElement son genéricas; es decir, no son específicas de un tipo de control concreto. Muchas de estas propiedades se exponen en la estructura AutomationElement.AutomationElementInformation.

Los patrones de control también tienen propiedades. Las propiedades de los patrones de control son específicas de cada patrón. Por ejemplo, ScrollPattern tiene propiedades que permiten a una aplicación cliente detectar si una ventana se puede desplazar en sentido vertical u horizontal, y cuáles son los tamaños de vista y las posiciones de desplazamiento actuales. Los patrones de control exponen todas sus propiedades mediante una estructura; por ejemplo, ScrollPattern.ScrollPatternInformation.

Las propiedades de la UI Automation son de sólo lectura. Para establecer las propiedades de un control, debe utilizar los métodos del patrón de control adecuado. Por ejemplo, utilice Scroll para cambiar los valores de posición de una ventana desplazable.

Para mejorar el rendimiento, los valores de las propiedades de los controles y de los patrones de control se pueden almacenar en memoria caché al recuperar los objetos AutomationElement. Para obtener más información, vea Almacenar en caché en los clientes de automatización de la interfaz de usuario.

Este tema contiene las secciones siguientes.

• Identificadores de propiedad
• Condiciones de propiedad
• Recuperar propiedades
• Valores predeterminados de las propiedades
• Eventos modificados por propiedades
• Propiedades adicionales de AutomationElement
• Temas relacionados

Identificadores de propiedad

Los identifiers (IDs) de propiedad son valores constantes únicos que se encapsulan en objetos AutomationProperty. Las aplicaciones cliente de Automatización de la interfaz de usuario obtienen estos IDs de la clase AutomationElement o de la clase de patrón de control correspondiente, como ScrollPattern. Los proveedores de Automatización de la interfaz de usuario los obtienen de AutomationElementIdentifiers o de una de las clases de identificadores de los patrones de control, como ScrollPatternIdentifiers.

Los proveedores utilizan el Id numérico de AutomationProperty para identificar las propiedades consultadas en el método IRawElementProviderSimple.GetPropertyValue. En general, las aplicaciones cliente no necesitan examinar el Id. La propiedad ProgrammaticName sólo se utiliza con fines de depuración y diagnóstico.

Condiciones de propiedad

Los IDs de propiedad se utilizan para la construcción de objetos PropertyCondition utilizados para buscar objetos AutomationElement. Por ejemplo, puede ser conveniente buscar un objeto AutomationElement con un nombre determinado o todos los controles que estén habilitados. Cada objeto PropertyCondition especifica un identificador de AutomationProperty y el valor con el que la propiedad debe coincidir.

Para obtener más información, vea los temas de referencia siguientes:

• FindFirst

• FindAll

• Condition

Recuperar propiedades

Algunas propiedades de AutomationElement y todas las propiedades de una clase de patrón de control se exponen como propiedades anidadas de la propiedad Current o Cached de AutomationElement o de un objeto de patrón de control.

Además, cualquier propiedad de AutomationElement o de un patrón de control, incluidas las propiedades que no estén disponibles en la estructura de Cached o Current, se puede recuperar utilizando uno de los métodos siguientes:

• GetCachedPropertyValue

• GetCurrentPropertyValue

Estos métodos proporcionan un rendimiento ligeramente mejor, así como acceso a todas las propiedades.

En el código de ejemplo siguiente se muestran las dos maneras de recuperar una propiedad de AutomationElement.

' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))

// elementList is an AutomationElement.

// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;

Para recuperar propiedades de los patrones de control admitidos por AutomationElement, no es necesario recuperar el objeto de patrón de control. Basta con pasar al método uno de los identificadores de propiedad del patrón.

En el código de ejemplo siguiente se muestran las dos maneras de recuperar una propiedad de un patrón de control.

' elementList is an AutomationElement representing a list box.
' Error-checking is omitted. Assume that elementList is known to support SelectionPattern.
Dim selectPattern As SelectionPattern = _
    DirectCast(elementList.GetCurrentPattern(SelectionPattern.Pattern), SelectionPattern)
Dim isMultipleSelect As Boolean = selectPattern.Current.CanSelectMultiple

' The following call is equivalent to the one above.
isMultipleSelect = CBool(elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty))

// elementList is an AutomationElement representing a list box.
// Error-checking is omitted. Assume that elementList is known to support SelectionPattern.

SelectionPattern selectPattern =
    elementList.GetCurrentPattern(SelectionPattern.Pattern) as SelectionPattern;
bool isMultipleSelect = selectPattern.Current.CanSelectMultiple;

// The following call is equivalent to the one above.
isMultipleSelect = (bool)
    elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty);

Los métodos Get devuelven un elemento Object. La aplicación debe convertir el objeto devuelto al tipo apropiado antes de utilizar el valor.

Valores predeterminados de las propiedades

Si un proveedor de Automatización de la interfaz de usuario no implementa una propiedad, el sistema de UI Automation puede proporcionar un valor predeterminado. Por ejemplo, si el proveedor de un control no admite la propiedad identificada por HelpTextProperty, la UI Automation devuelve una cadena vacía. De manera similar, si el proveedor no admite la propiedad identificada por IsDockPatternAvailableProperty, la UI Automation devuelve false.

Puede cambiar este comportamiento mediante las sobrecargas de los métodos AutomationElement.GetCachedPropertyValue y AutomationElement.GetCurrentPropertyValue. Cuando se especifica true como segundo parámetro, la UI Automation no devuelve un valor predeterminado, sino el valor especial NotSupported.

En el ejemplo de código siguiente se intenta recuperar una propiedad de un elemento y, si no se admite la propiedad, en su lugar se utiliza un valor definido por la aplicación.

' elementList is an AutomationElement.
Dim help As Object = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, True)
If help Is AutomationElement.NotSupported Then
    help = "No help available"
End If
Dim helpText As String = CStr(help)

// elementList is an AutomationElement.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
    help = "No help available";
}
string helpText = (string)help;

Para saber qué propiedades admite un elemento, utilice GetSupportedProperties. Devuelve una matriz de identificadores de AutomationProperty.

Eventos modificados por propiedades

Cuando cambia un valor de propiedad de AutomationElement o de un patrón de control, se provoca un evento. Una aplicación puede suscribirse a estos eventos mediante una llamada a AddAutomationPropertyChangedEventHandler, al que debe proporcionar una matriz de identificadores AutomationProperty como último parámetro a fin de especificar las propiedades de interés.

En AutomationPropertyChangedEventHandler, puede identificarse la propiedad que ha cambiado comprobando el miembro Property de los argumentos de evento. Los argumentos también contienen los valores anteriores y nuevos de la propiedad de UI Automation que ha cambiado. Estos valores son del tipo Object y se convierten al tipo correcto antes de utilizarse.

Propiedades adicionales de AutomationElement

Además de las estructuras de las propiedades Current y Cached, AutomationElement tiene las propiedades siguientes, que se recuperan mediante descriptores de acceso de propiedad simples.

Propiedad	Descripción
CachedChildren	Colección de objetos AutomationElement secundarios que se encuentran en la memoria caché.
CachedParent	Objeto primario AutomationElement que se encuentra en la caché.
FocusedElement	(Propiedad estática) AutomationElement que tiene el foco de entrada.
RootElement	(Propiedad estática) AutomationElement raíz.

Vea también

Tareas

Suscribirse a eventos de UI Automation

Conceptos

Almacenar en caché en los clientes de automatización de la interfaz de usuario

Implementación del proveedor de UI Automation en el servidor