Introduce MouseButton enum for MouseEvent.

anntzer · anntzer · commit 6cc4e4b4d7b6 · 2018-10-26T14:22:47.000+02:00
MouseButton.LEFT/MIDDLE/RIGHT is a bit less cryptic than 1/2/3 (which
remain available as MouseButton is an IntEnum).

The names LEFT/MIDDLE/RIGHT are used by both Qt and wx, with the same
inversion for left-handed mode as noted in the docstring.  (Gtk uses
PRIMARY/MIDDLE/SECONDARY, which works better for left-handed mode but
seems otherwise less readable; tk just uses 1/2/3).

Changed one example to demonstrate the use; I can change the other
examples if we agree on the general approach.  (That specific example
printed mouse coordinates both on move and on click, which seems a bit
redundant, so I moved the "disconnect" part to the click handler.)
diff --git a/doc/users/next_whats_new/2018-10-26-AL.rst b/doc/users/next_whats_new/2018-10-26-AL.rst
@@ -0,0 +1,9 @@
+MouseEvent button attribute is now an IntEnum
+`````````````````````````````````````````````
+
+The :attr:`button` attribute of `~.MouseEvent` instances can take the values
+None, 1 (left button), 2 (middle button), 3 (right button), "up" (scroll), and
+"down" (scroll).  For better legibility, the 1, 2, and 3 values are now
+represented using the `IntEnum` class `matplotlib.backend_bases.MouseButton`,
+with the values `MouseButton.LEFT` (``== 1``), `MouseButton.MIDDLE` (``== 2``),
+and `MouseButton.RIGHT` (``== 3``).
diff --git a/examples/event_handling/coords_demo.py b/examples/event_handling/coords_demo.py
@@ -1,12 +1,13 @@
 """
 ===========
-Coords Demo
+Coords demo
 ===========
 
-An example of how to interact with the plotting canvas by connecting
-to move and click events
+An example of how to interact with the plotting canvas by connecting to move
+and click events.
 """
-import sys
+
+from matplotlib.backend_bases import MouseButton
 import matplotlib.pyplot as plt
 import numpy as np
 
@@ -19,25 +20,18 @@
 def on_move(event):
     # get the x and y pixel coords
     x, y = event.x, event.y
-
     if event.inaxes:
         ax = event.inaxes  # the axes instance
         print('data coords %f %f' % (event.xdata, event.ydata))
 
 
 def on_click(event):
-    # get the x and y coords, flip y from top to bottom
-    x, y = event.x, event.y
-    if event.button == 1:
-        if event.inaxes is not None:
-            print('data coords %f %f' % (event.xdata, event.ydata))
+    if event.button is MouseButton.LEFT:
+        print('disconnecting callback')
+        plt.disconnect(binding_id)
 
 
 binding_id = plt.connect('motion_notify_event', on_move)
 plt.connect('button_press_event', on_click)
 
-if "test_disconnect" in sys.argv:
-    print("disconnecting console coordinate printout...")
-    plt.disconnect(binding_id)
-
 plt.show()
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -33,6 +33,7 @@
 """
 
 from contextlib import contextmanager
+from enum import IntEnum
 import importlib
 import io
 import os
@@ -1425,6 +1426,12 @@ def _update_enter_leave(self):
         LocationEvent.lastevent = self
 
 
+class MouseButton(IntEnum):
+    LEFT = 1
+    MIDDLE = 2
+    RIGHT = 3
+
+
 class MouseEvent(LocationEvent):
     """
     A mouse event ('button_press_event',
@@ -1437,21 +1444,26 @@ class MouseEvent(LocationEvent):
 
     Attributes
     ----------
-    button : {None, 1, 2, 3, 'up', 'down'}
+    button : {None, MouseButton.LEFT, MouseButton.MIDDLE, MouseButton.RIGHT, \
+'up', 'down'}
         The button pressed. 'up' and 'down' are used for scroll events.
         Note that in the nbagg backend, both the middle and right clicks
-        return 3 since right clicking will bring up the context menu in
+        return RIGHT since right clicking will bring up the context menu in
         some browsers.
+        Note that LEFT and RIGHT actually refer to the "primary" and
+        "secondary" buttons, i.e. if the user inverts their left and right
+        buttons ("left-handed setting") then the LEFT button will be the one
+        physically on the right.
 
     key : None or str
         The key pressed when the mouse event triggered, e.g. 'shift'.
         See `KeyEvent`.
 
     step : scalar
-        The Number of scroll steps (positive for 'up', negative for 'down').
+        The number of scroll steps (positive for 'up', negative for 'down').
 
     dblclick : bool
-        *True* if the event is a double-click.
+        Whether the event is a double-click.
 
     Examples
     --------
@@ -1470,6 +1482,8 @@ def __init__(self, name, canvas, x, y, button=None, key=None,
         button pressed None, 1, 2, 3, 'up', 'down'
         """
         LocationEvent.__init__(self, name, canvas, x, y, guiEvent=guiEvent)
+        if button in MouseButton.__members__.values():
+            button = MouseButton(button)
         self.button = button
         self.key = key
         self.step = step
