Module text

Expand description

Text widget, properties and other types.

The Text! widget implements text layout and rendering, it is also the base widget for SelectableText!, TextInput! and label!. Text properties are largely contextual, you can set text::font_size in any widget to affect all text inside that widget.

The Text! widget provides simple text rendering, that is all text is of the same style and different fonts are only used as fallback. You can implement rich text by combining multiple Text! and Wrap! panels, see the wrap module docs for an example. Some widgets also parse text and generate the rich text setup automatically, the Markdown! and AnsiText! widgets are examples of this.

The example below declares two text widgets, one displays a text that requires multiple fonts to render, the other displays debug information about the first.

use zng::prelude::*;

let txt = "text テキスト 📋";
let font_use = var(vec![]);
Stack! {
    text::font_family = ["Segoe UI", "Yu Gothic UI", "Segoe Ui Emoji", "sans-serif"];
    children = ui_vec![
        Text! {
            font_size = 1.5.em();
            txt;
            get_font_use = font_use.clone();
        },
        Text! {
            font_size = 0.9.em();
            txt = font_use.map(|u| {
                let mut r = Txt::from("");
                for (font, range) in u {
                    use std::fmt::Write as _;
                    writeln!(&mut r, "{} = {:?}", font.face().family_name(), &txt[range.clone()]).unwrap();
                }
                r.end_mut();
                r
            });
        },
    ];
    direction = StackDirection::top_to_bottom();
    spacing = 15;
}

Note that the font_family is set on the parent widget, both texts have the same font family value because of this, the font_size on the other hand is set for each text widget and only affects that widget.

§Rich Text

Rich text is a sequence of Text! of different styles and other widgets such as Image! inside one or more layout panels, usually a Wrap! panel for paragraphs and a Stack! panel for the full text or page, if you only intent to present the text that is all you need, the inline layout will coordinate the flow of lines across multiple Text! widgets.

To enable selection or editing in rich text you can enable the rich_text property on the panels. The outer panel will declare a rich text context that the inner Text! widgets will use to coordinate the caret position and selection across texts.

use zng::prelude::*;
Wrap! {
    text::rich_text = true;
    text::txt_selectable = true;
    children = ui_vec![
        Text! {
            txt = "red text";
            font_color = colors::RED;
        },
        Text! {
            txt = " green text";
            font_color = colors::GREEN;
        },
        Text! {
            txt = " blue text";
            font_color = colors::BLUE;
        },
    ];
}

The example above declares a rich text with three different text runs, by enabling rich_text the wrap panel becomes a rich text context that all descendant texts will use to coordinate text operations. In this case the txt_selectable property enables text selection (and copy) for all descendants, without rich_text the descendant texts would allow selection only within each text.

The rich_text property together with txt_editable is the base for rich text editor widgets, out of the box the descendant texts will coordinate the caret position and the focused text is edited by typing. A rich text editor needs to implement many other features, such as removing empty text widgets, inserting new styled texts, encoding all these texts into an unified representation for saving.

To suppress the default behavior of component texts you can handle keyboard events in the preview track and stop propagation, same for mouse/touch events. The full text API crate provides the zng_wgt_text::cmd module that can be used to programmatically control the texts. The active component text is just the focused widget, that can be controlled using the zng::focus module.

§Full API

See zng_wgt_text for the full widget API.

Modules§

cmd: Commands that controls the editable/selectable text.

Macros§

Em: A simple text run with italic font style.
Strong: A simple text run with bold font weight.
formatx: Creates a Txt by formatting using the format_args! syntax.

Structs§

AutoSelection: Defines when text is auto-selected on focus change.
CaretStatus: Display info of edit caret position.
ChangeStopArgs: Arguments for on_change_stop.
LangMix: m Language and text direction properties.
ParagraphMix: m Text paragraph properties.
SelectionToolbarArgs: Arguments for selection_toolbar_fn.
TEXT: Text internals used by text implementer nodes and properties.
Text: W A configured text run.
Txt: Text string type, can be one of multiple internal representations, mostly optimized for sharing and one for editing.
UnderlineSkip: Represents what parts of a text the underline must skip over.

Enums§

CaretShape: Defines the position of an interactive caret in relation to the selection.
ChangeStopCause: Cause of an on_change_stop.
InteractiveCaretMode: Defines when the interactive carets are used.
LinesWrapCount: Represents the number of lines and number of wrap lines in a text.
TextOverflow: Defines how text overflow is handled by the text widgets.
TxtRepr: Identifies how a Txt is currently storing the string data.
UnderlinePosition: Defines what line gets traced by the text underline decoration.

Statics§

FONT_COLOR_VAR: Color of Text! glyphs that are not colored by palette.

Traits§

ToTxt: A trait for converting a value to a Txt.
TxtParseValue: Represents a type that can be a var value, parse and display.

Functions§

