Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 57 ยท 3D, Animation and Advanced

Interactivity and Widgets

Learn matplotlib backends, mpl_connect events, Slider, Button and CheckButtons, picking, and the zoom toolbar, with simulated events that render static frames.

Most Matplotlib charts are pictures, but a figure can also react: you can drag a slider to change a curve, click a point to select it, or press a key to toggle a layer. All of this is built on one mechanism, the event system, plus a set of ready-made widgets.

Interactivity needs a window (or a notebook widget) to receive the mouse. A static page like this one has none, so here we do the interesting thing: we create real widgets, simulate the events by hand, and draw the resulting frames. Everything you learn works unchanged in a real window. You should be comfortable with the object-oriented API and subplots.

Backends: where figures are drawn

A backend turns the figure into something you can see or save. Interactive backends open windows; non-interactive ones render files.

Backend Kind Typical use
Agg non-interactive, PNG servers, tests, this site
module://matplotlib_inline.backend_inline non-interactive images Jupyter default (inline)
QtAgg, TkAgg, GTK4Agg, macosx interactive windows scripts and the Python REPL
ipympl (%matplotlib widget) interactive in notebooks zoom and widgets inside Jupyter
webagg interactive in a browser tab remote machines, no desktop

Choose a backend with matplotlib.use("QtAgg") before importing pyplot, with the MPLBACKEND environment variable, or with a notebook magic. matplotlib.get_backend() tells you the current one. The warning "FigureCanvasAgg is non-interactive, and thus cannot be shown" means exactly this: you called plt.show() on a backend with no window.

Three ways to interact

Events React to clicks, keys and scrolls.
Widgets Slider, Button, CheckButtons.
Toolbar Zoom, pan and save, built in.

Events are the foundation; widgets are events with a nice face.

1 / 2

The event system and mpl_connect

Every canvas has an event dispatcher. You register a function with fig.canvas.mpl_connect(event_name, callback). The callback receives an event object. The common event names are:

  • button_press_event, button_release_event, motion_notify_event (mouse)
  • scroll_event (wheel)
  • key_press_event, key_release_event (keyboard)
  • pick_event (an artist was clicked)
  • resize_event, draw_event, figure_enter_event, axes_enter_event

A mouse event has event.x and event.y (pixels), event.xdata and event.ydata (data coordinates, or None when the mouse is outside an Axes), event.inaxes (the Axes or None) and event.button. Always check event.inaxes first. mpl_connect returns an id you pass to fig.canvas.mpl_disconnect(cid) to stop listening.

Python
def on_click(event):
    if event.inaxes is None:
        return
    print(f"clicked at x={event.xdata:.2f}, y={event.ydata:.2f}")

cid = fig.canvas.mpl_connect("button_press_event", on_click)

In a window the click would come from a real mouse. To try the same callback here, we build the event ourselves. MouseEvent takes pixel coordinates, which we get from ax.transData.transform (you will meet transforms in Transforms and the Artist Layer).

Python Click-to-place points with simulated events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The callback is identical to what you would write for a window. Only the source of the events differs.

Widgets: Slider, Button and CheckButtons

The matplotlib.widgets module builds common controls out of Axes. Each widget needs its own small Axes to live in, created with fig.add_axes([left, bottom, width, height]) in figure fractions, and you must keep a reference to the widget object or it stops responding.

  • Slider(ax, label, valmin, valmax, valinit=...): on_changed(func) calls func(value).
  • Button(ax, label): on_clicked(func).
  • CheckButtons(ax, labels, actives): on_clicked(func) receives the label that was toggled; get_status() returns the booleans.
  • RadioButtons, TextBox, RangeSlider, SpanSelector, RectangleSelector and LassoSelector cover choices, text and region selection.

The pattern is always the same: the callback changes artist data, then calls fig.canvas.draw_idle(). To drive a slider in code, call slider.set_val(value), which behaves like a drag.

Python A slider and a checkbox, driven in code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The frame you see is the state after the simulated drag and click. In a real window the figure would update continuously while you drag.

Picking: clicking on artists

Mouse events tell you where the click happened. Picking tells you which artist was hit. Mark an artist as pickable with picker=True (or a radius in points for lines and scatter points), then listen for pick_event. The event has event.artist and, for collections and lines, event.ind, the indices of the picked data points.

Python
sc = ax.scatter(x, y, picker=5)         # pick within 5 points of a marker

def on_pick(event):
    i = event.ind[0]
    print("picked point", i, x[i], y[i])

fig.canvas.mpl_connect("pick_event", on_pick)

Picking is how clickable legends (toggle a line when its legend entry is clicked) and "click a point to show its label" features are built. Because the picking test is done by the artist itself, you can control the hit area with the number you pass.

The toolbar: zoom, pan and save

Interactive backends add a toolbar to each window. You rarely code this, but you should know it exists:

  • Home / Back / Forward step through the view history.
  • Pan (drag with the left button) moves the view; zoom (drag a rectangle) magnifies it.
  • Configure subplots adjusts spacing; save writes the figure to a file at the current dpi.
  • Keyboard shortcuts: s save, g toggle grid, l toggle log y scale, k toggle log x scale, f fullscreen, q close.

Zooming only changes the view limits, never your data. You can react to it with ax.callbacks.connect("xlim_changed", func), which is how plots that load more detail when you zoom in are built.

Set plt.rcParams["toolbar"] = "None" to hide the toolbar, for example in a kiosk-style app. In a script, nothing runs after plt.show() until the window is closed, so keep your callbacks short.

Notebooks versus scripts

In a script, plt.show() starts the GUI event loop and blocks until you close the window; widgets and callbacks work out of the box with a GUI backend. In a Jupyter notebook, the default inline backend produces a static image after each cell, so callbacks never fire: switch to %matplotlib widget (the ipympl package) for interactivity, or use ipywidgets with a function that redraws the figure on every change. On a server, use Agg and produce files, and leave interactivity to a web front end. On this site you have seen the fourth way: simulated events producing static frames, which is also how you can unit-test callbacks without any GUI.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you register a function to run when the mouse is clicked on a figure?

    mpl_connect on the canvas takes an event name and a callback and returns a connection id you can later pass to mpl_disconnect.
  2. 2. What does event.inaxes tell you in a mouse callback?

    Check event.inaxes first. xdata and ydata are only meaningful inside an Axes; outside they are None.
  3. 3. Why must you keep a reference to a Slider object?

    Widgets rely on callbacks held by the widget object. If it is garbage collected, the control stops working.
  4. 4. Which backend gives you interactive figures inside a Jupyter notebook?

    The inline backend only shows static images. ipympl provides an interactive canvas inside the notebook.

Summary

  • A backend decides how a figure is displayed; Agg is non-interactive, while Qt, Tk, ipympl and webagg can respond to the mouse.
  • fig.canvas.mpl_connect(name, callback) registers a listener; mouse events carry xdata, ydata, inaxes and button, and mpl_disconnect removes the listener.
  • Slider, Button, CheckButtons, RadioButtons and selectors live in their own Axes; keep references and call draw_idle() after changing data.
  • Picking (picker=... with pick_event) identifies the artist or data point that was clicked.
  • The toolbar zooms and pans by changing view limits only.
  • Callbacks can be tested without a GUI by building events and processing them, as the examples here do.

Next, look under the hood in Transforms and the Artist Layer.