Events¶

Rayon can produce a wide variety of static visualizations. It also has basic support for event processing when used with a supported GUI backend (see Installing for supported backends). Rayon can respond to various GUI events and report what sub-components within a data visualization were clicked on, dragged over, etc.

To enable Rayon to process events for a visualization, it is necessary to associate a chart with an event source – a component on the GUI that emits events. Usually, the most appropriate event source is the component to which the chart is/will be drawn to, but that isn’t a requirement.

The object representing the binding of a chart to an event source is the . This object translates the low-level events emitted by the GUI backend into a set of generic events to which Rayon responds. If the chart has registered interest in the translated even, it then passes the event on to the Chart object for processing.

The following example demonstrates how to handle an event from the GUI in Rayon, in this case a user hovering over a bar in a bar plot long enough to trigger a tooltip:

class MyBarListener(events.EventListener):
    def on_tooltip_(self, target, evt):
        bars = target.bars_at(
            evt.get_x(), evt.get_y())
        if len(bars) > 0:
            evt.set_tooltip(str(bars[0]), 1)

# chart is a Chart. component is a BarPlot.
# event_source comes from the GUI system.

component = chart.get_plot('bars')
listener = MyBarListener(component)

source = chart.get_event_source(gui_event_source,
                                activate=False)
listener.register_with(source)

In order to register interest in an event, it is necessary to have a listener object for that event. Therefore, we first create a subclass of the ComponentListenter class. This class handles one event, tooltip; however, a single ComponentListenter object can handle multiple events that might occur to a single component. on_tooltip uses target (the Rayon object handling the event – in this case a Barplot) and evt (a description of the event) to locate the portion of target that was affected and display a tooltip specific to it. (In this case, the string representation of a bar in the bar plot.) Finally, we associate an instance of MyBarListener with component – the BarPlot object that will be passed into on_tooltip as target.

Now, we need to attach our EventListener object to something that emits events. The get_event_source returns the EventSource object associated with both the Chart object and the supplied source of events. (In wxWidgets, this is usually the wxPanel object on which the Chart object is being drawn.)

By default, Rayon will start processing events from the GUI immediately; this may not always be appropriate. Since we haven’t yet drawn the chart, we know we should not yet respond to any events sent from event_source. Therefore, we pass activate a value of False; when we have drawn the chart, we will call the activate method to begin receiving events.

Finally, we indicate that listener should be listening to events sent from source by calling register_with. This connects the ComponentListenter object to the EventSource object; listener will now receive and process events.