UI Automation Properties for Clients
Observação
Esta documentação destina.Os desenvolvedores do NET Framework que desejam usar o gerenciado UI Automation classes definidas na System.Windows.Automation namespace.As informações mais recentes sobre UI Automation, consulte API de automação do Windows: Automação da interface do usuário.
This overview introduces you to UI Automation properties as they are exposed to UI Automation client applications.
Properties on AutomationElement objects contain information about user interface (UI) elements, usually controls. As propriedades de um AutomationElement são genéricos; ou seja, não é específico para um tipo de controle. Many of these properties are exposed in the AutomationElement.AutomationElementInformation structure.
Control patterns also have properties. The properties of control patterns are specific to the pattern. For example, ScrollPattern has properties that enable a client application to discover whether a window is vertically or horizontally scrollable, and what the current view sizes and scroll positions are. Control patterns expose all their properties through a structure; for example, ScrollPattern.ScrollPatternInformation.
UI Automation properties are read-only. To set properties of a control, you must use the methods of the appropriate control pattern. For example, use Scroll to change the position values of a scrolling window.
To improve performance, property values of controls and control patterns can be cached when AutomationElement objects are retrieved. For more information, see Cache em clientes de automação de interface do usuário.
Este tópico contém as seguintes seções.
- Property IDs
- Property Conditions
- Retrieving Properties
- Default Property Values
- Property-changed Events
- Additional AutomationElement Properties
- Tópicos relacionados
Property IDs
Property identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. UI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as ScrollPattern. Provedores de automação da interface do usuário obtê-los a partir de AutomationElementIdentifiers ou de um controle padrão de classes de identificadores, como ScrollPatternIdentifiers.
The numeric Id of an AutomationProperty is used by providers to identify properties that are being queried for in the IRawElementProviderSimple.GetPropertyValue method. In general, client applications do not need to examine the Id. The ProgrammaticName is used only for debugging and diagnostic purposes.
Property Conditions
The property IDs are used in constructing PropertyCondition objects used to find AutomationElement objects. Por exemplo, talvez você queira localizar um AutomationElement que tem um nome de alguns ou todos os controles que são habilitados. Cada PropertyCondition Especifica um AutomationProperty identificador e o valor que a propriedade deve coincidir.
For more information, see the following reference topics:
Retrieving Properties
Some properties of AutomationElement and all properties of a control pattern class are exposed as nested properties of the Current or Cached property of the AutomationElement or control pattern object.
In addition, any AutomationElement or control pattern property, including a property that is not available in the Cached or Current structure, can be retrieved by using one of the following methods:
These methods offer slightly better performance as well as access to the full range of properties.
The following code example shows the two ways of retrieving a property on an 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;
To retrieve properties of control patterns supported by the AutomationElement, you do not need to retrieve the control pattern object. Simply pass one of the pattern property identifiers to the method.
The following code example shows the two ways of retrieving a property on a control pattern.
' 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);
The Get methods return an Object. The application must cast the returned object to the proper type before using the value.
Default Property Values
If a UI Automation provider does not implement a property, the UI Automation system is able to supply a default value. Por exemplo, se o provedor para um controle não oferece suporte à propriedade identificada por HelpTextProperty, UI Automation retorna uma seqüência vazia. Da mesma forma, se o provedor não oferece suporte a propriedade identificada por IsDockPatternAvailableProperty, UI Automation retorna false.
You can change this behavior by using the AutomationElement.GetCachedPropertyValue and AutomationElement.GetCurrentPropertyValue method overloads. When you specify true as the second parameter, UI Automation does not return a default value, but instead returns the special value NotSupported.
The following example code attempts to retrieve a property from an element, and if the property is not supported, an application-defined value is used instead.
' 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;
To discover what properties are supported by an element, use GetSupportedProperties. This returns an array of AutomationProperty identifiers.
Property-changed Events
When a property value on an AutomationElement or control pattern changes, an event is raised. An application can subscribe to such events by calling AddAutomationPropertyChangedEventHandler, supplying an array of AutomationProperty identifiers as the last parameter in order to specify the properties of interest.
In the AutomationPropertyChangedEventHandler, you can identify the property that has changed by checking the Property member of the event arguments. The arguments also contain the old and new values of the UI Automation property that has changed. These values are of type Object and must be cast to the correct type before being used.
Additional AutomationElement Properties
In addition to the Current and Cached property structures, AutomationElement has the following properties, which are retrieved through simple property accessors.
Property |
Description |
|---|---|
A collection of child AutomationElement objects that are in the cache. |
|
An AutomationElement parent object that is in the cache. |
|
(Static property) The AutomationElement that has the input focus. |
|
(Static property) The root AutomationElement. |
Consulte também
Tarefas
Registre-se em Eventos de Automação de Interface do Usuário