Proprietà di automazione interfaccia utente per i client

Nota
La presente documentazione è destinata agli sviluppatori di .NET Framework che desiderano utilizzare le classi UI Automation gestite definite nello spazio dei nomi System.Windows.Automation.Per informazioni aggiornate sull'UI Automation, vedere Windows Automation API: Automazione interfaccia utente (la pagina potrebbe essere in inglese).

In questi cenni preliminari sono presentate le proprietà di UI Automation così come vengono esposte nelle applicazioni client di automazione interfaccia utente.

Le proprietà sugli oggetti AutomationElement contengono informazioni sugli elementi dell'user interface (UI), in genere i controlli. Le proprietà di un oggetto AutomationElement sono generiche, ovvero non sono specifiche di un tipo di controllo. Molte di queste proprietà sono esposte nella struttura AutomationElement.AutomationElementInformation.

Anche i pattern di controllo hanno proprietà. Le proprietà dei pattern di controllo sono specifiche del modello. Ad esempio, ScrollPattern dispone di proprietà che forniscono a un'applicazione client informazioni sulla possibilità di scorrere una finestra in senso verticale o orizzontale, sulle dimensioni correnti della visualizzazione e sulle posizioni di scorrimento. I pattern di controllo espongono tutte le proprietà tramite una struttura, ad esempio ScrollPattern.ScrollPatternInformation.

Le proprietà di UI Automation sono di sola lettura. Per impostare le proprietà di un controllo, è necessario utilizzare i metodi del pattern di controllo appropriato. Ad esempio, utilizzare il metodo Scroll per modificare i valori di posizione di una finestra a scorrimento.

Per migliorare le prestazioni, è possibile memorizzare nella cache i valori di proprietà di controlli e pattern di controllo quando vengono recuperati oggetti AutomationElement. Per ulteriori informazioni, vedere Memorizzazione nella cache dei client di automazione interfaccia utente.

Nel presente argomento sono contenute le seguenti sezioni.

• ID di proprietà
• Condizioni della proprietà
• Recupero di proprietà
• Valori di proprietà predefiniti
• Eventi modificati da proprietà
• Proprietà AutomationElement aggiuntiva
• Argomenti correlati

ID di proprietà

Gli identifiers (IDs) di proprietà sono valori univoci e costanti incapsulati in oggetti AutomationProperty. Le applicazioni client di automazione interfaccia utente ottengono questi IDs dalla classe AutomationElement o dalla classe di pattern di controllo appropriata, ad esempio ScrollPattern. I provider di automazione interfaccia utente li ottengono da AutomationElementIdentifiers o da una delle classi di identificatori di pattern di controllo, ad esempio ScrollPatternIdentifiers.

La proprietà Id numerica di un oggetto AutomationProperty viene utilizzata dai provider per identificare le proprietà sulle quali vengono eseguite query nel metodo IRawElementProviderSimple.GetPropertyValue. In genere, non è necessario che le applicazioni client esaminino la proprietà Id. La proprietà ProgrammaticName viene utilizzata solo a scopi di debug e diagnostica.

Condizioni della proprietà

Gli IDs di proprietà vengono utilizzati nella costruzione di oggetti PropertyCondition utilizzati per trovare oggetti AutomationElement. Ad esempio, può essere necessario trovare un oggetto AutomationElement con un determinato nome o tutti i controlli abilitati. Ogni PropertyCondition specifica un identificatore AutomationProperty e il valore a cui deve corrispondere la proprietà.

Per ulteriori informazioni, vedere gli argomenti di riferimento riportati di seguito:

• FindFirst

• FindAll

• Condition

Recupero di proprietà

Alcune proprietà di AutomationElement e tutte le proprietà di una classe di pattern di controllo sono esposte come proprietà annidate della proprietà Current o Cached dell'oggetto AutomationElement o dell'oggetto del pattern di controllo.

Inoltre, qualsiasi classe AutomationElement o proprietà del pattern di controllo, inclusa una proprietà non disponibile nella struttura Cached o Current, può essere recuperata utilizzando uno dei metodi seguenti:

• GetCachedPropertyValue

• GetCurrentPropertyValue

Questi metodi offrono prestazioni migliori oltre all'accesso alla gamma completa di proprietà.

Nell'esempio di codice seguente sono mostrate due modalità di recupero di una proprietà su una classe AutomationElement.

' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))

// elementList is an AutomationElement.

// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;

Per recuperare proprietà di pattern di controllo supportate dall'oggetto AutomationElement, non è necessario recuperare l'oggetto del pattern di controllo. È sufficiente passare al metodo uno degli identificatori di proprietà di modello.

Nell'esempio di codice seguente sono mostrate due modalità di recupero di una proprietà su un pattern di controllo.

' 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))

// 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);

I metodi Get restituiscono un oggetto Object. L'applicazione deve eseguire il cast dell'oggetto restituito al tipo corretto prima di utilizzare il valore.

Valori di proprietà predefiniti

Se un provider di automazione interfaccia utente non implementa una proprietà, il sistema di UI Automation è in grado di fornire un valore predefinito. Ad esempio, se il provider per un controllo non supporta la proprietà identificata da HelpTextProperty, UI Automation restituisce una stringa vuota. Analogamente, se il provider non supporta la proprietà identificata da IsDockPatternAvailableProperty, UI Automation restituisce false.

È possibile modificare questo comportamento utilizzando gli overload dei metodi AutomationElement.GetCachedPropertyValue e AutomationElement.GetCurrentPropertyValue. Quando si specifica true come secondo parametro, UI Automation non restituisce un valore predefinito, ma restituisce il valore speciale NotSupported.

Nel codice di esempio riportato di seguito si tenta di recuperare una proprietà da un elemento e, se la proprietà non è supportata, viene utilizzato in alternativa un valore definito dall'applicazione.

' 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)

// elementList is an AutomationElement.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
    help = "No help available";
}
string helpText = (string)help;

Per individuare le proprietà supportate da un elemento, utilizzare il metodo GetSupportedProperties. Restituisce una matrice di identificatori AutomationProperty.

Eventi modificati da proprietà

Quando viene modificato un valore di proprietà su un oggetto AutomationElement o un pattern di controllo, viene generato un evento. Un'applicazione può sottoscrivere tali eventi chiamando il metodo AddAutomationPropertyChangedEventHandler, fornendo una matrice di identificatori AutomationProperty come ultimo parametro per specificare le proprietà di interesse.

Nell'oggetto AutomationPropertyChangedEventHandler, è possibile identificare la proprietà modificata controllando il membro Property degli argomenti dell'evento. Gli argomenti contengono anche i valori obsoleti e nuovi della proprietà di UI Automation modificata. Questi valori sono di tipo Object ed è necessario eseguirne il cast al tipo corretto prima di utilizzarli.

Proprietà AutomationElement aggiuntiva

Oltre alle strutture delle proprietà Current e Cached, l'oggetto AutomationElement ha le proprietà seguenti, recuperate tramite semplici funzioni di accesso della proprietà.

Proprietà	Descrizione
CachedChildren	Insieme di oggetti AutomationElement figlio presenti nella cache.
CachedParent	Oggetto AutomationElement padre presente nella cache.
FocusedElement	(Proprietà statica) Oggetto AutomationElement con lo stato attivo per l'input.
RootElement	(Proprietà statica) Oggetto AutomationElement radice.

Vedere anche

Attività

Sottoscrivere gli eventi di automazione interfaccia utente

Concetti

Memorizzazione nella cache dei client di automazione interfaccia utente

Implementazione del provider di automazione interfaccia utente lato server