Skip to main content

Crate parley

Crate parley 

Source
Expand description

Parley is a library for rich text layout. It is backed by HarfRust for text shaping.

Some key types are:

  • FontContext and LayoutContext are resources which should be shared globally (or at coarse-grained boundaries).

    • FontContext is database of fonts.
    • LayoutContext is scratch space that allows for reuse of allocations between layouts.
  • Builders for creating a Layout:

    • RangedBuilder: styles specified as a flat Vec of property spans
    • TreeBuilder: styles specified as a tree of spans
    • StyleRunBuilder: styles specified as a shared style table plus non-overlapping indexed runs

    They are constructed using LayoutContext::ranged_builder, LayoutContext::tree_builder, and LayoutContext::style_run_builder.

  • Layout which represents styled paragraph(s) of text and can perform shaping, line-breaking, bidi-reordering, and alignment of that text.

    Layout supports re-linebreaking and re-aligning many times (in case the width at which wrapping should occur changes). But if the text content or the styles applied to that content change then a new Layout must be created using a new RangedBuilder, TreeBuilder, or StyleRunBuilder.

§Usage Example

See the examples directory for more complete usage examples that include rendering.

use parley::{
   FontContext, FontWeight, InlineBox, InlineBoxKind, Layout,
   LayoutContext, LineHeight, PositionedLayoutItem, StyleProperty, VerticalAlign,
};

// Create a FontContext (font database) and LayoutContext (scratch space).
// These are both intended to be constructed rarely (perhaps even once per app):
let mut font_cx = FontContext::new();
let mut layout_cx = LayoutContext::new();

// Create a `RangedBuilder` or a `TreeBuilder`, which are used to construct a `Layout`.
const DISPLAY_SCALE : f32 = 1.0;
const TEXT : &str = "Lorem\u{FFFC} Ipsum...";
let mut builder = layout_cx.ranged_builder(&mut font_cx, &TEXT, DISPLAY_SCALE, true);

// Set default styles that apply to the entire layout
builder.push_default(StyleProperty::FontSize(16.0));

// Set a style that applies to the first 4 characters
builder.push(StyleProperty::FontWeight(FontWeight::new(600.0)), 0..4);

// Add a box to be laid out inline with the text, in place of the U+FFFC OBJECT REPLACEMENT
// CHARACTER
builder.push_inline_box(InlineBox { id: 0, kind: InlineBoxKind::InFlow, index: 5, width: 50.0, height: 50.0, baseline: None, vertical_align: VerticalAlign::BASELINE });

// Build the builder into a Layout
let mut layout: Layout<()> = builder.build(&TEXT);

// Run line-breaking and alignment on the Layout
const MAX_WIDTH : Option<f32> = Some(100.0);
layout.break_all_lines(MAX_WIDTH);

// Inspect computed layout (see examples for more details)
let width = layout.width();
let height = layout.height();
for line in layout.lines() {
    for item in line.items() {
        match item {
            PositionedLayoutItem::GlyphRun(glyph_run) => {
                // Render the glyph run
            }
            PositionedLayoutItem::InlineBox(inline_box) => {
                // Render the inline box
            }
        };
    }
}

§Features

The following crate feature flags are available:

  • std (enabled by default): Get floating point functions from the standard library (likely using your target’s libc).
  • libm: Use floating point implementations from libm. This is useful for no_std environments. However, note that the libm crate is not as efficient as the standard library.
  • bytemuck: Forwarded to parlance which then implements traits from bytemuck on its types.
  • system (enabled by default): Enable support for system font backends. This also enables std.
  • complex-scripts: Enable dictionary-based line and word breaking for complex scripts (CJK, Thai, Khmer, Lao, Myanmar). When disabled, a lightweight segmenter is used that falls back to character-level breaks for those scripts. See DictionaryProvider for full details.

At least one of std and libm is required; std overrides libm. Note that Parley requires that an allocator is available (i.e. it uses alloc).

Re-exports§

pub use fontique;
pub use editing::*;
pub use layout::*;
pub use style::*;

Modules§

editing
layout
Layout types.
setting
OpenType settings (features and variations).
style
Rich styling support.

Structs§

AsciiLineBreakTable
A line break override table for ASCII character pairs.
AsciiLineBreakTableBuilder
A builder for an AsciiLineBreakTable.
BoundingBox
A bounding box.
FontContext
A font database/cache (wrapper around a Fontique Collection and SourceCache).
FontData
Owned shareable font resource.
InlineBox
A box to be laid out inline with text
Layout
Text layout.
LayoutContext
Shared scratch space used when constructing text layouts.
LineBreakContext
Context for a potential line break opportunity between two adjacent code points.
RangedBuilder
Builder for constructing a text layout with ranged attributes.
StyleRunBuilder
Builder for constructing a text layout from a style table and indexed style runs.
TreeBuilder
Builder for constructing a text layout with a tree of attributes.

Enums§

BaseDirection
The paragraph’s base direction.
InlineBoxKind
Whether a box is in-flow (takes up space in the layout) or out-of-flow (e.g. absolutely positioned) or custom-out-of-flow (line-breaking should yield control flow)

Statics§

CHROMIUM_LINE_BREAK_OVERRIDE
A line break override function mirroring Chromium’s preferred line breaking behavior.

Traits§

DictionaryProvider
An external source of complex script dictionaries for line and word breaking in Parley.

Type Aliases§

FontDeprecated
LineBreakOverrideFn
Line break opportunity override.