Add Quiverkey zorder option (matplotlib#28354)

* add zorder option in QuiverKey

modify docstring
add zorder test

Add new api changes doc

* fix typo in docstring

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Author: 3 people

doc/api/next_api_changes/behavior/28354-YN.rst

@@ -0,0 +1,4 @@
+Add zorder option in QuiverKey
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``zorder`` can be used as a keyword argument to `.QuiverKey`. Previously,
+that parameter did not have any effect because the zorder was hard coded.

lib/matplotlib/quiver.py

@@ -241,7 +241,8 @@ class QuiverKey(martist.Artist):
 
     def __init__(self, Q, X, Y, U, label,
                  *, angle=0, coordinates='axes', color=None, labelsep=0.1,
-                 labelpos='N', labelcolor=None, fontproperties=None, **kwargs):
+                 labelpos='N', labelcolor=None, fontproperties=None,
+                 zorder=None, **kwargs):
         """
         Add a key to a quiver plot.
 
@@ -285,6 +286,8 @@ def __init__(self, Q, X, Y, U, label,
             A dictionary with keyword arguments accepted by the
             `~matplotlib.font_manager.FontProperties` initializer:
             *family*, *style*, *variant*, *size*, *weight*.
+        zorder : float
+            The zorder of the key. The default is 0.1 above *Q*.
         **kwargs
             Any additional keyword arguments are used to override vector
             properties taken from *Q*.
@@ -312,7 +315,7 @@ def __init__(self, Q, X, Y, U, label,
         if self.labelcolor is not None:
             self.text.set_color(self.labelcolor)
         self._dpi_at_last_init = None
-        self.zorder = Q.zorder + 0.1
+        self.zorder = zorder if zorder is not None else Q.zorder + 0.1
 
     @property
     def labelsep(self):

lib/matplotlib/quiver.pyi

@@ -45,6 +45,7 @@ class QuiverKey(martist.Artist):
         labelpos: Literal["N", "S", "E", "W"] = ...,
         labelcolor: ColorType | None = ...,
         fontproperties: dict[str, Any] | None = ...,
+        zorder: float | None = ...,
         **kwargs
     ) -> None: ...
     @property

lib/matplotlib/tests/test_quiver.py

@@ -6,6 +6,7 @@
 
 from matplotlib import pyplot as plt
 from matplotlib.testing.decorators import image_comparison
+from matplotlib.testing.decorators import check_figures_equal
 
 
 def draw_quiver(ax, **kwargs):
@@ -333,3 +334,53 @@ def test_quiver_setuvc_numbers():
 
     q = ax.quiver(X, Y, U, V)
     q.set_UVC(0, 1)
+
+
+def draw_quiverkey_zorder_argument(fig, zorder=None):
+    """Draw Quiver and QuiverKey using zorder argument"""
+    x = np.arange(1, 6, 1)
+    y = np.arange(1, 6, 1)
+    X, Y = np.meshgrid(x, y)
+    U, V = 2, 2
+
+    ax = fig.subplots()
+    q = ax.quiver(X, Y, U, V, pivot='middle')
+    ax.set_xlim(0.5, 5.5)
+    ax.set_ylim(0.5, 5.5)
+    if zorder is None:
+        ax.quiverkey(q, 4, 4, 25, coordinates='data',
+                     label='U', color='blue')
+        ax.quiverkey(q, 5.5, 2, 20, coordinates='data',
+                     label='V', color='blue', angle=90)
+    else:
+        ax.quiverkey(q, 4, 4, 25, coordinates='data',
+                     label='U', color='blue', zorder=zorder)
+        ax.quiverkey(q, 5.5, 2, 20, coordinates='data',
+                     label='V', color='blue', angle=90, zorder=zorder)
+
+
+def draw_quiverkey_setzorder(fig, zorder=None):
+    """Draw Quiver and QuiverKey using set_zorder"""
+    x = np.arange(1, 6, 1)
+    y = np.arange(1, 6, 1)
+    X, Y = np.meshgrid(x, y)
+    U, V = 2, 2
+
+    ax = fig.subplots()
+    q = ax.quiver(X, Y, U, V, pivot='middle')
+    ax.set_xlim(0.5, 5.5)
+    ax.set_ylim(0.5, 5.5)
+    qk1 = ax.quiverkey(q, 4, 4, 25, coordinates='data',
+                       label='U', color='blue')
+    qk2 = ax.quiverkey(q, 5.5, 2, 20, coordinates='data',
+                       label='V', color='blue', angle=90)
+    if zorder is not None:
+        qk1.set_zorder(zorder)
+        qk2.set_zorder(zorder)
+
+
+@pytest.mark.parametrize('zorder', [0, 2, 5, None])
+@check_figures_equal(extensions=['png'])
+def test_quiverkey_zorder(fig_test, fig_ref, zorder):
+    draw_quiverkey_zorder_argument(fig_test, zorder=zorder)
+    draw_quiverkey_setzorder(fig_ref, zorder=zorder)