Automação de Propriedades de Interface de Usuário para Clientes.
Observação
Esta documentação destina-se a desenvolvedores de .NET Framework que querem usar as classes da Automação da Interface do Usuário gerenciadas definidas no namespace System.Windows.Automation. Para obter as informações mais recentes sobre a Automação da Interface do Usuário, confira API de Automação do Windows: Automação da Interface do Usuário.
Esta visão geral apresenta as propriedades de Automação da Interface do Usuário, pois elas são expostas a aplicativos cliente de Automação da Interface do Usuário.
As propriedades nos objetos AutomationElement contêm informações sobre elementos da interface do usuário, geralmente controles. As propriedades de um AutomationElement são genéricas; ou seja, não são específicas de um tipo de controle. Muitas dessas propriedades são expostas na estrutura AutomationElement.AutomationElementInformation.
Os padrões de controle também têm propriedades. As propriedades dos padrões de controle são específicas do padrão. Por exemplo, ScrollPattern tem propriedades que permitem que um aplicativo cliente descubra se uma janela é vertical ou horizontalmente rolável e quais são os tamanhos de exibição atuais e as posições de rolagem. Os padrões de controle expõem todas as suas propriedades por meio de uma estrutura; por exemplo, ScrollPattern.ScrollPatternInformation.
As propriedades da Automação da Interface do Usuário são somente leitura. Para definir as propriedades de um controle, use os métodos do padrão de controle apropriado. Por exemplo, use Scroll para alterar os valores de posição de uma janela de rolagem.
Para melhorar o desempenho, os valores de propriedade de controles e padrões de controle podem ser armazenados em cache quando os objetos AutomationElement são recuperados. Para obter mais informações, confira Armazenando em cache em clientes de Automação da Interface do Usuário.
IDs de propriedade
Os identificadores (IDs) de propriedade são valores exclusivos e constantes encapsulados nos objetos AutomationProperty. Os aplicativos cliente da Automação da Interface do Usuário obtêm esses IDs da classe AutomationElement ou da classe do padrão de controle apropriada, como ScrollPattern. Os provedores de Automação da Interface do Usuário os obtêm de AutomationElementIdentifiers ou de uma das classes de identificadores de padrão de controle, como ScrollPatternIdentifiers.
O Id numérico de um AutomationProperty é usado pelos provedores para identificar as propriedades que estão sendo consultadas no método IRawElementProviderSimple.GetPropertyValue. Em geral, os aplicativos cliente não precisam examinar o Id. O ProgrammaticName é usado apenas para fins de depuração e diagnóstico.
Condições da propriedade
Os IDs de propriedade são usados na construção de objetos PropertyCondition para localizar objetos AutomationElement. Por exemplo, talvez você queira encontrar um AutomationElement que tenha um determinado nome ou todos os controles habilitados. Cada PropertyCondition especifica um identificador AutomationProperty e o valor que a propriedade deve corresponder.
Para obter mais informações, confira os seguintes tópicos de referência:
Recuperando propriedades
Algumas propriedades de AutomationElement e todas as propriedades de uma classe de padrão de controle são expostas como propriedades aninhadas da propriedade Current ou Cached do AutomationElement ou objeto padrão de controle.
Além disso, qualquer AutomationElement ou propriedade padrão de controle, incluindo uma propriedade não disponível na estrutura Cached ou Current, pode ser recuperada usando um dos seguintes métodos:
Esses métodos oferecem um desempenho ligeiramente melhor, bem como acesso a toda a gama de propriedades.
O exemplo de código a seguir mostra as duas maneiras de recuperar uma propriedade em um AutomationElement.
// elementList is an AutomationElement.
// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;
' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))
Para recuperar propriedades de padrões de controle compatíveis com AutomationElement, você não precisa recuperar o objeto de padrão de controle. Basta passar um dos identificadores de propriedade padrão para o método.
O exemplo de código a seguir mostra as duas maneiras de recuperar uma propriedade em um padrão de controle.
// 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);
' 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))
Os métodos Get retornam um Object. O aplicativo deve converter o objeto retornado ao tipo adequado antes de usar o valor.
Valores de propriedade padrão
Se um provedor de Automação da Interface do Usuário não implementar uma propriedade, o sistema de Automação da Interface do Usuário poderá fornecer um valor padrão. Por exemplo, se o provedor de um controle não oferecer suporte à propriedade identificada por HelpTextProperty, a Automação da Interface do Usuário retornará uma cadeia de caracteres vazia. Da mesma maneira, se o provedor não oferecer suporte à propriedade identificada por IsDockPatternAvailableProperty, a Automação da Interface do Usuário retornará false.
Você pode alterar esse comportamento usando as sobrecargas de método AutomationElement.GetCachedPropertyValue e AutomationElement.GetCurrentPropertyValue. Quando você especifica true como o segundo parâmetro, a Automação da Interface do Usuário não retorna um valor padrão, mas retorna o valor NotSupported especial.
O exemplo de código a seguir tenta recuperar uma propriedade de um elemento e, se a propriedade não for compatível, um valor definido pelo aplicativo será usado.
// elementList is an AutomationElement.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
help = "No help available";
}
string helpText = (string)help;
' 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)
Para descobrir quais propriedades são compatíveis com um elemento, use GetSupportedProperties. Isso retorna uma matriz de identificadores AutomationProperty.
Eventos alterados por propriedade
Quando um valor de propriedade em um AutomationElement ou padrão de controle é alterado, um evento é gerado. Um aplicativo pode se inscrever nesses eventos chamando AddAutomationPropertyChangedEventHandler, fornecendo uma matriz de identificadores AutomationProperty como o último parâmetro para especificar as propriedades de interesse.
No AutomationPropertyChangedEventHandler, você identifica a propriedade que mudou verificando o membro Property dos argumentos do evento. Os argumentos também contêm os valores antigos e novos da propriedade Automação da Interface do Usuário que foi alterada. Esses valores são do tipo Object e devem ser convertidos no tipo correto antes de serem usados.
Propriedades AutomationElement adicionais
Além das estruturas de propriedade Current e Cached, AutomationElement tem as propriedades a seguir, que são recuperadas por meio de acessadores de propriedade simples.
| Propriedade | Descrição |
|---|---|
| CachedChildren | Uma coleção de objetos filho AutomationElement que estão no cache. |
| CachedParent | Um objeto pai AutomationElement que está no cache. |
| FocusedElement | (Propriedade estática) O AutomationElement que tem o foco de entrada. |
| RootElement | (Propriedade estática) A raiz AutomationElement. |