Skip to content

Commit 4c6b2cc

Browse files
committed
Merge pull request #3132 from tacaswell/widget_doc
DOC : added note about maintain ref to widgets
2 parents c4a014d + 1215566 commit 4c6b2cc

File tree

1 file changed

+99
-34
lines changed

1 file changed

+99
-34
lines changed

lib/matplotlib/widgets.py

Lines changed: 99 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,17 @@ class Widget(object):
7070

7171

7272
class AxesWidget(Widget):
73-
"""Widget that is connected to a single :class:`~matplotlib.axes.Axes`.
73+
"""Widget that is connected to a single
74+
:class:`~matplotlib.axes.Axes`.
75+
76+
To guarantee that the widget remains responsive and not garbage-collected,
77+
a reference to the object should be maintained by the user.
78+
79+
This is necessary because the callback registry
80+
maintains only weak-refs to the functions, which are member
81+
functions of the widget. If there are no references to the widget
82+
object it may be garbage collected which will disconnect the
83+
callbacks.
7484
7585
Attributes:
7686
@@ -112,7 +122,10 @@ def ignore(self, event):
112122

113123
class Button(AxesWidget):
114124
"""
115-
A GUI neutral button
125+
A GUI neutral button.
126+
127+
For the button to remain responsive
128+
you must keep a reference to it.
116129
117130
The following attributes are accessible
118131
@@ -134,22 +147,24 @@ class Button(AxesWidget):
134147
def __init__(self, ax, label, image=None,
135148
color='0.85', hovercolor='0.95'):
136149
"""
137-
*ax*
150+
Parameters
151+
----------
152+
ax : matplotlib.axes.Axes
138153
The :class:`matplotlib.axes.Axes` instance the button
139154
will be placed into.
140155
141-
*label*
156+
label : str
142157
The button text. Accepts string.
143158
144-
*image*
159+
image : array, mpl image, PIL image
145160
The image to place in the button, if not *None*.
146161
Can be any legal arg to imshow (numpy array,
147162
matplotlib Image instance, or PIL image).
148163
149-
*color*
164+
color : color
150165
The color of the button when not activated
151166
152-
*hovercolor*
167+
hovercolor : color
153168
The color of the button when the mouse is over it
154169
"""
155170
AxesWidget.__init__(self, ax)
@@ -233,7 +248,10 @@ def disconnect(self, cid):
233248

234249
class Slider(AxesWidget):
235250
"""
236-
A slider representing a floating point range
251+
A slider representing a floating point range.
252+
253+
For the slider
254+
to remain responsive you must maintain a reference to it.
237255
238256
The following attributes are defined
239257
*ax* : the slider :class:`matplotlib.axes.Axes` instance
@@ -269,28 +287,54 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f',
269287
closedmin=True, closedmax=True, slidermin=None,
270288
slidermax=None, dragging=True, **kwargs):
271289
"""
272-
Create a slider from *valmin* to *valmax* in axes *ax*
290+
Create a slider from *valmin* to *valmax* in axes *ax*.
291+
292+
additional kwargs are passed on to ``self.poly`` which is the
293+
:class:`matplotlib.patches.Rectangle` which draws the slider
294+
knob. See the :class:`matplotlib.patches.Rectangle` documentation
295+
valid property names (e.g., *facecolor*, *edgecolor*, *alpha*, ...)
273296
274-
*valinit*
297+
Parameters
298+
----------
299+
ax : Axes
300+
The Axes to put the slider in
301+
302+
label : str
303+
Slider label
304+
305+
valmin : float
306+
The minimum value of the slider
307+
308+
valmax : float
309+
The maximum value of the slider
310+
311+
valinit : float
275312
The slider initial position
276313
277-
*label*
314+
label : str
278315
The slider label
279316
280-
*valfmt*
281-
Used to format the slider value
317+
valfmt : str
318+
Used to format the slider value, fprint format string
282319
283-
*closedmin* and *closedmax*
284-
Indicate whether the slider interval is closed
320+
closedmin : bool
321+
Indicate whether the slider interval is closed on the bottom
285322
286-
*slidermin* and *slidermax*
287-
Used to constrain the value of this slider to the values
288-
of other sliders.
323+
closedmax : bool
324+
Indicate whether the slider interval is closed on the top
325+
326+
slidermin : Slider or None
327+
Do not allow the current slider to have a value less than
328+
`slidermin`
329+
330+
slidermax : Slider or None
331+
Do not allow the current slider to have a value greater than
332+
`slidermax`
333+
334+
335+
dragging : bool
336+
if the silder can be dragged by the mouse
289337
290-
additional kwargs are passed on to ``self.poly`` which is the
291-
:class:`matplotlib.patches.Rectangle` which draws the slider
292-
knob. See the :class:`matplotlib.patches.Rectangle` documentation
293-
valid property names (e.g., *facecolor*, *edgecolor*, *alpha*, ...)
294338
"""
295339
AxesWidget.__init__(self, ax)
296340

