matplotlib.widgets

GUI neutral widgets

Widgets that are designed to work for any of the GUI backends. All of these widgets require you to predefine a matplotlib.axes.Axes instance and pass that as the first parameter. Matplotlib doesn't try to be too smart with respect to layout -- you will have to figure out how wide and tall you want your Axes to be to accommodate your widget.

class matplotlib.widgets.AxesWidget(ax) [source]

Bases: matplotlib.widgets.Widget

Widget connected to a single Axes.

To guarantee that the widget remains responsive and not garbage-collected, a reference to the object should be maintained by the user.

This is necessary because the callback registry maintains only weak-refs to the functions, which are member functions of the widget. If there are no references to the widget object it may be garbage collected which will disconnect the callbacks.

Attributes:	axAxes The parent axes for the widget. canvasFigureCanvasBase The parent figure canvas for the widget. activebool Is the widget active?

connect_event(self, event, callback) [source]

Connect callback with an event.

This should be used in lieu of figure.canvas.mpl_connect since this function stores callback ids for later clean up.

disconnect_events(self) [source]

Disconnect all events created by this widget.

class matplotlib.widgets.Button(ax, label, image=None, color='0.85', hovercolor='0.95') [source]

Bases: matplotlib.widgets.AxesWidget

A GUI neutral button.

For the button to remain responsive you must keep a reference to it. Call on_clicked to connect to the button.

Attributes:	ax The matplotlib.axes.Axes the button renders into. label A matplotlib.text.Text instance. color The color of the button when not hovering. hovercolor The color of the button when hovering.

Parameters:	axAxes The Axes instance the button will be placed into. labelstr The button text. imagearray-like or PIL Image The image to place in the button, if not None. The parameter is directly forwarded to imshow. colorcolor The color of the button when not activated. hovercolorcolor The color of the button when the mouse is over it.

disconnect(self, cid) [source]

Remove the callback function with connection id cid.

on_clicked(self, func) [source]

Connect the callback function func to button click events.

Returns a connection id, which can be used to disconnect the callback.

class matplotlib.widgets.CheckButtons(ax, labels, actives=None) [source]

Bases: matplotlib.widgets.AxesWidget

A GUI neutral set of check buttons.

For the check buttons to remain responsive you must keep a reference to this object.

Connect to the CheckButtons with the on_clicked method.

Attributes:	axAxes The parent axes for the widget. labelslist of Text rectangleslist of Rectangle lineslist of (Line2D, Line2D) pairs List of lines for the x's in the check boxes. These lines exist for each box, but have set_visible(False) when its box is not checked.

Add check buttons to matplotlib.axes.Axes instance ax

Parameters:	axAxes The parent axes for the widget. labelslist of str The labels of the check buttons. activeslist of bool, optional The initial check states of the buttons. The list must have the same length as labels. If not given, all buttons are unchecked.

disconnect(self, cid) [source]

Remove the observer with connection id cid.

get_status(self) [source]

Return a tuple of the status (True/False) of all of the check buttons.

on_clicked(self, func) [source]

Connect the callback function func to button click events.

Returns a connection id, which can be used to disconnect the callback.

set_active(self, index) [source]

Toggle (activate or deactivate) a check button by index.

Callbacks will be triggered if eventson is True.

Parameters:	indexint Index of the check button to toggle.
Raises:	ValueError If index is invalid.

class matplotlib.widgets.Cursor(ax, horizOn=True, vertOn=True, useblit=False, **lineprops) [source]

Bases: matplotlib.widgets.AxesWidget

A crosshair cursor that spans the axes and moves with mouse cursor.

For the cursor to remain responsive you must keep a reference to it.

Parameters:	axmatplotlib.axes.Axes The Axes to attach the cursor to. horizOnbool, default: True Whether to draw the horizontal line. vertOnbool, default: True Whether to draw the vertical line. useblitbool, default: False Use blitting for faster drawing if supported by the backend.
Other Parameters:	**lineprops Line2D properties that control the appearance of the lines. See also axhline.

Examples

See Cursor.

clear(self, event) [source]

Internal event handler to clear the cursor.

onmove(self, event) [source]

Internal event handler to draw the cursor when the mouse moves.

class matplotlib.widgets.EllipseSelector(ax, onselect, drawtype='box', minspanx=0, minspany=0, useblit=False, lineprops=None, rectprops=None, spancoords='data', button=None, maxdist=10, marker_props=None, interactive=False, state_modifier_keys=None) [source]

Bases: matplotlib.widgets.RectangleSelector

Select an elliptical region of an axes.

For the cursor to remain responsive you must keep a reference to it.

