
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "gallery/userdemo/custom_boxstyle01.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_gallery_userdemo_custom_boxstyle01.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_gallery_userdemo_custom_boxstyle01.py:


=================
Custom box styles
=================

This example demonstrates the implementation of a custom `.BoxStyle`.
Custom `.ConnectionStyle`\s and `.ArrowStyle`\s can be similarly defined.

.. GENERATED FROM PYTHON SOURCE LINES 9-15

.. code-block:: default


    from matplotlib.patches import BoxStyle
    from matplotlib.path import Path
    import matplotlib.pyplot as plt









.. GENERATED FROM PYTHON SOURCE LINES 16-26

Custom box styles can be implemented as a function that takes arguments
specifying both a rectangular box and the amount of "mutation", and
returns the "mutated" path.  The specific signature is the one of
``custom_box_style`` below.

Here, we return a new path which adds an "arrow" shape on the left of the
box.

The custom box style can then be used by passing
``bbox=dict(boxstyle=custom_box_style, ...)`` to `.Axes.text`.

.. GENERATED FROM PYTHON SOURCE LINES 26-68

.. code-block:: default



    def custom_box_style(x0, y0, width, height, mutation_size, mutation_aspect=1):
        """
        Given the location and size of the box, return the path of the box around
        it.

        Rotation is automatically taken care of.

        Parameters
        ----------
        x0, y0, width, height : float
            Box location and size.
        mutation_size : float
            Mutation reference scale, typically the text font size.
        mutation_aspect
            Mutation aspect ratio.
        """
        # We ignore mutation_aspect. This is okay in general.

        # padding
        mypad = 0.3
        pad = mutation_size * mypad
        # width and height with padding added.
        width = width + 2 * pad
        height = height + 2 * pad
        # boundary of the padded box
        x0, y0 = x0 - pad, y0 - pad
        x1, y1 = x0 + width, y0 + height
        # return the new path
        return Path([(x0, y0),
                     (x1, y0), (x1, y1), (x0, y1),
                     (x0-pad, (y0+y1)/2), (x0, y0),
                     (x0, y0)],
                    closed=True)


    fig, ax = plt.subplots(figsize=(3, 3))
    ax.text(0.5, 0.5, "Test", size=30, va="center", ha="center", rotation=30,
            bbox=dict(boxstyle=custom_box_style, alpha=0.2))





.. image:: /gallery/userdemo/images/sphx_glr_custom_boxstyle01_001.png
    :alt: custom boxstyle01
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Text(0.5, 0.5, 'Test')



.. GENERATED FROM PYTHON SOURCE LINES 69-79

Alternatively, custom box styles can be implemented as subclasses of
``matplotlib.patches.BoxStyle._Base``, by overriding the ``transmute``
method, as demonstrated below.

The subclass can then be registered into the ``BoxStyle._style_list`` dict,
which allows specifying the box style as a string,
``bbox=dict(boxstyle="registered_name,param=value,...", ...)``.

Note that this approach relies on internal APIs and is therefore not
officially supported.

.. GENERATED FROM PYTHON SOURCE LINES 79-143

.. code-block:: default



    class MyStyle(BoxStyle._Base):
        """A simple box."""

        def __init__(self, pad=0.3):
            """
            The arguments must be floats and have default values.

            Parameters
            ----------
            pad : float
                amount of padding
            """
            self.pad = pad
            super().__init__()

        def transmute(self, x0, y0, width, height, mutation_size):
            """
            Given the location and size of the box, return the path of the box
            around it.

            Rotation is automatically taken care of.

            Parameters
            ----------
            x0, y0, width, height : float
                Box location and size.
            mutation_size : float
                Reference scale for the mutation, typically the text font size.

            Notes
            -----
            Unlike when defining the box style as a function (as in
            `custom_box_style`), here there is no *mutation_aspect* parameter.
            Matplotlib will first squeeze the box's y-axis by *mutation_aspect*
            before calling the `transmute` method, and then later reexpand the
            y-axis by the same amount.
            """
            # padding
            pad = mutation_size * self.pad
            # width and height with padding added
            width = width + 2.*pad
            height = height + 2.*pad
            # boundary of the padded box
            x0, y0 = x0 - pad, y0 - pad
            x1, y1 = x0 + width, y0 + height
            # return the new path
            return Path([(x0, y0),
                         (x1, y0), (x1, y1), (x0, y1),
                         (x0-pad, (y0+y1)/2.), (x0, y0),
                         (x0, y0)],
                        closed=True)


    BoxStyle._style_list["angled"] = MyStyle  # Register the custom style.

    fig, ax = plt.subplots(figsize=(3, 3))
    ax.text(0.5, 0.5, "Test", size=30, va="center", ha="center", rotation=30,
            bbox=dict(boxstyle="angled,pad=0.5", alpha=0.2))

    del BoxStyle._style_list["angled"]  # Unregister it.

    plt.show()



.. image:: /gallery/userdemo/images/sphx_glr_custom_boxstyle01_002.png
    :alt: custom boxstyle01
    :class: sphx-glr-single-img






.. _sphx_glr_download_gallery_userdemo_custom_boxstyle01.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: custom_boxstyle01.py <custom_boxstyle01.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: custom_boxstyle01.ipynb <custom_boxstyle01.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    Keywords: matplotlib code example, codex, python plot, pyplot
    `Gallery generated by Sphinx-Gallery
    <https://sphinx-gallery.readthedocs.io>`_
