UI Automation Events Overview

Microsoft UI Automation event notification is a key feature for assistive technologies such as screen readers and screen magnifiers. These UI Automation clients track events that are raised by UI Automation providers when something happens in the UI and use the information to notify end users.

Efficiency is improved by allowing provider applications to raise events selectively, depending on whether any clients are subscribed to those events, or not at all, if no clients are listening for any events.

This topic contains the following sections.

  • Types of Events
  • UI Automation Event Identifiers
  • UI Automation Event Arguments
  • Related Topics

Types of Events

UI Automation events fall into the following categories.

Event Description

Property change

Raised when a property on an UI Automation element or control pattern changes. For example, if a client needs to monitor an application's check box control, it can register to listen for a property change event on the ToggleState property. When the check box control is checked or unchecked, the provider raises the event and the client can act as necessary.

Element action

Raised when a change in the UI results from end user or programmatic activity; for example, when a button is clicked or invoked through InvokePattern.

Structure change

Raised when the structure of the UI Automation tree changes. The structure changes when new UI items become visible, hidden, or removed on the desktop.

Global desktop change

Raised when actions of global interest to the client occur, such as when the focus shifts from one element to another, or when a window closes.

Some events do not necessarily mean that the state of the UI has changed. For example, if the user tabs to a text entry field and then clicks a button to update the field, a TextChangedEvent is raised even if the user did not actually change the text. When processing an event, it may be necessary for a client application to check whether anything has actually changed before taking action.

The following events may be raised even when the state of the UI has not changed.

  • AutomationPropertyChangedEvent (depending on the property that has changed)

  • ElementSelectedEvent

  • InvalidatedEvent

  • TextChangedEvent

UI Automation Event Identifiers

Microsoft UI Automation events are identified by AutomationEvent objects. The Id property contains a value that uniquely identifies the kind of event.

The possible values for Id are given in the following table, along with the type used for event arguments. Note that the identifiers used by clients and providers are identically named fields from different classes.

Client Identifier Provider identifier Event Arguments Type

System.Windows.Automation.AutomationElement.AsyncContentLoadedEvent

System.Windows.Automation.AutomationElementIdentifiers.AsyncContentLoadedEvent

AsyncContentLoadedEventArgs

System.Windows.Automation.SelectionItemPattern.ElementAddedToSelectionEvent

System.Windows.Automation.SelectionItemPattern.ElementRemovedFromSelectionEvent

System.Windows.Automation.SelectionItemPattern.ElementSelectedEvent

System.Windows.Automation.SelectionPattern.InvalidatedEvent

System.Windows.Automation.InvokePattern.InvokedEvent

System.Windows.Automation.AutomationElement.LayoutInvalidatedEvent

System.Windows.Automation.AutomationElement.MenuClosedEvent

System.Windows.Automation.AutomationElement.MenuOpenedEvent

System.Windows.Automation.TextPattern.TextChangedEvent

System.Windows.Automation.TextPattern.TextSelectionChangedEvent

System.Windows.Automation.AutomationElement.ToolTipClosedEvent

System.Windows.Automation.AutomationElement.ToolTipOpenedEvent

System.Windows.Automation.WindowPattern.WindowOpenedEvent

System.Windows.Automation.SelectionItemPatternIdentifiers.ElementAddedToSelectionEvent

System.Windows.Automation.SelectionItemPatternIdentifiers.ElementRemovedFromSelectionEvent

System.Windows.Automation.SelectionItemPatternIdentifiers.ElementSelectedEvent

System.Windows.Automation.SelectionPatternIdentifiers.InvalidatedEvent

System.Windows.Automation.InvokePatternIdentifiers.InvokedEvent

System.Windows.Automation.AutomationElementIdentifiers.LayoutInvalidatedEvent

System.Windows.Automation.AutomationElementIdentifiers.MenuClosedEvent

System.Windows.Automation.AutomationElementIdentifiers.MenuOpenedEvent

System.Windows.Automation.TextPatternIdentifiers.TextChangedEvent

System.Windows.Automation.TextPatternIdentifiers.TextSelectionChangedEvent

System.Windows.Automation.AutomationElementIdentifiers.ToolTipClosedEvent

System.Windows.Automation.AutomationElementIdentifiers.ToolTipOpenedEvent

System.Windows.Automation.WindowPatternIdentifiers.WindowOpenedEvent

AutomationEventArgs

System.Windows.Automation.AutomationElement.AutomationFocusChangedEvent

System.Windows.Automation.AutomationElementIdentifiers.AutomationFocusChangedEvent

AutomationFocusChangedEventArgs

System.Windows.Automation.AutomationElement.AutomationPropertyChangedEvent

System.Windows.Automation.AutomationElementIdentifiers.AutomationPropertyChangedEvent

AutomationPropertyChangedEventArgs

System.Windows.Automation.AutomationElement.StructureChangedEvent

System.Windows.Automation.AutomationElementIdentifiers.StructureChangedEvent

StructureChangedEventArgs

System.Windows.Automation.WindowPattern.WindowClosedEvent

System.Windows.Automation.WindowPatternIdentifiers.WindowClosedEvent

WindowClosedEventArgs

UI Automation Event Arguments

The following classes encapsulate event arguments.


Class Description

AsyncContentLoadedEventArgs

Contains information about the asynchronous loading of content, including the percentage of loading completed.

AutomationEventArgs

Contains information about a simple event that requires no extra data.

AutomationFocusChangedEventArgs

Contains information about a change in input focus from one element to another. Events of this type are raised by the UI Automation system, not by providers.

AutomationPropertyChangedEventArgs

Contains information about a change in a property value of an element or control pattern.

StructureChangedEventArgs

Contains information about a change in the UI Automation tree.

WindowClosedEventArgs

Contains information about a window closing.

All the event argument classes contain an EventId member. This identifier is encapsulated in an AutomationEvent.

The AutomationEvent objects used to identify events are obtained by providers from fields in AutomationElementIdentifiers and control pattern identifier classes such as DockPatternIdentifiers. The equivalent fields are obtained by client applications from fields in AutomationElement and control pattern classes such as DockPattern.

For a list of event identifiers, see UI Automation Events for Clients.

See Also

Tasks

Subscribe to UI Automation Events

Concepts

UI Automation Events for Clients
Server-Side UI Automation Provider Implementation