Move QuiverKey position info onto its label Text

QuLogic · QuLogic · commit a3c503253cd3 · 2024-03-26T05:52:34.000-04:00
Additionally, add getters/setters for these properties, and use an
`offset_copy` Transform to implement `labelsep`. This makes one less
thing depending on the DPI change signal.
diff --git a/doc/api/next_api_changes/behavior/18794-ES.rst b/doc/api/next_api_changes/behavior/18794-ES.rst
@@ -9,8 +9,16 @@ effect on the final result.
 Now all such properties have getters and setters, and may be modified after
 creation:
 
+- `.QuiverKey.X` -> `.QuiverKey.get_x` / `.QuiverKey.set_x` /
+  `.QuiverKey.get_position` / `.QuiverKey.set_position`
+- `.QuiverKey.Y` -> `.QuiverKey.get_y` / `.QuiverKey.set_y` /
+  `.QuiverKey.get_position` / `.QuiverKey.set_position`
 - `.QuiverKey.label` -> `.QuiverKey.get_label` / `.QuiverKey.set_label`
 - `.QuiverKey.labelcolor` -> `.QuiverKey.get_labelcolor` /
   `.QuiverKey.set_labelcolor`
 - `.QuiverKey.labelpos` -> `.QuiverKey.get_labelpos` /
   `.QuiverKey.set_labelpos`
+- `.QuiverKey.labelsep` is now read-only as it used a different unit (pixels)
+  than the constructor (inches), and was automatically overwritten;
+  `.QuiverKey.get_labelsep` and `.QuiverKey.set_labelsep` have been added which
+  use inches
diff --git a/doc/users/next_whats_new/quiverkey.rst b/doc/users/next_whats_new/quiverkey.rst
@@ -9,8 +9,16 @@ effect on the final result.
 Now all such properties have getters and setters, and may be modified after
 creation:
 
+- `.QuiverKey.X` -> `.QuiverKey.get_x` / `.QuiverKey.set_x` /
+  `.QuiverKey.get_position` / `.QuiverKey.set_position`
+- `.QuiverKey.Y` -> `.QuiverKey.get_y` / `.QuiverKey.set_y` /
+  `.QuiverKey.get_position` / `.QuiverKey.set_position`
 - `.QuiverKey.label` -> `.QuiverKey.get_label` / `.QuiverKey.set_label`
 - `.QuiverKey.labelcolor` -> `.QuiverKey.get_labelcolor` /
   `.QuiverKey.set_labelcolor`
 - `.QuiverKey.labelpos` -> `.QuiverKey.get_labelpos` /
   `.QuiverKey.set_labelpos`
