vispy 0.15.0__cp313-cp313-win_amd64.whl

vispy/util/event.py

@@ -0,0 +1,774 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+
+"""
+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
+
+"""
+
+from __future__ import division
+
+from collections import OrderedDict
+import inspect
+import traceback
+import weakref
+
+from .logs import logger, _handle_exception
+
+
+class Event(object):
+    """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, native=None, **kwargs):
+        # stack of all sources this event has been emitted through
+        self._sources = []
+        self._handled = False
+        self._blocked = False
+        # Store args
+        self._type = type
+        self._native = native
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+    @property
+    def source(self):
+        """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 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):
+        # No docstring; documeted in class docstring
+        return self._type
+
+    @property
+    def native(self):
+        # No docstring; documeted in class docstring
+        return self._native
+
+    @property
+    def handled(self):
+        """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):
+        self._handled = bool(val)
+
+    @property
+    def blocked(self):
+        """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):
+        self._blocked = bool(val)
+
+    def __repr__(self):
+        # 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("%s=%s" % (name, attr))
+            return "<%s %s>" % (self.__class__.__name__, " ".join(attrs))
+        finally:
+            _event_repr_depth -= 1
+
+    def __str__(self):
+        """Shorter string representation"""
+        return self.__class__.__name__
+
+_event_repr_depth = 0
+
+
+class EventEmitter(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
+    :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=None, type=None, event_class=Event):
+        self._callbacks = []
+        self._callback_refs = []
+
+        # count number of times this emitter is blocked for each callback.
+        self._blocked = {None: 0}
+
+        # used to detect emitter loops
+        self._emitting = 0
+        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 = True
+        self.print_callback_errors = 'reminders'
+
+    @property
+    def ignore_callback_errors(self):
+        """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):
+        self._ignore_callback_errors = val
+
+    @property
+    def print_callback_errors(self):
+        """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):
+        if val not in ('first', 'reminders', 'always', 'never'):
+            raise ValueError('print_callback_errors must be "first", '
+                             '"reminders", "always", or "never"')
+        self._print_callback_errors = val
+
+    @property
+    def callback_refs(self):
+        """The set of callback references"""
+        return tuple(self._callback_refs)
+
+    @property
+    def callbacks(self):
+        """The set of callbacks"""
+        return tuple(self._callbacks)
+
+    @property
+    def source(self):
+        """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):
+        if s is None:
+            self._source = None
+        else:
+            self._source = weakref.ref(s)
+
+    def connect(self, callback, ref=False, position='first',
+                before=None, after=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.
+
+        Notes
+        -----
+        If ``ref=True``, the callback reference will be determined from:
+
+            1. If ``callback`` is ``tuple``, the secend 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
+
+        callback = self._normalize_cb(callback)
+
+        if callback in callbacks:
+            return
+
+        # deal with the ref
+        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 not isinstance(ref, str):
+            raise TypeError('ref must be a bool or string')
+        if ref is not None and ref in self._callback_refs:
+            raise ValueError('ref "%s" is not unique' % ref)
+
+        # positions
+        if position not in ('first', 'last'):
+            raise ValueError('position must be "first" or "last", not %s'
+                             % position)
+
+        # bounds
+        bounds = list()  # upper & lower bnds (inclusive) of possible cb locs
+        for ri, criteria in enumerate((before, after)):
+            if criteria is None or criteria == []:
+                bounds.append(len(callback_refs) if ri == 0 else 0)
+            else:
+                if not isinstance(criteria, list):
+                    criteria = [criteria]
+                for c in criteria:
+                    count = sum([(c == cn or c == cc) for cn, cc
+                                 in zip(callback_refs, callbacks)])
+                    if count != 1:
+                        raise ValueError('criteria "%s" is in the current '
+                                         'callback list %s times:\n%s\n%s'
+                                         % (criteria, count,
+                                            callback_refs, 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('cannot place callback before "%s" '
+                               'and after "%s" for callbacks: %s'
+                               % (before, after, 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)
+        return callback  # allows connect to be used as a decorator
+
+    def disconnect(self, callback=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 = []
+        else:
+            callback = self._normalize_cb(callback)
+            if callback in self._callbacks:
+                idx = self._callbacks.index(callback)
+                self._callbacks.pop(idx)
+                self._callback_refs.pop(idx)
+
+    def _normalize_cb(self, callback):
+        # dereference methods into a (self, method_name) pair so that we can
+        # make the connection without making a strong reference to the
+        # instance.
+        if inspect.ismethod(callback):
+            callback = (callback.__self__, callback.__name__)
+
+        # always use a weak ref
+        if (isinstance(callback, tuple) and not
+                isinstance(callback[0], weakref.ref)):
+            callback = (weakref.ref(callback[0]),) + callback[1:]
+
+        return callback
+
+    def __call__(self, *args, **kwargs):
+        """__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 += 1
+        try:
+            if blocked.get(None, 0) > 0:  # this is the same as self.blocked()
+                return event
+
+            rem = []
+            for cb in self._callbacks[:]:
+                if isinstance(cb, tuple):
+                    obj = cb[0]()
+                    if obj is None:
+                        rem.append(cb)
+                        continue
+                    cb = getattr(obj, cb[1], None)
+                    if cb is None:
+                        continue
+
+                if blocked.get(cb, 0) > 0:
+                    continue
+
+                if self._emitting > 1:
+                    raise RuntimeError('EventEmitter loop detected!')
+
+                self._invoke_callback(cb, event)
+                if event.blocked:
+                    break
+
+            # remove callbacks to dead objects
+            for cb in rem:
+                self.disconnect(cb)
+        finally:
+            self._emitting -= 1
+            if event._pop_source() != self.source:
+                raise RuntimeError("Event source-stack mismatch.")
+
+        return event
+
+    def _invoke_callback(self, cb, event):
+        try:
+            cb(event)
+        except Exception:
+            _handle_exception(self.ignore_callback_errors,
+                              self.print_callback_errors,
+                              self, cb_event=(cb, event))
+
+    def _prepare_event(self, *args, **kwargs):
+        # 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 = args[0]
+            # Ensure that the given event matches what we want to emit
+            assert isinstance(event, self.event_class)
+        elif not args:
+            args = self.default_args.copy()
+            args.update(kwargs)
+            event = self.event_class(**args)
+        else:
+            raise ValueError("Event emitters can be called with an Event "
+                             "instance or with keyword arguments only.")
+        return event
+
+    def blocked(self, callback=None):
+        """Return boolean indicating whether the emitter is blocked for
+        the given callback.
+        """
+        return self._blocked.get(callback, 0) > 0
+
+    def block(self, 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
+
+    def unblock(self, 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("Cannot unblock %s for callback %s; emitter "
+                               "was not previously blocked." %
+                               (self, callback))
+        b = self._blocked[callback] - 1
+        if b == 0 and callback is not None:
+            del self._blocked[callback]
+        else:
+            self._blocked[callback] = b
+
+    def blocker(self, callback=None):
+        """Return an EventBlocker to be used in 'with' statements.
+
+        Examples
+        --------
+        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, *args, **kwargs):
+        self._message = message
+        self._warned = False
+        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
+
+        traceback.print_stack()
+        logger.warning(self._message)
+        self._warned = True
+
+
+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 (default), 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.
+    emitters : keyword arguments
+        See the :func:`add <vispy.event.EmitterGroup.add>` method.
+    """
+
+    def __init__(self, source=None, auto_connect=True, **emitters):
+        EventEmitter.__init__(self, source)
+
+        self.auto_connect = auto_connect
+        self.auto_connect_format = "on_%s"
+        self._emitters = OrderedDict()
+        # whether the sub-emitters have been connected to the group:
+        self._emitters_connected = False
+        self.add(**emitters)
+
+    def __getitem__(self, name):
+        """
+        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, emitter):
+        """Alias for EmitterGroup.add(name=emitter)"""
+        self.add(**{name: emitter})
+
+    def add(self, auto_connect=None, **kwargs):
+        """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(
+                    "EmitterGroup already has an emitter named '%s'" %
+                    name)
+            elif hasattr(self, name):
+                raise ValueError("The name '%s' cannot be used as an emitter; "
+                                 "it is already an attribute of EmitterGroup"
+                                 % 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):
+                emitter = EventEmitter(
+                    source=self.source,
+                    type=name,
+                    event_class=emitter)
+            elif not isinstance(emitter, EventEmitter):
+                raise Exception('Emitter must be specified as either an '
+                                'EventEmitter instance or Event subclass. '
+                                '(got %s=%s)' % (name, emitter))
+
+            # give this emitter the same source as the group.
+            emitter.source = self.source
+
+            setattr(self, name, emitter)
+            self._emitters[name] = emitter
+
+            if auto_connect and self.source is not None:
+                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):
+        """List of current emitters in this group."""
+        return self._emitters
+
+    def __iter__(self):
+        """Iterates over the names of emitters in this group."""
+        for k in self._emitters:
+            yield k
+
+    def block_all(self):
+        """Block all emitters in this group."""
+        self.block()
+        for em in self._emitters.values():
+            em.block()
+
+    def unblock_all(self):
+        """Unblock all emitters in this group."""
+        self.unblock()
+        for em in self._emitters.values():
+            em.unblock()
+
+    def connect(self, callback, ref=False, position='first',
+                before=None, after=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)
+
+    def disconnect(self, 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:
+                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(EventEmitter, self).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)
+
+
+class EventBlocker(object):
+    """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
+
+    def __enter__(self):
+        self.target.block(self.callback)
+
+    def __exit__(self, *args):
+        self.target.unblock(self.callback)