IEventDispatcher

class carb.eventdispatcher.IEventDispatcher

Bases: pybind11_object

Methods

__init__(*args, **kwargs)

dispatch_event(self, event_name[, payload])

Dispatches an event and immediately calls all observers that would observe this particular event.

has_observers(self, event_name[, filter])

Queries the Event Dispatcher whether any observers are listening to a specific event signature.

observe_event(self, order, event_name, ...)

Registers an observer with the Event Dispatcher system.
__init__(*args, **kwargs)
dispatch_event(self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, event_name: str, payload: handle = None) → int

Dispatches an event and immediately calls all observers that would observe this particular event.

Finds and calls all observers (in the current thread) that observe the given event signature.

It is safe to recursively dispatch events (i.e. call `dispatch_event()` from within a called observer), but care must be taken to avoid endless recursion. See the rules in observe_event() for observers added during a `dispatch_event()` call.

Parameters

  • event_name – (str) The name of the event to dispatch

  • payload – (dict) If present, must be a dict of key(str)/value(any) pairs.

Returns

The number of observers that were called, excluding those from recursive calls.

has_observers(self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, event_name: str, filter: handle = None) → bool

Queries the Event Dispatcher whether any observers are listening to a specific event signature.

Emulates a call to dispatch_event()` (without actually calling any observers) and returns `True() if any observers would be called.

Parameters

  • event_name – (str) The event name to query

  • filter – [optional] (dict) If present, must be a dict of key(str)/value(any) pairs.

Returns

`True` if at least one observer would be called with the given `filter` arguments; `False` otherwise.

observe_event(self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, order: int = 0, event_name: str, on_event: Callable[[carb.eventdispatcher._eventdispatcher.Event], None], filter: handle = None, observer_name: str = '<python>') → carb.eventdispatcher._eventdispatcher.ObserverGuard

Registers an observer with the Event Dispatcher system.

An observer is a callback that is called whenever dispatch_event() is called. The observers are invoked in the thread that calls `dispatch_event()`, and multiple threads may be calling `dispatch_event()` simultaneously, so observers must be thread-safe unless the application can ensure synchronization around `dispatch_event()` calls.

Observers can pass an optional dictionary of `filter` arguments. The key/value pairs of `filter` arguments cause an observer to only be invoked for a `dispatch_event()` call that contains at least the same values. For instance, having a filter dictionary of `{“WindowID”: 1234}` will only cause the observer to be called if `dispatch_event()` is given the same value as a `”WindowID”` parameter.

Observers can be added inside of an observer notification (i.e. during a call to `dispatch_event()`), however these new observers will not be called for currently the dispatching event. A subsequent recursive call to `dispatch_event()` (on the current thread only) will also call the new observer. The new observer will be available to all other threads once the `dispatch_event()` call (in which it was added) completes.

Parameters

  • order – (int) A value determining call order. Observers with lower order values are called earlier. Observers with the same order value and same filter argument values will be called in the order they are registered. Observers with the same order value with different filter arguments are called in an indeterminate order.

  • event_name – (str) The event name to observe

  • on_event – (function) A function that is invoked when an event matching `event_name` and any `filter` arguments is dispatched.

  • filter – [optional] (dict) If present, must be a dict of key(str)/value(any) pairs.

  • observer_name – [optional] (str) If present, the name of the observer for debugging and profiling. If omitted, “<python>” is used instead.

Returns

An ObserverGuard object that, when collected, removes the observer from the Event Dispatcher system.