Trait piet::TextLayout

pub trait TextLayout: Clone {
    fn size(&self) -> Size;
    fn trailing_whitespace_width(&self) -> f64;
    fn image_bounds(&self) -> Rect;
    fn text(&self) -> &str;
    fn line_text(&self, line_number: usize) -> Option<&str>;
    fn line_metric(&self, line_number: usize) -> Option<LineMetric>;
    fn line_count(&self) -> usize;
    fn hit_test_point(&self, point: Point) -> HitTestPoint;
    fn hit_test_text_position(&self, idx: usize) -> HitTestPosition;

    fn rects_for_range(&self, range: impl RangeBounds<usize>) -> Vec<Rect> { ... }
}

A drawable text object.

Line Breaks

A text layout may be broken into multiple lines in order to fit within a given width. Line breaking is generally done between words (whitespace-separated).

A line’s text and LineMetrics can be accessed by 0-indexed line number.

Text Position

A text position is the offset in the underlying string, defined in utf-8 code units, as is standard for Rust strings.

However, text position is also related to valid cursor positions. Therefore:

• The beginning of a line has text position 0.
• The end of a line is a valid text position. e.g. text.len() is a valid text position.
• If the text position is not at a code point or grapheme boundary, undesirable behavior may occur.

Required methods

fn size(&self) -> Size

The total size of this TextLayout.

This is the size required to draw this TextLayout, as provided by the platform text system.

If the layout is empty (the text is the empty string) the returned Size will have the height required to draw a cursor in the layout’s default font.

Note

This is not currently defined very rigorously; in particular we do not specify whether this should include half-leading or paragraph spacing above or below the text.

We would ultimately like to review and attempt to standardize this behaviour, but it is out of scope for the time being.

fn trailing_whitespace_width(&self) -> f64

The width of this layout, including the width of any trailing whitespace.

In many situations you do not want to include the width of trailing whitespace when measuring width; for instance when word-wrap is enabled, trailing whitespace is ignored. In other circumstances, however, this width is important, such as when editing a single line of text; in these cases you want to use this method to ensure you account for the actual size of any trailing whitespace.

fn image_bounds(&self) -> Rect

Returns a Rect representing the bounding box of the glyphs in this layout, relative to the top-left of the layout object.

This is sometimes called the bounding box or the inking rect, and is used to determine when the layout has become visible (for instance, during scrolling) and thus needs to be drawn.

fn text(&self) -> &str

The text used to create this layout.

fn line_text(&self, line_number: usize) -> Option<&str>

Given a line number, return a reference to that line’s underlying string.

This will include any trailing whitespace.

fn line_metric(&self, line_number: usize) -> Option<LineMetric>

Given a line number, return a reference to that line’s metrics, if the line exists.

If this layout’s text is the empty string, calling this method with 0 returns some LineMetric; this will use the layout’s default font to determine what the expected height of the first line would be, which is necessary for things like cursor drawing.

fn line_count(&self) -> usize

Returns total number of lines in the text layout.

The return value will always be greater than 0; a layout of the empty string is considered to have a single line.

fn hit_test_point(&self, point: Point) -> HitTestPoint

Given a Point, return a HitTestPoint describing the corresponding text position.

This is used for things like mapping a mouse click to a cursor position.

The point should be in the coordinate space of the layout object.

Notes:

This will always return some text position. If the point is outside of the bounds of the layout, it will return the nearest text position.

For more on text positions, see docs for the TextLayout trait.

fn hit_test_text_position(&self, idx: usize) -> HitTestPosition

Given a grapheme boundary in the string used to create this TextLayout, return a HitTestPosition object describing the location of that boundary within the layout.

For more on text positions, see docs for the TextLayout trait.

Notes:

The user is expected to ensure that the provided index is a grapheme boundary. If it is a character boundary but not a grapheme boundary, the return value may be backend-specific.

Panics:

This method will panic if the text position is not a character boundary,

Provided methods

fn rects_for_range(&self, range: impl RangeBounds<usize>) -> Vec<Rect>

Returns a vector of Rects that cover the region of the text indicated by range.

The returned rectangles are suitable for things like drawing selection regions or highlights.

range will be clamped to the length of the text if necessary.

Note: this implementation is not currently BiDi aware; it will be updated when BiDi support is added.

Implementors