Skip to content

Event Handlers

Register UI Automation event handlers from Python. The register_* methods on AutomationElement and AutomationBase return an EventRegistration handle that keeps the callback alive and can unregister it (also usable as a context manager).

def on_invoked(element, event_id):
    print("invoked!")

registration = button.register_automation_event(
    button.patterns.invoke.pattern.raw_pattern.EventIds.InvokedEvent,
    TreeScope.Element,
    on_invoked,
)
# ... later ...
registration.unregister()

flaui.core.event_handlers.EventRegistration(cs_handler, callback, unregister)

Handle to a registered UI Automation event; keeps the callback alive and allows unregistering.

Use it as a context manager or call :meth:unregister / :meth:dispose when done.

Store the C# handler and callback and add the registration to the keep-alive registry.

Parameters:

Name Type Description Default
cs_handler Any

The C# event-handler object returned by the native Register* call.

 required
callback Callable[..., None]

The Python callback bridged to C# (kept alive to prevent GC).

 required
unregister Callable[[Any], None]

A callable that unregisters cs_handler from C#.

 required
Source code in flaui/core/event_handlers.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(self, cs_handler: Any, callback: Callable[..., None], unregister: Callable[[Any], None]) -> None:
    """Store the C# handler and callback and add the registration to the keep-alive registry.

    :param cs_handler: The C# event-handler object returned by the native ``Register*`` call.
    :param callback: The Python callback bridged to C# (kept alive to prevent GC).
    :param unregister: A callable that unregisters ``cs_handler`` from C#.
    """
    self._cs_handler = cs_handler
    self._callback = callback
    self._unregister = unregister
    self._active = True
    with _registry_lock:
        _live_registrations.add(self)

is_active property

Return whether the registration is still active.

Returns:

Type Description
bool

True until :meth:unregister has been called.

raw_handler property

Return the underlying C# event-handler object.

Returns:

Type Description
Any

The native handler returned by the Register* call.

__enter__()

Return self for use as a context manager.

Returns:

Type Description
'EventRegistration'

This registration.
Source code in flaui/core/event_handlers.py 
84
85
86
87
88
89
def __enter__(self) -> "EventRegistration":
    """Return self for use as a context manager.

    :return: This registration.
    """
    return self

__exit__(*exc)

Unregister the handler when leaving the with block.

Parameters:

Name Type Description Default
exc Any

Exception info (unused).

 ()
Source code in flaui/core/event_handlers.py 
91
92
93
94
95
96
def __exit__(self, *exc: Any) -> None:
    """Unregister the handler when leaving the ``with`` block.

    :param exc: Exception info (unused).
    """
    self.unregister()

dispose()

Alias for :meth:unregister (mirrors the C# disposable pattern).

Source code in flaui/core/event_handlers.py 
80
81
82
def dispose(self) -> None:
    """Alias for :meth:`unregister` (mirrors the C# disposable pattern)."""
    self.unregister()

unregister()

Unregister the event handler from C# and drop the keep-alive reference.

Source code in flaui/core/event_handlers.py 
69
70
71
72
73
74
75
76
77
78
def unregister(self) -> None:
    """Unregister the event handler from C# and drop the keep-alive reference."""
    if not self._active:
        return
    try:
        self._unregister(self._cs_handler)
    finally:
        self._active = False
        with _registry_lock:
            _live_registrations.discard(self)