[−][src]Trait piet::TextLayout
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).
When resizing the width of the text layout, calling update_width
on the text layout will
recalculate line breaks and modify in-place.
A line's text and LineMetric
s can be accessed line-by-line by 0-indexed line number.
Fields on ['LineMetric`] include:
- line start offset from text layout beginning (in UTF-8 code units)
- line end offset from text layout beginning (in UTF-8 code units)
- line trailing whitespace (in UTF-8 code units)
- line's baseline, distance of the baseline from the top of the line
- line height
The trailing whitespace distinction is important. Lines are broken at the grapheme boundary after whitespace, but that whitepace is not necessarily rendered since it's just the trailing whitepace at the end of a line. Keeping the trailing whitespace data available allows API consumers to determine their own trailing whitespace strategy.
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.
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 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.
fn text(&self) -> &str
The text used to create this layout.
fn update_width(
&mut self,
new_width: impl Into<Option<f64>>
) -> Result<(), Error>
&mut self,
new_width: impl Into<Option<f64>>
) -> Result<(), Error>
Change the width of this TextLayout
.
This may be an f64
, or None
if this layout is not constrained;
None
is equivalent to std::f64::INFINITY
.
fn line_text(&self, line_number: usize) -> Option<&str>
Given a line number, return a reference to that line's underlying string.
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.
fn hit_test_point(&self, point: Point) -> HitTestPoint
Given a Point
, determine 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.
Return value:
Returns a HitTestPoint
describing the results of the test.
The HitTestPoint
field is_inside
is true if the tested point
falls within the bounds of the text, false
otherwise.
The HitTestPoint
field idx
is the index, in the string used to
create this TextLayout
, of the start of the grapheme cluster
closest to the tested point.
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.
Panics:
This method will panic if the text position is not a character boundary,
Provided methods
fn width(&self) -> f64
Use size().width insead
Measure the advance width of the text.
fn rects_for_range(&self, range: impl RangeBounds<usize>) -> Vec<Rect>
Returns a vector of Rect
s 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.