Example usage:

import numpy as np
import matplotlib.pyplot as plt
from matplotlib.widgets import EllipseSelector

def onselect(eclick, erelease):
    "eclick and erelease are matplotlib events at press and release."
    print('startposition: (%f, %f)' % (eclick.xdata, eclick.ydata))
    print('endposition  : (%f, %f)' % (erelease.xdata, erelease.ydata))
    print('used button  : ', eclick.button)

def toggle_selector(event):
    print(' Key pressed.')
    if event.key in ['Q', 'q'] and toggle_selector.ES.active:
        print('EllipseSelector deactivated.')
        toggle_selector.RS.set_active(False)
    if event.key in ['A', 'a'] and not toggle_selector.ES.active:
        print('EllipseSelector activated.')
        toggle_selector.ES.set_active(True)

x = np.arange(100.) / 99
y = np.sin(x)
fig, ax = plt.subplots()
ax.plot(x, y)

toggle_selector.ES = EllipseSelector(ax, onselect, drawtype='line')
fig.canvas.mpl_connect('key_press_event', toggle_selector)
plt.show()

Parameters:

axAxes The parent axes for the widget. onselectfunction A callback function that is called after a selection is completed. It must have the signature: def onselect(eclick: MouseEvent, erelease: MouseEvent) where eclick and erelease are the mouse click and release MouseEvents that start and complete the selection. drawtype{"box", "line", "none"}, default: "box" Whether to draw the full rectangle box, the diagonal line of the rectangle, or nothing at all. minspanxfloat, default: 0 Selections with an x-span less than minspanx are ignored. minspanyfloat, default: 0 Selections with an y-span less than minspany are ignored. useblitbool, default: False Whether to use blitting for faster drawing (if supported by the backend). linepropsdict, optional Properties with which the line is drawn, if drawtype == "line". Default: dict(color="black", linestyle="-", linewidth=2, alpha=0.5) rectpropsdict, optional Properties with which the rectangle is drawn, if drawtype == "box". Default: dict(facecolor="red", edgecolor="black", alpha=0.2, fill=True) spancoords{"data", "pixels"}, default: "data" Whether to interpret minspanx and minspany in data or in pixel coordinates. buttonMouseButton, list of MouseButton, default: all buttons Button(s) that trigger rectangle selection. maxdistfloat, default: 10 Distance in pixels within which the interactive tool handles can be activated. marker_propsdict Properties with which the interactive handles are drawn. Currently not implemented and ignored. interactivebool, default: False Whether to draw a set of handles that allow interaction with the widget after it is drawn. state_modifier_keysdict, optional Keyboard modifiers which affect the widget's behavior. Values amend the defaults. "move": Move the existing shape, default: no modifier. "clear": Clear the current shape, default: "escape". "square": Makes the shape square, default: "shift". "center": Make the initial point the center of the shape, default: "ctrl". "square" and "center" can be combined.

draw_shape(self, extents) [source]

class matplotlib.widgets.Lasso(ax, xy, callback=None, useblit=True) [source]

Bases: matplotlib.widgets.AxesWidget

Selection curve of an arbitrary shape.

The selected path can be used in conjunction with contains_point to select data points from an image.

Unlike LassoSelector, this must be initialized with a starting point xy, and the Lasso events are destroyed upon release.

Parameters:	axAxes The parent axes for the widget. xy(float, float) Coordinates of the start of the lasso. callbackcallable Whenever the lasso is released, the callback function is called and passed the vertices of the selected path.

onmove(self, event) [source]

onrelease(self, event) [source]

class matplotlib.widgets.LassoSelector(ax, onselect=None, useblit=True, lineprops=None, button=None) [source]

Bases: matplotlib.widgets._SelectorWidget

Selection curve of an arbitrary shape.

For the selector to remain responsive you must keep a reference to it.

The selected path can be used in conjunction with contains_point to select data points from an image.

In contrast to Lasso, LassoSelector is written with an interface similar to RectangleSelector and SpanSelector, and will continue to interact with the axes until disconnected.

Example usage:

ax = subplot(111)
ax.plot(x, y)

def onselect(verts):
    print(verts)
lasso = LassoSelector(ax, onselect)

Parameters:	axAxes The parent axes for the widget. onselectfunction Whenever the lasso is released, the onselect function is called and passed the vertices of the selected path. buttonMouseButton or list of MouseButton, optional The mouse buttons used for rectangle selection. Default is None, which corresponds to all buttons.

onpress(self, event) [source]

onrelease(self, event) [source]

class matplotlib.widgets.LockDraw [source]

Bases: object

