wijjit.core.events.HandlerRegistry

class wijjit.core.events.HandlerRegistry

Registry for managing and dispatching event handlers.

The HandlerRegistry maintains a collection of event handlers and provides methods for registering, unregistering, and dispatching events to appropriate handlers based on scope and priority.

Variables:

• handlers (List[Handler]) – List of registered handlers

• current_view (str or None) – Name of the current view for view-scoped handlers

__init__()

Initialize handler registry.

Return type:

None

Methods

__init__()	Initialize handler registry.
clear_view(view_name)	Clear all handlers for a specific view.
dispatch_async(event[, executor, exclude_scope])	Dispatch an event to matching handlers (async).
register(callback[, scope, event_type, ...])	Register an event handler.
unregister(handler)	Unregister an event handler.

register(callback, scope=HandlerScope.GLOBAL, event_type=None, view_name=None, element_id=None, priority=0)

Register an event handler.

Supports both synchronous and asynchronous callbacks.

Parameters:

• callback (Callable[[Event], None] | Callable[[Event], Awaitable[None]]) – Function to call when event is dispatched (sync or async)

• scope (HandlerScope) – Scope at which this handler operates (default: GLOBAL)

• event_type (EventType or None) – Type of event to handle (None for all types)

• view_name (str or None) – View name for view-scoped handlers

• element_id (str or None) – Element ID for element-scoped handlers

• priority (int) – Handler priority (higher = earlier execution, default: 0)

Returns:

The registered handler object

Return type:

Handler

unregister(handler)

Unregister an event handler.

Parameters:

handler (Handler) – The handler to remove

Return type:

None

clear_view(view_name)

Clear all handlers for a specific view.

This is called when navigating away from a view to clean up view-scoped handlers.

Parameters:

view_name (str) – Name of the view whose handlers should be cleared

Return type:

None

async dispatch_async(event, executor=None, exclude_scope=None)

Dispatch an event to matching handlers (async).

Supports both synchronous and asynchronous handlers. Handlers are executed in priority order (highest priority first). If a handler cancels the event, subsequent handlers are not executed.

Parameters:

• event (Event) – The event to dispatch

• executor (ThreadPoolExecutor, optional) – Thread pool to use for synchronous handlers. If None, sync handlers run directly on the event loop thread (may block). If provided, sync handlers are executed in the thread pool to prevent blocking the event loop.

• exclude_scope (HandlerScope or collection of HandlerScope, optional) – If given, handlers registered at this scope (or any of these scopes) are not dispatched. Used to suppress view- and global-scoped key handlers while a text input is focused, so typing a character does not trigger a hotkey, without also suppressing element-scoped handlers.

Return type:

None

Notes

Threading model:

• Async handlers always execute on the event loop

• Sync handlers run in executor if provided, otherwise on event loop

• Running sync handlers on event loop may cause UI freezes if they perform blocking operations (file I/O, network calls, sleep, etc.)

• For production use, configure an executor to run sync handlers safely