Struct Text 

pub struct Text<T: FormattableText> { /* private fields */ }

Text type-setting object (theme aware)

This struct contains:

• A FormattableText
• A TextDisplay
• A FontSelector
• Type-setting configuration. Values have reasonable defaults:
  • The font is derived from the TextClass by Self::configure, otherwise using FontSelector::default().
  • The font size is derived from the TextClass by Self::configure, otherwise using a default size of 16px.
  • Default text direction and alignment is inferred from the text.

This struct tracks the TextDisplay’s state of preparation and will perform steps as required. Typical usage of this struct is as follows:

• Construct with some text and TextClass
• Configure by calling Self::configure
• Size and draw using Layout methods

Implementations

impl<T: FormattableText> Text<T>

pub fn new(text: T, class: TextClass, wrap: bool) -> Self

Construct from a text model

This struct must be made ready for usage by calling Text::prepare.

pub fn with_class(self, class: TextClass) -> Self

Set text class (inline)

TextClass::Edit(false) has special handling: line wrapping is disabled and the width of self is set to that of the text.

pub fn clone_text(&self) -> T

where T: Clone,

Clone the formatted text

pub fn take_text(self) -> T

Extract text object, discarding the rest

pub fn text(&self) -> &T

Access the formattable text object

pub fn text_mut(&mut self) -> &mut T

Access the formattable text object mutably

If the text is changed, one must call Self::require_reprepare after this method then Text::prepare.

