Skip to content

FlexiText

Handle storing and drawing of formatted text.

Parameters:

Name Type Description Default
texts tuple or list of flexitext.Text instances

These objects represent the text together with their styles.

 ()
Source code in flexitext/flexitext.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class FlexiText:
    """Handle storing and drawing of formatted text.

    Parameters
    ----------

    texts : tuple or list of flexitext.Text instances
        These objects represent the text together with their styles.
    """

    HORIZONTAL_ALIGNMENT = {"center": 0.5, "left": 0, "right": 1}
    VERTICAL_ALIGNMENT = {"center": 0.5, "top": 1, "bottom": 0}

    def __init__(self, *texts):
        self.texts = texts

    def plot(
        self,
        x,
        y,
        ha="left",
        va="center",
        ma="left",
        mva="baseline",
        xycoords="axes fraction",
        ax=None,
    ):
        """Draw text with multiple formats.

        Parameters
        ----------
        x : float
            The horizontal position to place the text. By default, this is in axes fraction
            coordinates.
        y : float
            The vertical position to place the text. By default, this is in axes fraction
            coordinates.
        ha : str
            Horizontal alignment. Must be one of `'center'`, `'right'`, or `'left'`.
        va : str
            Horizontal alignment. Must be one of `'center'`, `'top'`, or `'bottom'`.
        ma : str
            Alignment for multiline texts. The layout of the bounding box of all the lines is
            determined by the `ha` and `va` properties. This property controls the alignment of the
            text lines within that box.
        mva : str
            Vertical alignment for text within multiline texts. Can be one of `"top"`, `"bottom"`,
            `"left"`, `"right"`, `"center"`, or `"baseline"`. Defaults to `"baseline"`.
        xycoords : str
            The coordinate system for `x` and `y`. Must be one of `'data'`, `'axes fraction'`, or
            `'figure fraction'`.
        ax : matplotlib.axes.Axes
            Matplotlib `Axes`. The default value means the `Axes` is obtained with `plt.gca()`

        Returns
        -------
        annotation_box : matplotlib.offsetbox.AnnotationBbox
        """

        if ax is None:
            ax = plt.gca()
        if xycoords in ("axes fraction", "data"):
            parent = ax
        elif xycoords == "figure fraction":
            parent = ax.figure
            xycoords = ax.figure.transFigure
        else:
            raise ValueError(
                "'xycoords' must be one of 'data', 'axes fraction' or 'figure fraction', "
                f"not {xycoords}"
            )

        offsetbox = self._make_offset_box(ma, mva)
        box_alignment = self._make_box_alignment(ha, va)
        annotation_box = AnnotationBbox(
            offsetbox,
            (x, y),
            xycoords=xycoords,
            frameon=False,
            box_alignment=box_alignment,
            pad=0,
        )

        parent.add_artist(annotation_box)
        return annotation_box

    def _make_box_alignment(self, ha, va):
        """Convert `ha` and `va` to a touple of two numbers"""
        ha = self.HORIZONTAL_ALIGNMENT[ha]
        va = self.VERTICAL_ALIGNMENT[va]
        return (ha, va)

    def _make_offset_box(self, mha, mva):
        """Create grid with formatted text"""
        return make_text_grid(self.texts, mha, mva)

plot(x, y, ha='left', va='center', ma='left', mva='baseline', xycoords='axes fraction', ax=None)

Draw text with multiple formats.

Parameters:

Name Type Description Default
x float

The horizontal position to place the text. By default, this is in axes fraction coordinates.

 required
y float

The vertical position to place the text. By default, this is in axes fraction coordinates.

 required
ha str

Horizontal alignment. Must be one of 'center', 'right', or 'left'.

 'left'
va str

Horizontal alignment. Must be one of 'center', 'top', or 'bottom'.

 'center'
ma str

Alignment for multiline texts. The layout of the bounding box of all the lines is determined by the ha and va properties. This property controls the alignment of the text lines within that box.

 'left'
mva str

Vertical alignment for text within multiline texts. Can be one of "top", "bottom", "left", "right", "center", or "baseline". Defaults to "baseline".

 'baseline'
xycoords str

The coordinate system for x and y. Must be one of 'data', 'axes fraction', or 'figure fraction'.

 'axes fraction'
ax Axes

Matplotlib Axes. The default value means the Axes is obtained with plt.gca()

 None

Returns:

Name Type Description
annotation_box AnnotationBbox
Source code in flexitext/flexitext.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def plot(
    self,
    x,
    y,
    ha="left",
    va="center",
    ma="left",
    mva="baseline",
    xycoords="axes fraction",
    ax=None,
):
    """Draw text with multiple formats.

    Parameters
    ----------
    x : float
        The horizontal position to place the text. By default, this is in axes fraction
        coordinates.
    y : float
        The vertical position to place the text. By default, this is in axes fraction
        coordinates.
    ha : str
        Horizontal alignment. Must be one of `'center'`, `'right'`, or `'left'`.
    va : str
        Horizontal alignment. Must be one of `'center'`, `'top'`, or `'bottom'`.
    ma : str
        Alignment for multiline texts. The layout of the bounding box of all the lines is
        determined by the `ha` and `va` properties. This property controls the alignment of the
        text lines within that box.
    mva : str
        Vertical alignment for text within multiline texts. Can be one of `"top"`, `"bottom"`,
        `"left"`, `"right"`, `"center"`, or `"baseline"`. Defaults to `"baseline"`.
    xycoords : str
        The coordinate system for `x` and `y`. Must be one of `'data'`, `'axes fraction'`, or
        `'figure fraction'`.
    ax : matplotlib.axes.Axes
        Matplotlib `Axes`. The default value means the `Axes` is obtained with `plt.gca()`

    Returns
    -------
    annotation_box : matplotlib.offsetbox.AnnotationBbox
    """

    if ax is None:
        ax = plt.gca()
    if xycoords in ("axes fraction", "data"):
        parent = ax
    elif xycoords == "figure fraction":
        parent = ax.figure
        xycoords = ax.figure.transFigure
    else:
        raise ValueError(
            "'xycoords' must be one of 'data', 'axes fraction' or 'figure fraction', "
            f"not {xycoords}"
        )

    offsetbox = self._make_offset_box(ma, mva)
    box_alignment = self._make_box_alignment(ha, va)
    annotation_box = AnnotationBbox(
        offsetbox,
        (x, y),
        xycoords=xycoords,
        frameon=False,
        box_alignment=box_alignment,
        pad=0,
    )

    parent.add_artist(annotation_box)
    return annotation_box