cozmo.event

Event dispatch system.

The SDK is based around the dispatch and observation of events. Objects inheriting from the Dispatcher generate and dispatch events as the state of the robot and its world are updated.

For example the cozmo.objects.LightCube class generates an EvtObjectTapped event anytime the cube the object represents is tapped.

The event can be observed in a number of different ways:

  1. By calling the wait_for() method on the object to observe. This will wait until the specific event has been sent to that object and return the generated event.

  2. By calling add_event_handler() on the object to observe, which will cause the supplied function to be called every time the specified event occurs (use the oneshot() decorator to only have the handler called once)

  3. By sub-classing a type and implementing a receiver method. For example, subclass the cozmo.objects.LightCube type and implement evt_object_tapped. Note that the factory attribute would need to be updated on the generating class for your type to be used by the SDK. For example, light_cube_factory in this example.

  4. By subclassing a type and implementing a default receiver method. Events not dispatched to an explicit receiver method are dispatched to recv_default_handler.

Events are dispatched to a target object (by calling dispatch_event() on the receiving object). In line with the above, upon receiving an event, the object will:

  1. Dispatch the event to any handlers which have explicitly registered interest in the event (or a superclass of the event) via add_event_handler() or via Dispatcher.wait_for()

  2. Dispatch the event to any “children” of the object (see below)

  3. Dispatch the event to method handlers on the receiving object, or the recv_default_handler if it has no matching handler

  4. Dispatch the event to the parent of the object (if any), and in turn onto the parent’s parents.

Any handler may raise a StopPropogation exception to prevent the event reaching any subsequent handlers (but generally should have no need to do so).

Child objects receive all events that are sent to the originating object (which may have multiple children).

Originating objects may have one parent object, which receives all events sent to its child.

For example, cozmo.robot.Robot creates a cozmo.world.World object and sets itself as a parent and the World as the child; both receive events sent to the other.

The World class creates individual cozmo.objects.ObservableObject objects as they are discovered and makes itself a parent, so as to receive all events sent to the child. However, it does not make those ObservableObject objects children for the sake of message dispatch as they only need to receive a small subset of messages the World object receives.

Functions

filter_handler(event, **filters)

Decorates a handler function or Future to only be called if a filter is matched.

oneshot(f)

Event handler decorator; causes the handler to only be dispatched to once.

wait_for_first(*futures[, ...])

Wait the first of a set of futures to complete.

Classes

Dispatcher(*a[, dispatch_parent, loop])

Mixin to provide event dispatch handling.

Event(**kwargs)

An event representing an action that has occurred.

Filter(event, **filters)

Provides fine-grain filtering of events for dispatch.

Handler(obj, evt, f)

A Handler is returned by Dispatcher.add_event_handler()

NullHandler(obj, evt, f)

docstr