Condividi tramite

Implementazione del provider Server-Side di automazione dell'interfaccia utente

Annotazioni

Questa documentazione è destinata agli sviluppatori .NET Framework che vogliono usare le classi di automazione interfaccia utente gestite definite nello spazio dei nomi System.Windows.Automation. Per informazioni aggiornate su Automazione interfaccia utente, vedere API di automazione di Windows: Automazione interfaccia utente.

Questa sezione descrive come implementare un provider di automazione interfaccia utente lato server per un controllo personalizzato.

L'implementazione per gli elementi di Windows Presentation Foundation (WPF) e gli elementi non WPF (ad esempio quelli progettati per Windows Form) è fondamentalmente diversa. Gli elementi WPF forniscono il supporto per l'automazione interfaccia utente tramite una classe derivata da AutomationPeer. Gli elementi non WPF forniscono supporto tramite implementazioni di interfacce del provider.

Considerazioni sulla sicurezza

I provider devono essere scritti in modo che possano funzionare in un ambiente a fiducia parziale. Poiché UIAutomationClient.dll non è configurato per l'esecuzione con attendibilità parziale, il codice del provider non deve fare riferimento a tale assembly. Se ciò accade, il codice può essere eseguito in un ambiente con piena fiducia, ma fallire in un ambiente a fiducia parziale.

In particolare, non usare i campi delle classi in UIAutomationClient.dll, ad esempio quelli in AutomationElement. Usare invece i campi equivalenti delle classi in UIAutomationTypes.dll, ad esempio AutomationElementIdentifiers.

Implementazione del provider da elementi di Windows Presentation Foundation

Per altre informazioni su questo argomento, vedere Automazione interfaccia utente di un controllo personalizzato WPF.

Implementazione del provider da elementi non WPF

I controlli personalizzati che non fanno parte del framework WPF, ma che vengono scritti in codice gestito (più spesso si tratta di controlli Windows Form), forniscono il supporto per l'automazione interfaccia utente implementando le interfacce. Ogni elemento deve implementare almeno una delle interfacce elencate nella prima tabella della sezione successiva. Inoltre, se l'elemento supporta uno o più pattern di controllo, deve implementare l'interfaccia appropriata per ogni pattern di controllo.

Il progetto del provider di automazione interfaccia utente deve fare riferimento agli assembly seguenti:

  • UIAutomationProviders.dll

  • UIAutomationTypes.dll

  • WindowsBase.dll

Interfacce fornitore

Ogni provider di automazione interfaccia utente deve implementare una delle interfacce seguenti.

Interfaccia Descrizione
IRawElementProviderSimple Fornisce funzionalità per un controllo semplice ospitato in una finestra, incluso il supporto per i pattern di controllo e le proprietà.
IRawElementProviderFragment Eredita da IRawElementProviderSimple. Aggiunge caratteristiche per un elemento in un controllo complesso, tra cui la navigazione all'interno del frammento, l'impostazione dello stato attivo e la restituzione del rettangolo di delimitazione dell'elemento.
IRawElementProviderFragmentRoot Eredita da IRawElementProviderFragment. Aggiunge funzionalità per l'elemento radice in un controllo complesso, inclusa l'individuazione di un elemento figlio in corrispondenza delle coordinate specificate e l'impostazione dello stato attivo per l'intero controllo.

Le interfacce seguenti forniscono funzionalità aggiunte, ma non devono essere implementate.

Interfaccia Descrizione
IRawElementProviderAdviseEvents Consente al provider di tenere traccia delle richieste di eventi.
IRawElementProviderHwndOverride Abilita il riposizionamento degli elementi basati su finestra all'interno dell'albero di automazione interfaccia utente di un frammento.

Tutte le altre interfacce nello System.Windows.Automation.Provider spazio dei nomi sono destinate al supporto del modello di controllo.

Requisiti per i provider non WPF

Per comunicare con l'automazione interfaccia utente, il controllo deve implementare le seguenti aree principali di funzionalità:

Funzionalità Implementation
Esporre il provider all'Automazione dell'interfaccia utente In risposta a un messaggio di WM_GETOBJECT inviato alla finestra di controllo, restituire l'oggetto che implementa IRawElementProviderSimple (o un'interfaccia derivata). Per i frammenti, questo deve essere il provider della radice del frammento.
Specificare i valori delle proprietà Implementare GetPropertyValue per fornire o eseguire l'override dei valori.
Abilitare il client per interagire con il controllo Implementare interfacce che supportano modelli di controllo, ad esempio IInvokeProvider. Restituisci questi pattern provider nell'implementazione di GetPatternProvider.
Generare eventi Chiamare uno dei metodi statici di AutomationInteropProvider per attivare un evento a cui un client può ascoltare.
Abilitare la navigazione e concentrarsi all'interno di un frammento Implementare IRawElementProviderFragment per ogni elemento all'interno del frammento. Non necessario per gli elementi che non fanno parte di un frammento.
Abilitare la messa a fuoco e la posizione dell'elemento figlio in un frammento Implementare IRawElementProviderFragmentRoot. Non necessario per gli elementi che non sono radici frammentarie.

