[−][src]Module embedded_text::style

TextBox styling.

Style objects and why you need them

By itself, a TextBox does not contain the information necessary to draw it on a display. This information is called "style" and it is contained in TextBoxStyle objects.

The recommended (and most flexible) way of constructing a style object is using the TextBoxStyleBuilder builder object. The least amount of information necessary to create a text style is the Font used to render the text, so you'll need to specify this when you call TextBoxStyleBuilder::new. You can then chain together various builder methods to customize font rendering.

See the TextBoxStyleBuilder for more information on what styling options you have.

To apply a style, call TextBox::into_styled.

In-band text styling using ANSI escape codes

Sometimes you need more flexibility than what a single style object can provide, like changing font color for a specific word in the text. embedded-text supports this use case by using a subset of the standard ANSI escape codes. These are special character sequences you can use in the text to change the font stlye of the text itself. This documentation does not aim to provide a full specification of all the ANSI escape codes, only describes the supported subset.

Note: if embedded-text fails to parse an escape sequence, it will ignore the \x1b character and display the rest as normal text.

All escape sequences start with the \x1b[ sequence, where \x1b is the ASCII escape character. embedded-text supports a subset of the SGR parameters, which are numeric codes with specific functions, followed by a number of parameters and end with the m character.

Currently, embedded-text supports changing the text and background colors. To do this, you have the following options:

Standard color codes

The standard color codes option is the simplest, and least flexible way to set color.

Color name	Text color	Background color	RGB888
Black	`\x1b[30m`	`\x1b[40m`	12,12,12
Red	`\x1b[31m`	`\x1b[41m`	197,15,31
Green	`\x1b[32m`	`\x1b[42m`	19,161,14
Yellow	`\x1b[33m`	`\x1b[43m`	193,156,0
Blue	`\x1b[34m`	`\x1b[44m`	0,55,218
Magenta	`\x1b[35m`	`\x1b[45m`	136,23,152
Cyan	`\x1b[36m`	`\x1b[46m`	58,150,221
White	`\x1b[37m`	`\x1b[47m`	204,204,204
Gray (Bright Black)	`\x1b[90m`	`\x1b[100m`	118,118,118
Bright Red	`\x1b[91m`	`\x1b[101m`	231,72,86
Bright Green	`\x1b[92m`	`\x1b[102m`	22,198,12
Bright Yellow	`\x1b[93m`	`\x1b[103m`	249,241,165
Bright Blue	`\x1b[94m`	`\x1b[104m`	59,120,255
Bright Magenta	`\x1b[95m`	`\x1b[105m`	180,0,158
Bright Cyan	`\x1b[96m`	`\x1b[106m`	97,214,214
Bright White	`\x1b[97m`	`\x1b[107m`	242,242,242

8 bit colors

8 bit colors are in the form of either \x1b[38;5;<n>m (text color) or \x1b[48;5;<n>m (background color) sequece. Here, <n> marks a parameter that determines the color. <n> can have the following values:

0-15: standard colors in the order of the above table. For example, \x1b[38;5;12m is the Bright Blue color.
16-231: 6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
232-255: grayscale from black to white

24 bit colors

8 bit colors are in the form of either \x1b[38;2;<r>;<g>;<b>m (text color) or \x1b[48;2;<r>;<g>;<b>m (background color) sequece. Here, <r>, <g> and <b> can take any value between 0 and 255.

Color values on color spaces other than `Rgb888`

By default, embedded-text uses the following color types provided by embedded-graphics:

Rgb888
Rgb565
Rgb555
BinaryColor

Internally, all ANSI color sequences are turned into the Rgb type, which can be converted to the above types. The resulting color will be the closest match to what you specify.

If you wish to use a different color type, you'll need to implement From<Rgb> for your color type and write the conversion yourself.

Color values on monochrome displays

Monochrome displays use the BinaryColor color which can have two values: On or Off. You can still use the ANSI colors with the following considerations:

If the value of all three color channels are greater than 127, the resulting color in On
Otherwise, the color is converted to Off.

Other text styling options

The following Sgr sequences are supported:

\x1b[0m: Reset everything
\x1b[4m: Underlined text
\x1b[24m: Turn off text underline
\x1b[9m: Crossed out/strikethrough text
\x1b[29m: Turn off strikethrough
\x1b[39m: Reset text color
\x1b[49m: Reset background color

Reset style options to default

embedded-text supports the Reset all (\x1b[0m), Default text color (\x1b[39m) and Default background color (\x1b[49m) codes. These codes can be used to reset colors to transparent (i.e. no pixels drawn for text or background).

In addition, Reset all turns off the underlined and crossed out styles.

Other supported ANSI escape codes

Besides changing text style, you can also move the cursor using ANSI escape codes! You have the following options:

Move the cursor forward <n> characters: \x1b[<n>C. This command will stop at the end of line, so you can use it to simulate a highlighted line, for example. Note: Moving the cursor forward fills the line with the background color. If you want to avoid this, make sure to reset the background color before moving the cursor!
Move the cursor backward <n> characters: \x1b[<n>D. This command will stop at the start of line.

Re-exports

pub use builder::TextBoxStyleBuilder;

Modules

builder	Textbox style builder.
color	Colors.
height_mode	Height adjustment options.
vertical_overdraw	Vertical overdraw options.

Structs

TabSize	Tab size helper
TextBoxStyle	Styling options of a `TextBox`.