Struct embedded_text::TextBox
source · 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,
/* private fields */
}
Expand description
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§
source§impl<'a, S> TextBox<'a, S, NoPlugin<<S as TextRenderer>::Color>>where
S: TextRenderer + CharacterStyle,
impl<'a, S> TextBox<'a, S, NoPlugin<<S as TextRenderer>::Color>>where S: TextRenderer + CharacterStyle,
sourcepub fn new(text: &'a str, bounds: Rectangle, character_style: S) -> Self
pub fn new(text: &'a str, bounds: Rectangle, character_style: S) -> Self
Creates a new TextBox
instance with a given bounding Rectangle
.
sourcepub fn with_textbox_style(
text: &'a str,
bounds: Rectangle,
character_style: S,
textbox_style: TextBoxStyle
) -> Self
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
.
sourcepub fn with_alignment(
text: &'a str,
bounds: Rectangle,
character_style: S,
alignment: HorizontalAlignment
) -> Self
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.
sourcepub fn with_vertical_alignment(
text: &'a str,
bounds: Rectangle,
character_style: S,
vertical_alignment: VerticalAlignment
) -> Self
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.
sourcepub fn with_height_mode(
text: &'a str,
bounds: Rectangle,
character_style: S,
mode: HeightMode
) -> Self
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.
sourcepub fn with_line_height(
text: &'a str,
bounds: Rectangle,
character_style: S,
line_height: LineHeight
) -> Self
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.
sourcepub fn with_paragraph_spacing(
text: &'a str,
bounds: Rectangle,
character_style: S,
spacing: u32
) -> Self
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.
sourcepub fn with_tab_size(
text: &'a str,
bounds: Rectangle,
character_style: S,
tab_size: TabSize
) -> Self
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.
sourcepub fn set_vertical_offset(&mut self, offset: i32) -> &mut Self
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.
sourcepub fn add_plugin<M>(self, plugin: M) -> TextBox<'a, S, Chain<M>>where
M: Plugin<'a, <S as TextRenderer>::Color>,
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
.
source§impl<'a, S, P> TextBox<'a, S, P>where
S: TextRenderer + CharacterStyle,
P: Plugin<'a, <S as TextRenderer>::Color> + ChainElement,
impl<'a, S, P> TextBox<'a, S, P>where S: TextRenderer + CharacterStyle, P: Plugin<'a, <S as TextRenderer>::Color> + ChainElement,
sourcepub fn add_plugin<M>(self, plugin: M) -> TextBox<'a, S, Link<M, P>>where
M: Plugin<'a, <S as TextRenderer>::Color>,
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
.
sourcepub fn take_plugins(self) -> P
pub fn take_plugins(self) -> P
Deconstruct the text box and return the plugins.