Skip to content

Clarify Annotation arrowprops docs #21743

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 30, 2021
Merged

Clarify Annotation arrowprops docs #21743

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 23 additions & 27 deletions lib/matplotlib/text.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1710,9 +1710,13 @@ def transform(renderer) -> Transform

arrowprops : dict, optional
The properties used to draw a `.FancyArrowPatch` arrow between the
positions *xy* and *xytext*. Note that the edge of the arrow
pointing to *xytext* will be centered on the text itself and may
not point directly to the coordinates given in *xytext*.
positions *xy* and *xytext*. Defaults to None, i.e. no arrow is
drawn.

For historical reasons there are two different ways to specify
arrows, "simple" and "fancy":

**Simple arrow:**

If *arrowprops* does not contain the key 'arrowstyle' the
allowed keys are:
Expand All @@ -1727,35 +1731,22 @@ def transform(renderer) -> Transform
? Any key to :class:`matplotlib.patches.FancyArrowPatch`
========== ======================================================

If *arrowprops* contains the key 'arrowstyle' the
above keys are forbidden. The allowed values of
``'arrowstyle'`` are:

============ =============================================
Name Attrs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you drop this table on purpose?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. The table is incomplete: Not all styles are listed, not all parameters to the styles are listed. I think it's excessive to try and replicate all this information. Instead I hope that the sentence "Valid keys are the following ~matplotlib.patches.FancyArrowPatch parameters:" is enough context to it's subsequent table, which also lists arrowstyle. The FancyArrowPatch docs lists all styles and related parameters in detail.

============ =============================================
``'-'`` None
``'->'`` head_length=0.4,head_width=0.2
``'-['`` widthB=1.0,lengthB=0.2,angleB=None
``'|-|'`` widthA=1.0,widthB=1.0
``'-|>'`` head_length=0.4,head_width=0.2
``'<-'`` head_length=0.4,head_width=0.2
``'<->'`` head_length=0.4,head_width=0.2
``'<|-'`` head_length=0.4,head_width=0.2
``'<|-|>'`` head_length=0.4,head_width=0.2
``'fancy'`` head_length=0.4,head_width=0.4,tail_width=0.4
``'simple'`` head_length=0.5,head_width=0.5,tail_width=0.2
``'wedge'`` tail_width=0.3,shrink_factor=0.5
============ =============================================

Valid keys for `~matplotlib.patches.FancyArrowPatch` are:
The arrow is attached to the edge of the text box, the exact
position (corners or centers) depending on where it's pointing to.

**Fancy arrow:**

This is used if 'arrowstyle' is provided in the *arrowprops*.

Valid keys are the following `~matplotlib.patches.FancyArrowPatch`
parameters:

=============== ==================================================
Key Description
=============== ==================================================
arrowstyle the arrow style
connectionstyle the connection style
relpos default is (0.5, 0.5)
relpos see below; default is (0.5, 0.5)
patchA default is bounding box of the text
patchB default is None
shrinkA default is 2 points
Expand All @@ -1765,7 +1756,12 @@ def transform(renderer) -> Transform
? any key for :class:`matplotlib.patches.PathPatch`
=============== ==================================================

Defaults to None, i.e. no arrow is drawn.
The exact starting point position of the arrow is defined by
*relpos*. It's a tuple of relative coordinates of the text box,
where (0, 0) is the lower left corner and (1, 1) is the upper
right corner. Values <0 and >1 are supported and specify points
outside the text box. By default (0.5, 0.5) the starting point is
centered in the text box.

annotation_clip : bool or None, default: None
Whether to draw the annotation when the annotation point *xy* is
Expand Down