matplotlib.widgets#

Inheritance diagram of 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 an 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: 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(event, callback)[source]#

Connect a callback function 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()[source]#

Disconnect all events created by this widget.

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

Bases: 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 Axes the button renders into.

label

A 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.

useblitbool, default: True

Use blitting for faster drawing if supported by the backend. See the tutorial Faster rendering by using blitting for details.

New in version 3.7.

disconnect(cid)[source]#

Remove the callback function with connection id cid.

on_clicked(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, *, useblit=True, label_props=None, frame_props=None, check_props=None)[source]#

Bases: 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

[Deprecated]

lineslist of (Line2D, Line2D) pairs

[Deprecated]

Add check buttons to 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.

useblitbool, default: True

Use blitting for faster drawing if supported by the backend. See the tutorial Faster rendering by using blitting for details.

New in version 3.7.

label_propsdict, optional

Dictionary of Text properties to be used for the labels.

New in version 3.7.

frame_propsdict, optional

Dictionary of scatter Collection properties to be used for the check button frame. Defaults (label font size / 2)**2 size, black edgecolor, no facecolor, and 1.0 linewidth.

New in version 3.7.

check_propsdict, optional

Dictionary of scatter Collection properties to be used for the check button check. Defaults to (label font size / 2)**2 size, black color, and 1.0 linewidth.

New in version 3.7.

disconnect(cid)[source]#

Remove the observer with connection id cid.

get_status()[source]#

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

property lines[source]#

[Deprecated]

Notes

Deprecated since version 3.7: Any custom property styling may be lost.

on_clicked(func)[source]#

Connect the callback function func to button click events.

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

property rectangles[source]#

[Deprecated]

Notes

Deprecated since version 3.7: Any custom property styling may be lost.

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

set_check_props(props)[source]#

Set properties of the check button checks.

New in version 3.7.

Parameters:
propsdict

Dictionary of Collection properties to be used for the check button check.

set_frame_props(props)[source]#

Set properties of the check button frames.

New in version 3.7.

Parameters:
propsdict

Dictionary of Collection properties to be used for the check button frames.

set_label_props(props)[source]#

Set properties of the Text labels.

New in version 3.7.

Parameters:
propsdict

Dictionary of Text properties to be used for the labels.

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

Bases: 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:
axAxes

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. See the tutorial Faster rendering by using blitting for details.

Other Parameters:
**lineprops

Line2D properties that control the appearance of the lines. See also axhline.

Examples

See Cursor.

clear(event)[source]#

Internal event handler to clear the cursor.

onmove(event)[source]#

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

class matplotlib.widgets.EllipseSelector(ax, onselect, *, minspanx=0, minspany=0, useblit=False, props=None, spancoords='data', button=None, grab_range=10, handle_props=None, interactive=False, state_modifier_keys=None, drag_from_anywhere=False, ignore_event_outside=False, use_data_coordinates=False)[source]#

Bases: RectangleSelector

Select an elliptical region of an Axes.

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

Press and release events triggered at the same coordinates outside the selection will clear the selector, except when ignore_event_outside=True.

Parameters:
axAxes

The parent axes for the widget.

onselectfunction

A callback function that is called after a release event and the selection is created, changed or removed. 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.

minspanxfloat, default: 0

Selections with an x-span less than or equal to minspanx are removed (when already existing) or cancelled.

minspanyfloat, default: 0

Selections with an y-span less than or equal to minspanx are removed (when already existing) or cancelled.

useblitbool, default: False

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

propsdict, optional

Properties with which the ellipse is drawn. See Patch for valid properties. 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.

grab_rangefloat, default: 10

Distance in pixels within which the interactive tool handles can be activated.

handle_propsdict, optional

Properties with which the interactive handles (marker artists) are drawn. See the marker arguments in Line2D for valid properties. Default values are defined in mpl.rcParams except for the default value of markeredgecolor which will be the same as the edgecolor property in props.

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, which are:

  • "move": Move the existing shape, default: no modifier.

  • "clear": Clear the current shape, default: "escape".

  • "square": Make the shape square, default: "shift".

  • "center": change the shape around its center, default: "ctrl".

  • "rotate": Rotate the shape around its center between -45° and 45°, default: "r".

