IEventDispatcher#

class carb.eventdispatcher.IEventDispatcher#

Bases: pybind11_object

Methods

`__init__`(args, *kwargs)
`add_event_alias`(self, target_name, alias_name)	Adds an alias that can be used to observe and dispatch as a different event.
`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.
`remove_all_event_aliases_for`(self, target_name)	Removes all aliases for a given event target.
`remove_all_observers_for`(self, event_name)	Removes all observers for the given event.
`remove_event_alias`(self, target_name, alias_name)	Removes a previously-added alias.

__init__(*args, **kwargs)#

add_event_alias( self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, target_name: str, alias_name: str, ) → bool#

Adds an alias that can be used to observe and dispatch as a different event.

Event aliases are a powerful tool. An alias target may have as many aliases as necessary, but an alias may not have any aliases of its own. Similarly, an alias target may not function as an alias for any other alias target.

Thus an alias target is considered a primary event, and any aliases that it is known by can also be used to dispatch or receive events.

Dispatching to an alias acts the same as dispatching to an alias target directly: Any observers of any aliases for that alias target will observe the event, as well as the alias target itself. However, the `Event.event_name` property will be the same as the alias they’re observing, not the alias target and potentially not even the alias that was dispatched. See `observe_event()` for more information.

Aliases can be removed with `remove_event_alias()` or `remove_all_event_aliases_for()`.

While it is possible to add or remove an alias from an observer callback, it will not affect the current event dispatch.

Parameters:

target_name – (str) The target event to create an alias for.
alias_name – (str) The alias that will refer to `target_name`.

Returns:

`target_name` and `alias_name` are the same, `target_name` or `alias_name` are already used as aliases or targets respectively, or `alias_name` already exists as a target of `target_name`.

Return type:

`True` if a new alias was created, or `False` for one of the following reasons

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.

remove_all_event_aliases_for( self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, target_name: str, ) → int#

Removes all aliases for a given event target.

Aliases are added with `add_event_alias()`.

Once an alias is removed from a target, any former alias event can be added as an alias for a different target, or used as a target itself. Similarly, once `target_name` has all aliases removed, it can be used as an alias or as a target in the future.

While it is possible to add or remove an alias from an observer callback, it will not affect the current event dispatch.

Parameters:: target_name – (str) The target event to remove all aliases from.
Returns:: The number of aliases removed. A value of 0 indicates that `target_name` is not actually an event target or currently has no aliases.

remove_all_observers_for( self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, event_name: str, ) → int#

Removes all observers for the given event.

Typically a system might do this when it will never send a particular event again, such at shutdown. After calling this, `has_observers()` for `event_name` will return `false`. Observers with filter arguments for `event_name` will also be removed. Observers are removed in the reverse of the registration order.

Any existing `ObserverGuard` objects may be destroyed but will not have an effect.

WARNING: This will forcibly remove all observers, which will receive no notification that they have been removed.

Parameters:: event_name – (str) The event to remove all observers for.
Returns:: The number of observers that were removed.

remove_event_alias( self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, target_name: str, alias_name: str, ) → bool#

Removes a previously-added alias.

Aliases are added with `add_event_alias()`.

Once `alias_name` is removed as an alias, the `alias_name` event can be added as an alias for a different target, or used as a target itself. Similarly, once `target_name` has all aliases removed, it can be used as an alias or as a target in the future.

While it is possible to add or remove an alias from an observer callback, it will not affect the current event dispatch.

Parameters:

target_name – (str) The target event to remove an alias from.
alias_name – (str) The alias to remove from @p target.

Returns:

`target_name` and `alias_name` are the same, `target_name` is not an event target, or `alias_name` is not an event alias, or `target_name` does not have an alias `alias_name`.

Return type:

`True` if an existing alias was found and removed, or `False` for one of the following reasons