Skip to content

Backport PR #20745 on branch v3.5.x (Clean up some Event class docs.) #20960

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
Sep 1, 2021
Merged

Backport PR #20745 on branch v3.5.x (Clean up some Event class docs.) #20960

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
86 changes: 36 additions & 50 deletions lib/matplotlib/backend_bases.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1211,9 +1211,10 @@ def _on_timer(self):

class Event:
"""
A Matplotlib event. Attach additional attributes as defined in
:meth:`FigureCanvasBase.mpl_connect`. The following attributes
are defined and shown with their default values
A Matplotlib event.

The following attributes are defined and shown with their default values.
Subclasses may define additional attributes.

Attributes
----------
Expand All @@ -1232,20 +1233,20 @@ def __init__(self, name, canvas, guiEvent=None):

class DrawEvent(Event):
"""
An event triggered by a draw operation on the canvas
An event triggered by a draw operation on the canvas.

In most backends callbacks subscribed to this callback will be
fired after the rendering is complete but before the screen is
updated. Any extra artists drawn to the canvas's renderer will
be reflected without an explicit call to ``blit``.
In most backends, callbacks subscribed to this event will be fired after
the rendering is complete but before the screen is updated. Any extra
artists drawn to the canvas's renderer will be reflected without an
explicit call to ``blit``.

.. warning::

Calling ``canvas.draw`` and ``canvas.blit`` in these callbacks may
not be safe with all backends and may cause infinite recursion.

In addition to the `Event` attributes, the following event
attributes are defined:
A DrawEvent has a number of special attributes in addition to those defined
by the parent `Event` class.

Attributes
----------
Expand All @@ -1259,10 +1260,10 @@ def __init__(self, name, canvas, renderer):

class ResizeEvent(Event):
"""
An event triggered by a canvas resize
An event triggered by a canvas resize.

In addition to the `Event` attributes, the following event
attributes are defined:
A ResizeEvent has a number of special attributes in addition to those
defined by the parent `Event` class.

Attributes
----------
Expand All @@ -1284,32 +1285,23 @@ class LocationEvent(Event):
"""
An event that has a screen location.

The following additional attributes are defined and shown with
their default values.

In addition to the `Event` attributes, the following
event attributes are defined:
A LocationEvent has a number of special attributes in addition to those
defined by the parent `Event` class.

Attributes
----------
x : int
x position - pixels from left of canvas.
y : int
y position - pixels from bottom of canvas.
x, y : int or None
Event location in pixels from bottom left of canvas.
inaxes : `~.axes.Axes` or None
The `~.axes.Axes` instance over which the mouse is, if any.
xdata : float or None
x data coordinate of the mouse.
ydata : float or None
y data coordinate of the mouse.
xdata, ydata : float or None
Data coordinates of the mouse within *inaxes*, or *None* if the mouse
is not over an Axes.
"""

lastevent = None # the last event that was triggered before this one

def __init__(self, name, canvas, x, y, guiEvent=None):
"""
(*x*, *y*) in figure coords ((0, 0) = bottom left).
"""
super().__init__(name, canvas, guiEvent=guiEvent)
# x position - pixels from left of canvas
self.x = int(x) if x is not None else x
Expand Down Expand Up @@ -1378,13 +1370,11 @@ class MouseButton(IntEnum):

class MouseEvent(LocationEvent):
"""
A mouse event ('button_press_event',
'button_release_event',
'scroll_event',
'motion_notify_event').
A mouse event ('button_press_event', 'button_release_event', \
'scroll_event', 'motion_notify_event').

In addition to the `Event` and `LocationEvent`
attributes, the following attributes are defined:
A MouseEvent has a number of special attributes in addition to those
defined by the parent `Event` and `LocationEvent` classes.

Attributes
----------
Expand Down Expand Up @@ -1426,10 +1416,6 @@ def on_press(event):

def __init__(self, name, canvas, x, y, button=None, key=None,
step=0, dblclick=False, guiEvent=None):
"""
(*x*, *y*) in figure coords ((0, 0) = bottom left)
button pressed None, 1, 2, 3, 'up', 'down'
"""
if button in MouseButton.__members__.values():
button = MouseButton(button)
self.button = button
Expand All @@ -1450,11 +1436,14 @@ def __str__(self):

class PickEvent(Event):
"""
A pick event, fired when the user picks a location on the canvas
A pick event.

This event is fired when the user picks a location on the canvas
sufficiently close to an artist that has been made pickable with
`.Artist.set_picker`.

Attrs: all the `Event` attributes plus
A PickEvent has a number of special attributes in addition to those defined
by the parent `Event` class.

Attributes
----------
Expand Down Expand Up @@ -1495,19 +1484,16 @@ class KeyEvent(LocationEvent):
"""
A key event (key press, key release).

Attach additional attributes as defined in
:meth:`FigureCanvasBase.mpl_connect`.

In addition to the `Event` and `LocationEvent`
attributes, the following attributes are defined:
A KeyEvent has a number of special attributes in addition to those defined
by the parent `Event` and `LocationEvent` classes.

Attributes
----------
key : None or str
the key(s) pressed. Could be **None**, a single case sensitive ascii
character ("g", "G", "#", etc.), a special key
("control", "shift", "f1", "up", etc.) or a
combination of the above (e.g., "ctrl+alt+g", "ctrl+alt+G").
The key(s) pressed. Could be *None*, a single case sensitive Unicode
character ("g", "G", "#", etc.), a special key ("control", "shift",
"f1", "up", etc.) or a combination of the above (e.g., "ctrl+alt+g",
"ctrl+alt+G").

Notes
-----
Expand Down