r"""

Container classes for `.Artist`\s.

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

"""

import numpy as np

from matplotlib import _api, docstring, rcParams

import matplotlib.artist as martist

import matplotlib.path as mpath

import matplotlib.text as mtext

import matplotlib.transforms as mtransforms

from matplotlib.font_manager import FontProperties

from matplotlib.image import BboxImage

from matplotlib.patches import (

FancyBboxPatch, FancyArrowPatch, bbox_artist as mbbox_artist)

from matplotlib.transforms import Bbox, BboxBase, TransformedBbox

DEBUG = False

# for debugging use

def bbox_artist(*args, **kwargs):

if DEBUG:

mbbox_artist(*args, **kwargs)

def _get_packed_offsets(wd_list, total, sep, mode="fixed"):

r"""

Pack boxes specified by their ``(width, xdescent)`` pair.

For simplicity of the description, the terminology used here assumes a

horizontal layout, but the function works equally for a vertical layout.

*xdescent* is analogous to the usual descent, but along the x-direction; it

is currently ignored.

There are three packing *mode*\s:

- 'fixed': The elements are packed tight to the left with a spacing of

*sep* in between. If *total* is *None* the returned total will be the

right edge of the last box. A non-*None* total will be passed unchecked

to the output. In particular this means that right edge of the last

box may be further to the right than the returned total.

- 'expand': Distribute the boxes with equal spacing so that the left edge

of the first box is at 0, and the right edge of the last box is at

*total*. The parameter *sep* is ignored in this mode. A total of *None*

is accepted and considered equal to 1. The total is returned unchanged

(except for the conversion *None* to 1). If the total is smaller than

the sum of the widths, the laid out boxes will overlap.

- 'equal': If *total* is given, the total space is divided in N equal

ranges and each box is left-aligned within its subspace.

Otherwise (*total* is *None*), *sep* must be provided and each box is

left-aligned in its subspace of width ``(max(widths) + sep)``. The

total width is then calculated to be ``N * (max(widths) + sep)``.

Parameters

----------

wd_list : list of (float, float)

(width, xdescent) of boxes to be packed.

total : float or None

Intended total length. *None* if not used.

sep : float

Spacing between boxes.

mode : {'fixed', 'expand', 'equal'}

The packing mode.

Returns

-------

total : float

The total width needed to accommodate the laid out boxes.

offsets : array of float

The left offsets of the boxes.

"""

w_list, d_list = zip(*wd_list) # d_list is currently not used.

_api.check_in_list(["fixed", "expand", "equal"], mode=mode)

if mode == "fixed":

offsets_ = np.cumsum([0] + [w + sep for w in w_list])

offsets = offsets_[:-1]

if total is None:

total = offsets_[-1] - sep

return total, offsets

elif mode == "expand":

# This is a bit of a hack to avoid a TypeError when *total*

# is None and used in conjugation with tight layout.

if total is None:

total = 1

if len(w_list) > 1:

sep = (total - sum(w_list)) / (len(w_list) - 1)

else:

sep = 0

offsets_ = np.cumsum([0] + [w + sep for w in w_list])

offsets = offsets_[:-1]

return total, offsets

elif mode == "equal":

maxh = max(w_list)

if total is None:

if sep is None:

raise ValueError("total and sep cannot both be None when "

"using layout mode 'equal'")

total = (maxh + sep) * len(w_list)

else:

sep = total / len(w_list) - maxh

offsets = (maxh + sep) * np.arange(len(w_list))

return total, offsets

def _get_aligned_offsets(hd_list, height, align="baseline"):

"""

Align boxes each specified by their ``(height, descent)`` pair.

For simplicity of the description, the terminology used here assumes a

horizontal layout (i.e., vertical alignment), but the function works

equally for a vertical layout.

Parameters

----------

hd_list

List of (height, xdescent) of boxes to be aligned.

height : float or None

Intended total height. If None, the maximum of the heights in *hd_list*

is used.

align : {'baseline', 'left', 'top', 'right', 'bottom', 'center'}

The alignment anchor of the boxes.

Returns

-------

height

The total height of the packing (if a value was originally passed in,

it is returned without checking that it is actually large enough).

descent

The descent of the packing.

offsets

The bottom offsets of the boxes.

"""

if height is None:

height = max(h for h, d in hd_list)

_api.check_in_list(

["baseline", "left", "top", "right", "bottom", "center"], align=align)

if align == "baseline":

height_descent = max(h - d for h, d in hd_list)

descent = max(d for h, d in hd_list)

height = height_descent + descent

offsets = [0. for h, d in hd_list]

elif align in ["left", "top"]:

descent = 0.

offsets = [d for h, d in hd_list]

elif align in ["right", "bottom"]:

descent = 0.

offsets = [height - h + d for h, d in hd_list]

elif align == "center":

descent = 0.

offsets = [(height - h) * .5 + d for h, d in hd_list]

return height, descent, offsets

class OffsetBox(martist.Artist):

"""

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

"""

def __init__(self, *args, **kwargs):

super().__init__(*args, **kwargs)

# Clipping has not been implemented in the OffesetBox family, so

# disable the clip flag for consistency. It can always be turned back

# on to zero effect.

self.set_clip_on(False)

self._children = []

self._offset = (0, 0)

def set_figure(self, fig):

"""

Set the `.Figure` for the `.OffsetBox` and all its children.

Parameters

----------

fig : `~matplotlib.figure.Figure`

"""

super().set_figure(fig)

for c in self.get_children():

c.set_figure(fig)

@martist.Artist.axes.setter

def axes(self, ax):

# TODO deal with this better

martist.Artist.axes.fset(self, ax)

for c in self.get_children():

if c is not None:

c.axes = ax

def contains(self, mouseevent):

"""

Delegate the mouse event contains-check to the children.

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

mouseevents.

Parameters

----------

mouseevent : `matplotlib.backend_bases.MouseEvent`

Returns

-------

contains : bool

Whether any values are within the radius.

details : dict

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

"""

inside, info = self._default_contains(mouseevent)

if inside is not None:

return inside, info

for c in self.get_children():

a, b = c.contains(mouseevent)

if a:

return a, b

return False, {}

def set_offset(self, xy):

"""

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)

"""

self._offset = xy

self.stale = True

def get_offset(self, width, height, xdescent, ydescent, renderer):

"""

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

`~.OffsetBox.set_offset`).

Parameters

----------

width, height, xdescent, ydescent

Extent parameters.

renderer : `.RendererBase` subclass

"""

return (self._offset(width, height, xdescent, ydescent, renderer)

if callable(self._offset)

else self._offset)

def set_width(self, width):

"""

Set the width of the box.

Parameters

----------

width : float

"""

self.width = width

self.stale = True

def set_height(self, height):

"""

Set the height of the box.

Parameters

----------

height : float

"""

self.height = height

self.stale = True

def get_visible_children(self):

r"""Return a list of the visible child `.Artist`\s."""

return [c for c in self._children if c.get_visible()]

def get_children(self):

r"""Return a list of the child `.Artist`\s."""

return self._children

def get_extent_offsets(self, renderer):

"""

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

Parameters

----------

renderer : `.RendererBase` subclass

Returns

-------

width

height

xdescent

ydescent

list of (xoffset, yoffset) pairs

"""

raise NotImplementedError(

"get_extent_offsets must be overridden in derived classes.")

def get_extent(self, renderer):

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

w, h, xd, yd, offsets = self.get_extent_offsets(renderer)

return w, h, xd, yd

def get_window_extent(self, renderer):

"""Return the bounding box (`.Bbox`) in display space."""

w, h, xd, yd, offsets = self.get_extent_offsets(renderer)

px, py = self.get_offset(w, h, xd, yd, renderer)

return mtransforms.Bbox.from_bounds(px - xd, py - yd, w, h)

def draw(self, renderer):

"""

Update the location of children if necessary and draw them

to the given *renderer*.

"""

width, height, xdescent, ydescent, offsets = self.get_extent_offsets(

renderer)

px, py = self.get_offset(width, height, xdescent, ydescent, renderer)

for c, (ox, oy) in zip(self.get_visible_children(), offsets):

c.set_offset((px + ox, py + oy))

c.draw(renderer)

bbox_artist(self, renderer, fill=False, props=dict(pad=0.))

self.stale = False

class PackerBase(OffsetBox):

def __init__(self, pad=None, sep=None, width=None, height=None,

align="baseline", mode="fixed", children=None):

"""

Parameters

----------

pad : float, optional

The boundary padding in points.

sep : float, optional

The spacing between items in points.

width, height : float, optional

Width and height of the container box in pixels, calculated if

*None*.

align : {'top', 'bottom', 'left', 'right', 'center', 'baseline'}, \

default: 'baseline'

Alignment of boxes.

mode : {'fixed', 'expand', 'equal'}, default: 'fixed'

The packing mode.

- 'fixed' packs the given `.Artist`\\s 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.

children : list of `.Artist`

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

"""

super().__init__()

self.height = height

self.width = width

self.sep = sep

self.pad = pad

self.mode = mode

self.align = align

self._children = children

class VPacker(PackerBase):

"""

VPacker packs its children vertically, automatically adjusting their

relative positions at draw time.

"""

def get_extent_offsets(self, renderer):

# docstring inherited

dpicor = renderer.points_to_pixels(1.)

pad = self.pad * dpicor

sep = self.sep * dpicor

if self.width is not None:

for c in self.get_visible_children():

if isinstance(c, PackerBase) and c.mode == "expand":

c.set_width(self.width)

whd_list = [c.get_extent(renderer)

for c in self.get_visible_children()]

whd_list = [(w, h, xd, (h - yd)) for w, h, xd, yd in whd_list]

wd_list = [(w, xd) for w, h, xd, yd in whd_list]

width, xdescent, xoffsets = _get_aligned_offsets(wd_list,

self.width,

self.align)

pack_list = [(h, yd) for w, h, xd, yd in whd_list]

height, yoffsets_ = _get_packed_offsets(pack_list, self.height,

sep, self.mode)

yoffsets = yoffsets_ + [yd for w, h, xd, yd in whd_list]

ydescent = height - yoffsets[0]

yoffsets = height - yoffsets

yoffsets = yoffsets - ydescent

return (width + 2 * pad, height + 2 * pad,

xdescent + pad, ydescent + pad,

list(zip(xoffsets, yoffsets)))

class HPacker(PackerBase):

"""

HPacker packs its children horizontally, automatically adjusting their

relative positions at draw time.

"""

def get_extent_offsets(self, renderer):

# docstring inherited

dpicor = renderer.points_to_pixels(1.)

pad = self.pad * dpicor

sep = self.sep * dpicor

whd_list = [c.get_extent(renderer)

for c in self.get_visible_children()]

if not whd_list:

return 2 * pad, 2 * pad, pad, pad, []

if self.height is None:

height_descent = max(h - yd for w, h, xd, yd in whd_list)

ydescent = max(yd for w, h, xd, yd in whd_list)

height = height_descent + ydescent

else:

height = self.height - 2 * pad # width w/o pad

hd_list = [(h, yd) for w, h, xd, yd in whd_list]

height, ydescent, yoffsets = _get_aligned_offsets(hd_list,

self.height,

self.align)

pack_list = [(w, xd) for w, h, xd, yd in whd_list]

width, xoffsets_ = _get_packed_offsets(pack_list, self.width,

sep, self.mode)

xoffsets = xoffsets_ + [xd for w, h, xd, yd in whd_list]

xdescent = whd_list[0][2]

xoffsets = xoffsets - xdescent

return (width + 2 * pad, height + 2 * pad,

xdescent + pad, ydescent + pad,

list(zip(xoffsets, yoffsets)))

class PaddedBox(OffsetBox):

"""

A container to add a padding around an `.Artist`.

The `.PaddedBox` contains a `.FancyBboxPatch` that is used to visualize

it when rendering.

"""

def __init__(self, child, pad=None, draw_frame=False, patch_attrs=None):

"""

Parameters

----------

child : `~matplotlib.artist.Artist`

The contained `.Artist`.

pad : float

The padding in points. This will be scaled with the renderer dpi.

In contrast *width* and *height* are in *pixels* and thus not

scaled.

draw_frame : bool

Whether to draw the contained `.FancyBboxPatch`.

patch_attrs : dict or None

Additional parameters passed to the contained `.FancyBboxPatch`.

"""

super().__init__()

self.pad = pad

self._children = [child]

self.patch = FancyBboxPatch(

xy=(0.0, 0.0), width=1., height=1.,

facecolor='w', edgecolor='k',

mutation_scale=1, # self.prop.get_size_in_points(),

snap=True,

visible=draw_frame,

boxstyle="square,pad=0",

)

if patch_attrs is not None:

self.patch.update(patch_attrs)

def get_extent_offsets(self, renderer):

# docstring inherited.

dpicor = renderer.points_to_pixels(1.)

pad = self.pad * dpicor

w, h, xd, yd = self._children[0].get_extent(renderer)

return (w + 2 * pad, h + 2 * pad, xd + pad, yd + pad,

[(0, 0)])

def draw(self, renderer):

# docstring inherited

width, height, xdescent, ydescent, offsets = self.get_extent_offsets(

renderer)

px, py = self.get_offset(width, height, xdescent, ydescent, renderer)

for c, (ox, oy) in zip(self.get_visible_children(), offsets):

c.set_offset((px + ox, py + oy))

self.draw_frame(renderer)

for c in self.get_visible_children():

c.draw(renderer)

#bbox_artist(self, renderer, fill=False, props=dict(pad=0.))

self.stale = False

def update_frame(self, bbox, fontsize=None):

self.patch.set_bounds(bbox.x0, bbox.y0, bbox.width, bbox.height)

if fontsize:

self.patch.set_mutation_scale(fontsize)

self.stale = True

def draw_frame(self, renderer):

# update the location and size of the legend

self.update_frame(self.get_window_extent(renderer))

self.patch.draw(renderer)

class DrawingArea(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.

"""

def __init__(self, width, height, xdescent=0.,

ydescent=0., clip=False):

"""

Parameters

----------

width, height : float

Width and height of the container box.

xdescent, ydescent : float

Descent of the box in x- and y-direction.

clip : bool

Whether to clip the children to the box.

"""

super().__init__()

self.width = width

self.height = height

self.xdescent = xdescent

self.ydescent = ydescent

self._clip_children = clip

self.offset_transform = mtransforms.Affine2D()

self.dpi_transform = mtransforms.Affine2D()

@property

def clip_children(self):

"""

If the children of this DrawingArea should be clipped

by DrawingArea bounding box.

"""

return self._clip_children

@clip_children.setter

def clip_children(self, val):

self._clip_children = bool(val)

self.stale = True

def get_transform(self):

"""

Return the `~matplotlib.transforms.Transform` applied to the children.

"""

return self.dpi_transform + self.offset_transform

def set_transform(self, t):

"""

set_transform is ignored.

"""

def set_offset(self, xy):

"""

Set the offset of the container.

Parameters

----------

xy : (float, float)

The (x, y) coordinates of the offset in display units.

"""

self._offset = xy

self.offset_transform.clear()

self.offset_transform.translate(xy[0], xy[1])

self.stale = True

def get_offset(self):

"""Return offset of the container."""

return self._offset

def get_window_extent(self, renderer):

"""Return the bounding box in display space."""

w, h, xd, yd = self.get_extent(renderer)

ox, oy = self.get_offset() # w, h, xd, yd)

return mtransforms.Bbox.from_bounds(ox - xd, oy - yd, w, h)

def get_extent(self, renderer):

"""Return width, height, xdescent, ydescent of box."""

dpi_cor = renderer.points_to_pixels(1.)

return (self.width * dpi_cor, self.height * dpi_cor,

self.xdescent * dpi_cor, self.ydescent * dpi_cor)

def add_artist(self, a):

"""Add an `.Artist` to the container box."""

self._children.append(a)

if not a.is_transform_set():

a.set_transform(self.get_transform())

if self.axes is not None:

a.axes = self.axes

fig = self.figure

if fig is not None:

a.set_figure(fig)

def draw(self, renderer):

# docstring inherited

dpi_cor = renderer.points_to_pixels(1.)

self.dpi_transform.clear()

self.dpi_transform.scale(dpi_cor)

# At this point the DrawingArea has a transform

# to the display space so the path created is

# good for clipping children

tpath = mtransforms.TransformedPath(

mpath.Path([[0, 0], [0, self.height],

[self.width, self.height],

[self.width, 0]]),

self.get_transform())

for c in self._children:

if self._clip_children and not (c.clipbox or c._clippath):

c.set_clip_path(tpath)

c.draw(renderer)

bbox_artist(self, renderer, fill=False, props=dict(pad=0.))

self.stale = False

class TextArea(OffsetBox):

"""

The TextArea is a container artist for a single Text instance.

The text is placed at (0, 0) with baseline+left alignment, by default. The

width and height of the TextArea instance is the width and height of its

child text.

"""

@_api.delete_parameter("3.4", "minimumdescent")

def __init__(self, s,

textprops=None,

multilinebaseline=False,

minimumdescent=True,

):

"""

Parameters

----------

s : str

The text to be displayed.

textprops : dict, default: {}

Dictionary of keyword parameters to be passed to the `.Text`

instance in the TextArea.

multilinebaseline : bool, default: False

Whether the baseline for multiline text is adjusted so that it

is (approximately) center-aligned with single-line text.

minimumdescent : bool, default: True

If `True`, the box has a minimum descent of "p". This is now

effectively always True.

"""

if textprops is None:

textprops = {}

self._text = mtext.Text(0, 0, s, **textprops)

super().__init__()

self._children = [self._text]

self.offset_transform = mtransforms.Affine2D()

self._baseline_transform = mtransforms.Affine2D()

self._text.set_transform(self.offset_transform +

self._baseline_transform)

self._multilinebaseline = multilinebaseline

self._minimumdescent = minimumdescent

def set_text(self, s):

"""Set the text of this area as a string."""

self._text.set_text(s)

self.stale = True

def get_text(self):

"""Return the string representation of this area's text."""

return self._text.get_text()

def set_multilinebaseline(self, t):

"""

Set multilinebaseline.

If True, the baseline for multiline text is adjusted so that it is

(approximately) center-aligned with single-line text. This is used

e.g. by the legend implementation so that single-line labels are

baseline-aligned, but multiline labels are "center"-aligned with them.

"""

self._multilinebaseline = t

self.stale = True

def get_multilinebaseline(self):

"""

Get multilinebaseline.

"""

return self._multilinebaseline

@_api.deprecated("3.4")

def set_minimumdescent(self, t):

"""

Set minimumdescent.

If True, extent of the single line text is adjusted so that

its descent is at least the one of the glyph "p".

"""

# The current implementation of Text._get_layout always behaves as if

# this is True.

self._minimumdescent = t

self.stale = True

@_api.deprecated("3.4")

def get_minimumdescent(self):

"""

Get minimumdescent.

"""

return self._minimumdescent

def set_transform(self, t):

"""

set_transform is ignored.

"""

def set_offset(self, xy):

"""

Set the offset of the container.

Parameters

----------

xy : (float, float)

The (x, y) coordinates of the offset in display units.

"""

self._offset = xy

self.offset_transform.clear()

self.offset_transform.translate(xy[0], xy[1])

self.stale = True

def get_offset(self):

"""Return offset of the container."""

return self._offset

def get_window_extent(self, renderer):

"""Return the bounding box in display space."""

w, h, xd, yd = self.get_extent(renderer)

ox, oy = self.get_offset()

return mtransforms.Bbox.from_bounds(ox - xd, oy - yd, w, h)

def get_extent(self, renderer):

_, h_, d_ = renderer.get_text_width_height_descent(

"lp", self._text._fontproperties,

ismath="TeX" if self._text.get_usetex() else False)

bbox, info, yd = self._text._get_layout(renderer)

w, h = bbox.width, bbox.height

self._baseline_transform.clear()

if len(info) > 1 and self._multilinebaseline:

yd_new = 0.5 * h - 0.5 * (h_ - d_)

self._baseline_transform.translate(0, yd - yd_new)

yd = yd_new

else: # single line

h_d = max(h_ - d_, h - yd)

h = h_d + yd

ha = self._text.get_horizontalalignment()

if ha == 'left':

xd = 0

elif ha == 'center':

xd = w / 2

elif ha == 'right':

xd = w

return w, h, xd, yd

def draw(self, renderer):

# docstring inherited

self._text.draw(renderer)

bbox_artist(self, renderer, fill=False, props=dict(pad=0.))

self.stale = False

class AuxTransformBox(OffsetBox):

"""

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.

"""

def __init__(self, aux_transform):

self.aux_transform = aux_transform

super().__init__()

self.offset_transform = mtransforms.Affine2D()

# ref_offset_transform makes offset_transform always relative to the

# lower-left corner of the bbox of its children.

self.ref_offset_transform = mtransforms.Affine2D()

def add_artist(self, a):

"""Add an `.Artist` to the container box."""

self._children.append(a)

a.set_transform(self.get_transform())

self.stale = True

def get_transform(self):

"""

Return the :class:`~matplotlib.transforms.Transform` applied

to the children

"""

return (self.aux_transform

+ self.ref_offset_transform

+ self.offset_transform)

def set_transform(self, t):

"""

set_transform is ignored.

"""

def set_offset(self, xy):

"""

Set the offset of the container.

Parameters

----------

xy : (float, float)

The (x, y) coordinates of the offset in display units.

"""

self._offset = xy

self.offset_transform.clear()

self.offset_transform.translate(xy[0], xy[1])

self.stale = True

def get_offset(self):

"""Return offset of the container."""

return self._offset

def get_window_extent(self, renderer):

"""Return the bounding box in display space."""

w, h, xd, yd = self.get_extent(renderer)

ox, oy = self.get_offset() # w, h, xd, yd)

return mtransforms.Bbox.from_bounds(ox - xd, oy - yd, w, h)

def get_extent(self, renderer):

# clear the offset transforms

_off = self.offset_transform.get_matrix() # to be restored later

self.ref_offset_transform.clear()

self.offset_transform.clear()

# calculate the extent

bboxes = [c.get_window_extent(renderer) for c in self._children]

ub = mtransforms.Bbox.union(bboxes)

# adjust ref_offset_transform

self.ref_offset_transform.translate(-ub.x0, -ub.y0)

# restore offset transform

self.offset_transform.set_matrix(_off)

return ub.width, ub.height, 0., 0.

def draw(self, renderer):

# docstring inherited

for c in self._children:

c.draw(renderer)

bbox_artist(self, renderer, fill=False, props=dict(pad=0.))

self.stale = False

class AnchoredOffsetbox(OffsetBox):

"""

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

"""

zorder = 5 # zorder of the legend

# Location codes

codes = {'upper right': 1,

'upper left': 2,

'lower left': 3,

'lower right': 4,

'right': 5,

'center left': 6,

'center right': 7,

'lower center': 8,

'upper center': 9,

'center': 10,

}

def __init__(self, loc,

pad=0.4, borderpad=0.5,

child=None, prop=None, frameon=True,

bbox_to_anchor=None,

bbox_transform=None,

**kwargs):

"""

Parameters

----------

loc : str

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

pad : float, default: 0.4

Padding around the child as fraction of the fontsize.

borderpad : float, default: 0.5

Padding between the offsetbox frame and the *bbox_to_anchor*.

child : `.OffsetBox`

The box that will be anchored.

prop : `.FontProperties`