Struct masonry::text2::TextLayout

pub struct TextLayout<T> { /* private fields */ }

A component for displaying text on screen.

This is a type intended to be used by other widgets that display text. It allows for the text itself as well as font and other styling information to be set and modified. It wraps an inner layout object, and handles invalidating and rebuilding it as required.

This object is not valid until the rebuild_if_needed method has been called. You should generally do this in your widget’s layout method. Additionally, you should call needs_rebuild_after_update as part of your widget’s update method; if this returns true, you will need to call rebuild_if_needed again, generally by scheduling another layout pass.

TODO: Update docs to mentionParley

Implementations

impl<T> TextLayout<T>

pub fn new(text: T, text_size: f32) -> Self

Create a new TextLayout object.

pub fn invalidate(&mut self)

Mark that the inner layout needs to be updated.

This should be used if your T has interior mutability

pub fn set_scale(&mut self, scale: f32)

Set the scaling factor

pub fn set_brush(&mut self, brush: impl Into<TextBrush>)

Set the default brush used for the layout.

This is the non-layout impacting styling (primarily colour) used when displaying the text

pub fn set_font(&mut self, font: FontStack<'static>)

Set the default font stack.

pub fn set_text_size(&mut self, size: f32)

Set the font size.

pub fn set_weight(&mut self, weight: Weight)

Set the font weight.

pub fn set_style(&mut self, style: Style)

Set the font style.

pub fn set_text_alignment(&mut self, alignment: Alignment)

Set the Alignment for this layout.

pub fn set_max_advance(&mut self, max_advance: Option<f32>)

Set the width at which to wrap words.

You may pass None to disable word wrapping (the default behaviour).

pub fn needs_rebuild(&self) -> bool

Returns true if this layout needs to be rebuilt.

This happens (for instance) after style attributes are modified.

This does not account for things like the text changing, handling that is the responsibility of the user.

impl<T: TextStorage> TextLayout<T>

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

Set the text to display.

pub fn text(&self) -> &T

Returns the TextStorage backing this layout, if it exists.

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

Returns the TextStorage backing this layout, if it exists.

Invalidates the layout and so should only be used when definitely applying an edit

pub fn layout(&self) -> &Layout<TextBrush>

Returns the inner Parley Layout value.

pub fn size(&self) -> Size

The size of the laid-out text, excluding any trailing whitespace.

This is not meaningful until Self::rebuild has been called.

pub fn full_size(&self) -> Size

The size of the laid-out text, including any trailing whitespace.

This is not meaningful until Self::rebuild has been called.

pub fn layout_metrics(&self) -> LayoutMetrics

Return the text’s LayoutMetrics.

This is not meaningful until Self::rebuild has been called.

pub fn cursor_for_point(&self, point: Point) -> Cursor

For a given Point (relative to this object’s origin), returns index into the underlying text of the nearest grapheme boundary.

This is not meaningful until Self::rebuild has been called.

pub fn cursor_for_text_position(&self, text_pos: usize) -> Cursor

Given the utf-8 position of a character boundary in the underlying text, return the Point (relative to this object’s origin) representing the boundary of the containing grapheme.

Panics

Panics if text_pos is not a character boundary.

This is not meaningful until Self::rebuild has been called.

pub fn point_for_text_position(&self, text_pos: usize) -> Point

Given the utf-8 position of a character boundary in the underlying text, return the Point (relative to this object’s origin) representing the boundary of the containing grapheme.

Panics

Panics if text_pos is not a character boundary.

This is not meaningful until Self::rebuild has been called.

pub fn cursor_line_for_text_position(&self, text_pos: usize) -> Line

Given the utf-8 position of a character boundary in the underlying text, return a Line suitable for drawing a vertical cursor at that boundary.

This is not meaningful until Self::rebuild has been called.

pub fn link_for_pos(&self, pos: Point) -> Option<&Link>

Returns the Link at the provided point (relative to the layout’s origin) if one exists.

This can be used both for hit-testing (deciding whether to change the mouse cursor, or performing some other action when hovering) as well as for retrieving a Link on click.

pub fn rebuild(&mut self, fcx: &mut FontContext)

Rebuild the inner layout as needed.

This TextLayout object manages a lower-level layout object that may need to be rebuilt in response to changes to the text or attributes like the font.

This method should be called whenever any of these things may have changed. A simple way to ensure this is correct is to always call this method as part of your widget’s layout method.

pub fn rebuild_with_attributes( &mut self, fcx: &mut FontContext, attributes: impl for<'b> FnOnce(RangedBuilder<'b, TextBrush, &'b str>) -> RangedBuilder<'b, TextBrush, &'b str> )

Rebuild the inner layout as needed, adding attributes to the underlying layout.

See Self::rebuild for more information

pub fn draw(&mut self, scene: &mut Scene, point: impl Into<Point>)

Draw the layout at the provided Point.

The origin of the layout is the top-left corner.

You must call Self::rebuild at some point before you first call this method.

Trait Implementations

impl<T: Clone> Clone for TextLayout<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: TextStorage> Debug for TextLayout<T>

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

Formats the value using the given formatter.

impl<T: TextStorage + Default> Default for TextLayout<T>

fn default() -> Self

Returns the “default value” for a type.