Prefer using MouseButton to numeric values in docs and defaults.

anntzer · anntzer · commit 9d6542c2089c · 2020-01-21T01:41:29.000+01:00
They are more self-explanatory (and completely backcompatible, as they
inherit from int).
diff --git a/lib/matplotlib/blocking_input.py b/lib/matplotlib/blocking_input.py
@@ -103,15 +103,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/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.
 