Valori delle proprietà nei provider non WPF

I provider di automazione interfaccia utente per i controlli personalizzati devono supportare determinate proprietà che possono essere usate dal sistema di automazione e dalle applicazioni client. Per gli elementi ospitati in finestre (HWND), Automazione interfaccia utente può recuperare alcune proprietà dal provider di finestre predefinito, ma deve ottenere altri dal provider personalizzato.

I provider per i controlli basati su HWND non devono in genere fornire le proprietà seguenti (identificate dai valori dei campi):

Annotazioni

L'oggetto RuntimeIdProperty di una radice di elemento o frammento semplice ospitato in una finestra viene ottenuto dalla finestra. Tuttavia, gli elementi frammento sotto la radice (ad esempio gli elementi di elenco in una casella di riepilogo) devono fornire i propri identificatori. Per altre informazioni, vedere GetRuntimeId.

Deve IsKeyboardFocusableProperty essere restituito per i provider ospitati in un controllo Windows Forms. In questo caso, il provider di finestre predefinito potrebbe non essere in grado di recuperare il valore corretto.

L'oggetto NameProperty viene in genere fornito dal provider host. Ad esempio, se un controllo personalizzato è derivato da Control, il nome viene derivato dalla Text proprietà del controllo .

Per un esempio di codice, vedere Restituire proprietà da un provider di automazione dell'interfaccia utente.

Eventi nei provider non WPF

I provider di automazione interfaccia utente devono generare eventi per notificare alle applicazioni client modifiche nello stato dell'interfaccia utente. Per generare eventi vengono usati i metodi seguenti.

metodo Descrizione
RaiseAutomationEvent Genera vari eventi, inclusi gli eventi attivati dai pattern di controllo.
RaiseAutomationPropertyChangedEvent Genera un evento quando viene modificata una proprietà di automazione interfaccia utente.
RaiseStructureChangedEvent Genera un evento quando la struttura dell'albero di automazione interfaccia utente è cambiata; ad esempio, mediante la rimozione o l'aggiunta di un elemento.

Lo scopo di un evento è notificare al client un evento che si verifica nell'interfaccia utente, indipendentemente dal fatto che l'attività venga attivata dal sistema di automazione interfaccia utente stesso. Ad esempio, l'evento identificato da InvokedEvent deve essere generato ogni volta che viene richiamato il controllo, tramite input utente diretto o dall'applicazione client che chiama Invoke.

Per ottimizzare le prestazioni, un provider può generare eventi in modo selettivo o non generare alcun evento se nessuna applicazione client è registrata per riceverli. Per l'ottimizzazione vengono usati i metodi seguenti.

metodo Descrizione
ClientsAreListening Questa proprietà statica specifica se le applicazioni client hanno sottoscritto eventi di automazione interfaccia utente.
IRawElementProviderAdviseEvents L'implementazione di questa interfaccia da parte del provider su una radice di frammento consente di essere notificato quando i clienti registrano e annullano la registrazione dei gestori di eventi relativi agli eventi sul frammento.

Navigazione tra provider non WPF

I provider per controlli semplici, ad esempio un pulsante personalizzato ospitato in una finestra (HWND) non devono supportare lo spostamento all'interno dell'albero di automazione interfaccia utente. La navigazione da e verso l'elemento viene gestita dal provider predefinito per la finestra host, specificata nell'implementazione di HostRawElementProvider. Quando si implementa un provider per un controllo personalizzato complesso, tuttavia, è necessario supportare lo spostamento tra il nodo radice del frammento e i relativi discendenti e tra nodi di pari livello.

Annotazioni

Gli elementi di un frammento diverso dalla radice devono restituire un null riferimento da HostRawElementProvider, perché non sono ospitati direttamente in una finestra e nessun provider predefinito può supportare la navigazione da e verso di essi.

La struttura del frammento è determinata dall'implementazione di Navigate. Per ogni direzione possibile da ogni frammento, questo metodo restituisce l'oggetto provider per l'elemento in tale direzione. Se non è presente alcun elemento in tale direzione, il metodo restituisce un null riferimento.

