matplotlib.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 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.
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.
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
- 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.
Call on_clicked()
to connect to the button
Parameters: | ax : matplotlib.axes.Axes
label : str
image : array, mpl image, Pillow Image
color : color
hovercolor : color
|
---|
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.
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
- ax
- The
matplotlib.axes.Axes
instance the buttons are located in- labels
- List of
matplotlib.text.Text
instances- lines
- List of (line1, line2) tuples 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.- rectangles
- List of
matplotlib.patches.Rectangle
instances
Connect 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.
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:
- horizOn
- Controls the visibility of the horizontal line
- vertOn
- Controls the visibility of the horizontal line
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
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)¶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)¶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)¶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
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)¶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:
- ax
- The
matplotlib.axes.Axes
instance the buttons are in- activecolor
- The color of the button when clicked
- labels
- A list of
matplotlib.text.Text
instances- circles
- A list of
matplotlib.patches.Circle
instances- value_selected
- A string listing the current value selected
Connect 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.
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
¶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
label : str
valmin : float
valmax : float
valinit : float
label : str
valfmt : str
closedmin : bool
closedmax : bool
slidermin : Slider or None
slidermax : Slider or None
dragging : bool
|
---|
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)¶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)¶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)¶matplotlib.widgets.
ToolHandles
(ax, x, y, marker='o', marker_props=None, useblit=True)¶Bases: object
Control handles for canvas tools.
Parameters: | ax :
x, y : 1D arrays
marker : str
marker_props : dict
|
---|
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
¶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.