# vispy.util.event module

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

class vispy.util.event.EmitterGroup(source=None, auto_connect=True, **emitters)

  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 (default), 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.

    emitters keyword arguments

      See the `add` method.

  add(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))

  block_all()

    Block all emitters in this group.

  connect(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 `EventEmitter.connect()` for arguments.

  disconnect(callback=None)

    Disconnect the callback from this group. See `connect()` and `EventEmitter.connect()` for more information.

  property emitters

    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.

  unblock_all()

    Unblock all emitters in this group.

class vispy.util.event.Event(type, native=None, **kwargs)

  Bases: `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: `KeyEvent`, `MouseEvent`, `TouchEvent`, `StylusEvent`

  The creation of events and passing of events to the appropriate callback functions is the responsibility of `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.

  property blocked

    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.

  property handled

    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.

  property native
  property source

    The object that the event applies to (i.e. the source of the event).

  property sources

    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.

  property type

class vispy.util.event.EventBlocker(target, callback=None)

  Bases: `object`

  Represents a block for an EventEmitter to be used in a context manager (i.e. ‘with’ statement).

class vispy.util.event.EventEmitter(source=None, type=None, event_class=<class 'vispy.util.event.Event'>)

  Bases: `object`

  Encapsulates a list of event callbacks.

  Each instance of EventEmitter represents the source of a stream of similar events, such as mouse click events or timer activation events. For example, the following diagram shows the propagation of a mouse click event to the list of callbacks that are registered to listen for that event:

      User clicks    |Canvas creates
      mouse on       |MouseEvent:                |'mouse_press' EventEmitter:         |callbacks in sequence: # noqa
      Canvas         |                           |                                    |  # noqa
                  -->|event = MouseEvent(...) -->|Canvas.events.mouse_press(event) -->|callback1(event)  # noqa
                     |                           |                                 -->|callback2(event)  # noqa
                     |                           |                                 -->|callback3(event)  # noqa

  Callback functions may be added or removed from an EventEmitter using `connect()` or `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 `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.

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

  blocked(callback=None)

    Return boolean indicating whether the emitter is blocked for the given callback.

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

  property callback_refs

    The set of callback references

  property callbacks

    The set of callbacks

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

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

  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

    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

    The object that events generated by this emitter apply to

  unblock(callback=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)`.

class vispy.util.event.WarningEmitter(message, *args, **kwargs)

  Bases: `EventEmitter`

  EventEmitter subclass used to allow deprecated events to be used with a warning message.

  connect(cb, *args, **kwargs)

    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.

previous

vispy.util.eq module

next

vispy.util.fetching module