# Crate cosmic_text

Expand description

## §COSMIC Text

This library provides advanced text handling in a generic way. It provides abstractions for shaping, font discovery, font fallback, layout, rasterization, and editing. Shaping utilizes harfrust, font discovery utilizes fontdb, and the rasterization is optional and utilizes swash. The other features are developed internal to this library.

It is recommended that you start by creating a `FontSystem`, after which you can create a `Buffer`, provide it with some text, and then inspect the layout it produces. At this point, you can use the `SwashCache` to rasterize glyphs into either images or pixels.

    use cosmic_text::{Attrs, Color, FontSystem, SwashCache, Buffer, Metrics, Shaping};

    // A FontSystem provides access to detected system fonts, create one per application
    let mut font_system = FontSystem::new();

    // A SwashCache stores rasterized glyphs, create one per application
    let mut swash_cache = SwashCache::new();

    // Text metrics indicate the font size and line height of a buffer
    let metrics = Metrics::new(14.0, 20.0);

    // A Buffer provides shaping and layout for a UTF-8 string, create one per text widget
    let mut buffer = Buffer::new(&mut font_system, metrics);

    // Borrow buffer together with the font system for more convenient method calls
    let mut buffer = buffer.borrow_with(&mut font_system);

    // Attributes indicate what font to choose
    let attrs = Attrs::new();

    // Set size and text
    buffer.set_size(Some(80.0), Some(25.0));
    buffer.set_text("Hello, Rust! 🦀\n", &attrs, Shaping::Advanced, None);

    // Inspect the output runs
    for run in buffer.layout_runs() {
        for glyph in run.glyphs.iter() {
            println!("{:#?}", glyph);
        }
    }

    // Create a default text color
    let text_color = Color::rgb(0xFF, 0xFF, 0xFF);

    // Draw the buffer (for performance, instead use SwashCache directly)
    buffer.draw(&mut swash_cache, text_color, |x, y, w, h, color| {
        // Fill in your code here for drawing rectangles
    });

## Modules§

fallback
fontdb
  `fontdb` is a simple, in-memory font database with CSS-like queries.
harfrust
  A complete harfbuzz shaping algorithm port to Rust.
skrifa
  A robust, ergonomic, high performance crate for OpenType fonts.

## Structs§

Angle
  Represents an angle in degrees or radians.
Attrs
  Text attributes
AttrsList
  List of text attributes to apply to a line
AttrsOwned
  An owned version of `Attrs`
BidiParagraphs
  An iterator over the paragraphs in the input text. It is equivalent to `core::str::Lines` but follows `unicode-bidi` behaviour.
BorrowedWithFontSystem
  A value borrowed together with an `FontSystem`
Buffer
  A buffer of text that is shaped and laid out
BufferLine
  A line (or paragraph) of text that is shaped and laid out
CacheKey
  Key for building a glyph cache
CacheKeyFlags
  Flags that change rendering
CacheMetrics
  Metrics, but implementing Eq and Hash using u32 representation of f32
Change
  A set of change items grouped into one logical change
ChangeItem
  A unique change to an editor
Color
  Text color
Cursor
  Current cursor location
DecorationMetrics
  Offset and thickness for a text decoration line, in EM units.
DecorationSpan
  A span of consecutive glyphs sharing the same text decoration.
Editor
  A wrapper of [`Buffer`] for easy editing
Feature
FeatureTag
  A 4-byte `OpenType` feature tag identifier
Font
  A font
FontFeatures
FontMatchAttrs
  Font-specific part of `Attrs` to be used for matching
FontMatchKey
FontSystem
  Access to the system fonts.
GlyphDecorationData
LayoutCursor
  The position of a cursor within a [`Buffer`].
LayoutGlyph
  A laid out glyph
LayoutLine
  A line of laid out glyphs
LayoutRun
  A line of visible text for rendering
LayoutRunIter
  An iterator of visible text lines, see `LayoutRun`
LegacyRenderer
  Helper to migrate from old renderer
LetterSpacing
  A wrapper for letter spacing to get around that f32 doesn’t implement Eq and Hash
LineIter
  Iterator over lines terminated by `LineEnding`
Metrics
  Metrics of text
PhysicalGlyph
Placement
  Describes the offset and dimensions of a rendered mask.
PlatformFallback
  A platform-specific font fallback list, for Unix.
Scroll
  Scroll position in [`Buffer`]
ShapeBuffer
  A set of buffers containing allocations for shaped text.
ShapeGlyph
  A shaped glyph
ShapeLine
  A shaped line (or paragraph)
ShapeRunCache
  A helper structure for caching shape runs.
ShapeRunKey
  Key for caching shape runs.
ShapeSpan
  A shaped span (for bidirectional processing)
ShapeWord
  A shaped word (for word wrapping)
SwashCache
  Cache for rasterizing with the swash scaler
SwashImage
  Scaled glyph image.
TextDecoration
Transform
  Two dimensional transformation matrix.
Weight
  Specifies the weight of glyphs in the font, their degree of blackness or stroke thickness.

## Enums§

Action
  An action to perform on an `Editor`
Affinity
  Whether to associate cursors placed at a boundary between runs with the run before or after it.
Align
  Align or justify
BufferRef
Cached
  Helper for caching a value when the value is optionally present in the ‘unused’ state.
Command
  Path command.
Ellipsize
EllipsizeHeightLimit
Family
  A font family.
FamilyOwned
  An owned version of `Family`
Hinting
  Metrics hinting strategy
LineEnding
  Line ending
Motion
  A motion to perform on a `Cursor`
Selection
  Selection mode
Shaping
  The shaping strategy of some text.
Stretch
  A face width.
Style
  Allows italic or oblique faces to be selected.
SubpixelBin
  Binning of subpixel position for cache optimization
SwashContent
  Content of a scaled glyph image.
UnderlineStyle
Wrap
  Wrapping mode

## Traits§

Edit
  A trait to allow easy replacements of `Editor`, like `SyntaxEditor`
Fallback
  The `Fallback` trait allows for configurable font fallback lists to be set during construction of the `FontSystem`.
Renderer
  Custom renderer for buffers and editors

## Functions§

render_decoration
  Draw text decoration lines (underline, strikethrough, overline) for a layout run.