# Copyright (c) Vispy Development Team. All Rights Reserved.
# Distributed under the (new) BSD License. See LICENSE.txt for more info.
# # LICENSE.txt
# Vispy licensing terms
# ---------------------
# Vispy is licensed under the terms of the (new) BSD license:
#
# Copyright (c) 2013-2017, Vispy Development Team. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# * Neither the name of Vispy Development Team nor the names of its
# contributors may be used to endorse or promote products
# derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
# OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
#
# Exceptions
# ----------
#
# The examples code in the examples directory can be considered public
# domain, unless otherwise indicated in the corresponding source file.
"""
The event module implements the classes that make up the event system.
The Event class and its subclasses are used to represent "stuff that happens".
The EventEmitter class provides an interface to connect to events and
to emit events. The EmitterGroup groups EventEmitter objects.
For more information see http://github.com/vispy/vispy/wiki/API_Events
"""
import inspect
import os
import warnings
import weakref
from collections.abc import Sequence
from functools import partial
from typing import (
Any,
Callable,
Dict,
Generator,
List,
Optional,
Tuple,
Type,
Union,
cast,
)
from typing_extensions import Literal
from vispy.util.logs import _handle_exception
from ..translations import trans
[docs]class Event:
"""Class describing events that occur and can be reacted to with callbacks.
Each event instance contains information about a single event that has
occurred such as a key press, mouse motion, timer activation, etc.
Subclasses: :class:`KeyEvent`, :class:`MouseEvent`, :class:`TouchEvent`,
:class:`StylusEvent`
The creation of events and passing of events to the appropriate callback
functions is the responsibility of :class:`EventEmitter` instances.
Note that each event object has an attribute for each of the input
arguments listed below.
Parameters
----------
type : str
String indicating the event type (e.g. mouse_press, key_release)
native : object (optional)
The native GUI event object
**kwargs : keyword arguments
All extra keyword arguments become attributes of the event object.
"""
def __init__(self, type: str, native: Any = None, **kwargs: Any):
# stack of all sources this event has been emitted through
self._sources: List[Any] = []
self._handled: bool = False
self._blocked: bool = False
# Store args
self._type = type
self._native = native
self._kwargs = kwargs
for k, v in kwargs.items():
setattr(self, k, v)
@property
def source(self) -> Any:
"""The object that the event applies to (i.e. the source of the event)."""
return self._sources[-1] if self._sources else None
@property
def sources(self) -> List[Any]:
"""List of objects that the event applies to (i.e. are or have
been a source of the event). Can contain multiple objects in case
the event traverses a hierarchy of objects.
"""
return self._sources
def _push_source(self, source):
self._sources.append(source)
def _pop_source(self):
return self._sources.pop()
@property
def type(self) -> str:
# No docstring; documeted in class docstring
return self._type
@property
def native(self) -> Any:
# No docstring; documeted in class docstring
return self._native
@property
def handled(self) -> bool:
"""This boolean property indicates whether the event has already been
acted on by an event handler. Since many handlers may have access to
the same events, it is recommended that each check whether the event
has already been handled as well as set handled=True if it decides to
act on the event.
"""
return self._handled
@handled.setter
def handled(self, val) -> bool:
self._handled = bool(val)
@property
def blocked(self) -> bool:
"""This boolean property indicates whether the event will be delivered
to event callbacks. If it is set to True, then no further callbacks
will receive the event. When possible, it is recommended to use
Event.handled rather than Event.blocked.
"""
return self._blocked
@blocked.setter
def blocked(self, val) -> bool:
self._blocked = bool(val)
def __repr__(self) -> str:
# Try to generate a nice string representation of the event that
# includes the interesting properties.
# need to keep track of depth because it is
# very difficult to avoid excessive recursion.
global _event_repr_depth
_event_repr_depth += 1
try:
if _event_repr_depth > 2:
return "<...>"
attrs = []
for name in dir(self):
if name.startswith('_'):
continue
# select only properties
if not hasattr(type(self), name) or not isinstance(
getattr(type(self), name), property
):
continue
attr = getattr(self, name)
attrs.append(f"{name}={attr!r}")
return "<{} {}>".format(self.__class__.__name__, " ".join(attrs))
finally:
_event_repr_depth -= 1
def __str__(self) -> str:
"""Shorter string representation"""
return self.__class__.__name__
# mypy fix for dynamic attribute access
def __getattr__(self, name: str) -> Any:
return object.__getattribute__(self, name)
_event_repr_depth = 0
Callback = Union[Callable[[Event], None], Callable[[], None]]
CallbackRef = Tuple['weakref.ReferenceType[Any]', str] # dereferenced method
CallbackStr = Tuple[
Union['weakref.ReferenceType[Any]', object], str
] # dereferenced method
class _WeakCounter:
"""
Similar to collection counter but has weak keys.
It will only implement the methods we use here.
"""
def __init__(self):
self._counter = weakref.WeakKeyDictionary()
self._nonecount = 0
def update(self, iterable):
for it in iterable:
if it is None:
self._nonecount += 1
else:
self._counter[it] = self.get(it, 0) + 1
def get(self, key, default):
if key is None:
return self._nonecount
return self._counter.get(key, default)
[docs]class EventEmitter:
"""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
:func:`connect() <vispy.event.EventEmitter.connect>` or
:func:`disconnect() <vispy.event.EventEmitter.disconnect>`.
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 :class:`Event <vispy.event.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 : 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.
"""
def __init__(
self,
source: Any = None,
type: Optional[str] = None,
event_class: Type[Event] = Event,
):
# connected callbacks
self._callbacks: List[Union[Callback, CallbackRef]] = []
# used when connecting new callbacks at specific positions
self._callback_refs: List[Optional[str]] = []
self._callback_pass_event: List[bool] = []
# count number of times this emitter is blocked for each callback.
self._blocked: Dict[Optional[Callback], int] = {None: 0}
self._block_counter: _WeakCounter[Optional[Callback]] = _WeakCounter()
# used to detect emitter loops
self._emitting = False
self.source = source
self.default_args = {}
if type is not None:
self.default_args['type'] = type
assert inspect.isclass(event_class)
self.event_class = event_class
self._ignore_callback_errors: bool = False # True
self.print_callback_errors = 'reminders' # 'reminders'
@property
def ignore_callback_errors(self) -> bool:
"""Whether exceptions during callbacks will be caught by the emitter
This allows it to continue invoking other callbacks if an error
occurs.
"""
return self._ignore_callback_errors
@ignore_callback_errors.setter
def ignore_callback_errors(self, val: bool):
self._ignore_callback_errors = val
@property
def print_callback_errors(self) -> 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".
"""
return self._print_callback_errors
@print_callback_errors.setter
def print_callback_errors(
self,
val: Union[
Literal['first'],
Literal['reminders'],
Literal['always'],
Literal['never'],
],
):
if val not in ('first', 'reminders', 'always', 'never'):
raise ValueError(
trans._(
'print_callback_errors must be "first", "reminders", "always", or "never"',
deferred=True,
)
)
self._print_callback_errors = val
@property
def callback_refs(self) -> Tuple[Optional[str], ...]:
"""The set of callback references"""
return tuple(self._callback_refs)
@property
def callbacks(self) -> Tuple[Union[Callback, CallbackRef], ...]:
"""The set of callbacks"""
return tuple(self._callbacks)
@property
def source(self) -> Any:
"""The object that events generated by this emitter apply to"""
return (
None if self._source is None else self._source()
) # get object behind weakref
@source.setter
def source(self, s):
self._source = None if s is None else weakref.ref(s)
def _is_core_callback(
self, callback: Union[CallbackRef, Callback], core: str
):
"""
Check if the callback is a core callback
Parameters
----------
callback : Union[CallbackRef, Callback]
The callback to check. Callback could be function or
weak reference to object method coded using weakreference
to object and method name stored in tuple.
core : str
Name of core module, for example 'napari'.
"""
try:
if isinstance(callback, partial):
callback = callback.func
if not isinstance(callback, tuple):
return callback.__module__.startswith(core + '.')
obj = callback[0]() # get object behind weakref
if obj is None: # object is dead
return False
return obj.__module__.startswith(core + '.')
except AttributeError:
return False
[docs] def connect(
self,
callback: Union[Callback, CallbackRef, CallbackStr, 'EventEmitter'],
ref: Union[bool, str] = False,
position: Union[Literal['first'], Literal['last']] = 'first',
before: Union[str, Callback, List[Union[str, Callback]], None] = None,
after: Union[str, Callback, List[Union[str, Callback]], None] = None,
until: Optional['EventEmitter'] = None,
):
"""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 if ``ref``
is not unique in ``callback_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:
1. If ``callback`` is ``tuple``, the second element in the tuple.
2. The ``__name__`` attribute.
3. 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.
"""
callbacks = self.callbacks
callback_refs = self.callback_refs
old_callback = callback
callback, pass_event = self._normalize_cb(callback)
if callback in callbacks:
return
# deal with the ref
_ref: Union[str, None]
if isinstance(ref, bool):
if ref:
if isinstance(callback, tuple):
_ref = callback[1]
elif hasattr(callback, '__name__'): # function
_ref = callback.__name__
else: # Method, or other
_ref = callback.__class__.__name__
else:
_ref = None
elif isinstance(ref, str):
_ref = ref
else:
raise TypeError(
trans._(
'ref must be a bool or string',
deferred=True,
)
)
if _ref is not None and _ref in self._callback_refs:
raise ValueError(
trans._('ref "{ref}" is not unique', deferred=True, ref=_ref)
)
# positions
if position not in ('first', 'last'):
raise ValueError(
trans._(
'position must be "first" or "last", not {position}',
deferred=True,
position=position,
)
)
core_callbacks_indexes = [
i
for i, c in enumerate(self._callbacks)
if self._is_core_callback(c, 'napari')
]
core_callbacks_count = (
max(core_callbacks_indexes) + 1 if core_callbacks_indexes else 0
)
if self._is_core_callback(callback, 'napari'):
callback_bounds = (0, core_callbacks_count)
else:
callback_bounds = (core_callbacks_count, len(callback_refs))
# bounds: upper & lower bnds (inclusive) of possible cb locs
bounds: List[int] = []
for ri, criteria in enumerate((before, after)):
if criteria is None or criteria == []:
bounds.append(
callback_bounds[1] if ri == 0 else callback_bounds[0]
)
else:
if not isinstance(criteria, list):
criteria = [criteria]
for c in criteria:
count = sum(
c in [cn, cc]
for cn, cc in zip(callback_refs, callbacks)
)
if count != 1:
raise ValueError(
trans._(
'criteria "{criteria}" is in the current callback list {count} times:\n{callback_refs}\n{callbacks}',
deferred=True,
criteria=criteria,
count=count,
callback_refs=callback_refs,
callbacks=callbacks,
)
)
matches = [
ci
for ci, (cn, cc) in enumerate(
zip(callback_refs, callbacks)
)
if (cc in criteria or cn in criteria)
]
bounds.append(matches[0] if ri == 0 else (matches[-1] + 1))
if bounds[0] < bounds[1]: # i.e., "place before" < "place after"
raise RuntimeError(
trans._(
'cannot place callback before "{before}" and after "{after}" for callbacks: {callback_refs}',
deferred=True,
before=before,
after=after,
callback_refs=callback_refs,
)
)
idx = bounds[1] if position == 'first' else bounds[0] # 'last'
# actually add the callback
self._callbacks.insert(idx, callback)
self._callback_refs.insert(idx, _ref)
self._callback_pass_event.insert(idx, pass_event)
if until is not None:
until.connect(partial(self.disconnect, callback))
return old_callback # allows connect to be used as a decorator
[docs] def disconnect(
self, callback: Union[Callback, CallbackRef, None, object] = None
):
"""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.
"""
if callback is None:
self._callbacks = []
self._callback_refs = []
self._callback_pass_event = []
elif isinstance(callback, (Callable, tuple)):
callback, _pass_event = self._normalize_cb(callback)
if callback in self._callbacks:
idx = self._callbacks.index(callback)
self._callbacks.pop(idx)
self._callback_refs.pop(idx)
self._callback_pass_event.pop(idx)
else:
index_list = []
for idx, local_callback in enumerate(self._callbacks):
if not (
isinstance(local_callback, Sequence)
and isinstance(local_callback[0], weakref.ref)
):
continue
if (
local_callback[0]() is callback
or local_callback[0]() is None
):
index_list.append(idx)
for idx in index_list[::-1]:
self._callbacks.pop(idx)
self._callback_refs.pop(idx)
self._callback_pass_event.pop(idx)
@staticmethod
def _get_proper_name(callback):
assert inspect.ismethod(callback)
obj = callback.__self__
if (
not hasattr(obj, callback.__name__)
or getattr(obj, callback.__name__) != callback
):
# some decorators will alter method.__name__, so that obj.method
# will not be equal to getattr(obj, obj.method.__name__). We check
# for that case here and traverse to find the right method here.
for name in dir(obj):
meth = getattr(obj, name)
if inspect.ismethod(meth) and meth == callback:
return obj, name
raise RuntimeError(
trans._(
"During bind method {callback} of object {obj} an error happen",
deferred=True,
callback=callback,
obj=obj,
)
)
return obj, callback.__name__
@staticmethod
def _check_signature(fun: Callable) -> bool:
"""
Check if function will accept event parameter
"""
signature = inspect.signature(fun)
parameters_list = list(signature.parameters.values())
if sum(map(_is_pos_arg, parameters_list)) > 1:
raise RuntimeError(
trans._(
"Binning function cannot have more than one positional argument",
deferred=True,
)
)
return any(
map(
lambda x: x.kind
in [
inspect.Parameter.POSITIONAL_ONLY,
inspect.Parameter.POSITIONAL_OR_KEYWORD,
inspect.Parameter.VAR_POSITIONAL,
],
signature.parameters.values(),
)
)
def _normalize_cb(
self, callback
) -> Tuple[Union[CallbackRef, Callback], bool]:
# dereference methods into a (self, method_name) pair so that we can
# make the connection without making a strong reference to the
# instance.
start_callback = callback
if inspect.ismethod(callback):
callback = self._get_proper_name(callback)
# always use a weak ref
if isinstance(callback, tuple) and not isinstance(
callback[0], weakref.ref
):
callback = (weakref.ref(callback[0]), *callback[1:])
if isinstance(start_callback, Callable):
callback = callback, self._check_signature(start_callback)
else:
obj = callback[0]()
if obj is None:
callback = callback, False
else:
callback_fun = getattr(obj, callback[1])
callback = callback, self._check_signature(callback_fun)
return callback
def __call__(self, *args, **kwargs) -> Event:
"""__call__(**kwargs)
Invoke all callbacks for this emitter.
Emit a new event object, created with the given keyword
arguments, which must match with the input arguments of the
corresponding event class. Note that the 'type' argument is
filled in by the emitter.
Alternatively, the emitter can also be called with an Event
instance as the only argument. In this case, the specified
Event will be used rather than generating a new one. This allows
customized Event instances to be emitted and also allows EventEmitters
to be chained by connecting one directly to another.
Note that the same Event instance is sent to all callbacks.
This allows some level of communication between the callbacks
(notably, via Event.handled) but also requires that callbacks
be careful not to inadvertently modify the Event.
"""
# This is a VERY highly used method; must be fast!
blocked = self._blocked
# create / massage event as needed
event = self._prepare_event(*args, **kwargs)
# Add our source to the event; remove it after all callbacks have been
# invoked.
event._push_source(self.source)
self._emitting = True
try:
if blocked.get(None, 0) > 0: # this is the same as self.blocked()
self._block_counter.update([None])
return event
_log_event_stack(event)
rem: List[CallbackRef] = []
for cb, pass_event in zip(
self._callbacks[:], self._callback_pass_event[:]
):
if isinstance(cb, tuple):
obj = cb[0]()
if obj is None:
rem.append(cb) # add dead weakref
continue
old_cb = cb
cb = getattr(obj, cb[1], None)
if cb is None:
warnings.warn(
trans._(
"Problem with function {old_cb} of {obj} connected to event {self_}",
deferred=True,
old_cb=old_cb[1],
obj=obj,
self_=self,
),
stacklevel=2,
category=RuntimeWarning,
)
continue
cb = cast(Callback, cb)
if blocked.get(cb, 0) > 0:
self._block_counter.update([cb])
continue
self._invoke_callback(cb, event if pass_event else None)
if event.blocked:
break
# remove callbacks to dead objects
for cb in rem:
self.disconnect(cb)
finally:
self._emitting = False
if event._pop_source() != self.source:
raise RuntimeError(
trans._(
"Event source-stack mismatch.",
deferred=True,
)
)
return event
def _invoke_callback(
self, cb: Union[Callback, Callable[[], None]], event: Optional[Event]
):
try:
if event is not None:
cb(event)
else:
cb()
except Exception as e:
# dead Qt object with living python pointer. not importing Qt
# here... but this error is consistent across backends
if (
isinstance(e, RuntimeError)
and 'C++' in str(e)
and str(e).endswith(('has been deleted', 'already deleted.'))
):
self.disconnect(cb)
return
_handle_exception(
self.ignore_callback_errors,
self.print_callback_errors,
self,
cb_event=(cb, event),
)
def _prepare_event(self, *args, **kwargs) -> Event:
# When emitting, this method is called to create or otherwise alter
# an event before it is sent to callbacks. Subclasses may extend
# this method to make custom modifications to the event.
if len(args) == 1 and not kwargs and isinstance(args[0], Event):
event: Event = args[0]
# Ensure that the given event matches what we want to emit
assert isinstance(event, self.event_class)
elif not args:
_kwargs = self.default_args.copy()
_kwargs.update(kwargs)
event = self.event_class(**_kwargs)
else:
raise ValueError(
trans._(
"Event emitters can be called with an Event instance or with keyword arguments only.",
deferred=True,
)
)
return event
[docs] def blocked(self, callback: Optional[Callback] = None) -> bool:
"""Return boolean indicating whether the emitter is blocked for
the given callback.
"""
return self._blocked.get(callback, 0) > 0
[docs] def block(self, callback: Optional[Callback] = 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.
"""
self._blocked[callback] = self._blocked.get(callback, 0) + 1
[docs] def unblock(self, callback: Optional[Callback] = None):
"""Unblock this emitter. See :func:`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)``.
"""
if callback not in self._blocked or self._blocked[callback] == 0:
raise RuntimeError(
trans._(
"Cannot unblock {self_} for callback {callback}; emitter was not previously blocked.",
deferred=True,
self_=self,
callback=callback,
)
)
b = self._blocked[callback] - 1
if b == 0 and callback is not None:
del self._blocked[callback]
else:
self._blocked[callback] = b
[docs] def blocker(self, callback: Optional[Callback] = 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..
"""
return EventBlocker(self, callback)
class WarningEmitter(EventEmitter):
"""
EventEmitter subclass used to allow deprecated events to be used with a
warning message.
"""
def __init__(
self,
message,
category=FutureWarning,
stacklevel=3,
*args,
**kwargs,
):
self._message = message
self._warned = False
self._category = category
self._stacklevel = stacklevel
EventEmitter.__init__(self, *args, **kwargs)
def connect(self, cb, *args, **kwargs):
self._warn(cb)
return EventEmitter.connect(self, cb, *args, **kwargs)
def _invoke_callback(self, cb, event):
self._warn(cb)
return EventEmitter._invoke_callback(self, cb, event)
def _warn(self, cb):
if self._warned:
return
# don't warn about unimplemented connections
if isinstance(cb, tuple) and getattr(cb[0], cb[1], None) is None:
return
import warnings
warnings.warn(
self._message, category=self._category, stacklevel=self._stacklevel
)
self._warned = True
[docs]class EmitterGroup(EventEmitter):
"""EmitterGroup instances manage a set of related
:class:`EventEmitters <vispy.event.EventEmitter>`.
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
:class:`EventEmitters <vispy.event.EventEmitter>`,
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
:func:`emitter.connect((source, 'on_' + event_name))
<vispy.event.EventEmitter.connect>`.
This provides a simple mechanism for automatically connecting a large
group of emitters to default callbacks. By default, false.
emitters : keyword arguments
See the :func:`add <vispy.event.EmitterGroup.add>` method.
"""
def __init__(
self,
source: Any = None,
auto_connect: bool = False,
**emitters: Union[Type[Event], EventEmitter, None],
):
EventEmitter.__init__(self, source)
self.auto_connect = auto_connect
self.auto_connect_format = "on_%s"
self._emitters: Dict[str, EventEmitter] = dict()
# whether the sub-emitters have been connected to the group:
self._emitters_connected: bool = False
self.add(**emitters) # type: ignore
def __getattr__(self, name) -> EventEmitter:
return object.__getattribute__(self, name)
def __getitem__(self, name: str) -> EventEmitter:
"""
Return the emitter assigned to the specified name.
Note that emitters may also be retrieved as an attribute of the
EmitterGroup.
"""
return self._emitters[name]
def __setitem__(
self, name: str, emitter: Union[Type[Event], EventEmitter, None]
):
"""
Alias for EmitterGroup.add(name=emitter)
"""
self.add(**{name: emitter}) # type: ignore
[docs] def add(
self,
auto_connect: Optional[bool] = None,
**kwargs: Union[Type[Event], EventEmitter, None],
):
"""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))
"""
if auto_connect is None:
auto_connect = self.auto_connect
# check all names before adding anything
for name in kwargs:
if name in self._emitters:
raise ValueError(
trans._(
"EmitterGroup already has an emitter named '{name}'",
deferred=True,
name=name,
)
)
elif hasattr(self, name):
raise ValueError(
trans._(
"The name '{name}' cannot be used as an emitter; it is already an attribute of EmitterGroup",
deferred=True,
name=name,
)
)
# add each emitter specified in the keyword arguments
for name, emitter in kwargs.items():
if emitter is None:
emitter = Event
if inspect.isclass(emitter) and issubclass(emitter, Event): # type: ignore
emitter = EventEmitter(
source=self.source, type=name, event_class=emitter # type: ignore
)
elif not isinstance(emitter, EventEmitter):
raise RuntimeError(
trans._(
'Emitter must be specified as either an EventEmitter instance or Event subclass. (got {name}={emitter})',
deferred=True,
name=name,
emitter=emitter,
)
)
# give this emitter the same source as the group.
emitter.source = self.source
setattr(self, name, emitter) # this is a bummer for typing.
self._emitters[name] = emitter
if (
auto_connect
and self.source is not None
and hasattr(self.source, self.auto_connect_format % name)
):
emitter.connect((self.source, self.auto_connect_format % name))
# If emitters are connected to the group already, then this one
# should be connected as well.
if self._emitters_connected:
emitter.connect(self)
@property
def emitters(self) -> Dict[str, EventEmitter]:
"""List of current emitters in this group."""
return self._emitters
def __iter__(self) -> Generator[str, None, None]:
"""
Iterates over the names of emitters in this group.
"""
yield from self._emitters
[docs] def block_all(self):
"""
Block all emitters in this group by increase counter of semaphores for each event emitter
"""
self.block()
for em in self._emitters.values():
em.block()
[docs] def unblock_all(self):
"""
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
https://en.wikipedia.org/wiki/Semaphore_(programming)
"""
self.unblock()
for em in self._emitters.values():
em.unblock()
[docs] def connect(
self,
callback: Union[Callback, CallbackRef, 'EmitterGroup'],
ref: Union[bool, str] = False,
position: Union[Literal['first'], Literal['last']] = 'first',
before: Union[str, Callback, List[Union[str, Callback]], None] = None,
after: Union[str, Callback, List[Union[str, Callback]], None] = None,
):
"""Connect the callback to the event group. The callback will receive
events from *all* of the emitters in the group.
See :func:`EventEmitter.connect() <vispy.event.EventEmitter.connect>`
for arguments.
"""
self._connect_emitters(True)
return EventEmitter.connect(
self, callback, ref, position, before, after
)
[docs] def disconnect(self, callback: Optional[Callback] = None):
"""Disconnect the callback from this group. See
:func:`connect() <vispy.event.EmitterGroup.connect>` and
:func:`EventEmitter.connect() <vispy.event.EventEmitter.connect>` for
more information.
"""
ret = EventEmitter.disconnect(self, callback)
if len(self._callbacks) == 0:
self._connect_emitters(False)
return ret
def _connect_emitters(self, connect):
# Connect/disconnect all sub-emitters from the group. This allows the
# group to emit an event whenever _any_ of the sub-emitters emit,
# while simultaneously eliminating the overhead if nobody is listening.
if connect:
for emitter in self:
if not isinstance(self[emitter], WarningEmitter):
self[emitter].connect(self)
else:
for emitter in self:
self[emitter].disconnect(self)
self._emitters_connected = connect
@property
def ignore_callback_errors(self):
return super().ignore_callback_errors
@ignore_callback_errors.setter
def ignore_callback_errors(self, ignore):
EventEmitter.ignore_callback_errors.fset(self, ignore)
for emitter in self._emitters.values():
if isinstance(emitter, EventEmitter):
emitter.ignore_callback_errors = ignore
elif isinstance(emitter, EmitterGroup):
emitter.ignore_callback_errors_all(ignore)
[docs] def blocker_all(self) -> 'EventBlockerAll':
"""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..
"""
return EventBlockerAll(self)
class EventBlocker:
"""Represents a block for an EventEmitter to be used in a context
manager (i.e. 'with' statement).
"""
def __init__(self, target, callback=None):
self.target = target
self.callback = callback
self._base_count = target._block_counter.get(callback, 0)
@property
def count(self):
n_blocked = self.target._block_counter.get(self.callback, 0)
return n_blocked - self._base_count
def __enter__(self):
self.target.block(self.callback)
return self
def __exit__(self, *args):
self.target.unblock(self.callback)
class EventBlockerAll:
"""Represents a block_all for an EmitterGroup to be used in a context
manager (i.e. 'with' statement).
"""
def __init__(self, target):
self.target = target
def __enter__(self):
self.target.block_all()
def __exit__(self, *args):
self.target.unblock_all()
def _is_pos_arg(param: inspect.Parameter):
"""
Check if param is positional or named and has no default parameter.
"""
return (
param.kind
in [
inspect.Parameter.POSITIONAL_ONLY,
inspect.Parameter.POSITIONAL_OR_KEYWORD,
]
and param.default == inspect.Parameter.empty
)
try:
# this could move somewhere higher up in napari imports ... but where?
__import__('dotenv').load_dotenv()
except ImportError:
pass
def _noop(*a, **k):
pass
_log_event_stack = _noop
[docs]def set_event_tracing_enabled(enabled=True, cfg=None):
global _log_event_stack
if enabled:
from .debugging import log_event_stack
if cfg is not None:
_log_event_stack = partial(log_event_stack, cfg=cfg)
else:
_log_event_stack = log_event_stack
else:
_log_event_stack = _noop
if os.getenv("NAPARI_DEBUG_EVENTS", '').lower() in ('1', 'true'):
set_event_tracing_enabled(True)