Skip to content

09. Advanced: Events

Descolada edited this page Jan 16, 2023 · 2 revisions

Introduction

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:

  1. Create a event handler, which points to a function that we want the event to trigger
  2. Register the handler to an automation event listener
  3. When we are done, remove the event listener

Types of events

A more comprehensive overview of event types is available in Microsofts' documentations.

Property change

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.

Element action

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.

Structure change

Raised when the structure of the UIA tree changes, for example when new UI items become visible, hidden, or removed.

Global desktop change

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

Notification

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.

Creating event listeners

Creating handlers

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
}

Adding event handlers

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

Removing event handlers

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.

Examples

FocusChanged event

See Example7_FocusChangedEvent.ahk

Selection event

See Example8_SelectionEventHandler.ahk

TextChanged event

See Example18_TextRangeTextChangedEvent.ahk

PropertyChanged event

See Example19_PropertyChangedEvent.ahk

StructureChanged event

See Example20_StructureChangedEvent.ahk

Notification event

See Example21_NotificationEvent.ahk

Clone this wiki locally