# matplotlib.offsetbox¶

Container classes for Artists.

OffsetBox
The base of all container artists defined in this module.
AnchoredOffsetbox, AnchoredText
Anchor and align an arbitrary Artist or a text relative to the parent axes or a specific anchor point.
DrawingArea
A container with fixed width and height. Children have a fixed position inside the container and may be clipped.
HPacker, VPacker
Containers for layouting their children vertically or horizontally.
PaddedBox
A container to add a padding around an Artist.
TextArea
Contains a single Text instance.
class matplotlib.offsetbox.AnchoredOffsetbox(loc, pad=0.4, borderpad=0.5, child=None, prop=None, frameon=True, bbox_to_anchor=None, bbox_transform=None, **kwargs)[source]

An offset box placed according to location loc.

AnchoredOffsetbox has a single child. When multiple children are needed, use an extra OffsetBox to enclose them. By default, the offset box is anchored against its parent axes. You may explicitly specify the bbox_to_anchor.

Parameters: locstrThe box location. Supported values: 'upper right' 'upper left' 'lower left' 'lower right' 'center left' 'center right' 'lower center' 'upper center' 'center' For backward compatibility, numeric values are accepted as well. See the parameter loc of Legend for details. padfloat, default: 0.4Padding around the child as fraction of the fontsize. borderpadfloat, default: 0.5Padding between the offsetbox frame and the bbox_to_anchor. childOffsetBoxThe box that will be anchored. propFontPropertiesThis is only used as a reference for paddings. If not given, rcParams["legend.fontsize"] (default: 'medium') is used. frameonboolWhether to draw a frame around the box. bbox_to_anchorBboxBase, 2-tuple, or 4-tuple of floatsBox that is used to position the legend in conjunction with loc. bbox_transformThe transform for the bounding box (bbox_to_anchor). **kwargsAll other parameters are passed on to OffsetBox.

Notes

See Legend for a detailed description of the anchoring mechanism.

