Repository navigation
09. Advanced: Events
UIA events can be used to set up listeners for all sorts of changes in the user interface.
Usually dealing with event listeners/handlers, we need to follow three steps:
- Create a event handler, which points to a function that we want the event to trigger
- Register the handler to an automation event listener
- When we are done, remove the event listener
A more comprehensive overview of event types is available in Microsofts' documentations.
Raised when a property of a UIA element or control pattern changes. For example, these kinds of event listeners could be used to monitor for property changes on TogglePattern ToggleState, so when a checkbox's state is changed (toggled) then this event is raised.
Raised when a change in the UI results from user or programmatic activity, for example when a button is clicked or invoked through Invoke pattern.
Raised when the structure of the UIA tree changes, for example when new UI items become visible, hidden, or removed.
Raised when actions of global interest occur, such as when the focus shifts from one element to another, or when a window closes/opens.
Raised when an app specifically raises a notification event (for example, Edge raises this on page reload, page load complete, and many other situations). NotificationKind indicates the type of the notification.
New event handlers can be created with UIA.Create...EventHandler(callback), that returns a new handler object.
- funcName: the function that will receive the calls when an event happens
The "..." depends on the type of event that the handler will be used with. For example, if using in UIA.AddAutomationEventHandler, then use UIA.CreateAutomationEventHandler to create the handler.
Depending on the type of handler, the callback function needs to accept a certain number of parameters:
- HandleAutomationEvent(sender, eventId) <--- this is the most common handler type created with AddAutomationEventHandler, and the handler function needs to have exactly two arguments: sender (the element which sent the event), and eventId.
- HandleFocusChangedEvent(sender)
- HandlePropertyChangedEvent(sender, propertyId, newValue)
- HandleStructureChangedEvent(sender, changeType, runtimeId)
- HandleTextEditTextChangedEvent(sender, changeType, eventStrings)
- HandleChangesEvent(sender, uiaChanges, changesCount)
- HandleNotificationEvent(sender, notificationKind, notificationProcessing, displayString, activityId)
For example, the most common event handler is the AddAutomationEventHandler. For this type of handler you only need to specify a function name that will be called when the event happens, and that function needs to have two arguments:
handler := UIA.CreateAutomationEventHandler("HandleMyEvent")
; Add event listener with UIA.AddAutomationEventHandler(handler, eventId)
HandleMyEvent(senderElement, eventId) {
; Do something
}
- AddAutomationEventHandler(handler, element, eventId, scope:=0x4, cacheRequest:=0) where eventId needs to be one of the UIA.Event values
- AddPropertyChangedEventHandler(handler, element, propertyArray, scope:=0x4, cacheRequest:=0)
- AddStructureChangedEventHandler(handler, element)
- AddFocusChangedEventHandler(handler, cacheRequest=0)
- AddTextEditTextChangedEventHandler(handler, element, textEditChangeType, scope:=0x4, cacheRequest:=0)
- AddChangesEventHandler(handler, element, changeTypes, scope:=0x4, cacheRequest:=0)
Every Add...EventHandler has a corresponding Remove...EventHandler. For example, AddAutomationEventHandler and RemoveAutomationEventHandler.
- RemoveAllEventHandlers()
- RemoveAutomationEventHandler(handler, element, eventId)
- RemovePropertyChangedEventHandler(handler, element)
- RemoveStructureChangedEventHandler(handler, element)
- RemoveFocusChangedEventHandler(handler)
- RemoveTextEditTextChangedEventHandler(handler, element)
- RemoveChangesEventHandler(handler, element)
Easiest way is to set up a OnExit() function and call UIA.RemoveAllEventHandlers() before exiting to free all event handlers.
See Example7_FocusChangedEvent.ahk
See Example8_SelectionEventHandler.ahk
See Example18_TextRangeTextChangedEvent.ahk
See Example19_PropertyChangedEvent.ahk
See Example20_StructureChangedEvent.ahk
See Example21_NotificationEvent.ahk