"square" and "center" can be combined. The square shape can be defined in data or display coordinates as determined by the use_data_coordinates argument specified when creating the selector.

drag_from_anywherebool, default: False

If True, the widget can be moved by clicking anywhere within its bounds.

ignore_event_outsidebool, default: False

If True, the event triggered outside the span selector will be ignored.

use_data_coordinatesbool, default: False

If True, the "square" shape of the selector is defined in data coordinates instead of display coordinates.

Examples

Rectangle and ellipse selectors

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

Bases: 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.

useblitbool, default: True

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

onmove(event)[source]#
onrelease(event)[source]#
class matplotlib.widgets.LassoSelector(ax, onselect, *, useblit=True, props=None, button=None)[source]#

Bases: _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 = plt.subplot()
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.

useblitbool, default: True

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

propsdict, optional

Properties with which the line is drawn, see Line2D for valid properties. Default values are defined in mpl.rcParams.

buttonMouseButton or list of MouseButton, optional

The mouse buttons used for rectangle selection. Default is None, which corresponds to all buttons.

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(o)[source]#

Return whether drawing is available to o.

isowner(o)[source]#

Return whether o owns this lock.

locked()[source]#

Return whether the lock is currently held by an owner.

release(o)[source]#

Release the lock from o.

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

Bases: 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.

Parameters:
canvasobject

This parameter is entirely unused and only kept for back-compatibility.

axeslist of Axes

The Axes to attach the cursor to.

useblitbool, default: True

Use blitting for faster drawing if supported by the backend. See the tutorial Faster rendering by using blitting for details.

horizOnbool, default: False

Whether to draw the horizontal line.

vertOnbool, default: True

Whether to draw the vertical line.

Other Parameters:
**lineprops

Line2D properties that control the appearance of the lines. See also axhline.

Examples

See Multicursor.

clear(event)[source]#

Clear the cursor.

connect()[source]#

Connect events.

disconnect()[source]#

Disconnect events.

needclear()[source]#

[Deprecated]

Notes

Deprecated since version 3.7:

onmove(event)[source]#
class matplotlib.widgets.PolygonSelector(ax, onselect, *, useblit=False, props=None, handle_props=None, grab_range=10, draw_bounding_box=False, box_handle_props=None, box_props=None)[source]#

Bases: _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). Once drawn individual vertices can be moved by clicking and dragging with the left mouse button, or removed by clicking the right mouse button.

In addition, the following modifier keys can be used:

  • Hold ctrl and click and drag a vertex to reposition it before the polygon has 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

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

propsdict, optional

Properties with which the line is drawn, see Line2D for valid properties. Default:

dict(color='k', linestyle='-', linewidth=2, alpha=0.5)
handle_propsdict, optional

Artist properties for the markers drawn at the vertices of the polygon. See the marker arguments in Line2D for valid properties. Default values are defined in mpl.rcParams except for the default value of markeredgecolor which will be the same as the color property in props.

grab_rangefloat, default: 10

A vertex is selected (to complete the polygon or to move a vertex) if the mouse click is within grab_range pixels of the vertex.

draw_bounding_boxbool, optional

If True, a bounding box will be drawn around the polygon selector once it is complete. This box can be used to move and resize the selector.

box_handle_propsdict, optional

Properties to set for the box handles. See the documentation for the handle_props argument to RectangleSelector for more info.

box_propsdict, optional

Properties to set for the box. See the documentation for the props argument to RectangleSelector for more info.

Notes

If only one point remains after removing points, the selector reverts to an incomplete state and you can start drawing a new polygon from the existing point.

Examples

Polygon Selector Select indices from a collection using polygon selector

onmove(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=None, *, useblit=True, label_props=None, radio_props=None)[source]#

Bases: 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

[Deprecated]

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. The default is 'blue' if not specified here or in radio_props.

useblitbool, default: True

Use blitting for faster drawing if supported by the backend. See the tutorial Faster rendering by using blitting for details.

New in version 3.7.

label_propsdict or list of dict, optional

Dictionary of Text properties to be used for the labels.

