Struct embedded_text::TextBox

pub struct TextBox<'a, S, M = NoPlugin<<S as TextRenderer>::Color>> where
    S: TextRenderer,  {
    pub text: &'a str,
    pub bounds: Rectangle,
    pub character_style: S,
    pub style: TextBoxStyle,
    pub vertical_offset: i32,
    // some fields omitted
}

A text box object.

The TextBox object can be used to draw text on a draw target. It is meant to be a more feature-rich alternative to Text in embedded-graphics.

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. For more information about text box styling, see the documentation of the style module.

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 on text renderers and character styling.

Plugins

The feature set of TextBox can be extended by plugins. Plugins can be used to implement optional features which are not essential to the core functionality of embedded-text.

Use the add_plugin method to add a plugin to the TextBox object. Multiple plugins can be used at the same time. Plugins are applied in the reverse order they are added. Note that some plugins may interfere with others if used together or not in the expected order.

If you need to extract data from plugins after the text box has been rendered, you can use the take_plugins method.

See the list of built-in plugins in the plugin module.

Note: Implementing custom plugins is experimental and require enabling the plugin feature.

Example: advanced text styling using the ANSI plugin

use embedded_text::{TextBox, plugin::ansi::Ansi};
TextBox::new(
    "Some \x1b[4munderlined\x1b[24m text",
    bounding_box,
    character_style,
)
.add_plugin(Ansi::new())
.draw(&mut display)?;

Vertical offsetting

You can use the set_vertical_offset method to move the text inside the text box. Vertical offset is applied after all vertical measurements and alignments. This can be useful to scroll text in a fixed text box. Setting a positive value moves the text down.

Residual text

If the text does not fit the given bounding box, the draw method returns the part which was not processed. The return value can be used to flow text into multiple text boxes.

Fields

text: &'a str

The text to be displayed in this TextBox

bounds: Rectangle

The bounding box of this TextBox

character_style: S

The character style of the TextBox.

style: TextBoxStyle

The style of the TextBox.

vertical_offset: i32

Vertical offset applied to the text just before rendering.

Implementations

impl<'a, S> TextBox<'a, S, NoPlugin<<S as TextRenderer>::Color>> where
    <S as TextRenderer>::Color: From<Rgb888>,
    S: TextRenderer + CharacterStyle, 

pub fn new(text: &'a str, bounds: Rectangle, character_style: S) -> Self

Creates a new TextBox instance with a given bounding Rectangle.

pub fn with_textbox_style(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    textbox_style: TextBoxStyle
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a given TextBoxStyle.

pub fn with_alignment(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    alignment: HorizontalAlignment
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a default TextBoxStyle with the given horizontal alignment.

pub fn with_vertical_alignment(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    vertical_alignment: VerticalAlignment
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a default TextBoxStyle and the given vertical alignment.

pub fn with_height_mode(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    mode: HeightMode
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a default TextBoxStyle and the given height mode.

pub fn with_line_height(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    line_height: LineHeight
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a default TextBoxStyle and the given line height.

pub fn with_paragraph_spacing(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    spacing: u32
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a default TextBoxStyle and the given paragraph spacing.

pub fn with_tab_size(
    text: &'a str,
    bounds: Rectangle,
    character_style: S,
    tab_size: TabSize
) -> Self

Creates a new TextBox instance with a given bounding Rectangle and a default TextBoxStyle and the given tab size.

pub fn set_vertical_offset(&mut self, offset: i32) -> &mut Self

Sets the vertical text offset.

Vertical offset changes the vertical position of the displayed text within the bounding box. Setting a positive value moves the text down.

pub fn add_plugin<M>(self, plugin: M) -> TextBox<'a, S, Chain<M>> where
    M: Plugin<'a, <S as TextRenderer>::Color>, 

Adds a new plugin to the TextBox.

impl<'a, S, P> TextBox<'a, S, P> where
    <S as TextRenderer>::Color: From<Rgb888>,
    S: TextRenderer + CharacterStyle,
    P: Plugin<'a, <S as TextRenderer>::Color> + ChainElement, 

pub fn add_plugin<M>(self, plugin: M) -> TextBox<'a, S, Link<M, P>> where
    M: Plugin<'a, <S as TextRenderer>::Color>, 

Adds a new plugin to the TextBox.

pub fn take_plugins(self) -> P

Deconstruct the text box and return the plugins.

impl<'a, S, M> TextBox<'a, S, M> where
    S: TextRenderer,
    M: Plugin<'a, S::Color>,
    S::Color: From<Rgb888>, 

pub fn fit_height(&mut self) -> &mut Self

Sets the height of the TextBox to the height of the text.

pub fn fit_height_limited(&mut self, max_height: u32) -> &mut Self

Sets the height of the TextBox to the height of the text, limited to max_height.

This method allows you to set a maximum height. The TextBox will take up at most max_height pixel vertical space.

Trait Implementations

impl<'a, S: Clone, M: Clone> Clone for TextBox<'a, S, M> where
    S: TextRenderer,
    S::Color: Clone, 

fn clone(&self) -> TextBox<'a, S, M>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, S: Debug, M: Debug> Debug for TextBox<'a, S, M> where
    S: TextRenderer,
    S::Color: Debug, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, S, M> Dimensions for TextBox<'a, S, M> where
    S: TextRenderer,
    M: Plugin<'a, S::Color>, 

fn bounding_box(&self) -> Rectangle

Returns the bounding box.

impl<'a, F, M> Drawable for TextBox<'a, F, M> where
    F: TextRenderer<Color = <F as CharacterStyle>::Color> + CharacterStyle,
    <F as CharacterStyle>::Color: From<Rgb888>,
    M: Plugin<'a, <F as TextRenderer>::Color> + Plugin<'a, <F as CharacterStyle>::Color>, 

type Color = <F as CharacterStyle>::Color

The pixel color type.

type Output = &'a str

The return type of the draw method.

fn draw<D: DrawTarget<Color = Self::Color>>(
    &self,
    display: &mut D
) -> Result<&'a str, D::Error>

Draw the graphics object using the supplied DrawTarget.

impl<'a, S: Hash, M: Hash> Hash for TextBox<'a, S, M> where
    S: TextRenderer,
    S::Color: Hash, 

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'a, S, M> Transform for TextBox<'a, S, M> where
    S: TextRenderer + Clone,
    M: Plugin<'a, S::Color>, 

fn translate(&self, by: Point) -> Self

Move the origin of an object by a given number of (x, y) pixels, returning a new object

fn translate_mut(&mut self, by: Point) -> &mut Self

Move the origin of an object by a given number of (x, y) pixels, mutating the object in place