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 arg. 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)
Bases: matplotlib.widgets.Widget
Widget that is 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:
Axes
FigureCanvasBase
subclassconnect_event(event, callback)
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()
Disconnect all events created by this widget.
class matplotlib.widgets.Button(ax, label, image=None, color='0.85', hovercolor='0.95')
Bases: matplotlib.widgets.AxesWidget
A GUI neutral button.
For the button to remain responsive you must keep a reference to it.
The following attributes are accessible
matplotlib.axes.Axes
the button renders into.matplotlib.text.Text
instance.Call on_clicked()
to connect to the button
Parameters: |
ax : matplotlib.axes.Axes The label : str The button text. Accepts string. image : array, mpl image, Pillow Image The image to place in the button, if not None. Can be any legal arg to imshow (numpy array, matplotlib Image instance, or Pillow Image). color : color The color of the button when not activated hovercolor : color The color of the button when the mouse is over it |
---|
disconnect(cid)
remove the observer with connection id cid
on_clicked(func)
When the button is clicked, call this func with event.
A connection id is returned. It can be used to disconnect the button from its callback.
class matplotlib.widgets.CheckButtons(ax, labels, actives)
Bases: matplotlib.widgets.AxesWidget
A GUI neutral radio button.
For the check buttons to remain responsive you must keep a reference to this object.
The following attributes are exposed
matplotlib.axes.Axes
instance the buttons are located inmatplotlib.text.Text
instancesset_visible(False)
when its box is not checked.matplotlib.patches.Rectangle
instancesConnect to the CheckButtons with the on_clicked()
method
Add check buttons to matplotlib.axes.Axes
instance ax
disconnect(cid)
remove the observer with connection id cid
on_clicked(func)
When the button is clicked, call func with button label
A connection id is returned which can be used to disconnect
set_active(index)
Directly (de)activate a check button by index.
Callbacks will be triggered if eventson
is True.
class matplotlib.widgets.Cursor(ax, horizOn=True, vertOn=True, useblit=False, **lineprops)
Bases: matplotlib.widgets.AxesWidget
A horizontal and vertical line that spans the axes and moves with the pointer. You can turn off the hline or vline respectively with the following attributes:
and the visibility of the cursor itself with the visible attribute.
For the cursor to remain responsive you must keep a reference to it.
Add a cursor to ax. If useblit=True
, use the backend- dependent blitting features for faster updates (GTKAgg only for now). lineprops is a dictionary of line properties.
(Source code, png, hires.png, pdf)
clear(event)
clear the cursor
onmove(event)
on mouse motion draw the cursor if visible
class matplotlib.widgets.EllipseSelector(ax, onselect, drawtype='box', minspanx=None, minspany=None, useblit=False, lineprops=None, rectprops=None, spancoords='data', button=None, maxdist=10, marker_props=None, interactive=False, state_modifier_keys=None)
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:
from matplotlib.widgets import EllipseSelector from pylab import * 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 = arange(100)/(99.0) y = sin(x) fig = figure ax = subplot(111) ax.plot(x,y) toggle_selector.ES = EllipseSelector(ax, onselect, drawtype='line') connect('key_press_event', toggle_selector) show()
Create a selector in ax. When a selection is made, clear the span and call onselect with:
onselect(pos_1, pos_2)
and clear the drawn box/line. The pos_1
and pos_2
are arrays of length 2 containing the x- and y-coordinate.
If minspanx is not None then events smaller than minspanx in x direction are ignored (it’s the same for y).
The rectangle is drawn with rectprops; default:
rectprops = dict(facecolor='red', edgecolor = 'black', alpha=0.2, fill=True)
The line is drawn with lineprops; default:
lineprops = dict(color='black', linestyle='-', linewidth = 2, alpha=0.5)
Use drawtype if you want the mouse to draw a line, a box or nothing between click and actual position by setting
drawtype = 'line'
, drawtype='box'
or drawtype = 'none'
.
spancoords is one of ‘data’ or ‘pixels’. If ‘data’, minspanx and minspanx will be interpreted in the same coordinates as the x and y axis. If ‘pixels’, they are in pixels.
button is a list of integers indicating which mouse buttons should be used for rectangle selection. You can also specify a single integer if only a single button is desired. Default is None, which does not limit which button can be used.
interactive will draw a set of handles and allow you interact with the widget after it is drawn.
state_modifier_keys are keyboard modifiers that affect the behavior of the widget.
The defaults are: dict(move=’ ‘, clear=’escape’, square=’shift’, center=’ctrl’)
Keyboard modifiers, which: ‘move’: Move the existing shape. ‘clear’: Clear the current shape. ‘square’: Makes the shape square. ‘center’: Make the initial point the center of the shape. ‘square’ and ‘center’ can be combined.
draw_shape(extents)
class matplotlib.widgets.Lasso(ax, xy, callback=None, useblit=True)
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:
Axes
callback
function is called and passed the vertices of the selected path.onmove(event)
onrelease(event)
class matplotlib.widgets.LassoSelector(ax, onselect=None, useblit=True, lineprops=None, button=None)
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.
Parameters:
Axes
onselect
function is called and passed the vertices of the selected path.Example usage:
ax = subplot(111) ax.plot(x,y) def onselect(verts): print(verts) lasso = LassoSelector(ax, onselect) *button* is a list of integers indicating which mouse buttons should be used for rectangle selection. You can also specify a single integer if only a single button is desired. Default is *None*, which does not limit which button can be used. Note, typically: 1 = left mouse button 2 = center mouse button (scroll wheel) 3 = right mouse button
onpress(event)
onrelease(event)
class matplotlib.widgets.LockDraw
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. The module level “lock” allows someone to grab the lock and prevent other widgets from drawing. Use matplotlib.widgets.lock(someobj)
to prevent other widgets from drawing while you’re interacting with the canvas.
available(o)
drawing is available to o
isowner(o)
Return True if o owns this lock
locked()
Return True if the lock is currently held by an owner
release(o)
release the lock
class matplotlib.widgets.MultiCursor(canvas, axes, useblit=True, horizOn=False, vertOn=True, **lineprops)
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 from pylab import figure, show, np t = np.arange(0.0, 2.0, 0.01) s1 = np.sin(2*np.pi*t) s2 = np.sin(4*np.pi*t) fig = figure() ax1 = fig.add_subplot(211) ax1.plot(t, s1) ax2 = fig.add_subplot(212, sharex=ax1) ax2.plot(t, s2) multi = MultiCursor(fig.canvas, (ax1, ax2), color='r', lw=1, horizOn=False, vertOn=True) show()
clear(event)
clear the cursor
connect()
connect events
disconnect()
disconnect events
onmove(event)
class matplotlib.widgets.RadioButtons(ax, labels, active=0, activecolor='blue')
Bases: matplotlib.widgets.AxesWidget
A GUI neutral radio button.
For the buttons to remain responsive you must keep a reference to this object.
The following attributes are exposed:
matplotlib.axes.Axes
instance the buttons are inmatplotlib.text.Text
instancesmatplotlib.patches.Circle
instancesConnect to the RadioButtons with the on_clicked()
method
Add radio buttons to matplotlib.axes.Axes
instance ax
disconnect(cid)
remove the observer with connection id cid
on_clicked(func)
When the button is clicked, call func with button label
A connection id is returned which can be used to disconnect
set_active(index)
Trigger which radio button to make active.
Callbacks will be triggered if eventson
is True.
class matplotlib.widgets.RectangleSelector(ax, onselect, drawtype='box', minspanx=None, minspany=None, useblit=False, lineprops=None, rectprops=None, spancoords='data', button=None, maxdist=10, marker_props=None, interactive=False, state_modifier_keys=None)
Bases: matplotlib.widgets._SelectorWidget
Select a rectangular region of an axes.
For the cursor to remain responsive you must keep a reference to it.
Example usage:
from matplotlib.widgets import RectangleSelector from pylab import * 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.RS.active: print(' RectangleSelector deactivated.') toggle_selector.RS.set_active(False) if event.key in ['A', 'a'] and not toggle_selector.RS.active: print(' RectangleSelector activated.') toggle_selector.RS.set_active(True) x = arange(100)/(99.0) y = sin(x) fig = figure ax = subplot(111) ax.plot(x,y) toggle_selector.RS = RectangleSelector(ax, onselect, drawtype='line') connect('key_press_event', toggle_selector) show()
Create a selector in ax. When a selection is made, clear the span and call onselect with:
onselect(pos_1, pos_2)
and clear the drawn box/line. The pos_1
and pos_2
are arrays of length 2 containing the x- and y-coordinate.
If minspanx is not None then events smaller than minspanx in x direction are ignored (it’s the same for y).
The rectangle is drawn with rectprops; default:
rectprops = dict(facecolor='red', edgecolor = 'black', alpha=0.2, fill=True)
The line is drawn with lineprops; default:
lineprops = dict(color='black', linestyle='-', linewidth = 2, alpha=0.5)
Use drawtype if you want the mouse to draw a line, a box or nothing between click and actual position by setting
drawtype = 'line'
, drawtype='box'
or drawtype = 'none'
.
spancoords is one of ‘data’ or ‘pixels’. If ‘data’, minspanx and minspanx will be interpreted in the same coordinates as the x and y axis. If ‘pixels’, they are in pixels.
button is a list of integers indicating which mouse buttons should be used for rectangle selection. You can also specify a single integer if only a single button is desired. Default is None, which does not limit which button can be used.
interactive will draw a set of handles and allow you interact with the widget after it is drawn.
state_modifier_keys are keyboard modifiers that affect the behavior of the widget.
The defaults are: dict(move=’ ‘, clear=’escape’, square=’shift’, center=’ctrl’)
Keyboard modifiers, which: ‘move’: Move the existing shape. ‘clear’: Clear the current shape. ‘square’: Makes the shape square. ‘center’: Make the initial point the center of the shape. ‘square’ and ‘center’ can be combined.
center
Center of rectangle
corners
Corners of rectangle from lower left, moving clockwise.
draw_shape(extents)
edge_centers
Midpoint of rectangle edges from left, moving clockwise.
extents
Return (xmin, xmax, ymin, ymax).
geometry
class matplotlib.widgets.Slider(ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f', closedmin=True, closedmax=True, slidermin=None, slidermax=None, dragging=True, **kwargs)
Bases: matplotlib.widgets.AxesWidget
A slider representing a floating point range.
For the slider to remain responsive you must maintain a reference to it.
ax : the slider matplotlib.axes.Axes
instance
val : the current slider value
matplotlib.lines.Line2D
instancematplotlib.patches.Polygon
instancevalfmt : the format string for formatting the slider text
matplotlib.text.Text
instanceclosedmin : whether the slider is closed on the minimum
closedmax : whether the slider is closed on the maximum
dragging : allow for mouse dragging on slider
Call on_changed()
to connect to the slider event
Create a slider from valmin to valmax in axes ax.
Additional kwargs are passed on to self.poly
which is the matplotlib.patches.Rectangle
that draws the slider knob. See the matplotlib.patches.Rectangle
documentation for valid property names (e.g., facecolor, edgecolor, alpha, ...).
Parameters: |
ax : Axes The Axes to put the slider in label : str Slider label valmin : float The minimum value of the slider valmax : float The maximum value of the slider valinit : float The slider initial position label : str The slider label valfmt : str Used to format the slider value, fprint format string closedmin : bool Indicate whether the slider interval is closed on the bottom closedmax : bool Indicate whether the slider interval is closed on the top slidermin : Slider or None Do not allow the current slider to have a value less than slidermax : Slider or None Do not allow the current slider to have a value greater than dragging : bool if the slider can be dragged by the mouse |
---|
disconnect(cid)
remove the observer with connection id cid
on_changed(func)
When the slider value is changed, call func with the new slider position
A connection id is returned which can be used to disconnect
reset()
reset the slider to the initial value if needed
set_val(val)
class matplotlib.widgets.SpanSelector(ax, onselect, direction, minspan=None, useblit=False, rectprops=None, onmove_callback=None, span_stays=False, button=None)
Bases: matplotlib.widgets._SelectorWidget
Select a min/max range of the x or y axes for a matplotlib Axes.
For the selector to remain responsive you must keep a reference to it.
Example usage:
ax = subplot(111) ax.plot(x,y) def onselect(vmin, vmax): print(vmin, vmax) span = SpanSelector(ax, onselect, 'horizontal')
onmove_callback is an optional callback that is called on mouse move within the span range
Create a span selector in ax. When a selection is made, clear the span and call onselect with:
onselect(vmin, vmax)
and clear the span.
direction must be ‘horizontal’ or ‘vertical’
If minspan is not None, ignore events smaller than minspan
The span rectangle is drawn with rectprops; default:
rectprops = dict(facecolor='red', alpha=0.5)
Set the visible attribute to False if you want to turn off the functionality of the span selector
If span_stays is True, the span stays visble after making a valid selection.
button is a list of integers indicating which mouse buttons should be used for selection. You can also specify a single integer if only a single button is desired. Default is None, which does not limit which button can be used.
ignore(event)
return True if event should be ignored
new_axes(ax)
class matplotlib.widgets.SubplotTool(targetfig, toolfig)
Bases: matplotlib.widgets.Widget
A tool to adjust the subplot params of a matplotlib.figure.Figure
.
funcbottom(val)
funchspace(val)
funcleft(val)
funcright(val)
functop(val)
funcwspace(val)
class matplotlib.widgets.ToolHandles(ax, x, y, marker='o', marker_props=None, useblit=True)
Bases: object
Control handles for canvas tools.
Parameters: |
ax : Matplotlib axes where tool handles are displayed. x, y : 1D arrays Coordinates of control handles. marker : str Shape of marker used to display handle. See marker_props : dict Additional marker properties. See |
---|
closest(x, y)
Return index and pixel distance to closest index.
set_animated(val)
set_data(pts, y=None)
Set x and y positions of handles
set_visible(val)
x
y
class matplotlib.widgets.Widget
Bases: object
Abstract base class for GUI neutral widgets
active
Is the widget active?
drawon = True
eventson = True
get_active()
Get whether the widget is active.
ignore(event)
Return True if event should be ignored.
This method (or a version of it) should be called at the beginning of any event callback.
set_active(active)
Set whether the widget is active.
© 2012–2016 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
http://matplotlib.org/1.5.3/api/widgets_api.html