Module embedded_text::style[−][src]

Expand description

`TextBox` styling.

To construct a TextBox object at least a text string, a bounding box and character style are required. For advanced formatting options an additional TextBoxStyle object might be used.

Text rendering in embedded-graphics is designed to be extendable by text renderers for different font formats. embedded-text follows this philosophy by using the same text renderer infrastructure. To use a text renderer in an embedded-text project each renderer provides a character style object. See the embedded-graphics documentation for more information.

TextBox style

In addition to styling the individual characters the TextBox drawable also contains a TextBoxStyle setting. The text box style is used to set the horizontal and vertical alignment, line and paragraph spacing, tab size and some other advanced settings of text box objects.

The alignment option sets the horizontal alignment of the text. Note: alignment works differently from embedded-graphics. With the default value Left the start of each line will be lined up with the left side of the bounding box. Similarly Right aligned text will line up the ends of the lines with the right side of the bounding box. Centered text will be positioned at equal distance from the left and right sides. Justified text will distribute the text in such a way that both the start and end of a line will align with the respective sides of the bounding box.

The vertical_alignment setting sets the vertical alignment of the text. With the default value Top the top of the text is lined up with the top of the bounding box. Similarly Bottom aligned text will line up the bottom of the last line of the text with the bottom edge of the bounding box. Middle aligned text will be positioned at equal distance from the top and bottom sides.

The line_height option sets the distance between the baselines of the lines of text. It can be specified in either pixels or percentage of the line height defined by the font.

The paragraph_spacing setting sets the distance between paragraphs of text, in addition to the line spacing.

The tab_size setting sets the maximum width of a tab character. It can be specified in either pixels of number of space characters.

Advanced settings

The height_mode setting determines how the TextBox adjusts its height to its contents. The default value Exact does not adjust the height - the text box will be as tall as the bounding box given to it. FitToText will adjust the height to the height of the text, regardless of the initial bounding box’s height. ShrinkToText will decrease the height of the text box to the height of the text, if the bounding box given to the text box is too tall.

Exact and ShrinkToText have an additional VerticalOverdraw parameter. This setting specifies how the text outside of the adjusted bounding box is handled. Visible renders the text regardless of the bounding box. Hidden renders everything inside the bounding box. If a line is too tall to fit inside the bounding box, it will be drawn partially, the bottom part of the text clipped. FullRowsOnly only renders lines that are completely inside the bounding box.

For examples on how to use height mode settings, see the documentation of HeightMode.

The leading_spaces and trailing_spaces settings set whether the spaces at the beginning or the end of a line are visible. The default values depend on the alignment setting.

`alignment`	`leading_spaces`	`trailing_spaces`
`Left`	`true`	`false`
`Right`	`false`	`false`
`Center`	`false`	`false`
`Justified`	`false`	`false`

Ways to create and apply text box styles

Example 1: Setting multiple options using the `TextBoxStyleBuilder` object:

To build more complex styles, you can use the TextBoxStyleBuilder object and the TextBox::with_textbox_style constructor.

use embedded_text::{
    TextBox,
    style::TextBoxStyleBuilder,
    alignment::{
        HorizontalAlignment,
        VerticalAlignment,
    },
};

let textbox_style = TextBoxStyleBuilder::new()
    .alignment(HorizontalAlignment::Center)
    .vertical_alignment(VerticalAlignment::Middle)
    .build();

let textbox = TextBox::with_textbox_style(
    text,
    bounding_box,
    character_style,
    textbox_style,
);

Examples 2 and 3: Only setting a single option:

Both the TextBox and TextBoxStyle objects have different constructor methods in case you only want to set a single style option.

use embedded_text::{TextBox, alignment::HorizontalAlignment};

let textbox = TextBox::with_alignment(
    text,
    bounding_box,
    character_style,
    HorizontalAlignment::Center,
);

use embedded_text::{TextBox, style::TextBoxStyle, alignment::VerticalAlignment};

let textbox_style = TextBoxStyle::with_vertical_alignment(VerticalAlignment::Middle);

let textbox = TextBox::with_textbox_style(
    text,
    bounding_box,
    character_style,
    textbox_style,
);

Structs

TextBoxStyle

Styling options of a TextBox.

TextBoxStyleBuilder

TextBoxStyle builder object.

Enums

HeightMode

Specifies how the TextBox’s height should be adjusted.

TabSize

Tab size helper

VerticalOverdraw

Vertical overdraw options used by height modes that don’t conform exactly to the text size.