[−][src]Trait piet_common::TextLayout
Text Layout
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
- cumulative line height (includes previous line heights)
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 width(&self) -> f64
Measure the advance width of the text.
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.
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.
Return value:
Returns a HitTestPoint
describing the results of the test.
HitTestPoint
field is_inside
is true if the tested point falls within the bounds of the text, false
otherwise.
HitTestPoint
field metrics
is a HitTestMetrics
struct. HitTestMetrics
field text_position
is the text
position closest to the tested point.
Notes:
Some text position will always be returned; if the tested point is inside, it returns the appropriate text
position; if it's outside, it will return the nearest text position (either 0
or text.len()
).
For more on text positions, see docs for the TextLayout
trait.
fn hit_test_text_position(
&self,
text_position: usize
) -> Option<HitTestTextPosition>
&self,
text_position: usize
) -> Option<HitTestTextPosition>
Given a text position, determine the corresponding pixel location. (currently consider the text layout just one line)
Return value:
Returns a HitTestTextPosition
describing the results of the test.
HitTestTextPosition
field point
is the point offset of the boundary of the
grapheme cluster that the text position is a part of.
HitTestTextPosition
field metrics
is a HitTestMetrics
struct. HitTestMetrics
field text_position
is the original text position (unless out of bounds).
Notes:
In directwrite, if a text position is not at code point boundary, this method will panic. Cairo and web are more lenient and may not panic.
For text position that is greater than text.len()
, web/cairo will return the
HitTestTextPosition
as if text_position == text.len()
. In directwrite, the method will
panic, as the text position is out of bounds.
For more on text positions, see docs for the TextLayout
trait.
Implementations on Foreign Types
impl TextLayout for CairoTextLayout
[src]
fn width(&self) -> f64
[src]
fn update_width(
&mut self,
new_width: impl Into<Option<f64>>
) -> Result<(), Error>
[src]
&mut self,
new_width: impl Into<Option<f64>>
) -> Result<(), Error>
fn line_text(&self, line_number: usize) -> Option<&str>
[src]
fn line_metric(&self, line_number: usize) -> Option<LineMetric>
[src]
fn line_count(&self) -> usize
[src]
fn hit_test_point(&self, point: Point) -> HitTestPoint
[src]
fn hit_test_text_position(
&self,
text_position: usize
) -> Option<HitTestTextPosition>
[src]
&self,
text_position: usize
) -> Option<HitTestTextPosition>