Some widgets, like the cursor, draw onto the canvas, and this is not desirable under all circumstances, like when the toolbar is in zoom-to-rect mode and drawing a rectangle. To avoid this, a widget can acquire a canvas' lock with canvas.widgetlock(widget) before drawing on the canvas; this will prevent other widgets from doing so at the same time (if they also try to acquire the lock first).

available(self, o) [source]

Return whether drawing is available to o.

isowner(self, o) [source]

Return whether o owns this lock.

locked(self) [source]

Return whether the lock is currently held by an owner.

release(self, o) [source]

Release the lock from o.

class matplotlib.widgets.MultiCursor(canvas, axes, useblit=True, horizOn=False, vertOn=True, **lineprops) [source]

Bases: matplotlib.widgets.Widget

Provide a vertical (default) and/or horizontal line cursor shared between multiple axes.

For the cursor to remain responsive you must keep a reference to it.

Example usage:

from matplotlib.widgets import MultiCursor
import matplotlib.pyplot as plt
import numpy as np

fig, (ax1, ax2) = plt.subplots(nrows=2, sharex=True)
t = np.arange(0.0, 2.0, 0.01)
ax1.plot(t, np.sin(2*np.pi*t))
ax2.plot(t, np.sin(4*np.pi*t))

multi = MultiCursor(fig.canvas, (ax1, ax2), color='r', lw=1,
                    horizOn=False, vertOn=True)
plt.show()

clear(self, event) [source]

Clear the cursor.

connect(self) [source]

Connect events.

disconnect(self) [source]

Disconnect events.

onmove(self, event) [source]

class matplotlib.widgets.PolygonSelector(ax, onselect, useblit=False, lineprops=None, markerprops=None, vertex_select_radius=15) [source]

Bases: matplotlib.widgets._SelectorWidget

Select a polygon region of an axes.

Place vertices with each mouse click, and make the selection by completing the polygon (clicking on the first vertex). Hold the ctrl key and click and drag a vertex to reposition it (the ctrl key is not necessary if the polygon has already been completed). Hold the shift key and click and drag anywhere in the axes to move all vertices. Press the esc key to start a new polygon.

For the selector to remain responsive you must keep a reference to it.

Parameters:

axAxes The parent axes for the widget. onselectfunction When a polygon is completed or modified after completion, the onselect function is called and passed a list of the vertices as (xdata, ydata) tuples. useblitbool, default: False linepropsdict, default: dict(color='k', linestyle='-', linewidth=2, alpha=0.5). Artist properties for the line representing the edges of the polygon. markerpropsdict, default: dict(marker='o', markersize=7, mec='k', mfc='k', alpha=0.5). Artist properties for the markers drawn at the vertices of the polygon. vertex_select_radiusfloat, default: 15px A vertex is selected (to complete the polygon or to move a vertex) if the mouse click is within vertex_select_radius pixels of the vertex.

Examples

Polygon Selector Demo

onmove(self, event) [source]

Cursor move event handler and validator

property verts

The polygon vertices, as a list of (x, y) pairs.

class matplotlib.widgets.RadioButtons(ax, labels, active=0, activecolor='blue') [source]

Bases: matplotlib.widgets.AxesWidget

A GUI neutral radio button.

For the buttons to remain responsive you must keep a reference to this object.

Connect to the RadioButtons with the on_clicked method.

Attributes:	axAxes The parent axes for the widget. activecolorcolor The color of the selected button. labelslist of Text The button labels. circleslist of Circle The buttons. value_selectedstr The label text of the currently selected button.

Add radio buttons to an Axes.

Parameters:	axAxes The axes to add the buttons to. labelslist of str The button labels. activeint The index of the initially selected button. activecolorcolor The color of the selected button.

disconnect(self, cid) [source]

Remove the observer with connection id cid.

on_clicked(self, func) [source]

Connect the callback function func to button click events.

Returns a connection id, which can be used to disconnect the callback.

set_active(self, index) [source]

Select button with number index.

Callbacks will be triggered if eventson is True.

class matplotlib.widgets.RectangleSelector(ax, onselect, drawtype='box', minspanx=0, minspany=0, useblit=False, lineprops=None, rectprops=None, spancoords='data', button=None, maxdist=10, marker_props=None, interactive=False, state_modifier_keys=None) [source]

Bases: matplotlib.widgets._SelectorWidget

Select a rectangular region of an axes.

For the cursor to remain responsive you must keep a reference to it.

Examples

Rectangle Selector

Parameters:

