Struct TextRenderer 

pub struct TextRenderer {
    pub font_system: FontSystem,
    pub swash_cache: SwashCache,
    /* private fields */
}

Fields

font_system: FontSystem

swash_cache: SwashCache

Implementations

impl TextRenderer

pub fn new() -> TextRenderer

pub fn with_font_catalog( catalog: &FontCatalog, ) -> Result<TextRenderer, FontCatalogError>

Errors

Returns the catalog’s packaging error if its manifest or fonts cannot be loaded and validated.

pub fn with_font_system(font_system: FontSystem) -> TextRenderer

pub fn with_browser_font_system(font_system: FontSystem) -> TextRenderer

Construct a renderer over the verified browser startup catalog.

pub fn take_browser_font_demands(&mut self) -> Vec<String>

Drain optional asset names demanded by missing glyphs in authoritative shaping. The host may retry a failed name after later shaping reports it.

pub fn browser_font_failed(&mut self)

A host fetch failed. Clear cached fallback measurements so a later frame that still shapes the affected text can re-report demand.

pub fn install_browser_font( &mut self, name: &str, bytes: Vec<u8>, ) -> Result<bool, FontCatalogError>

Install one verified canonical optional asset and invalidate every cached metric/layout identity before another frame can be drawn.

Errors

Propagates canonical manifest, hash, size, and face validation errors.

pub fn set_text_scale(&mut self, scale: f32)

Set the accessibility text multiplier used by subsequent measurement and paint calls. Callers that custom-draw canvas text must set this from the current theme before layout/painting; the renderer is retained across frames and therefore keeps this value until it is replaced. Invalid values fall back to 1× rather than poisoning the shaping cache with NaN metrics.

pub fn set_ui_face(&mut self, family: &str)

Set the family the generic sans-serif resolves to: the theme’s UI face (crate::tokens::Typography::sans_family). Text that names a role already carries the family; this makes text built on the generic family (inputs, toolkit internals) follow the same face. A family the font system does not have is ignored.

pub fn apply_typography(&mut self, typography: &Typography)

Follow a theme’s type: its UI face (Self::set_ui_face) and its “Always distinguish similar letters” (Self::set_distinct_letters).

pub fn set_distinct_letters(&mut self, on: bool)

Turn the “Always distinguish similar letters” setting on or off: with it on, every look-alike (I, l, 1 and 0, O) is set apart in all text, whatever its kind, where the face has the forms. The theme’s resolved crate::tokens::Typography::distinct_letters.

pub fn distinguishes_letters(&self) -> bool

Whether every look-alike letter is set apart in text drawn now: the setting is on, or a security surface is being drawn.

pub fn security_surface<R>( &mut self, draw: impl FnOnce(&mut TextRenderer) -> R, ) -> R

Lay out or paint a security surface — a permission prompt, a link preview, an invite or join confirmation, identity verification — with every look-alike letter and figure set apart in all its text, prose included, whatever the setting.

pub fn text_scale(&self) -> f32

The effective accessibility text scale used for both measurement and drawing. Custom-drawn app chrome uses this to make its surrounding geometry grow with the shared renderer rather than letting enlarged type collide with fixed-size controls.

pub fn take_shape_stats(&mut self) -> (u64, u64, u128)

Take-and-reset the per-frame shape-cache stats: (hits, misses, nanoseconds_spent_shaping), so each call reports only that frame’s shaping work.

pub fn cache_stats(&self) -> (u64, u64)

Useful for benchmarks asserting “the static-label widgets warmed the cache and subsequent frames are pure hits”.

pub fn bump_generation(&mut self)

Call this when the font set or active locale changes; cosmic-text will shape glyphs differently after either swap, so stale numbers would let widgets compute wrong layouts.

pub fn measure( &mut self, text: &str, size: f32, max_width: Option<f32>, ) -> (f32, f32)

pub fn measure_weighted( &mut self, text: &str, size: f32, max_width: Option<f32>, weight: TextWeight, ) -> (f32, f32)

Same as TextRenderer::measure but respects a typographic weight. Heavier weights generally advance wider, so measurements must use the same weight the draw path will render with.

pub fn measure_style( &mut self, text: &str, max_width: Option<f32>, style: &TextStyle, ) -> (f32, f32)

Measure using one authoritative style value. This is the preferred API for new widgets because the same value can be passed to Self::draw_style, preventing measurement/paint metric drift.

pub fn measure_prepared( &mut self, text: &PreparedText, max_width: Option<f32>, ) -> (f32, f32)

Measure retained immutable input without hashing its text/style again.

pub fn elide_to_width( &mut self, text: &str, size: f32, max_width: f32, ) -> String