New in version 3.7.

radio_propsdict, optional

Dictionary of scatter Collection properties to be used for the radio buttons. Defaults to (label font size / 2)**2 size, black edgecolor, and activecolor facecolor (when active).

Note

If a facecolor is supplied in radio_props, it will override activecolor. This may be used to provide an active color per button.

New in version 3.7.

property activecolor#
property circles[source]#

[Deprecated]

Notes

Deprecated since version 3.7: Any custom property styling may be lost.

disconnect(cid)[source]#

Remove the observer with connection id cid.

on_clicked(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(index)[source]#

Select button with number index.

Callbacks will be triggered if eventson is True.

set_label_props(props)[source]#

Set properties of the Text labels.

New in version 3.7.

Parameters:
propsdict

Dictionary of Text properties to be used for the labels.

set_radio_props(props)[source]#

Set properties of the Text labels.

New in version 3.7.

Parameters:
propsdict

Dictionary of Collection properties to be used for the radio buttons.

class matplotlib.widgets.RangeSlider(ax, label, valmin, valmax, *, valinit=None, valfmt=None, closedmin=True, closedmax=True, dragging=True, valstep=None, orientation='horizontal', track_color='lightgrey', handle_style=None, **kwargs)[source]#

Bases: SliderBase

A slider representing a range of floating point values. Defines the min and max of the range via the val attribute as a tuple of (min, max).

Create a slider that defines a range contained within [valmin, 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:
valtuple of float

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.

valinittuple of float or None, default: None

The initial positions of the slider. If None the initial positions will be at the 25th and 75th percentiles of the range.

valfmtstr, default: None

%-format string used to format the slider values. 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.

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.

track_colorcolor, default: 'lightgrey'

The color of the background track. The track is accessible for further styling via the track attribute.

handle_styledict

Properties of the slider handles. Default values are

Key

Value

Default

Description

facecolor

color

'white'

The facecolor of the slider handles.

edgecolor

color

'.75'

The edgecolor of the slider handles.

size

int

10

The size of the slider handles in points.

Other values will be transformed as marker{foo} and passed to the Line2D constructor. e.g. handle_style = {'style'='x'} will result in markerstyle = 'x'.

Notes

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

on_changed(func)[source]#

Connect func as callback function to changes of the slider value.

Parameters:
funccallable

Function to call when slider is changed. The function must accept a 2-tuple of floats as its argument.

Returns:
int

Connection id (which can be used to disconnect func).

set_max(max)[source]#

Set the lower value of the slider to max.

Parameters:
maxfloat
set_min(min)[source]#

Set the lower value of the slider to min.

Parameters:
minfloat
set_val(val)[source]#

Set slider value to val.

Parameters:
valtuple or array-like of float
class matplotlib.widgets.RectangleSelector(ax, onselect, *, minspanx=0, minspany=0, useblit=False, props=None, spancoords='data', button=None, grab_range=10, handle_props=None, interactive=False, state_modifier_keys=None, drag_from_anywhere=False, ignore_event_outside=False, use_data_coordinates=False)[source]#

Bases: _SelectorWidget

Select a rectangular region of an Axes.

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

Press and release events triggered at the same coordinates outside the selection will clear the selector, except when ignore_event_outside=True.

Parameters:
axAxes

The parent axes for the widget.

onselectfunction

A callback function that is called after a release event and the selection is created, changed or removed. 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.

minspanxfloat, default: 0

Selections with an x-span less than or equal to minspanx are removed (when already existing) or cancelled.

minspanyfloat, default: 0

Selections with an y-span less than or equal to minspanx are removed (when already existing) or cancelled.

useblitbool, default: False

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

propsdict, optional

Properties with which the rectangle is drawn. See Patch for valid properties. 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.

grab_rangefloat, default: 10

Distance in pixels within which the interactive tool handles can be activated.

handle_propsdict, optional

Properties with which the interactive handles (marker artists) are drawn. See the marker arguments in Line2D for valid properties. Default values are defined in mpl.rcParams except for the default value of markeredgecolor which will be the same as the edgecolor property in props.

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, which are:

  • "move": Move the existing shape, default: no modifier.

  • "clear": Clear the current shape, default: "escape".

  • "square": Make the shape square, default: "shift".

  • "center": change the shape around its center, default: "ctrl".

  • "rotate": Rotate the shape around its center between -45° and 45°, default: "r".

"square" and "center" can be combined. The square shape can be defined in data or display coordinates as determined by the use_data_coordinates argument specified when creating the selector.

drag_from_anywherebool, default: False

If True, the widget can be moved by clicking anywhere within its bounds.

ignore_event_outsidebool, default: False

If True, the event triggered outside the span selector will be ignored.

use_data_coordinatesbool, default: False

If True, the "square" shape of the selector is defined in data coordinates instead of display coordinates.

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(eclick, erelease):
...     print(eclick.xdata, eclick.ydata)
...     print(erelease.xdata, erelease.ydata)
>>> props = dict(facecolor='blue', alpha=0.5)
>>> rect = mwidgets.RectangleSelector(ax, onselect, interactive=True,
...                                   props=props)
>>> fig.show()
>>> rect.add_state('square')

See also: Rectangle and ellipse selectors

property center#

Center of rectangle in data coordinates.

property corners#

Corners of rectangle in data coordinates from lower left, moving clockwise.

property edge_centers#

Midpoint of rectangle edges in data coordinates from left, moving anti-clockwise.

property extents#

Return (xmin, xmax, ymin, ymax) in data coordinates as defined by the bounding box before rotation.

property geometry#

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

property rotation#

Rotation in degree in interval [-45°, 45°]. The rotation is limited in range to keep the implementation simple.

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', initcolor='r', track_color='lightgrey', handle_style=None, **kwargs)[source]#

Bases: SliderBase

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 or array-like, default: None

If a float, the slider will snap to multiples of valstep. If an array the slider will snap to the values in the array.

orientation{'horizontal', 'vertical'}, default: 'horizontal'

The orientation of the slider.

initcolorcolor, default: 'r'

The color of the line at the valinit position. Set to 'none' for no line.

track_colorcolor, default: 'lightgrey'

The color of the background track. The track is accessible for further styling via the track attribute.

handle_styledict

Properties of the slider handle. Default values are

Key

Value

Default

Description

facecolor

color

'white'

The facecolor of the slider handle.

edgecolor

color

'.75'

The edgecolor of the slider handle.

size

int

10

The size of the slider handle in points.

Other values will be transformed as marker{foo} and passed to the Line2D constructor. e.g. handle_style = {'style'='x'} will result in markerstyle = 'x'.

Notes

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

on_changed(func)[source]#

Connect func as callback function to changes of the 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).

set_val(val)[source]#

Set slider value to val.

Parameters:
valfloat
class matplotlib.widgets.SliderBase(ax, orientation, closedmin, closedmax, valmin, valmax, valfmt, dragging, valstep)[source]#

Bases: AxesWidget

The base class for constructing Slider widgets. Not intended for direct usage.

For the slider to remain responsive you must maintain a reference to it.

disconnect(cid)[source]#

Remove the observer with connection id cid.

Parameters:
cidint

Connection id of the observer to be removed.

reset()[source]#

Reset the slider to the initial value.

class matplotlib.widgets.SpanSelector(ax, onselect, direction, *, minspan=0, useblit=False, props=None, onmove_callback=None, interactive=False, button=None, handle_props=None, grab_range=10, state_modifier_keys=None, drag_from_anywhere=False, ignore_event_outside=False, snap_values=None)[source]#

Bases: _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.

Press and release events triggered at the same coordinates outside the selection will clear the selector, except when ignore_event_outside=True.

Parameters:
axAxes
onselectcallable with signature func(min: float, max: float)

A callback function that is called after a release event and the selection is created, changed or removed.

direction{"horizontal", "vertical"}

The direction along which to draw the span selector.

minspanfloat, default: 0

If selection is less than or equal to minspan, the selection is removed (when already existing) or cancelled.

useblitbool, default: False

If True, use the backend-dependent blitting features for faster canvas updates. See the tutorial Faster rendering by using blitting for details.

propsdict, default: {'facecolor': 'red', 'alpha': 0.5}

Dictionary of Patch properties.

onmove_callbackcallable with signature func(min: float, max: float), optional

Called on mouse move while the span is being selected.

interactivebool, default: False

Whether to draw a set of handles that allow interaction with the widget after it is drawn.

buttonMouseButton or list of MouseButton, default: all buttons

The mouse buttons which activate the span selector.

handle_propsdict, default: None

Properties of the handle lines at the edges of the span. Only used when interactive is True. See Line2D for valid properties.

grab_rangefloat, default: 10

Distance in pixels within which the interactive tool handles can be activated.

state_modifier_keysdict, optional

Keyboard modifiers which affect the widget's behavior. Values amend the defaults, which are:

  • "clear": Clear the current shape, default: "escape".

drag_from_anywherebool, default: False

If True, the widget can be moved by clicking anywhere within its bounds.

ignore_event_outsidebool, default: False

If True, the event triggered outside the span selector will be ignored.

snap_values1D array-like, optional

Snap the selector edges to the given values.

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)
>>> span = mwidgets.SpanSelector(ax, onselect, 'horizontal',
...                              props=dict(facecolor='blue', alpha=0.5))
>>> fig.show()

