# -*- 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() ` or :func:`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 `. 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 `. 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 `, 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)) `. This provides a simple mechanism for automatically connecting a large group of emitters to default callbacks. emitters : keyword arguments See the :func:`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() ` 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() ` and :func:`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)