Module embedded_text::style
source · 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. Center
ed 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§
- Styling options of a
TextBox
. TextBoxStyle
builder object.
Enums§
- Specifies how the
TextBox
’s height should be adjusted. - Tab size helper
- Vertical overdraw options used by height modes that don’t conform exactly to the text size.