See also: Span Selector

connect_default_events()[source]#

Connect the major canvas events to methods.

property direction#

Direction of the span selector: 'vertical' or 'horizontal'.

property extents#
(float, float)

The values, in data coordinates, for the start and end points of the current selection. If there is no selection then the start and end values will be the same.

new_axes(ax, *, _props=None)[source]#

Set SpanSelector to operate on a new Axes.

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

Bases: Widget

A tool to adjust the subplot params of a Figure.

Parameters:
targetfigFigure

The figure instance to adjust.

toolfigFigure

The figure instance to embed the subplot tool into.

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

Bases: 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.

textalignment{'left', 'center', 'right'}

The horizontal location of the text.

begin_typing(x=<deprecated parameter>)[source]#
disconnect(cid)[source]#

Remove the observer with connection id cid.

on_submit(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(func)[source]#

When the text changes, call this func with event.

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

set_val(val)[source]#
stop_typing()[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:
axAxes

Matplotlib Axes where tool handles are displayed.

x, y1D arrays

Coordinates of control handles.

markerstr, default: 'o'

Shape of marker used to display handle. See plot.

marker_propsdict, optional

Additional marker properties. See Line2D.

useblitbool, default: True

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

property artists#
closest(x, y)[source]#

Return index and pixel distance to closest index.

set_animated(val)[source]#
set_data(pts, y=None)[source]#

Set x and y positions of handles.

set_visible(val)[source]#
property x#
property y#
class matplotlib.widgets.ToolLineHandles(ax, positions, direction, *, line_props=None, useblit=True)[source]#

Bases: object

Control handles for canvas tools.

Parameters:
axAxes

Matplotlib Axes where tool handles are displayed.

positions1D array

Positions of handles in data coordinates.

direction{"horizontal", "vertical"}

Direction of handles, either 'vertical' or 'horizontal'

line_propsdict, optional

Additional line properties. See Line2D.

useblitbool, default: True

Whether to use blitting for faster drawing (if supported by the backend). See the tutorial Faster rendering by using blitting for details.

property artists#
closest(x, y)[source]#

Return index and pixel distance to closest handle.

Parameters:
x, yfloat

x, y position from which the distance will be calculated to determinate the closest handle

Returns:
index, distanceindex of the handle and its distance from

position x, y

property direction#

Direction of the handle: 'vertical' or 'horizontal'.

property positions#

Positions of the handle in data coordinates.

remove()[source]#

Remove the handles artist from the figure.

set_animated(value)[source]#

Set the animated state of the handles artist.

set_data(positions)[source]#

Set x- or y-positions of handles, depending on if the lines are vertical or horizontal.

Parameters:
positionstuple of length 2

Set the positions of the handle in data coordinates

set_visible(value)[source]#

Set the visibility state of the handles artist.

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()[source]#

Get whether the widget is active.

ignore(event)[source]#

Return whether event should be ignored.

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

set_active(active)[source]#

Set whether the widget is active.