Propriedades de automação da interface do usuário para clientes

Observação

Esta documentação destina-se a desenvolvedores do .NET Framework que desejam usar as classes de Automação de Interface do Usuário gerenciadas definidas no namespace System.Windows.Automation. Para obter as informações mais recentes sobre Automação de Interface do Usuário, consulte API de Automação do Windows: Automação de Interface do Usuário.

Essa visão geral apresenta as propriedades da Automação da Interface do Usuário à medida que elas são expostas a aplicativos cliente de Automação de Interface do Usuário.

As propriedades em AutomationElement objetos contêm informações sobre elementos de interface do usuário, geralmente controles. As propriedades de um AutomationElement são genéricas; ou seja, não são específicas para um tipo de controle. Muitas dessas propriedades são expostas na AutomationElement.AutomationElementInformation estrutura.

Os padrões de controle também têm propriedades. As propriedades dos padrões de controle são específicas para o 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 e as posições de rolagem atuais. 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 propriedades de um controle, você deve usar 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 AutomationElement os objetos são recuperados. Para obter mais informações, consulte Cacheamento em clientes de automação da interface do usuário.

IDs de propriedade

IDs (identificadores de propriedade) são valores constantes exclusivos que são encapsulados em AutomationProperty objetos. Os aplicativos cliente de Automação da Interface do Usuário obtêm essas IDs da AutomationElement classe ou da classe de 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 número Id 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 de propriedade

As IDs de propriedade são usadas na construção de PropertyCondition objetos usados para localizar AutomationElement objetos. Por exemplo, talvez você queira encontrar um AutomationElement que tenha um determinado nome ou todos os controles habilitados. Cada PropertyCondition especifica um AutomationProperty identificador e o valor que a propriedade deve atender.

Para obter mais informações, consulte os seguintes tópicos de referência:

• FindFirst

• FindAll

• Condition

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 propriedade de controle ou padrão, incluindo uma propriedade que não está disponível na estrutura AutomationElement ou Cached, pode ser recuperada usando um dos seguintes métodos:

• GetCachedPropertyValue

• GetCurrentPropertyValue

Esses métodos oferecem um desempenho ligeiramente melhor, bem como acesso à gama completa 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 o 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 Get métodos retornam um Object. O aplicativo deve converter o objeto retornado para o tipo adequado antes de usar o valor.

Valores de propriedade padrão

Se um provedor de Automação de 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 der suporte à propriedade identificada por HelpTextProperty, a Automação da Interface do Usuário retorna uma string vazia. Da mesma forma, se o provedor não der suporte à propriedade identificada por IsDockPatternAvailableProperty, a Automação da Interface do Usuário retornará false.

Você pode alterar esse comportamento usando as sobrecargas do 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 NotSupportedespecial.

O código de exemplo a seguir tenta recuperar uma propriedade de um elemento e, se a propriedade não tiver suporte, 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 têm suporte por um elemento, use GetSupportedProperties. Isso retorna uma matriz de AutomationProperty identificadores.

Eventos alterados por propriedade

Quando um valor de propriedade em um AutomationElement ou padrão de controle é alterado, um evento é gerado. Um aplicativo pode assinar esses eventos chamando AddAutomationPropertyChangedEventHandler, fornecendo uma matriz de AutomationProperty identificadores como o último parâmetro para especificar as propriedades de interesse.

No AutomationPropertyChangedEventHandler, você pode identificar a propriedade que foi alterada verificando o membro Property dos argumentos do evento. Os argumentos também contêm os valores antigos e novos da propriedade de 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 adicionais de AutomationElement

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.

Consulte também

• Armazenar em cache em clientes de automação de interface do usuário
• Implementação do provedor de automação da interface do usuárioServer-Side
• Assinar eventos de automação da interface do usuário