napari.utils.events.EventEmitter#
- class napari.utils.events.EventEmitter(source: ~typing.Any = None, type_name: str | None = None, event_class: ~typing.Type[~napari.utils.events.event.Event] = <class 'napari.utils.events.event.Event'>)[source]#
Bases:
object
Encapsulates a list of event callbacks.
Each instance of EventEmitter represents the source of a stream of similar events, such as mouse click events or timer activation events. For example, the following diagram shows the propagation of a mouse click event to the list of callbacks that are registered to listen for that event:
User clicks |Canvas creates mouse on |MouseEvent: |'mouse_press' EventEmitter: |callbacks in sequence: # noqa Canvas | | | # noqa -->|event = MouseEvent(...) -->|Canvas.events.mouse_press(event) -->|callback1(event) # noqa | | -->|callback2(event) # noqa | | -->|callback3(event) # noqa
Callback functions may be added or removed from an EventEmitter using
connect()
ordisconnect()
.Calling an instance of EventEmitter will cause each of its callbacks to be invoked in sequence. All callbacks are invoked with a single argument which will be an instance of
Event
.EventEmitters are generally created by an EmitterGroup instance.
- Parameters:
source (object) – The object that the generated events apply to. All emitted Events will have their .source property set to this value.
type_name (str or None) – String indicating the event type (e.g. mouse_press, key_release)
event_class (subclass of Event) – The class of events that this emitter will generate.
Methods
block
([callback])Block this emitter.
blocked
([callback])Return boolean indicating whether the emitter is blocked for the given callback.
blocker
([callback])Return an EventBlocker to be used in 'with' statements
connect
(callback[, ref, position, before, ...])Connect this emitter to a new callback.
disconnect
([callback])Disconnect a callback from this emitter.
unblock
([callback])Unblock this emitter.
Attributes
The set of callback references
The set of callbacks
Whether exceptions during callbacks will be caught by the emitter
Print a message and stack trace if a callback raises an exception
The object that events generated by this emitter apply to
Details
- block(callback: Callable[[Event], None] | Callable[[], None] | None = None)[source]#
Block this emitter. Any attempts to emit an event while blocked will be silently ignored. If callback is given, then the emitter is only blocked for that specific callback.
Calls to block are cumulative; the emitter must be unblocked the same number of times as it is blocked.
- blocked(callback: Callable[[Event], None] | Callable[[], None] | None = None) bool [source]#
Return boolean indicating whether the emitter is blocked for the given callback.
- blocker(callback: Callable[[Event], None] | Callable[[], None] | None = None)[source]#
Return an EventBlocker to be used in ‘with’ statements
Notes
For example, one could do:
with emitter.blocker(): pass # ..do stuff; no events will be emitted..
- property callbacks: Tuple[Callable[[Event], None] | Callable[[], None] | Tuple[weakref[Any], str], ...]#
The set of callbacks
- connect(callback: Callable[[Event], None] | Callable[[], None] | Tuple[weakref[Any], str] | Tuple[weakref[Any] | object, str] | EventEmitter, ref: bool | str = False, position: Literal['first', 'last'] = 'first', before: str | Callable[[Event], None] | Callable[[], None] | List[str | Callable[[Event], None] | Callable[[], None]] | None = None, after: str | Callable[[Event], None] | Callable[[], None] | List[str | Callable[[Event], None] | Callable[[], None]] | None = None, until: EventEmitter | None = None)[source]#
Connect this emitter to a new callback.
- Parameters:
callback (function | tuple) – callback may be either a callable object or a tuple (object, attr_name) where object.attr_name will point to a callable object. Note that only a weak reference to
object
will be kept.ref (bool | str) – Reference used to identify the callback in
before
/after
. If True, the callback ref will automatically determined (see Notes). If False, the callback cannot be referred to by a string. If str, the given string will be used. Note that ifref
is not unique incallback_refs
, an error will be thrown.position (str) – If
'first'
, the first eligible position is used (that meets the before and after criteria),'last'
will use the last position.before (str | callback | list of str or callback | None) – List of callbacks that the current callback should precede. Can be None if no before-criteria should be used.
after (str | callback | list of str or callback | None) – List of callbacks that the current callback should follow. Can be None if no after-criteria should be used.
until (optional eventEmitter) – if provided, when the event until is emitted, callback will be disconnected from this emitter.
Notes
If
ref=True
, the callback reference will be determined from:If
callback
istuple
, the second element in the tuple.The
__name__
attribute.The
__class__.__name__
attribute.
The current list of callback refs can be obtained using
event.callback_refs
. Callbacks can be referred to by either their string reference (if given), or by the actual callback that was attached (e.g.,(canvas, 'swap_buffers')
).If the specified callback is already connected, then the request is ignored.
If before is None and after is None (default), the new callback will be added to the beginning of the callback list. Thus the callback that is connected _last_ will be the _first_ to receive events from the emitter.
- disconnect(callback: Callable[[Event], None] | Callable[[], None] | Tuple[weakref[Any], str] | None | object = None)[source]#
Disconnect a callback from this emitter.
If no callback is specified, then all callbacks are removed. If the callback was not already connected, then the call does nothing.
- property ignore_callback_errors: bool#
Whether exceptions during callbacks will be caught by the emitter
This allows it to continue invoking other callbacks if an error occurs.
- property print_callback_errors: str#
Print a message and stack trace if a callback raises an exception
Valid values are “first” (only show first instance), “reminders” (show complete first instance, then counts), “always” (always show full traceback), or “never”.
This assumes ignore_callback_errors=True. These will be raised as warnings, so ensure that the vispy logging level is set to at least “warning”.