API reference

aster_blueprint::text_wrap

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Line breaking for multi-line text, on top of any [TextMeasure].

Greedy word wrap at spaces using real measured widths (a candidate line is measured as a whole, so kerning is honoured), explicit '\n' always breaks, a word wider than the line is broken between characters as a fallback, and max_lines truncates with an ellipsis on the last line. Deterministic and allocation-light; measurements go through the measurer's own cache.

Two opt-in layers sit on that classic wrap: the break opportunities and the way the breaks are placed.

  • [WrapRules::Unicode] adds the break opportunities of a pragmatic UAX #14 subset: after hyphens and dashes, after the slashes of a URL or a path, at every CJK boundary (never before a closing punctuation), at a zero width space, and at a soft hyphen (the line then shows a hyphen). A no break space and a word joiner are non-breaks.
  • [WrapMode::Balance] re-breaks a paragraph into lines of near-equal width (the narrowest width that keeps the line count), and [WrapMode::Pretty] re-breaks the tail of a paragraph so the last line is not a short orphan (a small Knuth-Plass-style cost, bounded).

The default ([WrapRules::Ascii] + [WrapMode::Greedy]) is the classic greedy wrap, byte for byte.

The breaker asks a width source (the trait LineWidth), so a rich paragraph (several faces, sizes and colours in one paragraph) breaks exactly like a plain one: the width of a line is the sum of its runs.

Structs

structaster_blueprint::text_wrap::WrapOpts

pub struct WrapOpts { /* see fields */ }

The wrap options of one text node.

Public fields

fieldtype
rulesWrapRulesThe break opportunities the breaker may use.
modeWrapModeHow the breaker places the breaks.

Methods

  • const fn new(rules: WrapRules, mode: WrapMode) -> Self — The options of one mode and one rule set.

Trait implementations: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

Enums

enumaster_blueprint::text_wrap::WrapMode

pub enum WrapMode { Greedy, Balance, Pretty }

How the line breaker places the breaks.

Variants

  • Greedy — Greedy: every line takes as much as fits (the default).
  • Balance — Balance: keep the line count and narrow the lines to the narrowest width that still fits them (for headings and titles).
  • Pretty — Pretty: keep the line count and re-break the tail so the last line is not a short orphan.

Trait implementations: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::text_wrap::WrapRules

pub enum WrapRules { Ascii, Unicode }

Which break opportunities the line breaker may use.

Variants

  • Ascii — ASCII spaces only: the classic greedy wrap (the default).
  • Unicode — A pragmatic subset of UAX #14: after hyphens, en and em dashes, after the slashes of a URL or a path, at every CJK boundary (never before a closing punctuation), at a zero width space (U+200B) and at a soft hyphen (U+00AD, which shows a hyphen when the line breaks there). A no-break space (U+00A0) and a word joiner (U+2060) are non-breaks.

Trait implementations: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

Type aliases

typeaster_blueprint::text_wrap::Line

pub type Line = (String, f64);

A broken line: its text and measured width.

Functions

fnaster_blueprint::text_wrap::break_text

pub fn break_text(tm: &mut dyn TextMeasure, font: &str, size: f64, text: &str, avail: Option<f64>, wrap: bool, max_lines: Option<usize>) -> Result<Vec<Line>, layout::LayoutError>

Break text into lines. avail = content width (None = unconstrained). wrap enables word wrapping (needs avail); '\n' always breaks. max_lines keeps that many lines, ellipsizing the last (and, without wrap, ellipsizing any single line wider than avail). Never empty.

The classic greedy wrap at ASCII spaces; see [break_text_with] for the opt-in rules and modes.

fnaster_blueprint::text_wrap::break_text_bidi

pub fn break_text_bidi(tm: &mut dyn TextMeasure, font: &str, size: f64, text: &str, avail: Option<f64>, wrap: bool, max_lines: Option<usize>, opts: WrapOpts, fallback: layout::Direction) -> Result<(Vec<Line>, Vec<layout::Direction>), layout::LayoutError>

Break text into lines like [break_text_with_dir], but every \n paragraph reads in the direction of its own first strong character (UAX #9 P1-P3; fallback when it has none). Returns the lines and the base direction of the paragraph each line belongs to.

fnaster_blueprint::text_wrap::break_text_with

pub fn break_text_with(tm: &mut dyn TextMeasure, font: &str, size: f64, text: &str, avail: Option<f64>, wrap: bool, max_lines: Option<usize>, opts: WrapOpts) -> Result<Vec<Line>, layout::LayoutError>

Break text into lines, with the given wrap options.

opts.rules picks the break opportunities ([WrapRules]) and opts.mode picks how the breaks are placed ([WrapMode]). The default options give the classic greedy wrap at ASCII spaces.

fnaster_blueprint::text_wrap::break_text_with_dir

pub fn break_text_with_dir(tm: &mut dyn TextMeasure, font: &str, size: f64, text: &str, avail: Option<f64>, wrap: bool, max_lines: Option<usize>, opts: WrapOpts, dir: layout::Direction) -> Result<Vec<Line>, layout::LayoutError>

Break text into lines, with the given wrap options and reading direction.

dir is the direction the text is read in: a right-to-left line is measured with a right-to-left base direction (the same lines, the same breaks).

fnaster_blueprint::text_wrap::min_content_width

pub fn min_content_width(tm: &mut dyn TextMeasure, font: &str, size: f64, text: &str, opts: WrapOpts, dir: layout::Direction) -> Result<f64, layout::LayoutError>

The min-content width of text: the widest unbreakable piece between two break opportunities of its paragraphs (a long word, an unbroken URL, a soft-hyphen part), measured as a line would show it. A wrapped text laid out narrower than this has to break inside a word.

Constants

constaster_blueprint::text_wrap::ELLIPSIS

pub const ELLIPSIS: &str

Ellipsis appended to a truncated last line.