Metodo IUIAutomationElement::FindFirst (uiautomationclient.h)

Articolo
08/08/2024

Recupera il primo elemento figlio o discendente che corrisponde alla condizione specificata.

Sintassi

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

Parametri

[in] scope

Tipo: TreeScope

Combinazione di valori che specificano l'ambito della ricerca.

[in] condition

Tipo: IUIAutomationCondition*

Puntatore a una condizione che rappresenta i criteri da trovare.

[out, retval] found

Tipo: IUIAutomationElement**

Riceve un puntatore all'elemento . NULL viene restituito se non viene trovato alcun elemento corrispondente.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT.

Osservazioni

L'ambito della ricerca è relativo all'elemento in cui viene chiamato il metodo . Gli elementi vengono restituiti nell'ordine in cui sono stati rilevati nell'albero.

Questa funzione non può cercare elementi predecessori nell'albero di Automazione interfaccia utente Microsoft; ovvero, TreeScope_Ancestors non è un valore valido per il parametro ambito .

Quando si cercano finestre di primo livello sul desktop, assicurarsi di specificare TreeScope_Children nel parametro ambito , non TreeScope_Descendants. Una ricerca nell'intero sottoalbero del desktop potrebbe scorrere migliaia di elementi e causare un overflow dello stack.

Se l'applicazione client potrebbe provare a trovare elementi nella propria interfaccia utente, è necessario effettuare tutte le chiamate di automazione interfaccia utente in un thread separato.

Questa funzione ignora gli elementi nell'albero non elaborato. Chiamare FindFirstBuildCache per eseguire la ricerca nell'albero non elaborato specificando il TreeScope appropriato nel IUIAutomationCacheRequest passato a tale funzione.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 7, Windows Vista con SP2 e Aggiornamento della piattaforma per Windows Vista, Windows XP con SP3 e Aggiornamento della piattaforma per Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2008 R2, Windows Server 2008 con SP2 e Aggiornamento della piattaforma per Windows Server 2008, Windows Server 2003 con SP2 e Aggiornamento della piattaforma per Windows Server 2008 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	uiautomationclient.h (include UIAutomation.h)