Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC : added note about maintain ref to widgets #3132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 10, 2014
Merged

DOC : added note about maintain ref to widgets #3132

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e4e9ee6
DOC : added note about maintain ref to widgets
tacaswell Jun 10, 2014
1215566
DOC : improved docs in widgets.py
tacaswell Jun 10, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 99 additions & 34 deletions lib/matplotlib/widgets.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,17 @@ 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 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:

Expand Down Expand Up @@ -112,7 +122,10 @@ def ignore(self, event):

class Button(AxesWidget):
"""
A GUI neutral button
A GUI neutral button.

For the button to remain responsive
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about putting this in each of the widget subclass docstrings...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defense in depth?

you must keep a reference to it.

The following attributes are accessible

Expand All @@ -134,22 +147,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)
Expand Down Expand Up @@ -233,7 +248,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
Expand Down Expand Up @@ -269,28 +287,54 @@ 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
----------
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*
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*
Indicate whether the slider interval is closed
closedmin : bool
Indicate whether the slider interval is closed on the bottom

*slidermin* and *slidermax*
Used to constrain the value of this slider to the values
of other sliders.
closedmax : bool
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Github makes this look like you've repeated the line. Is that the case?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was hopping numpydoc would merge the docs on these (one is min and one is max), forgot to check that before I pushed.

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`


dragging : bool
if the silder can be dragged by the mouse

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*, ...)
"""
AxesWidget.__init__(self, ax)

Expand Down Expand Up @@ -415,7 +459,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

Expand Down Expand Up @@ -549,6 +596,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*
Expand Down Expand Up @@ -832,7 +882,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):
Expand Down Expand Up @@ -914,7 +967,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::

Expand Down Expand Up @@ -1027,7 +1083,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::

Expand Down Expand Up @@ -1062,8 +1121,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)
Expand All @@ -1085,7 +1144,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)
Expand Down Expand Up @@ -1126,7 +1185,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)

Expand All @@ -1152,7 +1211,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:
Expand All @@ -1168,14 +1227,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':
Expand Down Expand Up @@ -1245,7 +1304,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::

Expand Down Expand Up @@ -1528,6 +1590,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.
Expand Down