+- `.QuiverKey.labelsep` is now read-only as it used a different unit (pixels)
+  than the constructor (inches), and was automatically overwritten;
+  `.QuiverKey.get_labelsep` and `.QuiverKey.set_labelsep` have been added which
+  use inches
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -290,8 +290,6 @@ def __init__(self, Q, X, Y, U, label,
         """
         super().__init__()
         self.Q = Q
-        self.X = X
-        self.Y = Y
         self.U = U
         self.angle = angle
         self.coord = coordinates
@@ -303,14 +301,66 @@ def __init__(self, Q, X, Y, U, label,
         self.fontproperties = fontproperties or dict()
         self.kw = kwargs
         self.text = mtext.Text(
-            text=label,
+            x=X, y=Y, text=label,
             horizontalalignment=self.halign[self._labelpos],
             verticalalignment=self.valign[self._labelpos],
             fontproperties=self.fontproperties,
             color=labelcolor)
         self._dpi_at_last_init = None
         self.zorder = Q.zorder + 0.1
 
+    def get_x(self):
+        """Return the *x* position of the QuiverKey."""
+        return self.text.get_position()[0]
+
+    def set_x(self, x):
+        """
+        Set the *x* position of the QuiverKey.
+
+        Parameters
+        ----------
+        x : float
+            The *x* location of the key.
+        """
+        self.text.set_x(x)
+        self.stale = True
+
+    X = property(get_x, set_x)
+
+    def get_y(self):
+        """Return the *y* position of the QuiverKey."""
+        return self.text.get_position()[1]
+
+    def set_y(self, y):
+        """
+        Set the *y* position of the QuiverKey.
+
+        Parameters
+        ----------
+        y : float
+            The *y* location of the key.
+        """
+        self.text.set_y(y)
+        self.stale = True
+
+    Y = property(get_y, set_y)
+
+    def get_position(self):
+        """Return the (x, y) position of the QuiverKey."""
+        return self.text.get_position()
+
+    def set_position(self, xy):
+        """
+        Set the position of the QuiverKey.
+
+        Parameters
+        ----------
+        xy : (float, float)
+            The (*x*, *y*) position of the QuiverKey.
+        """
+        self.text.set_position(xy)
+        self.stale = True
+
     def get_label_text(self):
         """Return the label string."""
         return self.text.get_text()
@@ -351,13 +401,25 @@ def set_label_pos(self, labelpos):
         self._labelpos = labelpos
         self.text.set_horizontalalignment(self.halign[labelpos])
         self.text.set_verticalalignment(self.valign[labelpos])
+        self._update_text_transform()
         self._initialized = False
         self.stale = True
 
     labelpos = property(get_label_pos, set_label_pos, doc="The label position.")
 
+    def get_labelsep(self):
+        """Return the distance between the arrow and label in inches."""
+        return self._labelsep_inches
+
+    def set_labelsep(self, labelsep):
+        """Set the distance between the arrow and label in inches."""
+        self._labelsep_inches = labelsep
+        self._update_text_transform()
+        self.stale = True
+
     @property
     def labelsep(self):
+        """Return the distance between the arrow and label in pixels."""
         return self._labelsep_inches * self.Q.axes.figure.dpi
 
     def _init(self):
@@ -385,20 +447,21 @@ def _init(self):
             self.vector.set_figure(self.get_figure())
             self._dpi_at_last_init = self.Q.axes.figure.dpi
 
-    def _text_shift(self):
-        return {
-            "N": (0, +self.labelsep),
-            "S": (0, -self.labelsep),
-            "E": (+self.labelsep, 0),
-            "W": (-self.labelsep, 0),
+    def _update_text_transform(self):
+        x, y = {
+            "N": (0, +self._labelsep_inches),
+            "S": (0, -self._labelsep_inches),
+            "E": (+self._labelsep_inches, 0),
+            "W": (-self._labelsep_inches, 0),
         }[self._labelpos]
+        self.text.set_transform(
+            transforms.offset_copy(self.get_transform(), self.figure, x=x, y=y))
 
     @martist.allow_rasterization
     def draw(self, renderer):
         self._init()
         self.vector.draw(renderer)
-        pos = self.get_transform().transform((self.X, self.Y))
-        self.text.set_position(pos + self._text_shift())
+        self._update_text_transform()
         self.text.draw(renderer)
         self.stale = False
 
diff --git a/lib/matplotlib/quiver.pyi b/lib/matplotlib/quiver.pyi
@@ -17,8 +17,6 @@ class QuiverKey(martist.Artist):
     valign: dict[Literal["N", "S", "E", "W"], Literal["top", "center", "bottom"]]
     pivot: dict[Literal["N", "S", "E", "W"], Literal["middle", "tip", "tail"]]
     Q: Quiver
-    X: float
-    Y: float
     U: float
     angle: float
     coord: Literal["axes", "figure", "data", "inches"]
@@ -44,6 +42,14 @@ class QuiverKey(martist.Artist):
         fontproperties: dict[str, Any] | None = ...,
         **kwargs
     ) -> None: ...
+    def get_x(self) -> float: ...
+    def set_x(self, x: float) -> None: ...
+    X: float
+    def get_y(self) -> float: ...
+    def set_y(self, y: float) -> None: ...
+    Y: float
+    def get_position(self) -> tuple[float, float]: ...
+    def set_position(self, xy: tuple[float, float]) -> None: ...
     def get_label_text(self) -> str: ...
     def set_label_text(self, text: str) -> None: ...
     label: str
@@ -53,6 +59,8 @@ class QuiverKey(martist.Artist):
     def get_label_pos(self) -> Literal["N", "S", "E", "W"]: ...
     def set_label_pos(self, labelpos: Literal["N", "S", "E", "W"]) -> None: ...
     labelpos: Literal["N", "S", "E", "W"]
+    def get_labelsep(self) -> float: ...
+    def set_labelsep(self, labelsep: float) -> None: ...
     @property
     def labelsep(self) -> float: ...
     def set_figure(self, fig: Figure) -> None: ...
diff --git a/lib/matplotlib/tests/test_quiver.py b/lib/matplotlib/tests/test_quiver.py
@@ -113,11 +113,14 @@ def test_quiver_with_key():
     fig, ax = plt.subplots()
     ax.margins(0.1)
     Q = draw_quiver(ax)
-    qk = ax.quiverkey(Q, 0.5, 0.95, 2, '',
+    qk = ax.quiverkey(Q, 0, 0, 2, '',
                       angle=-10, coordinates='figure',
-                      labelpos='W', labelcolor='b',
+                      labelpos='N', labelcolor='b',
                       fontproperties={'weight': 'bold', 'size': 'large'})
+    qk.set_x(0.5)
+    qk.set_y(0.95)
     qk.set_label_text(r'$2\, \mathrm{m}\, \mathrm{s}^{-1}$')
+    qk.set_label_pos('W')
     qk.set_label_color('k')  # Go back to default to keep same test image.
 
 
