matplotlib · CharlieThornton33 · Dec 16, 2022 · Dec 16, 2022 · Dec 16, 2022 · Dec 16, 2022
diff --git a/doc/users/next_whats_new/box_arrow_size_controls.rst b/doc/users/next_whats_new/box_arrow_size_controls.rst
@@ -0,0 +1,48 @@
+Arrow-style sub-classes of ``BoxStyle`` support arrow head resizing
+-------------------------------------------------------------------
+
+The new *head_width* and *head_angle* parameters to
+`.BoxStyle.LArrow`, `.BoxStyle.RArrow` and `.BoxStyle.DArrow` allow for adjustment
+of the size and aspect ratio of the arrow heads used.
+
+By using negative angles (or corresponding reflex angles) for *head_angle*, arrows
+with 'backwards' heads may be created.
+
+.. plot::
+    :include-source: false
+    :alt: A plot containing two arrow-shaped text boxes. One arrow has a pentagonal 'road-sign' shape, and the other an inverted arrow head on each end.
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+
+    # Data for plotting; here, an intensity distribution for Fraunhofer diffraction
+    # from 7 thin slits
+    x_data = np.linspace(-3 * np.pi, 3 * np.pi, num=1000)
+    I_data = (np.sin(x_data * 3.5) / np.sin(x_data / 2)) ** 2
+
+    # Generate plot
+
+    fig, ax = plt.subplots()
+    plt.plot(x_data, I_data)
+
+    plt.xlim(-3 * np.pi, 3 * np.pi)
+    plt.ylim(0, 50)
+
+    #
+    # Annotate with boxed text in arrows
+    #
+
+    # head_width=1 gives 'road-sign' shape
+    t1 = ax.text(-1, 35, "Primary maximum",
+                ha="right", va="center", rotation=30, size=10,
+                bbox=dict(boxstyle="rarrow,pad=0.3,head_width=1,head_angle=60",
+                        fc="lightblue", ec="steelblue", lw=2))
+
+    # Negative head_angle gives reversed arrow heads
+    t2 = ax.text(np.pi, 30, "Lower intensity",
+                ha="center", va="center", rotation=0, size=10,
+                bbox=dict(boxstyle="darrow,pad=0.3,head_width=2,head_angle=-80",
+                        fc="lightblue", ec="steelblue", lw=2))
+
+
+    plt.show()
diff --git a/galleries/users_explain/text/annotations.py b/galleries/users_explain/text/annotations.py
@@ -230,20 +230,20 @@
 # The arguments are the name of the box style with its attributes as
 # keyword arguments. Currently, following box styles are implemented:
 #
-# ==========   ==============   ==========================
-# Class        Name             Attrs
-# ==========   ==============   ==========================
-# Circle       ``circle``       pad=0.3
-# DArrow       ``darrow``       pad=0.3
-# Ellipse      ``ellipse``      pad=0.3
-# LArrow       ``larrow``       pad=0.3
-# RArrow       ``rarrow``       pad=0.3
-# Round        ``round``        pad=0.3,rounding_size=None
-# Round4       ``round4``       pad=0.3,rounding_size=None
-# Roundtooth   ``roundtooth``   pad=0.3,tooth_size=None
-# Sawtooth     ``sawtooth``     pad=0.3,tooth_size=None
-# Square       ``square``       pad=0.3
-# ==========   ==============   ==========================
+#   ==========   ==============   ==========================
+#   Class        Name             Attrs
+#   ==========   ==============   ==========================
+#   Circle       ``circle``       pad=0.3
+#   DArrow       ``darrow``       pad=0.3,head_width=1.5,head_angle=90
+#   Ellipse      ``ellipse``      pad=0.3
+#   LArrow       ``larrow``       pad=0.3,head_width=1.5,head_angle=90
+#   RArrow       ``rarrow``       pad=0.3,head_width=1.5,head_angle=90
+#   Round        ``round``        pad=0.3,rounding_size=None
+#   Round4       ``round4``       pad=0.3,rounding_size=None
+#   Roundtooth   ``roundtooth``   pad=0.3,tooth_size=None
+#   Sawtooth     ``sawtooth``     pad=0.3,tooth_size=None
+#   Square       ``square``       pad=0.3
+#   ==========   ==============   ==========================
 #
 # .. figure:: /gallery/shapes_and_collections/images/sphx_glr_fancybox_demo_001.png
 #    :target: /gallery/shapes_and_collections/fancybox_demo.html
@@ -303,8 +303,8 @@ def custom_box_style(x0, y0, width, height, mutation_size):
     x0, y0 = x0 - pad, y0 - pad
     x1, y1 = x0 + width, y0 + height
     # return the new path
-    return Path([(x0, y0), (x1, y0), (x1, y1), (x0, y1),
-                 (x0-pad, (y0+y1)/2), (x0, y0), (x0, y0)],
+    return Path([(x0, y0), (x1, y0), (x1, y1), (x0, y1), (x0, y1-pad),
+                 (x0-pad, (y0+y1)/2), (x0, y0+pad), (x0, y0), (x0, y0)],
                 closed=True)
 
 fig, ax = plt.subplots(figsize=(3, 3))