Struct Text

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

Text type-setting object (theme aware)

This struct is a theme-aware variant of crate::text::Text. It contains:

• A TextClass
• A FormattableText
• A TextDisplay
• Type-setting configuration. Values have reasonable defaults:
  • The font is derived from the TextClass by ConfigCx::text_configure. Otherwise, the default font will be the first loaded font: see crate::text::fonts.
  • The font size is derived from the TextClass by ConfigCx::text_configure. Otherwise, the default font size is 16px (the web default).
  • Default text direction and alignment is inferred from the text.
  • The bounds used for alignment and line-wrapping must be set by calling Text::set_bounds.

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

• Configure by calling ConfigCx::text_configure
• (Optionally) check size requirements by calling SizeCx::text_rules
• Set the size and prepare by calling ConfigCx::text_set_size
• Draw by calling DrawCx::text (and/or other text methods)

Implementations

impl<T: FormattableText> Text<T>

Constructors and other methods requiring T: Sized

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

Construct from a text model

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

pub fn with_display(self, display: TextDisplay) -> Self

Replace the TextDisplay

This may be used with Self::new to reconstruct an object which was disolved into_parts.

pub fn into_parts(self) -> (TextDisplay, T)

Decompose into parts

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

Set text class (inline)

Default: TextClass::Label(true)

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 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.

impl<T: FormattableText + ?Sized> Text<T>

Text, font and type-setting getters and setters

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.

Default: TextClass::Label(true)

pub fn font(&self) -> FontId

Get the default font

pub fn set_font(&mut self, font_id: FontId)

Set the default FontId

This is derived from the TextClass by ConfigCx::text_configure.

This font_id is used by all unformatted texts and by any formatted texts which don’t immediately set formatting.

It is necessary to prepare the text after calling this.

pub fn font_size(&self) -> f32

Get the default font size (pixels)

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

Set the default font size (pixels)

This is derived from the TextClass by ConfigCx::text_configure.

This is a scaling factor used to convert font sizes, with units pixels/Em. Equivalently, this is the line-height in pixels. See crate::text::fonts documentation.

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

It is necessary to prepare the text after calling this.

pub fn bounds(&self) -> Vec2

Get text bounds

pub fn set_bounds(&mut self, bounds: Vec2)

Set text bounds

These are used for alignment and line-wrapping.

It is expected that bounds are finite.

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 + ?Sized> 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 configure(&mut self) -> Result<(), InvalidFontId>

Configure text

Text objects must be configured before use.

pub fn line_height(&self) -> Result<f32, NotReady>

Returns the height of horizontal text

Returns an error if called before Self::configure.

This depends on the font and font size, but is independent of the text.

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

Measure required width, up to some max_width

configure must be called before this method.

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) -> Result<f32, NotReady>

Measure required vertical height

configure must be called before this method. May partially prepare the text for display, but does not otherwise modify self.

pub fn prepare(&mut self) -> Result<bool, NotReady>

Prepare text for display, as necessary

Self::configure and Self::set_bounds 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 given bounds.

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

pub fn reprepare_action(&mut self) -> Action

Re-prepare, if previously prepared, and return an Action

Wraps Text::prepare, returning an appropriate Action:

• When this Text object was previously prepared and has sufficient bounds, it is updated and Action::REDRAW is returned
• When this Text object was previously prepared but does not have sufficient bounds, it is updated and Action::RESIZE is returned
• When this Text object was not previously prepared, Action::empty() is returned without updating self.

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

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 input bounds 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 find_line( &self, index: usize, ) -> Result<Option<(usize, Range<usize>)>, NotReady>

Find the line containing text index

See TextDisplay::find_line.

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

Get the range of a line, by line number

See TextDisplay::line_range.

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.

pub fn glyphs<F: FnMut(FaceId, f32, Glyph)>(&self, f: F) -> Result<(), NotReady>

Yield a sequence of positioned glyphs

See TextDisplay::glyphs.

pub fn glyphs_with_effects<X, F, G>( &self, effects: &[Effect<X>], default_aux: X, f: F, g: G, ) -> Result<(), NotReady>

where X: Copy, F: FnMut(FaceId, f32, Glyph, usize, X), G: FnMut(f32, f32, f32, f32, usize, X),

Like TextDisplay::glyphs but with added effects

See TextDisplay::glyphs_with_effects.

pub fn highlight_range<F>( &self, range: Range<usize>, f: F, ) -> Result<(), NotReady>

where F: FnMut(Vec2, Vec2),

Yield a sequence of rectangles to highlight a given text range

Calls f(top_left, bottom_right) for each highlighting rectangle.

impl<T: EditableText + ?Sized> Text<T>

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.

Formatting is adjusted: any specifiers starting at or after index are delayed by the length of c.

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.

Formatting is adjusted: any specifiers within the replaced text are pushed back to the end of the replacement, and the position of any specifiers after the replaced section is adjusted as appropriate.

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

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

Set text to a raw String

One must call Text::prepare afterwards.

All existing text formatting is removed.

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.

All existing text formatting is removed.

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

Trait Implementations

impl<T: Clone + FormattableText + ?Sized> 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 + ?Sized> Debug for Text<T>

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<T: FormattableText + ?Sized> SizableText for Text<T>

fn set_font(&mut self, font_id: FontId, dpem: f32)

Set font face and size

fn configure(&mut self) -> Result<(), InvalidFontId>

Configure text

fn measure_width(&mut self, max_width: f32) -> Result<f32, NotReady>

Measure required width, up to some max_width

fn measure_height(&mut self, wrap_width: f32) -> Result<f32, NotReady>

Measure required vertical height, wrapping as configured