La radice del frammento supporta la navigazione solo agli elementi figli. Ad esempio, una casella di riepilogo restituisce il primo elemento dell'elenco quando la direzione è FirstChilde l'ultimo elemento quando la direzione è LastChild. La radice del frammento non supporta la navigazione a un elemento padre o a elementi fratelli; questo è gestito dal provider della finestra host.

Gli elementi di un frammento che non sono la radice devono supportare la navigazione all'elemento padre, agli elementi fratelli e a qualsiasi elemento figlio di cui dispongono.

Reparenting del provider non WPF

Le finestre popup sono in realtà finestre di primo livello, quindi per impostazione predefinita vengono visualizzate nell'albero di automazione interfaccia utente come elementi figlio del desktop. In molti casi, tuttavia, le finestre popup sono elementi figli logici di un altro controllo. Ad esempio, l'elenco a discesa di una casella combinata è logicamente un sottoelemento della casella combinata. Analogamente, una finestra a comparsa del menu è logicamente un elemento figlio del menu. L'automazione dell'interfaccia utente fornisce supporto per riparentare le finestre popup in modo che appaiano come figli al controllo associato.

Per riassegnare una finestra popup:

  1. Creare un fornitore per la finestra popup. Ciò richiede che la classe della finestra popup sia nota in anticipo.

  2. Implementare tutte le proprietà e i modelli come di consueto per tale popup, come se fosse un controllo a sé stante.

  3. Implementare la HostRawElementProvider proprietà in modo che restituisca il valore ottenuto da HostProviderFromHandle, dove il parametro è l'handle di finestra della finestra popup.

  4. Implementare Navigate per la finestra popup e il relativo elemento padre in modo che lo spostamento venga gestito correttamente dall'elemento padre logico agli elementi figlio logici e tra elementi figlio di pari livello.

Quando UI Automation rileva la finestra popup, riconosce che lo spostamento viene sovrascritto rispetto all'impostazione predefinita e ignora la finestra popup quando è rilevata come figlia del desktop. Il nodo sarà invece raggiungibile solo tramite il frammento.

Il reparenting non è adatto per i casi in cui un controllo può ospitare una finestra di qualsiasi classe. Ad esempio, una barra degli strumenti può ospitare qualsiasi tipo di HWND nelle sue sezioni. Per gestire questi casi, l'Automazione UI supporta una forma alternativa di ricollocazione di HWND, come descritto nella sezione successiva.

Riposizionamento del provider non WPF

I frammenti di automazione interfaccia utente possono contenere due o più elementi contenuti in una finestra (HWND). Poiché ogni HWND ha un proprio provider predefinito che considera ciascun HWND come un figlio di un HWND che lo contiene, l'albero dell'Automazione UI mostrerà, per impostazione predefinita, gli HWND nella sezione come figli della finestra padre. Nella maggior parte dei casi questo comportamento è auspicabile, ma a volte può causare confusione perché non corrisponde alla struttura logica dell'interfaccia utente.

Un buon esempio di questo è un sistema di controllo per barre d'armatura. Una barra di rinforzo contiene bande, ognuna delle quali può a sua volta contenere un controllo basato su HWND, come ad esempio una barra degli strumenti, una casella di modifica o una casella combinata. Il provider di finestre predefinito per il controllo rebar HWND vede i HWND del controllo banda come elementi figlio e il provider rebar vede le bande come elementi figlio. Poiché il provider HWND e il provider della barra multifunzione lavorano insieme e combinano i relativi elementi figlio, sia le bande che i controlli basati su HWND vengono visualizzati come elementi figlio della barra multifunzione. Logicamente, tuttavia, solo le bande dovrebbero apparire come elementi figlio della barra degli strumenti e ogni fornitore di bande deve essere associato al provider HWND predefinito per il controllo che contiene.

A tale scopo, il provider radice del frammento per la barra degli strumenti espone un set di elementi figli che rappresentano le bande. Ogni banda ha un singolo provider che può esporre proprietà e modelli. Nell'implementazione di HostRawElementProvider, il provider di banda restituisce il provider di finestre predefinito per il controllo HWND, che si ottiene chiamando HostProviderFromHandle, passando l'handle della finestra del controllo. Infine, il provider radice del frammento per il rebar implementa l'interfaccia IRawElementProviderHwndOverride e, nella sua implementazione di GetOverrideProviderForHwnd, ritorna il provider di banda appropriato per il controllo contenuto nell'oggetto HWND specificato.

Vedere anche

  • Last updated on