axAxes The parent axes for the widget. onselectfunction A callback function that is called after a selection is completed. It must have the signature: def onselect(eclick: MouseEvent, erelease: MouseEvent) where eclick and erelease are the mouse click and release MouseEvents that start and complete the selection. drawtype{"box", "line", "none"}, default: "box" Whether to draw the full rectangle box, the diagonal line of the rectangle, or nothing at all. minspanxfloat, default: 0 Selections with an x-span less than minspanx are ignored. minspanyfloat, default: 0 Selections with an y-span less than minspany are ignored. useblitbool, default: False Whether to use blitting for faster drawing (if supported by the backend). linepropsdict, optional Properties with which the line is drawn, if drawtype == "line". Default: dict(color="black", linestyle="-", linewidth=2, alpha=0.5) rectpropsdict, optional Properties with which the rectangle is drawn, if drawtype == "box". Default: dict(facecolor="red", edgecolor="black", alpha=0.2, fill=True) spancoords{"data", "pixels"}, default: "data" Whether to interpret minspanx and minspany in data or in pixel coordinates. buttonMouseButton, list of MouseButton, default: all buttons Button(s) that trigger rectangle selection. maxdistfloat, default: 10 Distance in pixels within which the interactive tool handles can be activated. marker_propsdict Properties with which the interactive handles are drawn. Currently not implemented and ignored. interactivebool, default: False Whether to draw a set of handles that allow interaction with the widget after it is drawn. state_modifier_keysdict, optional Keyboard modifiers which affect the widget's behavior. Values amend the defaults. "move": Move the existing shape, default: no modifier. "clear": Clear the current shape, default: "escape". "square": Makes the shape square, default: "shift". "center": Make the initial point the center of the shape, default: "ctrl". "square" and "center" can be combined.

property center

Center of rectangle

property corners

Corners of rectangle from lower left, moving clockwise.

draw_shape(self, extents) [source]

property edge_centers

Midpoint of rectangle edges from left, moving clockwise.

property extents

Return (xmin, xmax, ymin, ymax).

property geometry

Return an array of shape (2, 5) containing the x (RectangleSelector.geometry[1, :]) and y (RectangleSelector.geometry[0, :]) coordinates of the four corners of the rectangle starting and ending in the top left corner.

class matplotlib.widgets.Slider(ax, label, valmin, valmax, valinit=0.5, valfmt=None, closedmin=True, closedmax=True, slidermin=None, slidermax=None, dragging=True, valstep=None, orientation='horizontal', **kwargs) [source]

Bases: matplotlib.widgets.AxesWidget

A slider representing a floating point range.

Create a slider from valmin to valmax in axes ax. For the slider to remain responsive you must maintain a reference to it. Call on_changed() to connect to the slider event.

Attributes:	valfloat Slider value.

Parameters:

axAxes The Axes to put the slider in. labelstr Slider label. valminfloat The minimum value of the slider. valmaxfloat The maximum value of the slider. valinitfloat, default: 0.5 The slider initial position. valfmtstr, default: None %-format string used to format the slider value. If None, a ScalarFormatter is used instead. closedminbool, default: True Whether the slider interval is closed on the bottom. closedmaxbool, default: True Whether the slider interval is closed on the top. sliderminSlider, default: None Do not allow the current slider to have a value less than the value of the Slider slidermin. slidermaxSlider, default: None Do not allow the current slider to have a value greater than the value of the Slider slidermax. draggingbool, default: True If True the slider can be dragged by the mouse. valstepfloat, default: None If given, the slider will snap to multiples of valstep. orientation{'horizontal', 'vertical'}, default: 'horizontal' The orientation of the slider.

Notes

Additional kwargs are passed on to self.poly which is the Rectangle that draws the slider knob. See the Rectangle documentation for valid property names (facecolor, edgecolor, alpha, etc.).

disconnect(self, cid) [source]

Remove the observer with connection id cid

Parameters:	cidint Connection id of the observer to be removed

on_changed(self, func) [source]

When the slider value is changed call func with the new slider value

Parameters:	funccallable Function to call when slider is changed. The function must accept a single float as its arguments.
Returns:	int Connection id (which can be used to disconnect func)

reset(self) [source]

Reset the slider to the initial value

set_val(self, val) [source]

Set slider value to val

Parameters:	valfloat

class matplotlib.widgets.SpanSelector(ax, onselect, direction, minspan=None, useblit=False, rectprops=None, onmove_callback=None, span_stays=False, button=None) [source]

Bases: matplotlib.widgets._SelectorWidget

Visually select a min/max range on a single axis and call a function with those values.

To guarantee that the selector remains responsive, keep a reference to it.

In order to turn off the SpanSelector, set span_selector.active to False. To turn it back on, set it to True.

