Skip to content

Commit

Permalink
Merge pull request matplotlib#20745 from QuLogic/event-docs
Browse files Browse the repository at this point in the history 
Clean up some Event class docs.
  • Loading branch information
@dstansby
dstansby authored Sep 1, 2021
2 parents 6683517 + 29fcdca commit a142369
Showing 1 changed file with 36 additions and 50 deletions.
86 changes: 36 additions & 50 deletions lib/matplotlib/backend_bases.py
View file
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

0 comments on commit a142369

Please sign in to comment.