Make some QuiverKey label properties modifiable

QuLogic · QuLogic · commit cb458736ae34 · 2024-03-26T01:16:57.000-04:00
diff --git a/doc/api/next_api_changes/behavior/18794-ES.rst b/doc/api/next_api_changes/behavior/18794-ES.rst
@@ -0,0 +1,16 @@
+``QuiverKey`` properties are now modifiable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `.QuiverKey` object returned by `.pyplot.quiverkey` and
+`.axes.Axes.quiverkey` formerly saved various properties as attributes during
+initialization. However, modifying these attributes may or may not have had an
+effect on the final result.
+
+Now all such properties have getters and setters, and may be modified after
+creation:
+
+- `.QuiverKey.label` -> `.QuiverKey.get_label` / `.QuiverKey.set_label`
+- `.QuiverKey.labelcolor` -> `.QuiverKey.get_labelcolor` /
+  `.QuiverKey.set_labelcolor`
+- `.QuiverKey.labelpos` -> `.QuiverKey.get_labelpos` /
+  `.QuiverKey.set_labelpos`
diff --git a/doc/users/next_whats_new/quiverkey.rst b/doc/users/next_whats_new/quiverkey.rst
@@ -0,0 +1,16 @@
+``QuiverKey`` properties are now modifiable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `.QuiverKey` object returned by `.pyplot.quiverkey` and
+`.axes.Axes.quiverkey` formerly saved various properties as attributes during
+initialization. However, modifying these attributes may or may not have had an
+effect on the final result.
+
+Now all such properties have getters and setters, and may be modified after
+creation:
+
+- `.QuiverKey.label` -> `.QuiverKey.get_label` / `.QuiverKey.set_label`
+- `.QuiverKey.labelcolor` -> `.QuiverKey.get_labelcolor` /
+  `.QuiverKey.set_labelcolor`
+- `.QuiverKey.labelpos` -> `.QuiverKey.get_labelpos` /
+  `.QuiverKey.set_labelpos`
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -296,23 +296,66 @@ def __init__(self, Q, X, Y, U, label,
         self.angle = angle
         self.coord = coordinates
         self.color = color
-        self.label = label
         self._labelsep_inches = labelsep
 
-        self.labelpos = labelpos
-        self.labelcolor = labelcolor
+        _api.check_in_list(['N', 'S', 'E', 'W'], labelpos=labelpos)
+        self._labelpos = labelpos
         self.fontproperties = fontproperties or dict()
         self.kw = kwargs
         self.text = mtext.Text(
             text=label,
-            horizontalalignment=self.halign[self.labelpos],
-            verticalalignment=self.valign[self.labelpos],
-            fontproperties=self.fontproperties)
-        if self.labelcolor is not None:
-            self.text.set_color(self.labelcolor)
+            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_label_text(self):
+        """Return the label string."""
+        return self.text.get_text()
+
+    def set_label_text(self, text):
+        """Set the label string."""
+        self.text.set_text(text)
+        self.stale = True
+
+    label = property(get_label_text, set_label_text, doc="The label string.")
+
+    def get_label_color(self):
+        """Return the label color."""
+        return self.text.get_color()
+
+    def set_label_color(self, labelcolor):
+        """Set the label color."""
+        self.text.set_color(labelcolor)
+        self.stale = True
+
+    labelcolor = property(get_label_color, set_label_color, doc="The label color.")
+
+    def get_label_pos(self):
+        """Return the label position."""
+        return self._labelpos
+
+    def set_label_pos(self, labelpos):
+        """
+        Set the label position.
+
+        Parameters
+        ----------
+        labelpos : {'N', 'S', 'E', 'W'}
+            Position the label above, below, to the right, to the left of the
+            arrow, respectively.
+        """
+        _api.check_in_list(['N', 'S', 'E', 'W'], labelpos=labelpos)
+        self._labelpos = labelpos
+        self.text.set_horizontalalignment(self.halign[labelpos])
+        self.text.set_verticalalignment(self.valign[labelpos])
+        self._initialized = False
+        self.stale = True
+
+    labelpos = property(get_label_pos, set_label_pos, doc="The label position.")
+
     @property
     def labelsep(self):
         return self._labelsep_inches * self.Q.axes.figure.dpi
@@ -322,7 +365,7 @@ def _init(self):
             if self.Q._dpi_at_last_init != self.Q.axes.figure.dpi:
                 self.Q._init()
             self._set_transform()
-            with cbook._setattr_cm(self.Q, pivot=self.pivot[self.labelpos],
+            with cbook._setattr_cm(self.Q, pivot=self.pivot[self._labelpos],
                                    # Hack: save and restore the Umask
                                    Umask=ma.nomask):
                 u = self.U * np.cos(np.radians(self.angle))
@@ -348,7 +391,7 @@ def _text_shift(self):
             "S": (0, -self.labelsep),
             "E": (+self.labelsep, 0),
             "W": (-self.labelsep, 0),
-        }[self.labelpos]
+        }[self._labelpos]
 
     @martist.allow_rasterization
     def draw(self, renderer):
