Merge pull request #16277 from anntzer/mousebuttondocs

timhoffm · web-flow · commit e3e7792a5b52 · 2020-01-21T22:08:34.000+01:00
Prefer using MouseButton to numeric values in docs and defaults.
diff --git a/lib/matplotlib/blocking_input.py b/lib/matplotlib/blocking_input.py
@@ -24,6 +24,7 @@
 from numbers import Integral
 
 from matplotlib import cbook
+from matplotlib.backend_bases import MouseButton
 import matplotlib.lines as mlines
 
 _log = logging.getLogger(__name__)
@@ -103,15 +104,18 @@ class BlockingMouseInput(BlockingInput):
     Callable for retrieving mouse clicks in a blocking way.
 
     This class will also retrieve keypresses and map them to mouse clicks:
-    delete and backspace are like mouse button 3, enter is like mouse button 2
-    and all others are like mouse button 1.
+    delete and backspace are a right click, enter is like a middle click,
+    and all others are like a left click.
     """
 
-    button_add = 1
-    button_pop = 3
-    button_stop = 2
+    button_add = MouseButton.LEFT
+    button_pop = MouseButton.RIGHT
+    button_stop = MouseButton.MIDDLE
 
-    def __init__(self, fig, mouse_add=1, mouse_pop=3, mouse_stop=2):
+    def __init__(self, fig,
+                 mouse_add=MouseButton.LEFT,
+                 mouse_pop=MouseButton.RIGHT,
+                 mouse_stop=MouseButton.MIDDLE):
         BlockingInput.__init__(self, fig=fig,
                                eventslist=('button_press_event',
                                            'key_press_event'))
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -21,7 +21,8 @@
 
 import matplotlib.artist as martist
 from matplotlib.artist import Artist, allow_rasterization
-from matplotlib.backend_bases import FigureCanvasBase, NonGuiException
+from matplotlib.backend_bases import (
+    FigureCanvasBase, NonGuiException, MouseButton)
 import matplotlib.cbook as cbook
 import matplotlib.colorbar as cbar
 import matplotlib.image as mimage
@@ -2233,8 +2234,10 @@ def subplots_adjust(self, left=None, bottom=None, right=None, top=None,
                 ax.set_position(ax.figbox)
         self.stale = True
 
-    def ginput(self, n=1, timeout=30, show_clicks=True, mouse_add=1,
-               mouse_pop=3, mouse_stop=2):
+    def ginput(self, n=1, timeout=30, show_clicks=True,
+               mouse_add=MouseButton.LEFT,
+               mouse_pop=MouseButton.RIGHT,
+               mouse_stop=MouseButton.MIDDLE):
         """
         Blocking call to interact with a figure.
 
@@ -2248,13 +2251,7 @@ def ginput(self, n=1, timeout=30, show_clicks=True, mouse_add=1,
         - Stop the interaction and return the points added so far.
 
         The actions are assigned to mouse buttons via the arguments
-        *mouse_add*, *mouse_pop* and *mouse_stop*. Mouse buttons are defined
-        by the numbers:
-
-        - 1: left mouse button
-        - 2: middle mouse button
-        - 3: right mouse button
-        - None: no mouse button
+        *mouse_add*, *mouse_pop* and *mouse_stop*.
 
         Parameters
         ----------
@@ -2266,11 +2263,11 @@ def ginput(self, n=1, timeout=30, show_clicks=True, mouse_add=1,
             will never timeout.
         show_clicks : bool, default: True
             If True, show a red cross at the location of each click.
-        mouse_add : {1, 2, 3, None}, default: 1 (left click)
+        mouse_add : `.MouseButton` or None, default: `.MouseButton.LEFT`
             Mouse button used to add points.
-        mouse_pop : {1, 2, 3, None}, default: 3 (right click)
+        mouse_pop : `.MouseButton` or None, default: `.MouseButton.RIGHT`
             Mouse button used to remove the most recently added point.
-        mouse_stop : {1, 2, 3, None}, default: 2 (middle click)
+        mouse_stop : `.MouseButton` or None, default: `.MouseButton.MIDDLE`
             Mouse button used to stop input.
 
         Returns
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -36,7 +36,7 @@
 from matplotlib import cbook
 from matplotlib.cbook import dedent, deprecated, silent_list, warn_deprecated
 from matplotlib import docstring
-from matplotlib.backend_bases import FigureCanvasBase
+from matplotlib.backend_bases import FigureCanvasBase, MouseButton
 from matplotlib.figure import Figure, figaspect
 from matplotlib.gridspec import GridSpec
 from matplotlib import rcParams, rcParamsDefault, get_backend, rcParamsOrig
@@ -2132,8 +2132,9 @@ def gci():
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @docstring.copy(Figure.ginput)
 def ginput(
-        n=1, timeout=30, show_clicks=True, mouse_add=1, mouse_pop=3,
-        mouse_stop=2):
+        n=1, timeout=30, show_clicks=True,
+        mouse_add=MouseButton.LEFT, mouse_pop=MouseButton.RIGHT,
+        mouse_stop=MouseButton.MIDDLE):
     return gcf().ginput(
         n=n, timeout=timeout, show_clicks=show_clicks,
         mouse_add=mouse_add, mouse_pop=mouse_pop,
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -2008,11 +2008,6 @@ def __init__(self, ax, onselect, drawtype='box',
         *button* is the `.MouseButton` or list of `.MouseButton`\s used for
         rectangle selection.  Default is *None*, which means any button.
 
-        Note, typically:
-         1 = left mouse button
-         2 = center mouse button (scroll wheel)
-         3 = right mouse button
-
         *interactive* will draw a set of handles and allow you interact
         with the widget after it is drawn.
 
diff --git a/tools/boilerplate.py b/tools/boilerplate.py
@@ -13,6 +13,7 @@
 # runtime with the proper signatures, a static pyplot.py is simpler for static
 # analysis tools to parse.
 
+from enum import Enum
 import inspect
 from inspect import Parameter
 from pathlib import Path
@@ -84,6 +85,9 @@ def __init__(self, value):
             self._repr = "np.mean"
         elif value is cbook.deprecation._deprecated_parameter:
             self._repr = "cbook.deprecation._deprecated_parameter"
+        elif isinstance(value, Enum):
+            # Enum str is Class.Name whereas their repr is <Class.Name: value>.
+            self._repr = str(value)
         else:
             self._repr = repr(value)
 