accepts_enter: P If the '\n' character is inserted when enter is pressed and the text is editable.
accepts_tab: P If the '\t' character is inserted when tab is pressed and the text is editable.
auto_selection: P Auto-selection on focus change when the text is selectable.
caret_color: P Defines the color of the non-interactive caret.
change_stop_delay: P Debounce time for on_change_stop.
direction: P Sets the layout direction used in the layout of the widget and descendants.
font_aa: P Configure the anti-aliasing used to render text glyphs inside the widget.
font_annotation: P Sets the font annotation alternative feature.
font_caps: P Sets the font capital variant features.
font_char_variant: P Sets the font character variant alternative feature.
font_cn_variant: P Sets the Chinese logographic set.
font_color: P Defines the color the most text glyphs are filled with.
font_common_lig: P Sets the font common ligatures features.
font_contextual_alt: P Sets the font contextual alternatives feature.
font_discretionary_lig: P Sets the font discretionary ligatures feature.
font_ea_width: P Sets the East Asian figure width.
font_family: P Font family name or list of names for texts in this widget or descendants.
font_features: P Sets font features.
font_historical_forms: P Sets the font historical forms alternative feature.
font_historical_lig: P Sets the font historical ligatures feature.
font_jp_variant: P Sets the Japanese logographic set.
font_kerning: P Sets the font kerning feature.
font_num_fraction: P Sets the font numeric fraction features.
font_num_spacing: P Sets the font numeric spacing features.
font_numeric: P Sets the font numeric variant features.
font_ornaments: P Sets the font ornaments alternative feature.
font_palette: P Defines the palette used to render colored glyphs (Emoji).
font_palette_colors: P Defines custom palette colors that affect Emoji colors.
font_position: P Sets the font sub/super script position alternative feature.
font_size: P Sets the font size for the widget and descendants.
font_stretch: P Defines how condensed or expanded the preferred font should be.
font_style: P Defines the skew style of the font glyphs.
font_style_set: P Sets the font stylistic set alternative feature.
font_stylistic: P Sets the font stylistic alternative feature.
font_swash: P Sets the font swash features.
font_synthesis: P Configure if a synthetic font is generated for fonts that do not implement bold or oblique variants.
font_variations: P Sets font variations.
font_weight: P Defines the thickness or boldness the preferred font should have.
get_caret_index: P Gets the caret char index, if the text is editable.
get_caret_status: P Gets the caret display status, if the text is editable.
get_chars_count: P Gets the number of character in the text.
get_lines_len: P Gets the number of lines in the text, including wrap lines.
get_lines_wrap_count: P Gets the number of wrap lines per text lines.
get_overflow: P Gets the overflow text, that is a clone of the text starting from the first overflow character.
has_selection: P If widget or rich context has selection.
hyphen_char: P The char or small string that is rendered when text is auto-hyphenated.
hyphens: P Configure hyphenation.
ime_underline: P Style and thickness of the line drawn under the IME preview text.
interactive_caret: P Defines when the interactive carets are used.
interactive_caret_visual: P Defines custom caret visual for interactive caret.
is_line_overflown: P Gets if the text has an entire line overflown.
is_overflown: P Gets if the text is overflown.
is_parse_pending: P If text has changed but txt_parse has not tried to parse the new text yet.
justify_mode: P Config the automatic spacing inserted between words and letters when text is aligned to fill.
lang: P Sets the text language and script for the widget and descendants.
letter_spacing: P Extra spacing added in between text letters.
line_break: P Configuration of text wrapping for Chinese, Japanese, or Korean text.
line_height: P Height of each text line.
line_spacing: P Extra spacing in-between text lines.
max_chars_count: P Maximum number of characters that can be input.
obscure_txt: P Enable typed text obscuring in render.
obscuring_char: P Replacement character used when obscuring text.
on_change_stop: P Called after the text changed and interaction has stopped.
overline: P Draw lines above each text line.
overline_color: P Custom overline color, if not set the font_color is used.
paragraph_spacing: P Extra spacing in-between paragraphs.
rich_text: P Defines a rich text context.
selection_color: P Sets the SELECTION_COLOR_VAR.
selection_toolbar: P Defines the floating mini-toolbar that shows near a new text selection.
selection_toolbar_anchor: P Position the selection toolbar in relation to the bounding box of all selection rectangles.
selection_toolbar_fn: P Defines the floating mini-toolbar that shows near a new text selection.
set_interactive_caret_spot: Set the caret hotspot that marks the middle of the caret on the text line.
strikethrough: P Draw lines across each text line.
strikethrough_color: P Custom strikethrough color, if not set the font_color is used.
tab_length: P Length of the TAB character space, relative to the normal space advance.
txt_align: P Alignment of text inside available space.
txt_editable: P Enable text caret, input and makes the widget focusable.
txt_overflow: P Defines if text overflow is truncated, with optional suffix append.
txt_overflow_align: P Alignment of text inside available space when the text overflows.
txt_selectable: P Enable text selection, copy and makes the widget focusable.
txt_selectable_alt_only: P Only start mouse and touch selections from this widget when the Alt keyboard modifier is pressed.
underline: P Draw lines under each text line.
underline_color: P Custom underline color, if not set the font_color is used.
underline_skip: P Defines what segments of each text line are skipped when tracing the underline.
white_space: P Text white space transform.
word_break: P Configure line breaks inside words during text wrap.
word_spacing: P Extra spacing added to the Unicode U+0020 SPACE character.

Module text

Module text Copy item path

§Rich Text

§Full API

Modules§

Macros§

Structs§

Enums§

Statics§

Traits§

Functions§

Module text