@@ -415,7 +459,10 @@ def reset(self):
415459

416460
class CheckButtons(AxesWidget):
417461
"""
418-
A GUI neutral radio button
462+
A GUI neutral radio button.
463+
464+
For the check buttons to remain responsive you much keep a
465+
reference to this object.
419466
420467
The following attributes are exposed
421468
@@ -549,6 +596,9 @@ class RadioButtons(AxesWidget):
549596
"""
550597
A GUI neutral radio button
551598
599+
For the buttons to remain responsive
600+
you much keep a reference to this object.
601+
552602
The following attributes are exposed
553603
554604
*ax*
@@ -832,7 +882,10 @@ class Cursor(AxesWidget):
832882
*vertOn*
833883
Controls the visibility of the horizontal line
834884
835-
and the visibility of the cursor itself with the *visible* attribute
885+
and the visibility of the cursor itself with the *visible* attribute.
886+
887+
For the cursor to remain responsive you much keep a reference to
888+
it.
836889
"""
837890
def __init__(self, ax, horizOn=True, vertOn=True, useblit=False,
838891
**lineprops):
@@ -914,7 +967,10 @@ def _update(self):
914967
class MultiCursor(Widget):
915968
"""
916969
Provide a vertical (default) and/or horizontal line cursor shared between
917-
multiple axes
970+
multiple axes.
971+
972+
For the cursor to remain responsive you much keep a reference to
973+
it.
918974
919975
Example usage::
920976
@@ -1027,7 +1083,10 @@ def _update(self):
10271083

10281084
class SpanSelector(AxesWidget):
10291085
"""
1030-
Select a min/max range of the x or y axes for a matplotlib Axes
1086+
Select a min/max range of the x or y axes for a matplotlib Axes.
1087+
1088+
For the selector to remain responsive you much keep a reference to
1089+
it.
10311090
10321091
Example usage::
10331092
@@ -1062,8 +1121,8 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
10621121
10631122
Set the visible attribute to *False* if you want to turn off
10641123
the functionality of the span selector
1065-
1066-
If *span_stays* is True, the span stays visble after making
1124+
1125+
If *span_stays* is True, the span stays visble after making
10671126
a valid selection.
10681127
"""
10691128
AxesWidget.__init__(self, ax)
@@ -1085,7 +1144,7 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
10851144
self.onmove_callback = onmove_callback
10861145
self.minspan = minspan
10871146
self.span_stays = span_stays
1088-
1147+
10891148
# Needed when dragging out of axes
10901149
self.buttonDown = False
10911150
self.prev = (0, 0)
@@ -1126,7 +1185,7 @@ def new_axes(self, ax):
11261185
visible=False,
11271186
**self.rectprops)
11281187
self.ax.add_patch(self.stay_rect)
1129-
1188+
11301189
if not self.useblit:
11311190
self.ax.add_patch(self.rect)
11321191

@@ -1152,7 +1211,7 @@ def press(self, event):
11521211
self.rect.set_visible(self.visible)
11531212
if self.span_stays:
11541213
self.stay_rect.set_visible(False)
1155-
1214+
11561215
if self.direction == 'horizontal':
11571216
self.pressv = event.xdata
11581217
else:
@@ -1168,14 +1227,14 @@ def release(self, event):
11681227
self.buttonDown = False
11691228

11701229
self.rect.set_visible(False)
1171-
1230+
11721231
if self.span_stays:
11731232
self.stay_rect.set_x(self.rect.get_x())
11741233
self.stay_rect.set_y(self.rect.get_y())
11751234
self.stay_rect.set_width(self.rect.get_width())
11761235
self.stay_rect.set_height(self.rect.get_height())
11771236
self.stay_rect.set_visible(True)
1178-
1237+
11791238
self.canvas.draw()
11801239
vmin = self.pressv
11811240
if self.direction == 'horizontal':
@@ -1245,7 +1304,10 @@ def onmove(self, event):
12451304

12461305
class RectangleSelector(AxesWidget):
12471306
"""
1248-
Select a min/max range of the x axes for a matplotlib Axes
1307+
Select a rectangular region of an axes.
1308+
1309+
For the cursor to remain responsive you much keep a reference to
1310+
it.
12491311
12501312
Example usage::
12511313
@@ -1528,6 +1590,9 @@ def get_active(self):
15281590
class LassoSelector(AxesWidget):
15291591
"""Selection curve of an arbitrary shape.
15301592
1593+
For the selector to remain responsive you much keep a reference to
1594+
it.
1595+
15311596
The selected path can be used in conjunction with
15321597
:func:`~matplotlib.path.Path.contains_point` to select
15331598
data points from an image.

0 commit comments

Comments
 (0)