Struct kas_text::TextDisplay

pub struct TextDisplay { /* private fields */ }

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

pub fn text_glyph_pos(&self, index: usize) -> MarkerPosIter

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

Get the number of glyphs

This method is a simple memory-read.

pub fn glyphs<F: FnMut(FaceId, f32, Glyph)>(&self, f: F)

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. The closure f receives parameters face_id, dpem, glyph.

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(|_, dpem, glyph| glyphs.push((dpem, 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>],
    default_aux: X,
    f: F,
    g: G
) where
    X: Copy,
    F: FnMut(FaceId, f32, Glyph, usize, X),
    G: FnMut(f32, f32, f32, f32, usize, X), 

Like TextDisplay::glyphs but with added effects

If the list effects is empty or has first entry with start > 0, the result of Effect::default(default_aux) is used. The user payload of type X is simply passed through to f and g calls and may be useful for color information.

The callback f receives face_id, dpem, 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/strike-through 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)>

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)>

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

pub fn resize_runs<F: FormattableText>(
    &mut self,
    text: &F,
    dpp: f32,
    pt_size: f32
)

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: FormattableText>(
    &mut self,
    text: &F,
    bidi: bool,
    dir: Direction,
    font_id: FontId,
    dpp: f32,
    pt_size: f32
)

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

pub fn prepare_lines(
    &mut self,
    bounds: Vec2,
    flags: EnvFlags,
    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

pub fn required_action(&self) -> Action

Get required action

pub fn require_action(&mut self, action: Action)

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: FormattableText>(
    &mut self,
    text: &F,
    env: &Environment
) -> Option<Vec2>

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.

Returns new size requirements, if an update action occurred. Returns None if no action was required (since requirements are computed as a side-effect of line-wrapping, and presumably in this case the existing allocation is sufficient). One may force calculation of this value by calling text.require_action(Action::Wrap).

pub fn num_lines(&self) -> usize

Get the number of lines

pub fn find_line(&self, index: usize) -> Option<(usize, Range<usize>)>

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>>

Get the range of a line, by line number

pub fn line_is_ltr(&self, line: usize) -> bool

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

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

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>

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: FormattableText> AsMut<TextDisplay> for Text<T>

fn as_mut(&mut self) -> &mut TextDisplay

Performs the conversion.

impl<T: FormattableText> AsRef<TextDisplay> for Text<T>

fn as_ref(&self) -> &TextDisplay

Performs the conversion.

impl Clone for TextDisplay

fn clone(&self) -> TextDisplay

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TextDisplay

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

Formats the value using the given formatter.

impl Default for TextDisplay

fn default() -> Self

Returns the “default value” for a type.