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

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 Self::set_rect
• Draw by calling DrawCx::text (and/or other text methods)

The size according to Self::rect may be adjusted to that of the text; see Self::set_align.

Implementations

impl<T: FormattableText> Text<T>

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)

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

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.

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.

Default: TextClass::Label(true)

pub fn font(&self) -> FontSelector

Get the default font

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

Set the default FontSelector

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

This font 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

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) -> f32

Measure required vertical height

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) -> 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 size, it is updated and Action::REDRAW is returned
• When this Text object was previously prepared but does not have sufficient size, 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 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 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.

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 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_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: Default + FormattableText> Default for Text<T>

fn default() -> Self

Returns the “default value” for a type.

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, sizer: SizeCx<'_>, axis: AxisInfo) -> SizeRules

Get size rules for the given axis

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

Set size and position

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

Draw a widget and its children

fn try_probe(&self, coord: Coord) -> Option<Id>

Probe a coordinate for a widget’s Id

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

fn set_font(&mut self, font: FontSelector, dpem: f32)

Set font face and size

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

Measure required width, up to some max_width

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

Measure required vertical height, wrapping as configured