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 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 de utilizador, consulte API de automação do Windows: Automação da Interface de Utilizador.

Esta visão geral apresenta as propriedades da Automação da Interface de Utilizador como são apresentadas aos aplicativos cliente da Automação da Interface de Utilizador.

As propriedades em AutomationElement objetos contêm informações sobre elementos da interface do usuário (UI), geralmente controles. As propriedades de um AutomationElement são genéricas, ou seja, não específicas de um tipo de controle. Muitas dessas propriedades estã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 pode ser rolada vertical ou horizontalmente e quais são os tamanhos de exibição e as posições de rolagem atuais. Os padrões de controlo expõem todas as suas propriedades através de uma estrutura; por exemplo, ScrollPattern.ScrollPatternInformation.

As propriedades de Automação de UI 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 Caching in UI Automation Clients.

Identificadores de propriedade

Os identificadores de propriedade (IDs) 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 obtêm-nos de AutomationElementIdentifiers ou de uma das classes de identificadores de padrão de controle, como ScrollPatternIdentifiers.

O valor numérico Id de um AutomationProperty é utilizado por fornecedores para identificar propriedades que estão a ser 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 do Imóvel

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

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 controlo são expostas como propriedades aninhadas da propriedade Current ou Cached do objeto de AutomationElement ou de padrão de controlo.

Além disso, qualquer propriedade ou padrão de controle AutomationElement, incluindo uma propriedade que não está disponível na Cached ou na Current estrutura, pode ser recuperada usando um dos seguintes métodos:

• GetCachedPropertyValue

• GetCurrentPropertyValue

Estes 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 AutomationElementarquivo .

// 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 dos padrões de controle suportados pelo AutomationElement, não é necessário recuperar o objeto do padrão de controle. Basta passar um dos identificadores da propriedade de 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 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 pelo HelpTextProperty, a Automação da Interface do Usuário retornará uma cadeia de caracteres vazia. Da mesma forma, se o provedor não oferecer suporte à propriedade identificada pelo 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 NotSupportedespecial.

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

Eventos de alteração de propriedade

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

AutomationPropertyChangedEventHandlerNo , você pode identificar a propriedade que foi alterada verificando o Property membro dos argumentos do evento. Os argumentos também contêm os valores antigos e novos da propriedade de Automação de Interface do Utilizador que foi alterada. Esses valores são do tipo Object e devem ser convertidos para o tipo correto antes de serem usados.

Propriedades adicionais de AutomationElement

Além das estruturas de Current e das propriedades de Cached, AutomationElement tem as seguintes propriedades, que são recuperadas através de simples acessores de propriedade.

Propriedade	Descrição
CachedChildren	Uma coleção de objetos filho AutomationElement que estão no cache.
CachedParent	Um AutomationElement objeto pai que está em cache.
FocusedElement	(Propriedade estática) O AutomationElement que tem o foco de entrada.
RootElement	(Propriedade estática) A raiz AutomationElement.

Ver também

• Caching em clientes de automação da interface do usuário
• Server-Side Implementação de Provedor de Automação de Interface do Usuário
• Inscrever-se em eventos de automação da interface do usuário