matplotlib.offsetbox

The OffsetBox is a simple container artist. Its child artists are meant to be drawn at a relative position to OffsetBox. The [VH]Packer, DrawingArea and TextArea are derived from the OffsetBox.

The [VH]Packer automatically adjust the relative positions of their children, which should be instances of the OffsetBox. This is used to align similar artists together, e.g., in legend.

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 TextArea is contains a single Text instance. The width and height of the TextArea instance is the width and height of the its child text.

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]

Bases: matplotlib.offsetbox.OffsetBox

An offset box placed according to the legend location loc. AnchoredOffsetbox has a single child. When multiple children is needed, use other OffsetBox class to enclose them. By default, the offset box is anchored against its parent axes. You may explicitly specify the bbox_to_anchor.

loc is a string or an integer specifying the legend location. The valid location codes are:

'upper right'  : 1,
'upper left'   : 2,
'lower left'   : 3,
'lower right'  : 4,
'right'        : 5, (same as 'center right', for back-compatibility)
'center left'  : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center'       : 10,
padpad around the child for drawing a frame. given in
fraction of fontsize.

borderpad : pad between offsetbox frame and the bbox_to_anchor,

child : OffsetBox instance that will be anchored.

prop : font property. This is only used as a reference for paddings.

frameon : draw a frame box if True.

bbox_to_anchor : bbox to anchor. Use self.axes.bbox if None.

bbox_transform : with which the bbox_to_anchor will be transformed.

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]

draw the artist

get_bbox_to_anchor(self) [source]

return the bbox that the legend will be anchored

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 artist. The extent of the child added with the pad is returned

get_window_extent(self, renderer) [source]

get the bounding box in display space.

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

set the bbox that the child will be anchored.

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]

Bases: matplotlib.offsetbox.AnchoredOffsetbox

AnchoredOffsetbox with Text.

Parameters:
sstr

Text.

locstr

Location code.

padfloat, optional

Pad between the text and the frame as fraction of the font size.

borderpadfloat, optional

Pad between the frame and the axes (or bbox_to_anchor).

propdictionary, optional, default: None

Dictionary of keyword parameters to be passed to the Text instance contained inside AnchoredText.

Notes

Other keyword parameters of AnchoredOffsetbox are also allowed.

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

Annotation-like class, but with offsetbox instead of Text.

offsetbox : OffsetBox instance

xycoordssame as Annotation but can be a tuple of two
strings which are interpreted as x and y coordinates.
boxcoordssimilar to textcoords as Annotation but can be a
tuple of two strings which are interpreted as x and y coordinates.
box_alignmenta 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).

other parameters are identical to that of Annotation.

property anncoords
contains(self, mouseevent) [source]

Test whether the artist contains the mouse event.

Parameters:
mouseeventmatplotlib.backend_bases.MouseEvent
Returns:
containsbool

Whether any values are within the radius.

detailsdict

An 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.

See also

set_contains, get_contains
draw(self, renderer) [source]

Draw the Annotation object to the given renderer.

get_children(self) [source]

Return a list of the child Artists of this Artist.

get_fontsize(self, s=None) [source]

return fontsize in points

set_figure(self, fig) [source]

Set the Figure instance the artist belongs to.

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

set fontsize in points

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]

Bases: matplotlib.offsetbox.OffsetBox

Offset Box with the aux_transform. Its children will be transformed with the aux_transform first then will be offseted. 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 any Artist to the container box

draw(self, renderer) [source]

Draw the children

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]

get 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]

Bases: matplotlib.offsetbox.DraggableBase

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 methods:

def artist_picker(self, artist, evt):
    '''The picker method that will be used.'''
    return self.ref_artist.contains(evt)

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]
disconnect(self) [source]

Disconnect the callbacks.

finalize_offset(self) [source]
on_motion(self, evt) [source]
on_motion_blit(self, evt) [source]
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]

Bases: matplotlib.offsetbox.DraggableBase

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]

Bases: matplotlib.offsetbox.OffsetBox

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.

width, height : width and height of the container box. xdescent, ydescent : descent of the box in x- and y-direction. clip : Whether to clip the children

add_artist(self, a) [source]

Add any 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]

Draw the children

get_extent(self, renderer) [source]

Return with, 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]

get 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]

Bases: matplotlib.offsetbox.PackerBase

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

Parameters:
padfloat, optional

The boundary padding in points.

sepfloat, optional

The spacing between items in points.

width, heightfloat, optional

Width 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 Artist

The artists to pack.

Notes

pad and sep need to given in points and will be scale with the renderer dpi, while width and height need to be in pixels.

get_extent_offsets(self, renderer) [source]

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

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

Bases: matplotlib.artist.Artist

The OffsetBox is a simple container artist. The child artist are meant to be drawn at a relative position to its parent.

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
Returns:
containsbool

Whether any values are within the radius.

detailsdict

An 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.

See also

Artist.contains
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
Returns:
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, ydescent

Extent 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 callable

The (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=1, filterrad=4.0, resample=False, dpi_cor=True, **kwargs) [source]

Bases: matplotlib.offsetbox.OffsetBox

draw(self, renderer) [source]

Draw the children

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]

get 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]

Bases: matplotlib.offsetbox.OffsetBox

Parameters:
padfloat, optional

The boundary padding in points.

sepfloat, optional

The spacing between items in points.

width, heightfloat, optional

Width 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 Artist

The artists to pack.

Notes

pad and sep need to given in points and will be scale with the renderer dpi, while width and height need to be in pixels.

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

Bases: matplotlib.offsetbox.OffsetBox

A container to add a padding around an Artist.

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

Parameters:
childArtist

The contained Artist.

padfloat

The padding in points. This will be scaled with the renderer dpi. In contrast width and hight are in pixel and thus not scaled.

draw_framebool

Whether to draw the contained FancyBboxPatch.

patch_attrsdict or None

Additional 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
Returns:
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]

Bases: matplotlib.offsetbox.OffsetBox

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:
sstr

a string to be displayed.

textpropsdictionary, optional, default: None

Dictionary of keyword parameters to be passed to the Text instance contained inside TextArea.

multilinebaselinebool, optional

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

minimumdescentbool, optional

If True, the box has a minimum descent of "p".
draw(self, renderer) [source]

Draw the children

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]

Returns the string representation of this area's text

get_window_extent(self, renderer) [source]

get 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]

Bases: matplotlib.offsetbox.PackerBase

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

Parameters:
padfloat, optional

The boundary padding in points.

sepfloat, optional

The spacing between items in points.

width, heightfloat, optional

Width 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 Artist

The artists to pack.

Notes

pad and sep need to given in points and will be scale with the renderer dpi, while width and height need to be in pixels.

get_extent_offsets(self, renderer) [source]

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

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

© 2012–2018 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
https://matplotlib.org/3.2.2/api/offsetbox_api.html