pub fn configure(&mut self, cx: &mut SizeCx<'_>)

Set the font and font size (dpem) according to configuration

Font selection depends on the TextClass, theme configuration and the loaded fonts. Font size depends on the TextClass, theme configuration and scale factor.

Alternatively, one may call Self::set_font and Self::set_font_size or use the default values (without respecting theme configuration).

pub fn require_reprepare(&mut self)

Force full repreparation of text

This may be required after calling Self::text_mut.

pub fn set_text(&mut self, text: T)

Set the text

One must call Text::prepare afterwards and may wish to inspect its return value to check the size allocation meets requirements.

pub fn str_len(&self) -> usize

Length of text

This is a shortcut to self.as_str().len().

It is valid to reference text within the range 0..text_len(), even if not all text within this range will be displayed (due to runs).

pub fn as_str(&self) -> &str

Access whole text as contiguous str

It is valid to reference text within the range 0..text_len(), even if not all text within this range will be displayed (due to runs).

pub fn clone_string(&self) -> String

Clone the unformatted text as a String

pub fn class(&self) -> TextClass

Get text class

pub fn set_class(&mut self, class: TextClass)

Set text class

This controls line-wrapping, font and font size selection.

TextClass::Edit(false) has special handling: line wrapping is disabled and the width of self is set to that of the text.

pub fn wrap(&self) -> bool

Get whether long lines are automatically wrapped

pub fn set_wrap(&mut self, wrap: bool)

Set whether long lines are automatically wrapped

pub fn font(&self) -> FontSelector

Get the font selector

pub fn set_font(&mut self, font: FontSelector)

Set the font selector

Typically, Self::configure is called to set the font selector from the TextClass and configuration. This method sets the font selector directly.

Note that effect tokens may further affect the font selector.

It is necessary to prepare the text after calling this.

pub fn font_size(&self) -> f32

Get the font size (pixels)

pub fn set_font_size(&mut self, dpem: f32)

Set the font size (pixels)

Typically, Self::configure is called to set the font size from the TextClass and configuration. This method sets the font size directly.

Note that effect tokens may further affect the font size.

To calculate this from text size in Points, use dpem = dpp * pt_size where the dots-per-point is usually dpp = scale_factor * 96.0 / 72.0 on PC platforms, or dpp = 1 on MacOS (or 2 for retina displays).

It is necessary to prepare the text after calling this.

pub fn set_font_size_pt(&mut self, pt_size: f32, scale_factor: f32)

Set font size

This is an alternative to Text::set_font_size. It is assumed that 72 Points = 1 Inch and the base screen resolution is 96 DPI. (Note: MacOS uses a different definition where 1 Point = 1 Pixel.)

pub fn direction(&self) -> Direction

Get the base text direction

pub fn set_direction(&mut self, direction: Direction)

Set the base text direction

It is necessary to prepare the text after calling this.

pub fn align(&self) -> (Align, Align)

Get text (horizontal, vertical) alignment

pub fn set_align(&mut self, align: (Align, Align))

Set text alignment

When vertical alignment is Align::Default, Self::prepare will set the vertical size of this Layout to that of the text.

It is necessary to prepare the text after calling this.

pub fn text_is_rtl(&self) -> bool

Get the base directionality of the text

This does not require that the text is prepared.

pub fn effect_tokens(&self) -> &[Effect]

Get the sequence of effect tokens

This method has some limitations: (1) it may only return a reference to an existing sequence, (2) effect tokens cannot be generated dependent on input state, and (3) it does not incorporate color information. For most uses it should still be sufficient, but for other cases it may be preferable not to use this method (use a dummy implementation returning &[] and use inherent methods on the text object via Text::text).

impl<T: FormattableText> Text<T>

Type-setting operations and status

pub fn check_status(&self, status: Status) -> Result<(), NotReady>

Check whether the status is at least status

pub fn is_prepared(&self) -> bool

Check whether the text is fully prepared and ready for usage

pub fn unchecked_display(&self) -> &TextDisplay

Read the TextDisplay, without checking status

pub fn display(&self) -> Result<&TextDisplay, NotReady>

Read the TextDisplay, if fully prepared

pub fn wrapped_display(&self) -> Result<&TextDisplay, NotReady>

Read the TextDisplay, if at least wrapped

pub fn measure_width(&mut self, max_width: f32) -> f32

Measure required width, up to some max_width

This method partially prepares the TextDisplay as required.

This method allows calculation of the width requirement of a text object without full wrapping and glyph placement. Whenever the requirement exceeds max_width, the algorithm stops early, returning max_width.

The return value is unaffected by alignment and wrap configuration.

pub fn measure_height( &mut self, wrap_width: f32, max_lines: Option<NonZeroUsize>, ) -> f32

Measure required vertical height, wrapping as configured

Stops after max_lines, if provided.

May partially prepare the text for display, but does not otherwise modify self.

pub fn prepare(&mut self) -> bool

Prepare text for display, as necessary

Self::set_rect must be called before this method.

Does all preparation steps necessary in order to display or query the layout of this text. Text is aligned within the set Rect.

Returns true on success when some action is performed, false when the text is already prepared.

pub fn reprepare_action(&mut self, cx: &mut ConfigCx<'_>)

Re-prepare, requesting a redraw or resize as required

The text is prepared and a redraw is requested. If the allocated size is too small, a resize is requested.

This is typically called after updating a Text object in a widget.

pub fn ensure_no_left_overhang(&mut self)

Offset prepared content to avoid left-overhangs

This might be called after Self::prepare to ensure content does not overhang to the left (i.e. that the x-component of the first Vec2 returned by Self::bounding_box is not negative).

This is a special utility intended for content which may be scrolled using the size reported by Self::bounding_box. Note that while vertical alignment is untouched by this method, text is never aligned above the top (the first y-component is never negative).

pub fn bounding_box(&self) -> Result<(Vec2, Vec2), NotReady>

Get the size of the required bounding box

This is the position of the upper-left and lower-right corners of a bounding box on content. Alignment and size do affect the result.

pub fn num_lines(&self) -> Result<usize, NotReady>

Get the number of lines (after wrapping)

See TextDisplay::num_lines.

pub fn get_line(&self, index: usize) -> Result<Option<&Line>, NotReady>

Get line properties

pub fn lines(&self) -> Result<impl Iterator<Item = &Line>, NotReady>

Iterate over line properties

Requires status: lines have been wrapped.

pub fn find_line( &self, index: usize, ) -> Result<Option<(usize, Range<usize>)>, NotReady>

Find the line containing text index

See TextDisplay::find_line.

pub fn line_is_rtl(&self, line: usize) -> Result<Option<bool>, NotReady>

Get the directionality of the current line

See TextDisplay::line_is_rtl.

pub fn text_index_nearest(&self, pos: Vec2) -> Result<usize, NotReady>

Find the text index for the glyph nearest the given pos

See TextDisplay::text_index_nearest.

pub fn line_index_nearest( &self, line: usize, x: f32, ) -> Result<Option<usize>, NotReady>

Find the text index nearest horizontal-coordinate x on line

See TextDisplay::line_index_nearest.

pub fn text_glyph_pos(&self, index: usize) -> Result<MarkerPosIter, NotReady>

Find the starting position (top-left) of the glyph at the given index

See TextDisplay::text_glyph_pos.

impl Text<String>

Text editing operations

pub fn insert_char(&mut self, index: usize, c: char)

Insert a char at the given position

This may be used to edit the raw text instead of replacing it. One must call Text::prepare afterwards.

Currently this is not significantly more efficient than Text::set_text. This may change in the future (TODO).

pub fn insert_str(&mut self, index: usize, text: &str)

Insert a text at the given position

This may be used to edit the raw text instead of replacing it. One must call Text::prepare afterwards.

Currently this is not significantly more efficient than Text::set_text. This may change in the future (TODO).

pub fn replace_range(&mut self, range: Range<usize>, replace_with: &str)

Replace a section of text

This may be used to edit the raw text instead of replacing it. One must call Text::prepare afterwards.

One may simulate an unbounded range by via start..usize::MAX.

Currently this is not significantly more efficient than Text::set_text. This may change in the future (TODO).

pub fn set_str(&mut self, text: &str) -> bool

Set text to a raw &str

Returns true when new text contents do not match old contents. In this case the new text is assigned, but the caller must also call Text::prepare afterwards.

pub fn set_string(&mut self, text: String) -> bool

Set text to a raw String

Returns true when new text contents do not match old contents. In this case the new text is assigned, but the caller must also call Text::prepare afterwards.

pub fn swap_string(&mut self, string: &mut String)

Swap the raw text with a String

This may be used to edit the raw text instead of replacing it. One must call Text::prepare afterwards.

Currently this is not significantly more efficient than Text::set_text. This may change in the future (TODO).

Trait Implementations

impl<T: Clone + FormattableText> Clone for Text<T>

fn clone(&self) -> Text<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug + FormattableText> Debug for Text<T>

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

Formats the value using the given formatter.

impl<T: FormattableText> Layout for Text<T>

Implement Layout, using default alignment where alignment is not provided

fn rect(&self) -> Rect

Get the widget’s region

fn size_rules(&mut self, cx: &mut SizeCx<'_>, axis: AxisInfo) -> SizeRules

Calculate size requirements for an axis

fn set_rect(&mut self, _: &mut SizeCx<'_>, rect: Rect, hints: AlignHints)

Set size and position

fn draw(&self, draw: DrawCx<'_>)

Draw a widget and its children