napari.utils.events.EmitterGroup#

class napari.utils.events.EmitterGroup(source: Any | None = None, auto_connect: bool = False, **emitters: type[Event] | EventEmitter | None)[source]#

Bases: EventEmitter

EmitterGroup instances manage a set of related EventEmitters. Its primary purpose is to provide organization for objects that make use of multiple emitters and to reduce the boilerplate code needed to initialize those emitters with default connections.

EmitterGroup instances are usually stored as an ‘events’ attribute on objects that use multiple emitters. For example:

 EmitterGroup  EventEmitter
         |       |
Canvas.events.mouse_press
Canvas.events.resized
Canvas.events.key_press

EmitterGroup is also a subclass of EventEmitters, allowing it to emit its own events. Any callback that connects directly to the EmitterGroup will receive all of the events generated by the group’s emitters.

Parameters:

source (object) – The object that the generated events apply to.
auto_connect (bool) – If auto_connect is True, then one connection will be made for each emitter that looks like emitter.connect((source, 'on_' + event_name)). This provides a simple mechanism for automatically connecting a large group of emitters to default callbacks. By default, false.
emitters (keyword arguments) – See the add method.

Methods

`add`([auto_connect])	Add one or more EventEmitter instances to this emitter group. Each keyword argument may be specified as either an EventEmitter instance or an Event subclass, in which case an EventEmitter will be generated automatically::.
`block`([callback])	Block this emitter.
`block_all`()	Block all emitters in this group by increase counter of semaphores for each event 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
`blocker_all`()	Return an EventBlockerAll to be used in 'with' statements
`connect`(callback[, ref, position, before, after])	Connect the callback to the event group.
`disconnect`([callback])	Disconnect the callback from this group.
`unblock`([callback])	Unblock this emitter.
`unblock_all`()	Unblock all emitters in this group, by decrease counter of semaphores for each event emitter.

Attributes

`callback_refs`	The set of callback references
`callbacks`	The set of callbacks
`emitters`	List of current emitters in this group.
`ignore_callback_errors`	Whether exceptions during callbacks will be caught by the emitter
`print_callback_errors`	Print a message and stack trace if a callback raises an exception
`source`	The object that events generated by this emitter apply to

Details

add(auto_connect: bool | None = None, **kwargs: type[Event] | EventEmitter | None)[source]#

Add one or more EventEmitter instances to this emitter group. Each keyword argument may be specified as either an EventEmitter instance or an Event subclass, in which case an EventEmitter will be generated automatically:

# This statement:
group.add(mouse_press=MouseEvent,
          mouse_release=MouseEvent)

# ..is equivalent to this statement:
group.add(mouse_press=EventEmitter(group.source, 'mouse_press',
                                   MouseEvent),
          mouse_release=EventEmitter(group.source, 'mouse_press',
                                     MouseEvent))

block(callback: Callable[[Event], None] | Callable[[], None] | None = None)#

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.

block_all()[source]#: Block all emitters in this group by increase counter of semaphores for each event emitter

blocked(callback: Callable[[Event], None] | Callable[[], None] | None = None) → bool#: Return boolean indicating whether the emitter is blocked for the given callback.

blocker(callback: Callable[[Event], None] | Callable[[], None] | None = None)#

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..

blocker_all() → EventBlockerAll[source]#

Return an EventBlockerAll to be used in ‘with’ statements

Notes

For example, one could do:

with emitter.blocker_all():
    pass  # ..do stuff; no events will be emitted..

property callback_refs: tuple[str | None, ...]#: The set of callback references

property callbacks: tuple[Callable[[Event], None] | Callable[[], None] | tuple[weakref.ReferenceType[Any], str], ...]#: The set of callbacks

Connect the callback to the event group. The callback will receive events from all of the emitters in the group.

See EventEmitter.connect() for arguments.

disconnect(callback: Callable[[Event], None] | Callable[[], None] | None = None)[source]#: Disconnect the callback from this group. See connect() and EventEmitter.connect() for more information.

property emitters: dict[str, EventEmitter]#: List of current emitters in this group.

property ignore_callback_errors#

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”.

property source: Any#: The object that events generated by this emitter apply to

unblock(callback: Callable[[Event], None] | Callable[[], None] | None = None)#

Unblock this emitter. See event.EventEmitter.block().

Note: Use of unblock(None) only reverses the effect of block(None); it does not unblock callbacks that were explicitly blocked using block(callback).

unblock_all()[source]#: Unblock all emitters in this group, by decrease counter of semaphores for each event emitter. if block is called twice and unblock is called once, then events will be still blocked. See Semaphore (programming).