Método IUIAutomationElement::FindFirst (uiautomationclient.h)

Artigo
08/08/2024

Recupera o primeiro elemento filho ou descendente que corresponde à condição especificada.

Sintaxe

HRESULT FindFirst(
  [in]          TreeScope              scope,
  [in]          IUIAutomationCondition *condition,
  [out, retval] IUIAutomationElement   **found
);

Parâmetros

[in] scope

Tipo: TreeScope

Uma combinação de valores que especificam o escopo da pesquisa.

[in] condition

Tipo: * IUIAutomationCondition

Um ponteiro para uma condição que representa os critérios a serem correspondidos.

[out, retval] found

Tipo: ** IUIAutomationElement

Recebe um ponteiro para o elemento. NULL será retornado se nenhum elemento correspondente for encontrado.

Valor de retorno

Tipo: HRESULT

Se esse método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Observações

O escopo da pesquisa é relativo ao elemento no qual o método é chamado. Os elementos são retornados na ordem em que foram encontrados na árvore.

Essa função não pode procurar elementos ancestrais na árvore de Automação da Interface do Usuário da Microsoft; ou seja, TreeScope_Ancestors não é um valor válido para o parâmetro de escopo .

Ao pesquisar janelas de nível superior na área de trabalho, especifique TreeScope_Children no escopo parâmetro, não TreeScope_Descendants. Uma pesquisa por toda a subárvore da área de trabalho poderia iterar por meio de milhares de itens e levar a um estouro de pilha.

Se o aplicativo cliente tentar encontrar elementos em sua própria interface do usuário, você deverá fazer todas as chamadas de Automação da Interface do Usuário em um thread separado.

Essa função ignora os elementos na árvore bruta. Chame FindFirstBuildCache para pesquisar a árvore bruta especificando o TreeScope apropriado no IUIAutomationCacheRequest passado para essa função.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 7, Windows Vista com SP2 e Platform Update para Windows Vista, Windows XP com SP3 e Platform Update para Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 R2, Windows Server 2008 com SP2 e Platform Update para Windows Server 2008, Windows Server 2003 com SP2 e Platform Update para Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	uiautomationclient.h (include UIAutomation.h)