matplotlib.text
¶Classes for including text in a figure.
matplotlib.text.
Annotation
(text, xy, xytext=None, xycoords='data', textcoords=None, arrowprops=None, annotation_clip=None, **kwargs)[source]¶Bases: matplotlib.text.Text
, matplotlib.text._AnnotationBase
An Annotation
is a Text
that can refer to a specific position xy.
Optionally an arrow pointing from the text to xy can be drawn.
Attributes: |
|
---|
Annotate the point xy with text text.
In the simplest form, the text is placed at xy.
Optionally, the text can be displayed in another position xytext. An arrow pointing from the text to the annotated point xy can then be added by defining arrowprops.
Parameters: |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Returns: |
|
See also
anncoords
¶The coordinate system to use for Annotation.xyann
.
arrow
¶[Deprecated]
Notes
Deprecated since version 3.0: arrow was deprecated in Matplotlib 3.0 and will be removed in 3.2. Use arrow_patch instead.
contains
(self, event)[source]¶Test whether the mouse event occurred in the patch.
In the case of text, a hit is true anywhere in the axis-aligned bounding-box containing the text.
Returns: |
|
---|
draw
(self, renderer)[source]¶Draw the Annotation
object to the given renderer.
get_anncoords
(self)¶Return the coordinate system to use for Annotation.xyann
.
See also xycoords in Annotation
.
get_window_extent
(self, renderer=None)[source]¶Return the Bbox
bounding the text and arrow, in display units.
Parameters: |
|
---|
set_anncoords
(self, coords)¶Set the coordinate system to use for Annotation.xyann
.
See also xycoords in Annotation
.
set_figure
(self, fig)[source]¶Set the Figure
instance the artist belongs to.
Parameters: |
|
---|
update_positions
(self, renderer)[source]¶Update the pixel positions of the annotated point and the text.
xyann
¶The the text position.
See also xytext in Annotation
.
matplotlib.text.
OffsetFrom
(artist, ref_coord, unit='points')[source]¶Bases: object
Callable helper class for working with Annotation
Parameters: |
|
---|
matplotlib.text.
Text
(x=0, y=0, text='', color=None, verticalalignment='baseline', horizontalalignment='left', multialignment=None, fontproperties=None, rotation=None, linespacing=None, rotation_mode=None, usetex=None, wrap=False, **kwargs)[source]¶Bases: matplotlib.artist.Artist
Handle storing and drawing of text in window or data coordinates.
Create a Text
instance at x, y with string text.
Valid kwargs are
Property Description agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha
float animated
bool backgroundcolor
color bbox
dict with properties for patches.FancyBboxPatch
clip_box
Bbox
clip_on
bool clip_path
[( Path
,Transform
) |Patch
| None]color
or ccolor contains
callable figure
Figure
fontfamily
or family{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontproperties
or font_propertiesfont_manager.FontProperties
fontsize
or size{size in points, 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} fontstretch
or stretch{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'} fontstyle
or style{'normal', 'italic', 'oblique'} fontvariant
or variant{'normal', 'small-caps'} fontweight
or weight{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'} gid
str horizontalalignment
or ha{'center', 'right', 'left'} in_layout
bool label
object linespacing
float (multiple of font size) multialignment
or ma{'left', 'right', 'center'} path_effects
AbstractPathEffect
picker
None or bool or float or callable position
(float, float) rasterized
bool or None rotation
{angle in degrees, 'vertical', 'horizontal'} rotation_mode
{None, 'default', 'anchor'} sketch_params
(scale: float, length: float, randomness: float) snap
bool or None text
object transform
Transform
url
str usetex
bool or None verticalalignment
or va{'center', 'top', 'bottom', 'baseline', 'center_baseline'} visible
bool wrap
bool x
float y
float zorder
float
contains
(self, mouseevent)[source]¶Test whether the mouse event occurred in the patch.
In the case of text, a hit is true anywhere in the axis-aligned bounding-box containing the text.
Returns: |
|
---|
get_bbox_patch
(self)[source]¶Return the bbox Patch, or None if the patches.FancyBboxPatch
is not made.
get_family
(self)¶Alias for get_fontfamily
.
get_font_properties
(self)¶Alias for get_fontproperties
.
get_fontproperties
(self)[source]¶Return the font_manager.FontProperties
object
get_ha
(self)¶Alias for get_horizontalalignment
.
get_horizontalalignment
(self)[source]¶Return the horizontal alignment as string. Will be one of 'left', 'center' or 'right'.
get_name
(self)¶Alias for get_fontname
.
get_prop_tup
(self, renderer=None)[source]¶Return a hashable tuple of properties.
Not intended to be human readable, but useful for backends who want to cache derived information about text (e.g., layouts) and need to know if the text has changed.
get_size
(self)¶Alias for get_fontsize
.
get_style
(self)¶Alias for get_fontstyle
.
get_va
(self)¶Alias for get_verticalalignment
.
get_variant
(self)¶Alias for get_fontvariant
.
get_verticalalignment
(self)[source]¶Return the vertical alignment as string. Will be one of 'top', 'center', 'bottom' or 'baseline'.
get_weight
(self)¶Alias for get_fontweight
.
get_window_extent
(self, renderer=None, dpi=None)[source]¶Return the Bbox
bounding the text, in display units.
In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.
Parameters: |
|
---|
is_math_text
(s, usetex=None)[source]¶[Deprecated] Returns a cleaned string and a boolean flag. The flag indicates if the given string s contains any mathtext, determined by counting unescaped dollar signs. If no mathtext is present, the cleaned string has its dollar signs unescaped. If usetex is on, the flag always has the value "TeX".
Notes
Deprecated since version 3.1.
set_backgroundcolor
(self, color)[source]¶Set the background color of the text by updating the bbox.
Parameters: |
|
---|
See also
set_bbox
set_bbox
(self, rectprops)[source]¶Draw a bounding box around self.
Parameters: |
|
---|
Examples
t.set_bbox(dict(facecolor='red', alpha=0.5))
set_clip_on
(self, b)[source]¶Set whether the artist uses clipping.
When False artists will be visible out side of the axes which can lead to unexpected results.
Parameters: |
|
---|
set_clip_path
(self, path, transform=None)[source]¶Set the artist's clip path, which may be:
Patch
(or subclass) instance; orPath
instance, in which case a
Transform
instance, which will be
applied to the path before using it for clipping, must be provided;
orNone
, to remove a previously set clipping path.For efficiency, if the path happens to be an axis-aligned rectangle,
this method will set the clipping box to the corresponding rectangle
and set the clipping path to None
.
set_family
(self, fontname)¶Alias for set_fontfamily
.
set_font_properties
(self, fp)¶Alias for set_fontproperties
.
set_fontfamily
(self, fontname)[source]¶Set the font family. May be either a single string, or a list of strings in decreasing priority. Each string may be either a real font name or a generic font class name. If the latter, the specific font names will be looked up in the corresponding rcParams.
If a Text
instance is constructed with fontfamily=None
, then the
font is set to rcParams["font.family"] = ['sans-serif']
, and the
same is done when set_fontfamily()
is called on an existing
Text
instance.
Parameters: |
|
---|
set_fontname
(self, fontname)[source]¶Alias for set_family
.
One-way alias only: the getter differs.
Parameters: |
|
---|
set_fontsize
(self, fontsize)[source]¶Set the font size. May be either a size string, relative to the default font size, or an absolute font size in points.
Parameters: |
|
---|
See also
set_fontstretch
(self, stretch)[source]¶Set the font stretch (horizontal condensation or expansion).
Parameters: |
|
---|
set_fontstyle
(self, fontstyle)[source]¶Set the font style.
Parameters: |
|
---|
set_fontvariant
(self, variant)[source]¶Set the font variant, either 'normal' or 'small-caps'.
Parameters: |
|
---|
set_fontweight
(self, weight)[source]¶Set the font weight.
Parameters: |
|
---|
set_ha
(self, align)¶Alias for set_horizontalalignment
.
set_horizontalalignment
(self, align)[source]¶Set the horizontal alignment to one of
Parameters: |
|
---|
set_linespacing
(self, spacing)[source]¶Set the line spacing as a multiple of the font size. Default is 1.2.
Parameters: |
|
---|
set_ma
(self, align)¶Alias for set_multialignment
.
set_multialignment
(self, align)[source]¶Set the alignment for multiple lines layout. The layout of the bounding box of all the lines is determined by the horizontalalignment and verticalalignment properties, but the multiline text within that box can be
Parameters: |
|
---|
set_name
(self, fontname)¶Alias for set_fontname
.
set_position
(self, xy)[source]¶Set the (x, y) position of the text.
Parameters: |
|
---|
set_rotation
(self, s)[source]¶Set the rotation of the text.
Parameters: |
|
---|
set_rotation_mode
(self, m)[source]¶Set text rotation mode.
Parameters: |
|
---|
set_size
(self, fontsize)¶Alias for set_fontsize
.
set_stretch
(self, stretch)¶Alias for set_fontstretch
.
set_style
(self, fontstyle)¶Alias for set_fontstyle
.
set_text
(self, s)[source]¶Set the text string s.
It may contain newlines (\n
) or math in LaTeX syntax.
Parameters: |
|
---|
set_usetex
(self, usetex)[source]¶Parameters: |
|
---|
set_va
(self, align)¶Alias for set_verticalalignment
.
set_variant
(self, variant)¶Alias for set_fontvariant
.
set_verticalalignment
(self, align)[source]¶Set the vertical alignment
Parameters: |
|
---|
set_weight
(self, weight)¶Alias for set_fontweight
.
update_bbox_position_size
(self, renderer)[source]¶Update the location and the size of the bbox.
This method should be used when the position and size of the bbox needs to be updated before actually drawing the bbox.
zorder
= 3¶matplotlib.text.
TextWithDash
(**kwargs)[source]¶Bases: matplotlib.text.Text
[Deprecated] This is basically a Text
with a dash
(drawn with a Line2D
) before/after
it. It is intended to be a drop-in replacement for
Text
, and should behave identically to
it when dashlength = 0.0.
The dash always comes between the point specified by
set_position()
and the text. When a
dash exists, the text alignment arguments (horizontalalignment,
verticalalignment) are ignored.
dashlength is the length of the dash in canvas units. (default = 0.0).
dashdirection is one of 0 or 1, where 0 draws the dash after the text and 1 before. (default = 0).
dashrotation specifies the rotation of the dash, and should
generally stay None. In this case
get_dashrotation()
returns
get_rotation()
. (i.e., the dash takes
its rotation from the text's rotation). Because the text center is
projected onto the dash, major deviations in the rotation cause
what may be considered visually unappealing results.
(default = None)
dashpad is a padding length to add (or subtract) space between the text and the dash, in canvas units. (default = 3)
dashpush "pushes" the dash and text away from the point
specified by set_position()
by the
amount in canvas units. (default = 0)
Note
The alignment of the two objects is based on the bounding box
of the Text
, as obtained by
get_window_extent()
. This, in
turn, appears to depend on the font metrics as given by the
rendering backend. Hence the quality of the "centering" of the
label text with respect to the dash varies depending on the
backend used.
Note
I'm not sure that I got the
get_window_extent()
right,
or whether that's sufficient for providing the object bounding
box.
Notes
Deprecated since version 3.1.
draw
(self, renderer)[source]¶Draw the TextWithDash
object to the given renderer.
get_dashpush
(self)[source]¶Get the extra spacing between the dash and the specified text position, in canvas units.
get_prop_tup
(self, renderer=None)[source]¶Return a hashable tuple of properties.
Not intended to be human readable, but useful for backends who want to cache derived information about text (e.g., layouts) and need to know if the text has changed.
get_window_extent
(self, renderer=None)[source]¶Return a Bbox
object bounding
the text, in display units.
In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.
renderer defaults to the _renderer attribute of the text
object. This is not assigned until the first execution of
draw()
, so you must use this kwarg if you want
to call get_window_extent()
prior to the first
draw()
. For getting web page regions, it is
simpler to call the method after saving the figure.
set_dashdirection
(self, dd)[source]¶Set the direction of the dash following the text. 1 is before the text and 0 is after. The default is 0, which is what you'd want for the typical case of ticks below and on the left of the figure.
Parameters: |
|
---|
set_dashlength
(self, dl)[source]¶Set the length of the dash, in canvas units.
Parameters: |
|
---|
set_dashpad
(self, dp)[source]¶Set the "pad" of the TextWithDash, which is the extra spacing between the dash and the text, in canvas units.
Parameters: |
|
---|
set_dashpush
(self, dp)[source]¶Set the "push" of the TextWithDash, which is the extra spacing between the beginning of the dash and the specified position.
Parameters: |
|
---|
set_dashrotation
(self, dr)[source]¶Set the rotation of the dash, in degrees.
Parameters: |
|
---|
set_figure
(self, fig)[source]¶Set the figure instance the artist belongs to.
Parameters: |
|
---|
set_position
(self, xy)[source]¶Set the (x, y) position of the TextWithDash
.
Parameters: |
|
---|
set_transform
(self, t)[source]¶Set the matplotlib.transforms.Transform
instance used
by this artist.
Parameters: |
|
---|
set_x
(self, x)[source]¶Set the x position of the TextWithDash
.
Parameters: |
|
---|
set_y
(self, y)[source]¶Set the y position of the TextWithDash
.
Parameters: |
|
---|