@@ -70,7 +70,17 @@ class Widget(object):
70
70
71
71
72
72
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.
74
84
75
85
Attributes:
76
86
@@ -112,7 +122,10 @@ def ignore(self, event):
112
122
113
123
class Button (AxesWidget ):
114
124
"""
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.
116
129
117
130
The following attributes are accessible
118
131
@@ -134,22 +147,24 @@ class Button(AxesWidget):
134
147
def __init__ (self , ax , label , image = None ,
135
148
color = '0.85' , hovercolor = '0.95' ):
136
149
"""
137
- *ax*
150
+ Parameters
151
+ ----------
152
+ ax : matplotlib.axes.Axes
138
153
The :class:`matplotlib.axes.Axes` instance the button
139
154
will be placed into.
140
155
141
- * label*
156
+ label : str
142
157
The button text. Accepts string.
143
158
144
- * image*
159
+ image : array, mpl image, PIL image
145
160
The image to place in the button, if not *None*.
146
161
Can be any legal arg to imshow (numpy array,
147
162
matplotlib Image instance, or PIL image).
148
163
149
- * color*
164
+ color : color
150
165
The color of the button when not activated
151
166
152
- * hovercolor*
167
+ hovercolor : color
153
168
The color of the button when the mouse is over it
154
169
"""
155
170
AxesWidget .__init__ (self , ax )
@@ -233,7 +248,10 @@ def disconnect(self, cid):
233
248
234
249
class Slider (AxesWidget ):
235
250
"""
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.
237
255
238
256
The following attributes are defined
239
257
*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',
269
287
closedmin = True , closedmax = True , slidermin = None ,
270
288
slidermax = None , dragging = True , ** kwargs ):
271
289
"""
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*, ...)
273
296
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
275
312
The slider initial position
276
313
277
- * label*
314
+ label : str
278
315
The slider label
279
316
280
- * valfmt*
281
- Used to format the slider value
317
+ valfmt : str
318
+ Used to format the slider value, fprint format string
282
319
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
285
322
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
289
337
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*, ...)
294
338
"""
295
339
AxesWidget .__init__ (self , ax )
296
340
@@ -415,7 +459,10 @@ def reset(self):
415
459
416
460
class CheckButtons (AxesWidget ):
417
461
"""
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.
419
466
420
467
The following attributes are exposed
421
468
@@ -549,6 +596,9 @@ class RadioButtons(AxesWidget):
549
596
"""
550
597
A GUI neutral radio button
551
598
599
+ For the buttons to remain responsive
600
+ you much keep a reference to this object.
601
+
552
602
The following attributes are exposed
553
603
554
604
*ax*
@@ -832,7 +882,10 @@ class Cursor(AxesWidget):
832
882
*vertOn*
833
883
Controls the visibility of the horizontal line
834
884
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.
836
889
"""
837
890
def __init__ (self , ax , horizOn = True , vertOn = True , useblit = False ,
838
891
** lineprops ):
@@ -914,7 +967,10 @@ def _update(self):
914
967
class MultiCursor (Widget ):
915
968
"""
916
969
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.
918
974
919
975
Example usage::
920
976
@@ -1027,7 +1083,10 @@ def _update(self):
1027
1083
1028
1084
class SpanSelector (AxesWidget ):
1029
1085
"""
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.
1031
1090
1032
1091
Example usage::
1033
1092
@@ -1062,8 +1121,8 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
1062
1121
1063
1122
Set the visible attribute to *False* if you want to turn off
1064
1123
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
1067
1126
a valid selection.
1068
1127
"""
1069
1128
AxesWidget .__init__ (self , ax )
@@ -1085,7 +1144,7 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
1085
1144
self .onmove_callback = onmove_callback
1086
1145
self .minspan = minspan
1087
1146
self .span_stays = span_stays
1088
-
1147
+
1089
1148
# Needed when dragging out of axes
1090
1149
self .buttonDown = False
1091
1150
self .prev = (0 , 0 )
@@ -1126,7 +1185,7 @@ def new_axes(self, ax):
1126
1185
visible = False ,
1127
1186
** self .rectprops )
1128
1187
self .ax .add_patch (self .stay_rect )
1129
-
1188
+
1130
1189
if not self .useblit :
1131
1190
self .ax .add_patch (self .rect )
1132
1191
@@ -1152,7 +1211,7 @@ def press(self, event):
1152
1211
self .rect .set_visible (self .visible )
1153
1212
if self .span_stays :
1154
1213
self .stay_rect .set_visible (False )
1155
-
1214
+
1156
1215
if self .direction == 'horizontal' :
1157
1216
self .pressv = event .xdata
1158
1217
else :
@@ -1168,14 +1227,14 @@ def release(self, event):
1168
1227
self .buttonDown = False
1169
1228
1170
1229
self .rect .set_visible (False )
1171
-
1230
+
1172
1231
if self .span_stays :
1173
1232
self .stay_rect .set_x (self .rect .get_x ())
1174
1233
self .stay_rect .set_y (self .rect .get_y ())
1175
1234
self .stay_rect .set_width (self .rect .get_width ())
1176
1235
self .stay_rect .set_height (self .rect .get_height ())
1177
1236
self .stay_rect .set_visible (True )
1178
-
1237
+
1179
1238
self .canvas .draw ()
1180
1239
vmin = self .pressv
1181
1240
if self .direction == 'horizontal' :
@@ -1245,7 +1304,10 @@ def onmove(self, event):
1245
1304
1246
1305
class RectangleSelector (AxesWidget ):
1247
1306
"""
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.
1249
1311
1250
1312
Example usage::
1251
1313
@@ -1528,6 +1590,9 @@ def get_active(self):
1528
1590
class LassoSelector (AxesWidget ):
1529
1591
"""Selection curve of an arbitrary shape.
1530
1592
1593
+ For the selector to remain responsive you much keep a reference to
1594
+ it.
1595
+
1531
1596
The selected path can be used in conjunction with
1532
1597
:func:`~matplotlib.path.Path.contains_point` to select
1533
1598
data points from an image.
0 commit comments