[−][src]Struct kas::text::TextDisplay
Text display, without source text representation
In general, it is recommended to use crate::Text
instead, which includes
a representation of the source text and environment state.
Once prepared (via TextDisplay::prepare
), this struct contains
everything needed to display text, query glyph position and size
requirements, and even re-wrap text lines. It cannot, however, support
editing or cloning the source text.
This struct tracks its state of preparation and can be default-constructed in an unprepared state with no text.
Text navigation
Despite lacking a copy of the underlying text, text-indices may be mapped to glyphs and lines, and vice-versa.
The text range is 0..self.text_len()
. Any index within this range
(inclusive of end point) is valid for usage in all methods taking an index.
Multiple indices may map to the same glyph (e.g. within multi-byte chars,
with combining-diacritics, and with ligatures). In some cases a single index
corresponds to multiple glyph positions (due to line-wrapping or change of
direction in bi-directional text).
Navigating to the start or end of a line can be done with
TextDisplay::find_line
and TextDisplay::line_range
.
Navigating left or right should be done via a library such as
unicode-segmentation
which provides a
GraphemeCursor
to step back or forward one "grapheme", in logical order. Navigating glyphs
in display-order is not currently supported. Optionally, the direction may
be reversed for right-to-left lines TextDisplay::line_is_rtl
, but note
that the result may be confusing since not all text on the line follows the
line's base direction and adjacent lines may have different directions.
To navigate "up" and "down" lines, use TextDisplay::text_glyph_pos
to
get the position of the cursor, TextDisplay::find_line
to get the line
number, then TextDisplay::line_index_nearest
to find the new index.
Implementations
impl TextDisplay
[src]
pub fn text_glyph_pos(&self, index: usize) -> MarkerPosIterⓘNotable traits for MarkerPosIter
impl Iterator for MarkerPosIter type Item = MarkerPos;
[src]
Notable traits for MarkerPosIter
impl Iterator for MarkerPosIter type Item = MarkerPos;
Find the starting position (top-left) of the glyph at the given index
The index should be no greater than the text length. It is not required to be on a code-point boundary. Returns an iterator over matching positions. Length of results is guaranteed to be one of 0, 1 or 2:
- 0 if the index is not included in any run of text (probably only possible within a multi-byte line break or beyond the text length)
- 1 is the normal case
- 2 if the index is at the end of one run of text and at the start
of another; these positions may be the same or may not be (over
line breaks and with bidirectional text). If only a single position
is desired, usually the latter is preferred (via
next_back()
).
Note: if the text's bounding rect does not start at the origin, then
the coordinates of the top-left corner should be added to the result(s).
The result is also not guaranteed to be within the expected window
between 0 and self.env().bounds
. The user should clamp the result.
pub fn num_glyphs(&self) -> usize
[src]
Get the number of glyphs
This method is a simple memory-read.
pub fn glyphs<F>(&self, f: F) where
F: FnMut(FontId, f32, f32, Glyph),
[src]
F: FnMut(FontId, f32, f32, Glyph),
Yield a sequence of positioned glyphs
Glyphs are yielded in undefined order by a call to f
. The number of
glyphs yielded will equal TextDisplay::num_glyphs
. This may be used as
follows:
let mut text = Text::new_single("Some example text"); text.prepare(); let mut glyphs = Vec::with_capacity(text.num_glyphs()); text.glyphs(|_, _, height, glyph| glyphs.push((height, glyph))); draw(glyphs);
This method has fairly low cost: O(n)
in the number of glyphs with
low overhead.
One must call TextDisplay::prepare
before this method.
pub fn glyphs_with_effects<X, F, G>(&self, effects: &[Effect<X>], f: F, g: G) where
F: FnMut(FontId, f32, f32, Glyph, usize, X),
G: FnMut(f32, f32, f32, f32, usize, X),
X: Copy + Default,
[src]
F: FnMut(FontId, f32, f32, Glyph, usize, X),
G: FnMut(f32, f32, f32, f32, usize, X),
X: Copy + Default,
Like TextDisplay::glyphs
but with added effects
If the list effects
is empty or has have first entry with start > 0
,
a default-constructed Effect<X>
token is used.
The user payload X
is simply passed
through to f
and g
calls and may be useful for colour information.
The callback f
receives font_id, dpu, height, glyph, i, aux
where
dpu
and height
are both measures of the font size (pixels per font
unit and pixels per height, respectively), and i
is the index within
effects
(or usize::MAX
when a default-constructed effect token is
used).
The callback g
receives positioning for each underline/strikethrough
segment: x1, x2, y_top, h
where h
is the thickness (height). Note
that it is possible to have h < 1.0
and y_top, y_top + h
to round to
the same number; the renderer is responsible for ensuring such lines
are actually visible. The last parameters are i, aux
as for f
.
Note: this is significantly more computationally expensive than
TextDisplay::glyphs
. Optionally one may choose to cache the result,
though this is not really necessary.
pub fn highlight_lines(&self, range: Range<usize>) -> Vec<(Vec2, Vec2), Global>
[src]
Yield a sequence of rectangles to highlight a given range, by lines
Rectangles span to end and beginning of lines when wrapping lines. (Note: gaps are possible between runs in the first and last lines. This is a defect which should be fixed but low priority and trickier than it might seem due to bi-directional text allowing re-ordering of runs.)
This locates the ends of a range as with TextDisplay::text_glyph_pos
, but
yields a separate rect for each "run" within this range (where "run" is
a line or part of a line). Rects are represented by the top-left
vertex and the bottom-right vertex.
Note: if the text's bounding rect does not start at the origin, then
the coordinates of the top-left corner should be added to the result(s).
The result is also not guaranteed to be within the expected window
between 0 and self.env().bounds
. The user should clamp the result.
pub fn highlight_runs(&self, range: Range<usize>) -> Vec<(Vec2, Vec2), Global>
[src]
Yield a sequence of rectangles to highlight a given range, by runs
Rectangles tightly fit each "run" (piece) of text highlighted. (As an artifact, the highlighting may leave gaps between runs. This may or may not change in the future.)
This locates the ends of a range as with TextDisplay::text_glyph_pos
, but
yields a separate rect for each "run" within this range (where "run" is
is a line or part of a line). Rects are represented by the top-left
vertex and the bottom-right vertex.
Note: if the text's bounding rect does not start at the origin, then
the coordinates of the top-left corner should be added to the result(s).
The result is also not guaranteed to be within the expected window
between 0 and self.env().bounds
. The user should clamp the result.
impl TextDisplay
[src]
pub fn resize_runs<F>(&mut self, text: &F, dpp: f32, pt_size: f32) where
F: FormattableText,
[src]
F: FormattableText,
Update font size
This updates the result of TextDisplay::prepare_runs
due to change
in font size.
Prerequisites: prepared runs: panics if action is greater than Action::Wrap
.
Post-requirements: prepare lines (requires action Action::Wrap
).
Parameters: see crate::Environment
documentation.
pub fn prepare_runs<F>(
&mut self,
text: &F,
bidi: bool,
dir: Direction,
dpp: f32,
pt_size: f32
) where
F: FormattableText,
[src]
&mut self,
text: &F,
bidi: bool,
dir: Direction,
dpp: f32,
pt_size: f32
) where
F: FormattableText,
Prepare text runs
This is the first step of preparation: breaking text into runs according to font properties, bidi-levels and line-wrap points.
Prerequisites: none (ignores current action
state).
Post-requirements: prepare lines (requires action Action::Wrap
).
Parameters: see crate::Environment
documentation.
impl TextDisplay
[src]
pub fn prepare_lines(
&mut self,
bounds: Vec2,
wrap: bool,
align: (Align, Align)
) -> Vec2
[src]
&mut self,
bounds: Vec2,
wrap: bool,
align: (Align, Align)
) -> Vec2
Prepare lines ("wrap")
This does text layout, with wrapping if enabled.
Prerequisites: prepared runs: panics if action is greater than Action::Wrap
.
Post-requirements: none (Action::None
).
Parameters: see crate::Environment
documentation.
Returns: required size, in pixels.
impl TextDisplay
[src]
pub fn required_action(&self) -> Action
[src]
Get required action
pub fn require_action(&mut self, action: Action)
[src]
Require an action
Required actions are tracked internally. This combines internal action
state with that input via max
. It may be used, for example, to mark
that fonts need resizing due to change in environment.
pub fn prepare<F>(&mut self, text: &F, env: &Environment) where
F: FormattableText,
[src]
F: FormattableText,
Prepare text for display, as necessary
Does all preparation steps necessary in order to display or query the layout of this text.
Required preparation actions are tracked internally, but cannot
notice changes in the environment. In case the environment has changed
one should either call TextDisplay::require_action
before this
method or use the TextDisplay::prepare_runs
,
TextDisplay::resize_runs
and TextDisplay::prepare_lines
methods.
pub fn num_lines(&self) -> usize
[src]
Get the number of lines
pub fn find_line(&self, index: usize) -> Option<(usize, Range<usize>)>
[src]
Find the line containing text index
Returns the line number and the text-range of the line.
Returns None
in case index
does not line on or at the end of a line
(which means either that index
is beyond the end of the text or that
index
is within a mult-byte line break).
pub fn line_range(&self, line: usize) -> Option<Range<usize>>
[src]
Get the range of a line, by line number
pub fn line_is_ltr(&self, line: usize) -> bool
[src]
Get the directionality of the current line
Returns true
for left-to-right lines, false
for RTL.
Panics if line >= self.num_lines()
.
pub fn line_is_rtl(&self, line: usize) -> bool
[src]
Get the directionality of the current line
Returns true
for right-to-left lines, false
for LTR.
Panics if line >= self.num_lines()
.
pub fn text_index_nearest(&self, pos: Vec2) -> usize
[src]
Find the text index for the glyph nearest the given pos
This includes the index immediately after the last glyph, thus
result ≤ text.len()
.
Note: if the font's rect does not start at the origin, then its top-left
coordinate should first be subtracted from pos
.
pub fn line_index_nearest(&self, line: usize, x: f32) -> Option<usize>
[src]
Find the text index nearest horizontal-coordinate x
on line
This is similar to TextDisplay::text_index_nearest
, but allows the
line to be specified explicitly. Returns None
only on invalid line
.
Trait Implementations
impl<T> AsMut<TextDisplay> for Text<T> where
T: FormattableText,
[src]
T: FormattableText,
pub fn as_mut(&mut self) -> &mut TextDisplay
[src]
impl<T> AsRef<TextDisplay> for Text<T> where
T: FormattableText,
[src]
T: FormattableText,
pub fn as_ref(&self) -> &TextDisplay
[src]
impl Clone for TextDisplay
[src]
pub fn clone(&self) -> TextDisplay
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl Debug for TextDisplay
[src]
impl Default for TextDisplay
[src]
pub fn default() -> TextDisplay
[src]
Auto Trait Implementations
impl RefUnwindSafe for TextDisplay
impl Send for TextDisplay
impl Sync for TextDisplay
impl Unpin for TextDisplay
impl UnwindSafe for TextDisplay
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,