Obtendo elementos da automação interface do usuário

Este tópico descreve várias maneiras de obter interfaces IUIAutomationElement para elementos da interface do usuário.

O IUIAutomationElement é usado no aplicativo de exemplo de cliente de conteúdo de documento da Automação da Interface do Usuário.

Elemento Root

Embora os elementos possam ser recuperados diretamente usando métodos, como IUIAutomation::GetFocusedElement, alguns aplicativos cliente exigem uma exibição da estrutura hierárquica dos elementos, conhecida como árvore de Automação da IU. O elemento raiz dessa hierarquia é a área de trabalho. Você pode obter esse elemento usando o método IUIAutomation::GetRootElement ou o método IUIAutomation::GetRootElementBuildCache. Ambos os métodos recuperam um ponteiro da interface IUIAutomationElement. Você pode pesquisar elementos descendentes usando métodos, como IUIAutomationElement::FindFirst e FindAll.

Condições

Para a maioria das técnicas usadas para recuperar elementos de Automação da Interface do Usuário, você deverá especificar uma condição. Uma condição é um conjunto de critérios que define os elementos que você deseja recuperar. Uma condição é representada pela interface IUIAutomationCondition.

A condição mais simples é a condição verdadeira, que é um objeto predefinido que especifica que todos os elementos no escopo da pesquisa devem ser retornados. A condição false é o inverso da condição verdadeira e é menos útil, pois evitaria que quaisquer elementos fossem encontrados. Você pode obter uma interface para a condição verdadeira usando IUIAutomation::CreateTrueCondition.

Três outras condições predefinidas, disponíveis como propriedades no objeto IUIAutomation, podem ser usadas sozinhas ou em combinação com outras condições: IUIAutomation::ContentViewCondition, ControlViewCondition e RawViewCondition. RawViewCondition, usado por si só, é equivalente à condição verdadeira, pois não filtra elementos pelas propriedades IUIAutomationElement::CurrentIsControlElement ou CurrentIsContentElement..

Outras condições são criadas a partir de objetos de condição, cada um dos quais especifica um valor de propriedade. Por exemplo, uma condição de propriedade pode especificar que o elemento está habilitado ou que dá suporte a um determinado padrão de controle.

As condições que usam a lógica booliana podem ser combinadas chamando IUIAutomation::CreateAndCondition, CreateOrCondition, CreateNotCondition e métodos relacionados.

Escopo de pesquisa

Pesquisas executadas usando IUIAutomationElement::FindFirst ou FindAll devem ter um escopo e um ponto de partida.

O escopo define o espaço ao redor do ponto de partida que deve ser pesquisado. Isso pode incluir o próprio elemento, seus irmãos, seu pai, seus filhos imediatos e seus descendentes. Lembre-se de que os métodos Find não dão suporte à pesquisa na árvore de automação da IU da Microsoft, ou seja, não há suporte para a pesquisa de elementos ancestrais.

O escopo de uma pesquisa é definido por uma combinação bit a bit de valores do tipo enumerado TreeScope.

Localizando um elemento conhecido

Para localizar um elemento conhecido identificado por nome, ID de automação ou alguma outra propriedade ou combinação de propriedades, é mais fácil usar o método IUIAutomationElement::FindFirst. Se o elemento procurado for uma janela de aplicativo, o ponto de partida da pesquisa poderá ser o elemento raiz.

Essa forma de encontrar elementos Automação da Interface do Usuário é mais útil em cenários de teste automatizados.

Para obter um exemplo de código que mostra como encontrar um elemento conhecido, consulte Localizar um elemento por nome.

Localizando elementos em uma subárvore

Para localizar todos os elementos que atendam a critérios específicos e estejam relacionados a um elemento conhecido, você pode chamar IUIAutomationElement::FindAll no elemento conhecido. Por exemplo, use esse método para recuperar itens de lista ou itens de menu de uma lista ou menu ou para identificar todos os controles em uma caixa de diálogo.

Para obter um exemplo de código que mostra como encontrar elementos em uma subárvore, consulte Como localizar elementos relacionados.

Caminhando por uma subárvore

Se você não tiver conhecimento prévio dos aplicativos com os quais seu cliente pode ser usado, poderá construir uma subárvore de todos os elementos de interesse usando IUIAutomationTreeWalker. Seu cliente pode fazer isso, por exemplo, em resposta a um evento com foco alterado, ou seja, quando um aplicativo ou controle recebe o foco de entrada, o cliente de Automação da Interface do Usuário examina os filhos e talvez todos os descendentes do elemento em foco.

Lembre-se de que percorrer a árvore de automação da IU consome muitos recursos. Percorra a árvore somente quando não for viável usar os métodos IUIAutomationElement::FindFirst, FindAll ou BuildUpdatedCache.

Você pode definir seu próprio percorredor de árvore passando uma condição personalizada para IUIAutomation::CreateTreeWalker ou pode usar um dos seguintes objetos predefinidos que são definidos como propriedades da interface base IUIAutomation.

Depois de obter um IUIAutomationTreeWalker, chame os métodos IUIAutomationTreeWalker::GetXxx para percorrer os elementos da subárvore, passando o elemento pelo qual começar.

O método IUIAutomationTreeWalker::Normalize pode ser usado para navegar até um elemento na subárvore de outro elemento que não faz parte da exibição. Por exemplo, suponha que você crie uma exibição de uma subárvore usando IUIAutomation::ContentViewWalker. Seu aplicativo recebe uma notificação de que uma barra de rolagem recebeu o foco de entrada. Como uma barra de rolagem não é um elemento de conteúdo, ela não está presente na exibição da subárvore. No entanto, você pode passar o IUIAutomationElement que representa a barra de rolagem para IUIAutomationTreeWalker::Normalize e recuperar o ancestral mais próximo que está no modo de exibição de conteúdo.

Para obter exemplos de código que mostram como usar a interface IUIAutomationTreeWalker, consulte Como percorrer a árvore de automação da IU.

Outras maneiras de recuperar um elemento

Além de pesquisas e navegação, você pode recuperar um IUIAutomationElement das seguintes maneiras.

De um evento

Quando seu aplicativo recebe um evento de Automação da Interface do Usuário, o objeto de origem passado para o manipulador de eventos é representado por um IUIAutomationElement. Por exemplo, se você assinar eventos com alteração de foco, a origem passada para o IUIAutomationFocusChangedEventHandler será o elemento que recebeu o foco. Para obter mais informações, consulte Assinar eventos de Automação da Interface do Usuário.

De um ponto

Para recuperar um IUIAutomationElement de coordenadas de tela, por exemplo, uma posição de cursor, use o método IUIAutomation::ElementFromPoint.

De um identificador de janela

Para recuperar um IUIAutomationElement de um HWND, use o método IUIAutomation::ElementFromHandle.

No controle focalizado

Para recuperar um IUIAutomationElement que representa o controle focado, use o método IUIAutomation::GetFocusedElement.

Tópicos relacionados

Visão geral da árvore de automação de interface do usuário

Aplicativo de exemplo de cliente de conteúdo de documento da Automação da Interface do Usuário