Parameters:

axmatplotlib.axes.Axes onselectfunc(min, max), min/max are floats direction{"horizontal", "vertical"} The direction along which to draw the span selector. minspanfloat, default: None If selection is less than minspan, do not call onselect. useblitbool, default: False If True, use the backend-dependent blitting features for faster canvas updates. rectpropsdict, default: None Dictionary of matplotlib.patches.Patch properties. onmove_callbackfunc(min, max), min/max are floats, default: None Called on mouse move while the span is being selected. span_staysbool, default: False If True, the span stays visible after the mouse is released. buttonMouseButton or list of MouseButton The mouse buttons which activate the span selector.

Examples

>>> import matplotlib.pyplot as plt
>>> import matplotlib.widgets as mwidgets
>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3], [10, 50, 100])
>>> def onselect(vmin, vmax):
...     print(vmin, vmax)
>>> rectprops = dict(facecolor='blue', alpha=0.5)
>>> span = mwidgets.SpanSelector(ax, onselect, 'horizontal',
...                              rectprops=rectprops)
>>> fig.show()

See also: Span Selector

ignore(self, event) [source]

Return whether event should be ignored.

This method should be called at the beginning of any event callback.

new_axes(self, ax) [source]

Set SpanSelector to operate on a new Axes.

class matplotlib.widgets.SubplotTool(targetfig, toolfig) [source]

Bases: matplotlib.widgets.Widget

A tool to adjust the subplot params of a matplotlib.figure.Figure.

Parameters:	targetfigFigure The figure instance to adjust. toolfigFigure The figure instance to embed the subplot tool into.

property axbottom

property axhspace

property axleft

property axright

property axtop

property axwspace

funcbottom(self, val) [source]

[Deprecated]

Notes

Deprecated since version 3.3:

funchspace(self, val) [source]

[Deprecated]

Notes

Deprecated since version 3.3:

funcleft(self, val) [source]

[Deprecated]

Notes

Deprecated since version 3.3:

funcright(self, val) [source]

[Deprecated]

Notes

Deprecated since version 3.3:

functop(self, val) [source]

[Deprecated]

Notes

Deprecated since version 3.3:

funcwspace(self, val) [source]

[Deprecated]

Notes

Deprecated since version 3.3:

class matplotlib.widgets.TextBox(ax, label, initial='', color='.95', hovercolor='1', label_pad=0.01) [source]

Bases: matplotlib.widgets.AxesWidget

A GUI neutral text input box.

For the text box to remain responsive you must keep a reference to it.

Call on_text_change to be updated whenever the text changes.

Call on_submit to be updated whenever the user hits enter or leaves the text entry field.

Attributes:	axAxes The parent axes for the widget. labelText colorcolor The color of the text box when not hovering. hovercolorcolor The color of the text box when hovering.

Parameters:	axAxes The Axes instance the button will be placed into. labelstr Label for this text box. initialstr Initial value in the text box. colorcolor The color of the box. hovercolorcolor The color of the box when the mouse is over it. label_padfloat The distance between the label and the right side of the textbox.

begin_typing(self, x) [source]

disconnect(self, cid) [source]

Remove the observer with connection id cid.

on_submit(self, func) [source]

When the user hits enter or leaves the submission box, call this func with event.

A connection id is returned which can be used to disconnect.

on_text_change(self, func) [source]

When the text changes, call this func with event.

A connection id is returned which can be used to disconnect.

property params_to_disable

position_cursor(self, x) [source]

set_val(self, val) [source]

stop_typing(self) [source]

property text

class matplotlib.widgets.ToolHandles(ax, x, y, marker='o', marker_props=None, useblit=True) [source]

Bases: object

Control handles for canvas tools.

Parameters:	axmatplotlib.axes.Axes Matplotlib axes where tool handles are displayed. x, y1D arrays Coordinates of control handles. markerstr Shape of marker used to display handle. See matplotlib.pyplot.plot. marker_propsdict Additional marker properties. See matplotlib.lines.Line2D.

closest(self, x, y) [source]

Return index and pixel distance to closest index.

set_animated(self, val) [source]

set_data(self, pts, y=None) [source]

Set x and y positions of handles

set_visible(self, val) [source]

property x

property y

class matplotlib.widgets.Widget [source]

Bases: object

Abstract base class for GUI neutral widgets

property active

Is the widget active?

drawon = True

eventson = True

get_active(self) [source]

Get whether the widget is active.

ignore(self, event) [source]

Return whether event should be ignored.

This method should be called at the beginning of any event callback.

set_active(self, active) [source]

Set whether the widget is active.