Truncate text to fit within max_width on a single line, appending ELLIPSIS when anything was dropped; returns just the ellipsis when not even one character fits before it, and an empty string for empty text or a non-positive width. Measures with TextWeight::Regular; pair with Self::elide_to_width_weighted or Self::elide_to_width_style when the draw style differs.

pub fn elide_to_width_weighted( &mut self, text: &str, size: f32, max_width: f32, weight: TextWeight, ) -> String

Weighted variant of Self::elide_to_width — measures with the supplied TextWeight so the fit matches a bold/medium draw call.

pub fn elide_to_width_style( &mut self, text: &str, max_width: f32, style: &TextStyle, ) -> String

Self::elide_to_width measured with a full TextStyle — the family (monospace), italic and weight the text will be drawn with.

Cuts only between grapheme clusters, so a combining mark, an emoji sequence or a flag is never split, and drops whitespace before the ellipsis so it never reads as " …". The kept prefix is the longest whose shaped width including the ellipsis fits, found by binary search, so a long label costs a handful of measures rather than one per character.

pub fn clamp_to_lines( &mut self, text: &str, style: &TextStyle, max_width: f32, max_lines: usize, ) -> Vec<String>

Word-wraps text in style to max_width and clamps to at most max_lines lines, eliding the last kept line when content overflows. Draw each returned line in the same style, one TextStyle::line_height_px apart. max_lines == 1 degenerates to Self::elide_to_width_style.

pub fn clamp_to_lines_style( &mut self, text: &str, max_width: f32, max_lines: usize, style: &TextStyle, ) -> Vec<String>

Style-aware line clamping. Wrapping and the final truncation marker use the same font, weight and features as the text that will be drawn.

pub fn draw_text( &mut self, scene: &mut Scene, text: &str, size: f32, color: AlphaColor<Srgb>, transform: Affine, max_width: Option<f32>, )

pub fn measure_font( &mut self, text: &str, size: f32, max_width: Option<f32>, weight: TextWeight, italic: bool, family: &FontChoice, ) -> (f32, f32)

Measure text shaped in an explicit FontChoice.

pub fn system_families(&self) -> Vec<String>

Distinct family names of installed faces, sorted and de-duplicated across weights/styles — the pool an app’s font picker offers.

pub fn measure_styled( &mut self, text: &str, size: f32, max_width: Option<f32>, weight: TextWeight, italic: bool, monospace: bool, ) -> (f32, f32)

Measure text with style attributes and an optional monospace family. NOT cached — these calls are rare (one per segment per frame).

pub fn draw_text_weighted( &mut self, scene: &mut Scene, text: &str, size: f32, color: AlphaColor<Srgb>, transform: Affine, max_width: Option<f32>, weight: TextWeight, )

Same as TextRenderer::draw_text but takes an explicit typographic TextWeight, for chrome labels that need to lift off the body.

pub fn draw_style( &mut self, scene: &mut Scene, text: &str, color: AlphaColor<Srgb>, transform: Affine, max_width: Option<f32>, style: &TextStyle, )

Shape and paint with one authoritative style value. Pair this with Self::measure_style so font metrics, wrapping, and glyph placement cannot silently diverge.

pub fn first_baseline_style( &mut self, text: &str, max_width: Option<f32>, style: &TextStyle, ) -> f32

How far below the origin Self::draw_style, given the same arguments, puts the first line’s baseline: what places text by its baseline rather than its line box.

pub fn draw_prepared( &mut self, scene: &mut Scene, text: &PreparedText, color: AlphaColor<Srgb>, transform: Affine, max_width: Option<f32>, )

Draw retained immutable input; colour and transform do not affect geometry identity.

pub fn glyph_outlines( &mut self, text: &str, max_width: Option<f32>, style: &TextStyle, ) -> Vec<GlyphOutline>

text shaped exactly as Self::draw_style paints it, one outline per glyph: what draws text as geometry (an outlined export, words set along a curve) and measures its ink. Colour and bitmap glyphs, which have no outline, are left out.

pub fn draw_rich( &mut self, scene: &mut Scene, layout: &RichTextLayout, transform: Affine, color: AlphaColor<Srgb>, )

Draw a crate::richtext::RichTextLayout (attributed, wrapped text) in a single color, including its underline decorations.

pub fn draw_rich_in_clip( &mut self, scene: &mut Scene, layout: &RichTextLayout, transform: Affine, color: AlphaColor<Srgb>, clip: Rect, )

Draw rich text while omitting only glyph batches proven outside clip. The clip is in final scene coordinates; callers must keep actual clip layers. Decorations remain unchanged. Unsupported ink draws normally.

Trait Implementations

impl Default for TextRenderer

fn default() -> TextRenderer

Returns the “default value” for a type.