From e4e9ee6cc49532de2c0651aacc64a3753e734f21 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Mon, 9 Jun 2014 21:52:19 -0400 Subject: [PATCH 1/2] DOC : added note about maintain ref to widgets Added note to widget doc-strings that the user must maintain a reference to the widgets to keep them responsive (if they get gc'd the call backs go away). Some random conversion to numpyboc Closes #3105 --- lib/matplotlib/widgets.py | 107 +++++++++++++++++++++++++++----------- 1 file changed, 76 insertions(+), 31 deletions(-) diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index c3875901c465..8ff605355e10 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -70,7 +70,15 @@ class Widget(object): class AxesWidget(Widget): - """Widget that is connected to a single :class:`~matplotlib.axes.Axes`. + """Widget that is connected to a single + :class:`~matplotlib.axes.Axes`. + + To guarantee that the widgets stay responsive maintain a reference + to them. 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: @@ -112,7 +120,10 @@ def ignore(self, event): class Button(AxesWidget): """ - A GUI neutral button + A GUI neutral button. + + For the button to remain responsive + you much keep a reference to it. The following attributes are accessible @@ -134,22 +145,24 @@ class Button(AxesWidget): def __init__(self, ax, label, image=None, color='0.85', hovercolor='0.95'): """ - *ax* + Parameters + ---------- + ax : matplotlib.axes.Axes The :class:`matplotlib.axes.Axes` instance the button will be placed into. - *label* + label : str The button text. Accepts string. - *image* + image : array, mpl image, PIL image The image to place in the button, if not *None*. Can be any legal arg to imshow (numpy array, matplotlib Image instance, or PIL image). - *color* + color : color The color of the button when not activated - *hovercolor* + hovercolor : color The color of the button when the mouse is over it """ AxesWidget.__init__(self, ax) @@ -233,7 +246,10 @@ def disconnect(self, cid): class Slider(AxesWidget): """ - A slider representing a floating point range + A slider representing a floating point range. + + For the slider + to remain responsive you must maintain a reference to it. The following attributes are defined *ax* : the slider :class:`matplotlib.axes.Axes` instance @@ -269,28 +285,36 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f', closedmin=True, closedmax=True, slidermin=None, slidermax=None, dragging=True, **kwargs): """ - Create a slider from *valmin* to *valmax* in axes *ax* + Create a slider from *valmin* to *valmax* in axes *ax*. + + additional kwargs are passed on to ``self.poly`` which is the + :class:`matplotlib.patches.Rectangle` which draws the slider + knob. See the :class:`matplotlib.patches.Rectangle` documentation + valid property names (e.g., *facecolor*, *edgecolor*, *alpha*, ...) - *valinit* + Parameters + ---------- + valinit : float The slider initial position - *label* + label : str The slider label - *valfmt* - Used to format the slider value + valfmt : str + Used to format the slider value, fprint format string - *closedmin* and *closedmax* + closedmin : bool + closedmax : bool Indicate whether the slider interval is closed - *slidermin* and *slidermax* + slidermin : float + slidermax : float Used to constrain the value of this slider to the values of other sliders. - additional kwargs are passed on to ``self.poly`` which is the - :class:`matplotlib.patches.Rectangle` which draws the slider - knob. See the :class:`matplotlib.patches.Rectangle` documentation - valid property names (e.g., *facecolor*, *edgecolor*, *alpha*, ...) + dragging : bool + if the silder can be dragged by the mouse + """ AxesWidget.__init__(self, ax) @@ -415,7 +439,10 @@ def reset(self): class CheckButtons(AxesWidget): """ - A GUI neutral radio button + A GUI neutral radio button. + + For the check buttons to remain responsive you much keep a + reference to this object. The following attributes are exposed @@ -549,6 +576,9 @@ class RadioButtons(AxesWidget): """ A GUI neutral radio button + For the buttons to remain responsive + you much keep a reference to this object. + The following attributes are exposed *ax* @@ -832,7 +862,10 @@ class Cursor(AxesWidget): *vertOn* Controls the visibility of the horizontal line - and the visibility of the cursor itself with the *visible* attribute + and the visibility of the cursor itself with the *visible* attribute. + + For the cursor to remain responsive you much keep a reference to + it. """ def __init__(self, ax, horizOn=True, vertOn=True, useblit=False, **lineprops): @@ -914,7 +947,10 @@ def _update(self): class MultiCursor(Widget): """ Provide a vertical (default) and/or horizontal line cursor shared between - multiple axes + multiple axes. + + For the cursor to remain responsive you much keep a reference to + it. Example usage:: @@ -1027,7 +1063,10 @@ def _update(self): class SpanSelector(AxesWidget): """ - Select a min/max range of the x or y axes for a matplotlib Axes + Select a min/max range of the x or y axes for a matplotlib Axes. + + For the selector to remain responsive you much keep a reference to + it. Example usage:: @@ -1062,8 +1101,8 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False, 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 + + If *span_stays* is True, the span stays visble after making a valid selection. """ AxesWidget.__init__(self, ax) @@ -1085,7 +1124,7 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False, self.onmove_callback = onmove_callback self.minspan = minspan self.span_stays = span_stays - + # Needed when dragging out of axes self.buttonDown = False self.prev = (0, 0) @@ -1126,7 +1165,7 @@ def new_axes(self, ax): visible=False, **self.rectprops) self.ax.add_patch(self.stay_rect) - + if not self.useblit: self.ax.add_patch(self.rect) @@ -1152,7 +1191,7 @@ def press(self, event): self.rect.set_visible(self.visible) if self.span_stays: self.stay_rect.set_visible(False) - + if self.direction == 'horizontal': self.pressv = event.xdata else: @@ -1168,14 +1207,14 @@ def release(self, event): self.buttonDown = False self.rect.set_visible(False) - + if self.span_stays: self.stay_rect.set_x(self.rect.get_x()) self.stay_rect.set_y(self.rect.get_y()) self.stay_rect.set_width(self.rect.get_width()) self.stay_rect.set_height(self.rect.get_height()) self.stay_rect.set_visible(True) - + self.canvas.draw() vmin = self.pressv if self.direction == 'horizontal': @@ -1245,7 +1284,10 @@ def onmove(self, event): class RectangleSelector(AxesWidget): """ - Select a min/max range of the x axes for a matplotlib Axes + Select a rectangular region of an axes. + + For the cursor to remain responsive you much keep a reference to + it. Example usage:: @@ -1528,6 +1570,9 @@ def get_active(self): class LassoSelector(AxesWidget): """Selection curve of an arbitrary shape. + For the selector to remain responsive you much keep a reference to + it. + The selected path can be used in conjunction with :func:`~matplotlib.path.Path.contains_point` to select data points from an image. From 121556637cd003bf16278b0c3fb47f0e63772401 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Tue, 10 Jun 2014 08:33:33 -0400 Subject: [PATCH 2/2] DOC : improved docs in widgets.py - corrected docstring in Slider.__init__ - feedback on previous commit --- lib/matplotlib/widgets.py | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index 8ff605355e10..bef623bb64e0 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -73,8 +73,10 @@ class AxesWidget(Widget): """Widget that is connected to a single :class:`~matplotlib.axes.Axes`. - To guarantee that the widgets stay responsive maintain a reference - to them. This is necessary because the callback registry + 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 @@ -123,7 +125,7 @@ class Button(AxesWidget): A GUI neutral button. For the button to remain responsive - you much keep a reference to it. + you must keep a reference to it. The following attributes are accessible @@ -294,6 +296,18 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f', 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 @@ -304,13 +318,19 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f', 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 + 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 + `slidermin` + + slidermax : Slider or None + Do not allow the current slider to have a value greater than + `slidermax` - slidermin : float - slidermax : float - Used to constrain the value of this slider to the values - of other sliders. dragging : bool if the silder can be dragged by the mouse @@ -949,7 +969,7 @@ class MultiCursor(Widget): Provide a vertical (default) and/or horizontal line cursor shared between multiple axes. - For the cursor to remain responsive you much keep a reference to + For the cursor to remain responsive you much keep a reference to it. Example usage::