codes = {'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}
draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

get_bbox_to_anchor(self)[source]

Return the bbox that the box is anchored to.

get_child(self)[source]

Return the child.

get_children(self)[source]

Return the list of children.

get_extent(self, renderer)[source]

Return the extent of the box as (width, height, x, y).

This is the extent of the child plus the padding.

get_window_extent(self, renderer)[source]

Return the bounding box in display space.

set_bbox_to_anchor(self, bbox, transform=None)[source]

Set the bbox that the box is anchored to.

bbox can be a Bbox instance, a list of [left, bottom, width, height], or a list of [left, bottom] where the width and height will be assumed to be zero. The bbox will be transformed to display coordinate by the given transform.

set_child(self, child)[source]

Set the child to be anchored.

update_frame(self, bbox, fontsize=None)[source]
zorder = 5
class matplotlib.offsetbox.AnchoredText(s, loc, pad=0.4, borderpad=0.5, prop=None, **kwargs)[source]

AnchoredOffsetbox with Text.

Parameters: sstrText. locstrLocation code. See AnchoredOffsetbox. padfloat, default: 0.4Padding around the text as fraction of the fontsize. borderpadfloat, default: 0.5Spacing between the offsetbox frame and the bbox_to_anchor. propdict, optionalDictionary of keyword parameters to be passed to the Text instance contained inside AnchoredText. **kwargsAll other parameters are passed to AnchoredOffsetbox.
class matplotlib.offsetbox.AnnotationBbox(offsetbox, xy, xybox=None, xycoords='data', boxcoords=None, frameon=True, pad=0.4, annotation_clip=None, box_alignment=0.5, 0.5, bboxprops=None, arrowprops=None, fontsize=None, **kwargs)[source]

Bases: matplotlib.artist.Artist, matplotlib.text._AnnotationBase

Container for an OffsetBox referring to a specific position xy.

Optionally an arrow pointing from the offsetbox to xy can be drawn.

This is like Annotation, but with OffsetBox instead of Text.

Parameters: offsetboxOffsetBox xy(float, float)The point (x, y) to annotate. The coordinate system is determined by xycoords. xybox(float, float), default: xyThe position (x, y) to place the text at. The coordinate system is determined by boxcoords. xycoordsstr or Artist or Transform or callable or (float, float), default: 'data'The coordinate system that xy is given in. See the parameter xycoords in Annotation for a detailed description. boxcoordsstr or Artist or Transform or callable or (float, float), default: value of xycoordsThe coordinate system that xybox is given in. See the parameter textcoords in Annotation for a detailed description. frameonbool, default: TrueWhether to draw a frame around the box. padfloat, default: 0.4Padding around the offsetbox. box_alignment(float, float)A tuple of two floats for a vertical and horizontal alignment of the offset box w.r.t. the boxcoords. The lower-left corner is (0, 0) and upper-right corner is (1, 1). **kwargsOther parameters are identical to Annotation.
property anncoords
contains(self, mouseevent)[source]

Test whether the artist contains the mouse event.

Parameters: mouseeventmatplotlib.backend_bases.MouseEvent containsboolWhether any values are within the radius. detailsdictAn artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
draw(self, renderer)[source]

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters: rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

get_children(self)[source]

Return a list of the child Artists of this Artist.

get_fontsize(self, s=<deprecated parameter>)[source]

Return the fontsize in points.

get_tightbbox(self, renderer)[source]

get tight bounding box in display space.

get_window_extent(self, renderer)[source]

get the bounding box in display space.

set_figure(self, fig)[source]

Set the Figure instance the artist belongs to.

Parameters: figFigure
set_fontsize(self, s=None)[source]

Set the fontsize in points.

If s is not given, reset to rcParams["legend.fontsize"] (default: 'medium').

update_positions(self, renderer)[source]

Update the pixel positions of the annotated point and the text.

property xyann
zorder = 3
class matplotlib.offsetbox.AuxTransformBox(aux_transform)[source]

Offset Box with the aux_transform. Its children will be transformed with the aux_transform first then will be offsetted. The absolute coordinate of the aux_transform is meaning as it will be automatically adjust so that the left-lower corner of the bounding box of children will be set to (0, 0) before the offset transform.

It is similar to drawing area, except that the extent of the box is not predetermined but calculated from the window extent of its children. Furthermore, the extent of the children will be calculated in the transformed coordinate.

add_artist(self, a)[source]

Add an Artist to the container box.

draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

get_extent(self, renderer)[source]

Return a tuple width, height, xdescent, ydescent of the box.

get_offset(self)[source]

Return offset of the container.

get_transform(self)[source]

Return the Transform applied to the children

get_window_extent(self, renderer)[source]

Return the bounding box in display space.

set_offset(self, xy)[source]

Set the offset of the container.

Parameters: xy(float, float)The (x, y) coordinates of the offset in display units.
set_transform(self, t)[source]

set_transform is ignored.

class matplotlib.offsetbox.DraggableAnnotation(annotation, use_blit=False)[source]
save_offset(self)[source]
update_offset(self, dx, dy)[source]
class matplotlib.offsetbox.DraggableBase(ref_artist, use_blit=False)[source]

Bases: object

Helper base class for a draggable artist (legend, offsetbox).

Derived classes must override the following methods:

def save_offset(self):
'''
Called when the object is picked for dragging; should save the
reference position of the artist.
'''

def update_offset(self, dx, dy):
'''
Called during the dragging; (*dx*, *dy*) is the pixel offset from
the point where the mouse drag started.
'''


Optionally, you may override the following method:

def finalize_offset(self):
'''Called when the mouse is released.'''


In the current implementation of DraggableLegend and DraggableAnnotation, update_offset places the artists in display coordinates, and finalize_offset recalculates their position in axes coordinate and set a relevant attribute.

artist_picker(self, artist, evt)[source]

[Deprecated]

Notes

Deprecated since version 3.3:

disconnect(self)[source]

Disconnect the callbacks.

finalize_offset(self)[source]
on_motion(self, evt)[source]
on_motion_blit(self, evt)[source]

[Deprecated]

Notes

Deprecated since version 3.3:

on_pick(self, evt)[source]
on_release(self, event)[source]
save_offset(self)[source]
update_offset(self, dx, dy)[source]
class matplotlib.offsetbox.DraggableOffsetBox(ref_artist, offsetbox, use_blit=False)[source]
get_loc_in_canvas(self)[source]
save_offset(self)[source]
update_offset(self, dx, dy)[source]
class matplotlib.offsetbox.DrawingArea(width, height, xdescent=0.0, ydescent=0.0, clip=False)[source]

The DrawingArea can contain any Artist as a child. The DrawingArea has a fixed width and height. The position of children relative to the parent is fixed. The children can be clipped at the boundaries of the parent.

Parameters: width, heightfloatWidth and height of the container box. xdescent, ydescentfloatDescent of the box in x- and y-direction. clipboolWhether to clip the children to the box.
add_artist(self, a)[source]

Add an Artist to the container box.

property clip_children

If the children of this DrawingArea should be clipped by DrawingArea bounding box.

draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

get_extent(self, renderer)[source]

Return width, height, xdescent, ydescent of box.

get_offset(self)[source]

Return offset of the container.

get_transform(self)[source]

Return the Transform applied to the children.

get_window_extent(self, renderer)[source]

Return the bounding box in display space.

set_offset(self, xy)[source]

Set the offset of the container.

Parameters: xy(float, float)The (x, y) coordinates of the offset in display units.
set_transform(self, t)[source]

set_transform is ignored.

class matplotlib.offsetbox.HPacker(pad=None, sep=None, width=None, height=None, align='baseline', mode='fixed', children=None)[source]

The HPacker has its children packed horizontally. It automatically adjusts the relative positions of children at draw time.

Parameters: padfloat, optionalThe boundary padding in points. sepfloat, optionalThe spacing between items in points. width, heightfloat, optionalWidth and height of the container box in pixels, calculated if None. align{'top', 'bottom', 'left', 'right', 'center', 'baseline'}Alignment of boxes. mode{'fixed', 'expand', 'equal'}The packing mode. 'fixed' packs the given Artists tight with sep spacing. 'expand' uses the maximal available space to distribute the artists with equal spacing in between. 'equal': Each artist an equal fraction of the available space and is left-aligned (or top-aligned) therein. childrenlist of ArtistThe artists to pack.

Notes

pad and sep are in points and will be scaled with the renderer dpi, while width and height are in in pixels.

get_extent_offsets(self, renderer)[source]

Update offset of the children and return the extent of the box.

Parameters: rendererRendererBase subclass width height xdescent ydescent list of (xoffset, yoffset) pairs
class matplotlib.offsetbox.OffsetBox(*args, **kwargs)[source]

The OffsetBox is a simple container artist.

The child artists are meant to be drawn at a relative position to its parent.

Being an artist itself, all parameters are passed on to Artist.

property axes

The Axes instance the artist resides in, or None.

contains(self, mouseevent)[source]

Delegate the mouse event contains-check to the children.

As a container, the OffsetBox does not respond itself to mouseevents.

Parameters: mouseeventmatplotlib.backend_bases.MouseEvent containsboolWhether any values are within the radius. detailsdictAn artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

get_children(self)[source]

Return a list of the child Artists.

get_extent(self, renderer)[source]

Return a tuple width, height, xdescent, ydescent of the box.

get_extent_offsets(self, renderer)[source]

Update offset of the children and return the extent of the box.

Parameters: rendererRendererBase subclass width height xdescent ydescent list of (xoffset, yoffset) pairs
get_offset(self, width, height, xdescent, ydescent, renderer)[source]

Return the offset as a tuple (x, y).

The extent parameters have to be provided to handle the case where the offset is dynamically determined by a callable (see set_offset).

Parameters: width, height, xdescent, ydescentExtent parameters. rendererRendererBase subclass
get_visible_children(self)[source]

Return a list of the visible child Artists.

get_window_extent(self, renderer)[source]

Return the bounding box (Bbox) in display space.

set_figure(self, fig)[source]

Set the Figure for the OffsetBox and all its children.

Parameters: figFigure
set_height(self, height)[source]

Set the height of the box.

Parameters: heightfloat
set_offset(self, xy)[source]

Set the offset.

Parameters: xy(float, float) or callableThe (x, y) coordinates of the offset in display units. These can either be given explicitly as a tuple (x, y), or by providing a function that converts the extent into the offset. This function must have the signature: def offset(width, height, xdescent, ydescent, renderer) -> (float, float) 
set_width(self, width)[source]

Set the width of the box.

Parameters: widthfloat
class matplotlib.offsetbox.OffsetImage(arr, zoom=1, cmap=None, norm=None, interpolation=None, origin=None, filternorm=True, filterrad=4.0, resample=False, dpi_cor=True, **kwargs)[source]
draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

get_children(self)[source]

Return a list of the child Artists.

get_data(self)[source]
get_extent(self, renderer)[source]

Return a tuple width, height, xdescent, ydescent of the box.

get_offset(self)[source]

Return offset of the container.

get_window_extent(self, renderer)[source]

Return the bounding box in display space.

get_zoom(self)[source]
set_data(self, arr)[source]
set_zoom(self, zoom)[source]
class matplotlib.offsetbox.PackerBase(pad=None, sep=None, width=None, height=None, align=None, mode=None, children=None)[source]
Parameters: padfloat, optionalThe boundary padding in points. sepfloat, optionalThe spacing between items in points. width, heightfloat, optionalWidth and height of the container box in pixels, calculated if None. align{'top', 'bottom', 'left', 'right', 'center', 'baseline'}Alignment of boxes. mode{'fixed', 'expand', 'equal'}The packing mode. 'fixed' packs the given Artists tight with sep spacing. 'expand' uses the maximal available space to distribute the artists with equal spacing in between. 'equal': Each artist an equal fraction of the available space and is left-aligned (or top-aligned) therein. childrenlist of ArtistThe artists to pack.

Notes

pad and sep are in points and will be scaled with the renderer dpi, while width and height are in in pixels.

class matplotlib.offsetbox.PaddedBox(child, pad=None, draw_frame=False, patch_attrs=None)[source]

A container to add a padding around an Artist.

The PaddedBox contains a FancyBboxPatch that is used to visualize it when rendering.

Parameters: childArtistThe contained Artist. padfloatThe padding in points. This will be scaled with the renderer dpi. In contrast width and height are in pixels and thus not scaled. draw_frameboolWhether to draw the contained FancyBboxPatch. patch_attrsdict or NoneAdditional parameters passed to the contained FancyBboxPatch.
draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

draw_frame(self, renderer)[source]
get_extent_offsets(self, renderer)[source]

Update offset of the children and return the extent of the box.

Parameters: rendererRendererBase subclass width height xdescent ydescent list of (xoffset, yoffset) pairs
update_frame(self, bbox, fontsize=None)[source]
class matplotlib.offsetbox.TextArea(s, textprops=None, multilinebaseline=None, minimumdescent=True)[source]

The TextArea is contains a single Text instance. The text is placed at (0, 0) with baseline+left alignment. The width and height of the TextArea instance is the width and height of the its child text.

Parameters: sstrThe text to be displayed. textpropsdict, optionalDictionary of keyword parameters to be passed to the Text instance contained inside TextArea. multilinebaselinebool, optionalIf True, baseline for multiline text is adjusted so that it is (approximately) center-aligned with singleline text. minimumdescentbool, optionalIf True, the box has a minimum descent of "p".
draw(self, renderer)[source]

Update the location of children if necessary and draw them to the given renderer.

get_extent(self, renderer)[source]

Return a tuple width, height, xdescent, ydescent of the box.

get_minimumdescent(self)[source]

Get minimumdescent.

get_multilinebaseline(self)[source]

Get multilinebaseline.

get_offset(self)[source]

Return offset of the container.

get_text(self)[source]

Return the string representation of this area's text.

get_window_extent(self, renderer)[source]

Return the bounding box in display space.

set_minimumdescent(self, t)[source]

Set minimumdescent.

If True, extent of the single line text is adjusted so that it has minimum descent of "p"

set_multilinebaseline(self, t)[source]

Set multilinebaseline.

If True, baseline for multiline text is adjusted so that it is (approximately) center-aligned with single-line text.

set_offset(self, xy)[source]

Set the offset of the container.

Parameters: xy(float, float)The (x, y) coordinates of the offset in display units.
set_text(self, s)[source]

Set the text of this area as a string.

set_transform(self, t)[source]

set_transform is ignored.

class matplotlib.offsetbox.VPacker(pad=None, sep=None, width=None, height=None, align='baseline', mode='fixed', children=None)[source]

The VPacker has its children packed vertically. It automatically adjusts the relative positions of children at drawing time.

Parameters: padfloat, optionalThe boundary padding in points. sepfloat, optionalThe spacing between items in points. width, heightfloat, optionalWidth and height of the container box in pixels, calculated if None. align{'top', 'bottom', 'left', 'right', 'center', 'baseline'}Alignment of boxes. mode{'fixed', 'expand', 'equal'}The packing mode. 'fixed' packs the given Artists tight with sep spacing. 'expand' uses the maximal available space to distribute the artists with equal spacing in between. 'equal': Each artist an equal fraction of the available space and is left-aligned (or top-aligned) therein. childrenlist of ArtistThe artists to pack.

Notes

pad and sep are in points and will be scaled with the renderer dpi, while width and height are in in pixels.

get_extent_offsets(self, renderer)[source]

Update offset of the children and return the extent of the box.

Parameters: rendererRendererBase subclass width height xdescent ydescent list of (xoffset, yoffset) pairs
matplotlib.offsetbox.bbox_artist(*args, **kwargs)[source]