Trait kas::text::TextApi

pub trait TextApi {
    // Required methods
    fn as_str(&self) -> &str;
    fn clone_string(&self) -> String;
    fn env(&self) -> Environment;
    fn set_env(&mut self, env: Environment);
    fn display(&self) -> &TextDisplay;
    fn require_action(&mut self, action: Action);
    fn prepare_runs(&mut self) -> Result<(), InvalidFontId>;
    fn measure_width(&mut self, limit: f32) -> Result<f32, InvalidFontId>;
    fn measure_height(&mut self) -> Result<f32, InvalidFontId>;
    fn prepare(&mut self) -> Result<bool, InvalidFontId>;
    fn effect_tokens(&self) -> &[Effect<()>];

    // Provided method
    fn str_len(&self) -> usize { ... }
}

Expand description

Trait over a sub-set of Text functionality

This allows dynamic dispatch over Text’s type parameters.

Required Methods§

fn as_str(&self) -> &str

Access whole text as contiguous str

It is valid to reference text within the range 0..text_len(), even if not all text within this range will be displayed (due to runs).

fn clone_string(&self) -> String

Clone the unformatted text as a String

fn env(&self) -> Environment

Read the environment

fn set_env(&mut self, env: Environment)

Set the environment

Use of this method may require new preparation actions. Call TextApiExt::update_env instead to perform such actions with a single method call.

fn display(&self) -> &TextDisplay

Read the TextDisplay

fn require_action(&mut self, action: Action)

Require an action

See TextDisplay::require_action.

fn prepare_runs(&mut self) -> Result<(), InvalidFontId>

Prepare text runs

Wraps TextDisplay::prepare_runs, passing parameters from the environment state.

fn measure_width(&mut self, limit: f32) -> Result<f32, InvalidFontId>

Measure required width, up to some limit

This calls Self::prepare_runs where necessary, but does not fully prepare text for display. It is a significantly faster way to calculate the required line length than by fully preparing text.

The return value is at most limit and is unaffected by alignment and wrap configuration of Environment.

fn measure_height(&mut self) -> Result<f32, InvalidFontId>

Measure required vertical height, wrapping as configured

This partially prepares text for display. Remaining prepartion should be fast.

fn prepare(&mut self) -> Result<bool, InvalidFontId>

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.

Returns true if at least some action is performed and the text exceeds the allocated bounds (Environment::bounds).

fn effect_tokens(&self) -> &[Effect<()>]

Get the sequence of effect tokens

This method has some limitations: (1) it may only return a reference to an existing sequence, (2) effect tokens cannot be generated dependent on input state, and (3) it does not incorporate color information. For most uses it should still be sufficient, but for other cases it may be preferable not to use this method (use a dummy implementation returning &[] and use inherent methods on the text object via Text::text).

Provided Methods§

fn str_len(&self) -> usize

Length of text

This is a shortcut to self.as_str().len().