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.
For a broader view of UI Automation events, see UI Automation Events Overview.
This topic contains the following sections.
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|
|AddPropertyChangedEventHandler, AddPropertyChangedEventHandlerNativeArray||Property change||IUIAutomationPropertyChangedEventHandler|
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.
|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.|
|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.
For code examples that show how to handle UI Automation events, see How to Implement Event Handlers.