Skip to content

Cleanup backend_bases docstrings. #15791

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 1 commit into from
Dec 2, 2019
Merged

Cleanup backend_bases docstrings. #15791

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
135 changes: 64 additions & 71 deletions lib/matplotlib/backend_bases.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1035,29 +1035,23 @@ class TimerBase:
own timing mechanisms so that the timer events are integrated into their
event loops.

Mandatory functions that must be implemented:
Subclasses must override the following methods:

* `_timer_start`: Contains backend-specific code for starting
the timer
- ``_timer_start``: Backend-specific code for starting the timer.
- ``_timer_stop``: Backend-specific code for stopping the timer.

* `_timer_stop`: Contains backend-specific code for stopping
the timer
Subclasses may additionally override the following methods:

Optional overrides:
- ``_timer_set_single_shot``: Code for setting the timer to single shot
operating mode, if supported by the timer object. If not, the `Timer`
class itself will store the flag and the ``_on_timer`` method should be
overridden to support such behavior.

* `_timer_set_single_shot`: Code for setting the timer to
single shot operating mode, if supported by the timer
object. If not, the `Timer` class itself will store the flag
and the `_on_timer` method should be overridden to support
such behavior.
- ``_timer_set_interval``: Code for setting the interval on the timer, if
there is a method for doing so on the timer object.

* `_timer_set_interval`: Code for setting the interval on the
timer, if there is a method for doing so on the timer
object.

* `_on_timer`: This is the internal function that any timer
object should call, which will handle the task of running
all callbacks that have been set.
- ``_on_timer``: The internal function that any timer object should call,
which will handle the task of running all callbacks that have been set.

Attributes
----------
Expand Down Expand Up @@ -1414,8 +1408,7 @@ class MouseEvent(LocationEvent):

Examples
--------
Usage::

::
def on_press(event):
print('you pressed', event.button, event.xdata, event.ydata)

Expand Down Expand Up @@ -1466,8 +1459,7 @@ class PickEvent(Event):

Examples
--------
Usage::

::
ax.plot(np.rand(100), 'o', picker=5) # 5 points tolerance

def on_pick(event):
Expand All @@ -1477,7 +1469,6 @@ def on_pick(event):
print('on pick line:', np.array([xdata[ind], ydata[ind]]).T)

cid = fig.canvas.mpl_connect('pick_event', on_pick)

"""
def __init__(self, name, canvas, mouseevent, artist,
guiEvent=None, **kwargs):
Expand Down Expand Up @@ -1514,13 +1505,11 @@ class KeyEvent(LocationEvent):

Examples
--------
Usage::

::
def on_key(event):
print('you pressed', event.key, event.xdata, event.ydata)

cid = fig.canvas.mpl_connect('key_press_event', on_key)

"""
def __init__(self, name, canvas, key, x=0, y=0, guiEvent=None):
LocationEvent.__init__(self, name, canvas, x, y, guiEvent=guiEvent)
Expand Down Expand Up @@ -2173,44 +2162,50 @@ def switch_backends(self, FigureCanvasClass):

def mpl_connect(self, s, func):
"""
Connect event with string *s* to *func*. The signature of *func* is::

def func(event)

where event is a :class:`matplotlib.backend_bases.Event`. The
following events are recognized

- 'button_press_event'
- 'button_release_event'
- 'draw_event'
- 'key_press_event'
- 'key_release_event'
- 'motion_notify_event'
- 'pick_event'
- 'resize_event'
- 'scroll_event'
- 'figure_enter_event',
- 'figure_leave_event',
- 'axes_enter_event',
- 'axes_leave_event'
- 'close_event'

For the location events (button and key press/release), if the
mouse is over the axes, the variable ``event.inaxes`` will be
set to the :class:`~matplotlib.axes.Axes` the event occurs is
over, and additionally, the variables ``event.xdata`` and
``event.ydata`` will be defined. This is the mouse location
in data coords. See
:class:`~matplotlib.backend_bases.KeyEvent` and
:class:`~matplotlib.backend_bases.MouseEvent` for more info.

Return value is a connection id that can be used with
:meth:`~matplotlib.backend_bases.Event.mpl_disconnect`.
Bind function *func* to event *s*.

Parameters
----------
s : str
One of the following events ids:

- 'button_press_event'
- 'button_release_event'
- 'draw_event'
- 'key_press_event'
- 'key_release_event'
- 'motion_notify_event'
- 'pick_event'
- 'resize_event'
- 'scroll_event'
- 'figure_enter_event',
- 'figure_leave_event',
- 'axes_enter_event',
- 'axes_leave_event'
- 'close_event'.

func : callable
The callback function to be executed, which must have the
signature::

def func(event: Event) -> Any

For the location events (button and key press/release), if the
mouse is over the axes, the ``inaxes`` attribute of the event will
be set to the `~matplotlib.axes.Axes` the event occurs is over, and
additionally, the variables ``xdata`` and ``ydata`` attributes will
be set to the mouse location in data coordinates. See `.KeyEvent`
and `.MouseEvent` for more info.

Returns
-------
cid
A connection id that can be used with
`.FigureCanvasBase.mpl_disconnect`.

Examples
--------
Usage::

::
def on_press(event):
print('you pressed', event.button, event.xdata, event.ydata)

Expand All @@ -2221,24 +2216,23 @@ def on_press(event):

def mpl_disconnect(self, cid):
"""
Disconnect callback id cid
Disconnect the callback with id *cid*.

Examples
--------
Usage::

::
cid = canvas.mpl_connect('button_press_event', on_press)
#...later
# ... later
canvas.mpl_disconnect(cid)
"""
return self.callbacks.disconnect(cid)

def new_timer(self, *args, **kwargs):
"""
Creates a new backend-specific subclass of
:class:`backend_bases.Timer`. This is useful for getting periodic
events through the backend's native event loop. Implemented only for
backends with GUIs.
Create a new backend-specific subclass of `.Timer`.

This is useful for getting periodic events through the backend's native
event loop. Implemented only for backends with GUIs.

Other Parameters
----------------
Expand All @@ -2249,13 +2243,12 @@ def new_timer(self, *args, **kwargs):
Sequence of (func, args, kwargs) where ``func(*args, **kwargs)``
will be executed by the timer every *interval*.

callbacks which return ``False`` or ``0`` will be removed from the
Callbacks which return ``False`` or ``0`` will be removed from the
timer.

Examples
--------
>>> timer = fig.canvas.new_timer(callbacks=[(f1, (1, ), {'a': 3}),])

"""
return TimerBase(*args, **kwargs)

Expand Down