diff --git a/lib/matplotlib/quiver.pyi b/lib/matplotlib/quiver.pyi
@@ -23,9 +23,6 @@ class QuiverKey(martist.Artist):
     angle: float
     coord: Literal["axes", "figure", "data", "inches"]
     color: ColorType | None
-    label: str
-    labelpos: Literal["N", "S", "E", "W"]
-    labelcolor: ColorType | None
     fontproperties: dict[str, Any]
     kw: dict[str, Any]
     text: Text
@@ -47,6 +44,15 @@ class QuiverKey(martist.Artist):
         fontproperties: dict[str, Any] | None = ...,
         **kwargs
     ) -> None: ...
+    def get_label_text(self) -> str: ...
+    def set_label_text(self, text: str) -> None: ...
+    label: str
+    def get_label_color(self) -> ColorType | None: ...
+    def set_label_color(self, labelcolor: ColorType | None) -> None: ...
+    labelcolor: ColorType | None
+    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"]
     @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,12 +113,12 @@ def test_quiver_with_key():
     fig, ax = plt.subplots()
     ax.margins(0.1)
     Q = draw_quiver(ax)
-    ax.quiverkey(Q, 0.5, 0.95, 2,
-                 r'$2\, \mathrm{m}\, \mathrm{s}^{-1}$',
-                 angle=-10,
-                 coordinates='figure',
-                 labelpos='W',
-                 fontproperties={'weight': 'bold', 'size': 'large'})
+    qk = ax.quiverkey(Q, 0.5, 0.95, 2, '',
+                      angle=-10, coordinates='figure',
+                      labelpos='W', labelcolor='b',
+                      fontproperties={'weight': 'bold', 'size': 'large'})
+    qk.set_label_text(r'$2\, \mathrm{m}\, \mathrm{s}^{-1}$')
+    qk.set_label_color('k')  # Go back to default to keep same test image.
 
 
 @image_comparison(['quiver_single_test_image.png'], remove_text=True)
@@ -147,8 +147,8 @@ def test_quiver_key_pivot():
     ax.set_ylim(-2, 11)
     ax.quiverkey(q, 0.5, 1, 1, 'N', labelpos='N')
     ax.quiverkey(q, 1, 0.5, 1, 'E', labelpos='E')
-    ax.quiverkey(q, 0.5, 0, 1, 'S', labelpos='S')
-    ax.quiverkey(q, 0, 0.5, 1, 'W', labelpos='W')
+    ax.quiverkey(q, 0.5, 0, 1, 'S').set_label_pos('S')
+    ax.quiverkey(q, 0, 0.5, 1, 'W').set_label_pos('W')
 
 
 @image_comparison(['quiver_key_xy.png'], remove_text=True)
