From 8596a8d1101c8b7cc06ff189af69e6867bf5e3ea Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 14 Mar 2025 19:58:23 +0100 Subject: [PATCH] DOC: Improve FancyArrowPatch docstring --- lib/matplotlib/patches.py | 87 ++++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 23 deletions(-) diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 2cc09a5931f6..63453d416b99 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -2358,7 +2358,7 @@ def get_styles(cls): @classmethod def pprint_styles(cls): """Return the available styles as pretty-printed string.""" - table = [('Class', 'Name', 'Attrs'), + table = [('Class', 'Name', 'Parameters'), *[(cls.__name__, # Add backquotes, as - and | have special meaning in reST. f'``{name}``', @@ -4182,49 +4182,90 @@ def __init__(self, posA=None, posB=None, *, patchA=None, patchB=None, shrinkA=2, shrinkB=2, mutation_scale=1, mutation_aspect=1, **kwargs): """ - There are two ways for defining an arrow: + **Defining the arrow position and path** - - If *posA* and *posB* are given, a path connecting two points is - created according to *connectionstyle*. The path will be - clipped with *patchA* and *patchB* and further shrunken by - *shrinkA* and *shrinkB*. An arrow is drawn along this - resulting path using the *arrowstyle* parameter. + There are two ways to define the arrow position and path: - - Alternatively if *path* is provided, an arrow is drawn along this - path and *patchA*, *patchB*, *shrinkA*, and *shrinkB* are ignored. + - **Start, end and connection**: + The typical approach is to define the start and end points of the + arrow using *posA* and *posB*. The curve between these two can + further be configured using *connectionstyle*. + + If given, the arrow curve is clipped by *patchA* and *patchB*, + allowing it to start/end at the border of these patches. + Additionally, the arrow curve can be shortened by *shrinkA* and *shrinkB* + to create a margin between start/end (after possible clipping) and the + drawn arrow. + + - **path**: Alternatively if *path* is provided, an arrow is drawn along + this Path. In this case, *connectionstyle*, *patchA*, *patchB*, + *shrinkA*, and *shrinkB* are ignored. + + **Styling** + + The *arrowstyle* defines the styling of the arrow head, tail and shaft. + The resulting arrows can be styled further by setting the `.Patch` + properties such as *linewidth*, *color*, *facecolor*, *edgecolor* + etc. via keyword arguments. Parameters ---------- - posA, posB : (float, float), default: None - (x, y) coordinates of arrow tail and arrow head respectively. + posA, posB : (float, float), optional + (x, y) coordinates of start and end point of the arrow. + The actually drawn start and end positions may be modified + through *patchA*, *patchB*, *shrinkA*, and *shrinkB*. - path : `~matplotlib.path.Path`, default: None + *posA*, *posB* are exclusive of *path*. + + path : `~matplotlib.path.Path`, optional If provided, an arrow is drawn along this path and *patchA*, *patchB*, *shrinkA*, and *shrinkB* are ignored. + *path* is exclusive of *posA*, *posB*. + arrowstyle : str or `.ArrowStyle`, default: 'simple' - The `.ArrowStyle` with which the fancy arrow is drawn. If a - string, it should be one of the available arrowstyle names, with - optional comma-separated attributes. The optional attributes are - meant to be scaled with the *mutation_scale*. The following arrow - styles are available: + The styling of arrow head, tail and shaft. This can be + + - `.ArrowStyle` or one of its subclasses + - The shorthand string name (e.g. "->") as given in the table below, + optionally containing a comma-separated list of style parameters, + e.g. "->, head_length=10, head_width=5". + + The style parameters are scaled by *mutation_scale*. + + The following arrow styles are available. See also + :doc:`/gallery/text_labels_and_annotations/fancyarrow_demo`. %(ArrowStyle:table)s + Only the styles ``<|-``, ``-|>``, ``<|-|>`` ``simple``, ``fancy`` + and ``wedge`` contain closed paths and can be filled. + connectionstyle : str or `.ConnectionStyle` or None, optional, \ default: 'arc3' - The `.ConnectionStyle` with which *posA* and *posB* are connected. - If a string, it should be one of the available connectionstyle - names, with optional comma-separated attributes. The following - connection styles are available: + `.ConnectionStyle` with which *posA* and *posB* are connected. + This can be + + - `.ConnectionStyle` or one of its subclasses + - The shorthand string name as given in the table below, e.g. "arc3". %(ConnectionStyle:table)s + Ignored if *path* is provided. + patchA, patchB : `~matplotlib.patches.Patch`, default: None - Head and tail patches, respectively. + Optional Patches at *posA* and *posB*, respectively. If given, + the arrow path is clipped by these patches such that head and tail + are at the border of the patches. + + Ignored if *path* is provided. shrinkA, shrinkB : float, default: 2 - Shrink amount, in points, of the tail and head of the arrow respectively. + Shorten the arrow path at *posA* and *posB* by this amount in points. + This allows to add a margin between the intended start/end points and + the arrow. + + Ignored if *path* is provided. mutation_scale : float, default: 1 Value with which attributes of *arrowstyle* (e.g., *head_length*) pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy