Skip to content

Backport PR #15380 on branch v3.2.x (Update docs of BoxStyle) #15420

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
Oct 15, 2019
Merged

Backport PR #15380 on branch v3.2.x (Update docs of BoxStyle) #15420

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
166 changes: 93 additions & 73 deletions lib/matplotlib/patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1909,26 +1909,24 @@ class BoxStyle(_Style):

class _Base:
"""
:class:`BBoxTransmuterBase` and its derivatives are used to make a
fancy box around a given rectangle. The :meth:`__call__` method
returns the :class:`~matplotlib.path.Path` of the fancy box. This
class is not an artist and actual drawing of the fancy box is done
by the :class:`FancyBboxPatch` class.
"""
Abstract base class for styling of `.FancyBboxPatch`.

# The derived classes are required to be able to be initialized
# w/o arguments, i.e., all its argument (except self) must have
# the default values.
This class is not an artist itself. The `__call__` method returns the
`~matplotlib.path.Path` for outlining the fancy box. The actual drawing
is handled in `.FancyBboxPatch`.

Subclasses may only use parameters with default values in their
``__init__`` method because they must be able to be initialized
without arguments.

Subclasses must implement the `transmute` method. It receives the
enclosing rectangle *x0, y0, width, height* as well as the
*mutation_size*, which scales the outline properties such as padding.
It returns the outline of the fancy box as `.path.Path`.
"""

def transmute(self, x0, y0, width, height, mutation_size):
"""
The transmute method is a very core of the
:class:`BboxTransmuter` class and must be overridden in the
subclasses. It receives the location and size of the
rectangle, and the mutation_size, with which the amount of
padding and etc. will be scaled. It returns a
:class:`~matplotlib.path.Path` instance.
"""
"""Return the `~.path.Path` outlining the given rectangle."""
raise NotImplementedError('Derived must override')

def __call__(self, x0, y0, width, height, mutation_size,
Expand All @@ -1937,9 +1935,18 @@ def __call__(self, x0, y0, width, height, mutation_size,
Given the location and size of the box, return the path of
the box around it.

- *x0*, *y0*, *width*, *height* : location and size of the box
- *mutation_size* : a reference scale for the mutation.
- *aspect_ratio* : aspect-ration for the mutation.
Parameters
----------
x0, y0, width, height : float
Location and size of the box.
mutation_size : float
A reference scale for the mutation.
aspect_ratio : float, default: 1
Aspect-ratio for the mutation.

Returns
-------
path : `~matplotlib.path.Path`
"""
# The __call__ method is a thin wrapper around the transmute method
# and takes care of the aspect.
Expand All @@ -1959,15 +1966,14 @@ def __call__(self, x0, y0, width, height, mutation_size,
@_register_style(_style_list)
class Square(_Base):
"""
A simple square box.
"""
A square box.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
"""
def __init__(self, pad=0.3):
"""
Parameters
----------
pad : float
"""
self.pad = pad
super().__init__()

Expand All @@ -1987,14 +1993,15 @@ def transmute(self, x0, y0, width, height, mutation_size):

@_register_style(_style_list)
class Circle(_Base):
"""A simple circle box."""
"""
A circular box.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
"""
def __init__(self, pad=0.3):
"""
Parameters
----------
pad : float
The amount of padding around the original box.
"""
self.pad = pad
super().__init__()

Expand All @@ -2010,7 +2017,12 @@ def transmute(self, x0, y0, width, height, mutation_size):
@_register_style(_style_list)
class LArrow(_Base):
"""
(left) Arrow Box
A box in the shape of a left-pointing arrow.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
"""
def __init__(self, pad=0.3):
self.pad = pad
Expand Down Expand Up @@ -2048,9 +2060,13 @@ def transmute(self, x0, y0, width, height, mutation_size):
@_register_style(_style_list)
class RArrow(LArrow):
"""
(right) Arrow Box
"""
A box in the shape of a right-pointing arrow.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
"""
def __init__(self, pad=0.3):
super().__init__(pad)

Expand All @@ -2063,7 +2079,12 @@ def transmute(self, x0, y0, width, height, mutation_size):
@_register_style(_style_list)
class DArrow(_Base):
"""
(Double) Arrow Box
A box in the shape of a two-way arrow.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
"""
# This source is copied from LArrow,
# modified to add a right arrow to the bbox.
Expand Down Expand Up @@ -2114,16 +2135,15 @@ def transmute(self, x0, y0, width, height, mutation_size):
class Round(_Base):
"""
A box with round corners.
"""

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
rounding_size : float, default: *pad*
Radius of the corners.
"""
def __init__(self, pad=0.3, rounding_size=None):
"""
*pad*
amount of padding

*rounding_size*
rounding radius of corners. *pad* if None
"""
self.pad = pad
self.rounding_size = rounding_size
super().__init__()
Expand Down Expand Up @@ -2175,17 +2195,16 @@ def transmute(self, x0, y0, width, height, mutation_size):
@_register_style(_style_list)
class Round4(_Base):
"""
Another box with round edges.
"""
A box with rounded edges.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
rounding_size : float, default: *pad*/2
Rounding of edges.
"""
def __init__(self, pad=0.3, rounding_size=None):
"""
*pad*
amount of padding

*rounding_size*
rounding size of edges. *pad* if None
"""
self.pad = pad
self.rounding_size = rounding_size
super().__init__()
Expand Down Expand Up @@ -2228,17 +2247,16 @@ def transmute(self, x0, y0, width, height, mutation_size):
@_register_style(_style_list)
class Sawtooth(_Base):
"""
A sawtooth box.
"""
A box with a sawtooth outline.

Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
tooth_size : float, default: *pad*/2
Size of the sawtooth.
"""
def __init__(self, pad=0.3, tooth_size=None):
"""
*pad*
amount of padding

*tooth_size*
size of the sawtooth. pad* if None
"""
self.pad = pad
self.tooth_size = tooth_size
super().__init__()
Expand Down Expand Up @@ -2325,15 +2343,17 @@ def transmute(self, x0, y0, width, height, mutation_size):

@_register_style(_style_list)
class Roundtooth(Sawtooth):
"""A rounded tooth box."""
def __init__(self, pad=0.3, tooth_size=None):
"""
*pad*
amount of padding
"""
A box with a rounded sawtooth outline.

*tooth_size*
size of the sawtooth. pad* if None
"""
Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
tooth_size : float, default: *pad*/2
Size of the sawtooth.
"""
def __init__(self, pad=0.3, tooth_size=None):
super().__init__(pad, tooth_size)

def transmute(self, x0, y0, width, height, mutation_size):
Expand Down Expand Up @@ -2364,7 +2384,7 @@ class FancyBboxPatch(Patch):

`.FancyBboxPatch` is similar to `.Rectangle`, but it draws a fancy box
around the rectangle. The transformation of the rectangle box to the
fancy box is delegated to the `.BoxTransmuterBase` and its derived classes.
fancy box is delegated to the style classes defined in `.BoxStyle`.
"""

_edge_default = True
Expand Down