Improve documentation

Author: ericpre

doc/api/next_api_changes/deprecations/20839-EP.rst

@@ -1,4 +1,4 @@
 Selector widget state internals
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*state_modifier_keys* now have to be defined when creating a selector widget.
-The *state_modifier_keys* attribute is deprecated.
+*state_modifier_keys* are immutable now. They can be set when creating the
+widget, but cannot be changed afterwards anymore.

doc/users/next_whats_new/selector_improvement.rst

@@ -1,8 +1,16 @@
-Selectors improvement
----------------------
+Rotating selectors and aspect ratio correction
+----------------------------------------------
 
 The `~matplotlib.widgets.RectangleSelector` and
-`~matplotlib.widgets.EllipseSelector` can now be rotated interactively. The rotation is
-enabled and disabled by pressing the 'r' key.
-The "square" shape can be defined in data or display coordinate system as defined
-by the *data_coordinates* modifier.
+`~matplotlib.widgets.EllipseSelector` can now be rotated interactively.
+
+The rotation is enabled when *rotate* is added to
+:py:attr:`~matplotlib.widgets._SelectorWidget.state`, which can be done using
+:py:meth:`~matplotlib.widgets._SelectorWidget.add_state` or by striking
+the *state_modifier_keys* for *rotate* (default *r*).
+
+The aspect ratio of the axes can now be taken into account when using the
+"square" state. When *data_coordinates* is added to
+:py:attr:`~matplotlib.widgets._SelectorWidget.state`, which can be done using
+:py:meth:`~matplotlib.widgets._SelectorWidget.add_state` or by striking
+the *state_modifier_keys* for *data_coordinates* (default *d*).

lib/matplotlib/patches.py

@@ -721,7 +721,7 @@ def __init__(self, xy, width, height, angle=0.0, *,
             Rotation in degrees anti-clockwise about the rotation point.
         rotation_point : {'xy', 'center', (number, number)}, default: 'xy'
             If ``'xy'``, rotate around the anchor point. If ``'center'`` rotate
-            around the center. If 2-tuple of number, rotate around these
+            around the center. If 2-tuple of number, rotate around this
             coordinate.
 
         Other Parameters
@@ -740,7 +740,8 @@ def __init__(self, xy, width, height, angle=0.0, *,
         # The patch is defined in data coordinates and when changing the
         # selector with square modifier and not in data coordinates, we need
         # to correct for the aspect ratio difference between the data and
-        # display coordinate systems.
+        # display coordinate systems. Its value is typically provide by
+        # Axes._get_aspect_ratio()
         self._aspect_ratio_correction = 1.0
         self._convert_units()  # Validate the inputs.
 

lib/matplotlib/tests/test_widgets.py

@@ -440,7 +440,6 @@ def onselect(epress, erelease):
     tool.rotation = 45
     assert tool.rotation == 45
     # Corners should move
-    # The third corner is at (100, 145)
     assert_allclose(tool.corners,
                     np.array([[118.53, 139.75, 111.46, 90.25],
                               [95.25, 116.46, 144.75, 123.54]]), atol=0.01)

lib/matplotlib/widgets.py

@@ -3048,10 +3048,13 @@ def _onmove(self, event):
 
         dx = event.xdata - eventpress.xdata
         dy = event.ydata - eventpress.ydata
+        # refmax is used when moving the corner handle with the square state
+        # and is the maximum between refx and refy
         refmax = None
         if 'data_coordinates' in state:
             refx, refy = dx, dy
         else:
+            # Add 1e-6 to avoid divided by zero error
             refx = event.xdata / (eventpress.xdata + 1e-6)
             refy = event.ydata / (eventpress.ydata + 1e-6)