Make arrow annotation arrowhead adjustable (tests, whatsnew).

[Only part of the patch was kept by the PR committer.]

Author: CharlieThornton33

doc/release/next_whats_new/box_arrow_size_controls.rst

@@ -0,0 +1,37 @@
+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.
+
+To give a consistent appearance across all parameter values, the
+default head position (where the head starts relative to text) is
+slightly changed compared to the previous hard-coded position.
+
+By using negative angles (or corresponding reflex angles) for *head_angle*, arrows
+with 'backwards' heads may be created.
+
+.. plot::
+    :include-source: true
+    :alt:
+        Six arrow-shaped text boxes.  The arrows on the left have the shaft on
+        their left; the arrows on the right have the shaft on the right; the
+        arrows in the middle have shafts on both sides.
+
+    import matplotlib.pyplot as plt
+
+    plt.text(0.2, 0.8, "LArrow", ha='center', size=16,
+             bbox=dict(boxstyle="larrow, pad=0.3, head_angle=150"))
+    plt.text(0.2, 0.2, "LArrow", ha='center', size=16,
+             bbox=dict(boxstyle="larrow, pad=0.3, head_width=0.5"))
+    plt.text(0.5, 0.8, "DArrow", ha='center', size=16,
+             bbox=dict(boxstyle="darrow, pad=0.3, head_width=3"))
+    plt.text(0.5, 0.2, "DArrow", ha='center', size=16,
+             bbox=dict(boxstyle="darrow, pad=0.3, head_width=1, head_angle=60"))
+    plt.text(0.8, 0.8, "RArrow", ha='center', size=16,
+             bbox=dict(boxstyle="rarrow, pad=0.3, head_angle=30"))
+    plt.text(0.8, 0.2, "RArrow", ha='center', size=16,
+             bbox=dict(boxstyle="rarrow, pad=0.3, head_width=2, head_angle=-90"))
+
+    plt.show()

lib/matplotlib/patches.pyi

@@ -381,7 +381,11 @@ class BoxStyle(_Style):
 
     class RArrow(BoxStyle):
         pad: float
-        def __init__(self, pad: float = ...) -> None: ...
+        head_width: float
+        head_angle: float
+        def __init__(
+            self, pad: float = ..., head_width: float = ..., head_angle: float = ...
+        ) -> None: ...
         def __call__(
             self,
             x0: float,
@@ -403,7 +407,11 @@ class BoxStyle(_Style):
 
     class DArrow(RArrow):
         pad: float
-        def __init__(self, pad: float = ...) -> None: ...
+        head_width: float
+        head_angle: float
+        def __init__(
+            self, pad: float = ..., head_width: float = ..., head_angle: float = ...
+        ) -> None: ...
         def __call__(
             self,
             x0: float,

lib/matplotlib/tests/baseline_images/test_arrow_patches/boxarrow_adjustment_test_image.png

@@ -49,6 +49,48 @@ def test_boxarrow():
                  bbox=dict(boxstyle=stylename, fc="w", ec="k"))
 
 
+@image_comparison(['boxarrow_adjustment_test_image.png'], style='mpl20')
+def test_boxarrow_adjustment():
+
+    styles = ['larrow', 'rarrow', 'darrow']
+
+    # Cases [head_width, head_angle] to test for each arrow style
+    cases = [
+        [1.5, 90],
+        [1.5, 170],     # Test dynamic padding
+        [0.75, 30],
+        [0.5, -10],     # Should just give a rectangle
+        [2, -90],
+        [2, -15]        # None of arrow body is outside of head
+    ]
+
+    # Horizontal and vertical spacings of arrow centres
+    spacing_horizontal = 3.75
+    spacing_vertical = 1.6
+
+    # Numbers of styles and cases
+    m = len(styles)
+    n = len(cases)
+
+    figwidth = (m * spacing_horizontal)
+    figheight = (n * spacing_vertical) + .5
+
+    fig = plt.figure(figsize=(figwidth / 1.5, figheight / 1.5))
+
+    fontsize = 0.3 * 72
+
+    for i, stylename in enumerate(styles):
+        for j, case in enumerate(cases):
+            # Draw arrow
+            fig.text(
+                ((m - i) * spacing_horizontal - 1.5) / figwidth,
+                ((n - j) * spacing_vertical - 0.5) / figheight,
+                stylename, ha='center', va='center',
+                size=fontsize, transform=fig.transFigure,
+                bbox=dict(boxstyle=f"{stylename}, head_width={case[0]}, \
+                    head_angle={case[1]}", fc="w", ec="k"))
+
+
 def __prepare_fancyarrow_dpi_cor_test():
     """
     Convenience function that prepares and returns a FancyArrowPatch. It aims