Subscribing to UI Automation Events
Microsoft UI Automation allows clients to subscribe to events of interest. This capability improves performance by eliminating the need to continually poll the UI elements in the system to see if any information, structure, or state has changed.
Efficiency is also improved by the ability to listen for events only within a defined scope. For example, a client can listen for selection changes on an item in a list, on the list itself, or on an entire dialog box.
Note
Do not assume that all possible events are raised by a UI Automation provider. For example, not all property changes cause events to be raised by the standard proxy providers for Windows Forms and Microsoft Win32 controls.
For a broader view of UI Automation events, see UI Automation Events Overview.
Note
Before implementing an event handler, you should be familiar with the threading issues described in Understanding Threading Issues.
This topic contains the following sections.
Registering Event Handlers
Client applications subscribe to events of a particular kind by registering an event handler, using one of the following IUIAutomation methods.
| Subscription Method | Event Type | Callback Interface |
|---|---|---|
| AddFocusChangedEventHandler | Focus change | IUIAutomationFocusChangedEventHandler |
| AddPropertyChangedEventHandler, AddPropertyChangedEventHandlerNativeArray | Property change | IUIAutomationPropertyChangedEventHandler |
| AddStructureChangedEventHandler | Structure change | IUIAutomationStructureChangedEventHandler |
| AddNotificationEventHandler | Notification | IUIAutomationNotificationEventHandler |
| AddAutomationEventHandler | Other events | IUIAutomationEventHandler |
When a client adds an event handler for all descendants (TreeScope_Descendants), UI Automation adds only one handler for the root of sub-tree, and the handler listens across all descendents. UI Automation does not add event handlers recursively.
When a client calls the IUIAutomation::RemoveAllEventHandlers method, UI Automation removes all event handlers from the client process.
To receive and handle events, you implement an event-handling object that exposes a callback interface, and you must register the object by calling an event registration method such as IUIAutomation::AddPropertyChangedEventHandler. The callback interface has a single method; UI Automation calls this method when the event is processed.
On shutdown, or when UI Automation events are no longer of interest to the application, UI Automation clients should call one or more of the following IUIAutomation methods.
Note
A UI Automation client should not use multiple threads to add or remove event handlers. Unexpected behavior can result if one event handler is being added or removed while another is being added or removed in the same client process.
| Method | Description |
|---|---|
| RemoveAutomationEventHandler | Unregisters an event handler that was registered by using AddAutomationEventHandler. |
| RemoveFocusChangedEventHandler | Unregisters an event handler that was registered by using AddFocusChangedEventHandler. |
| RemovePropertyChangedEventHandler | Unregisters an event handler that was registered by using AddPropertyChangedEventHandler or AddPropertyChangedEventHandlerNativeArray. |
| RemoveStructureChangedEventHandler | Unregisters an event handler that was registered by using AddStructureChangedEventHandler. |
| RemoveNotificationEventHandler | Unregisters an event handler that weas registered by using AddNotificationEventHandler. |
| RemoveAllEventHandlers | Unregisters all registered event handlers. |
It is possible for an event to be delivered to an event handler after the handler has been unsubscribed, if the event is received simultaneously with the request to unsubscribe the event. The best practice is to follow the Component Object Model (COM) standard and avoid destroying the event handler object until its reference count has reached zero. Destroying an event handler immediately after unsubscribing for events may result in an access violation if an event is delivered late.
Examples
For code examples that show how to handle UI Automation events, see How to Implement Event Handlers.
Related topics