matplotlib · muchojp · Jun 4, 2024 · Jun 4, 2024 · Jun 4, 2024 · Jun 4, 2024
diff --git a/doc/api/next_api_changes/behavior/23116-YN.rst b/doc/api/next_api_changes/behavior/23116-YN.rst
@@ -0,0 +1,5 @@
+Add zorder option in QuiverKey
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It has been needed to use ``set_zorder`` when you set zorder in the QuiverKey.
+This change can set zorder with ``zorder`` argument in the QuiverKey
+in the same way as other plots.
diff --git a/lib/matplotlib/quiver.py b/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,9 @@ 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 self.zorder is None:
+            self.zorder = Q.zorder + 0.1
 
     @property
     def labelsep(self):

diff --git a/lib/matplotlib/quiver.pyi b/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

diff --git a/lib/matplotlib/tests/test_quiver.py b/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,93 @@ 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)
+
+
+@check_figures_equal(extensions=['png'])
+def test_quiverkey_zorder_default(fig_test, fig_ref):
+    """Check QuiverKey zorder option"""
+    draw_quiverkey_zorder_argument(fig_test)
+    draw_quiverkey_setzorder(fig_ref)
+
+
+@check_figures_equal(extensions=['png'])
+def test_quiverkey_zorder_zero(fig_test, fig_ref):
+    """
+    Check QuiverKey zorder option
+    zorder=0 means quiverkey is under quiver.
+    """
+    draw_quiverkey_zorder_argument(fig_test, zorder=0)
+    draw_quiverkey_setzorder(fig_ref, zorder=0)
+
+
+@check_figures_equal(extensions=['png'])
+def test_quiverkey_zorder_two(fig_test, fig_ref):
+    """
+    Check QuiverKey zorder option
+    zorder=2 means quiverkey is same as default.
+    """
+    draw_quiverkey_zorder_argument(fig_test, zorder=2)
+    draw_quiverkey_setzorder(fig_ref, zorder=2)
+
+
+@check_figures_equal(extensions=['png'])
+def test_quiverkey_zorder_five(fig_test, fig_ref):
+    """
+    Check QuiverKey zorder option
+    zorder=5 means quiverkey is over ticks.
+    """
+    draw_quiverkey_zorder_argument(fig_test, zorder=5)
+    draw_quiverkey_setzorder(fig_ref, zorder=5)
+
+
+@check_figures_equal(extensions=['png'])
+def test_quiverkey_zorder_None(fig_test, fig_ref):
+    """
+    Check QuiverKey zorder option
+    zorder=None means quiverkey is over ticks.
+    """
+    draw_quiverkey_zorder_argument(fig_test, zorder=None)
+    draw_quiverkey_setzorder(fig_ref, zorder=None)