Parley
Rich text layout
Parley is a library for rich text layout. It is backed by HarfRust for text shaping.
Some key types are:
-
FontContextandLayoutContextare resources which should be shared globally (or at coarse-grained boundaries).FontContextis database of fonts.LayoutContextis scratch space that allows for reuse of allocations between layouts.
-
Builders for creating a
Layout:RangedBuilder: styles specified as a flatVecof property spansTreeBuilder: styles specified as a tree of spansStyleRunBuilder: styles specified as a shared style table plus non-overlapping indexed runs
They are constructed using
LayoutContext::ranged_builder,LayoutContext::tree_builder, andLayoutContext::style_run_builder. -
Layoutwhich represents styled paragraph(s) of text and can perform shaping, line-breaking, bidi-reordering, and alignment of that text.Layoutsupports 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 newLayoutmust be created using a newRangedBuilder,TreeBuilder, orStyleRunBuilder.
Usage Example
See the examples directory for more complete usage examples that include rendering.
use ;
// 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 = new;
let mut layout_cx = 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;
// Set default styles that apply to the entire layout
builder.push_default;
// Set a style that applies to the first 4 characters
builder.push;
// Add a box to be laid out inline with the text, in place of the U+FFFC OBJECT REPLACEMENT
// CHARACTER
builder.push_inline_box;
// Build the builder into a Layout
let mut layout: = builder.build;
// Run line-breaking and alignment on the Layout
const MAX_WIDTH : = Some;
layout.break_all_lines;
// Inspect computed layout (see examples for more details)
let width = layout.width;
let height = layout.height;
for line in layout.lines
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 forno_stdenvironments. However, note that thelibmcrate is not as efficient as the standard library.bytemuck: Forwarded to [parlance][] which then implements traits frombytemuckon its types.system(enabled by default): Enable support for system font backends. This also enablesstd.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. SeeDictionaryProviderfor 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).
Minimum supported Rust Version (MSRV)
This version of Parley has been verified to compile with Rust 1.88 and later.
Future versions of Parley might increase the Rust version requirement. It will not be treated as a breaking change and as such can even happen with small patch releases.
As time has passed, some of Parley's dependencies could have released versions with a higher Rust requirement. If you encounter a compilation issue due to a dependency and don't want to upgrade your Rust toolchain, then you could downgrade the dependency.
# Use the problematic dependency's name and version
Community
Discussion of Parley development happens in the Linebender Zulip, specifically the #parley channel. All public content can be read without logging in.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Contributions are welcome by pull request. The Rust code of conduct applies. Please feel free to add your name to the AUTHORS file in any substantive pull request.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.