cosmic_text/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! # COSMIC Text
4//!
5//! This library provides advanced text handling in a generic way. It provides abstractions for
6//! shaping, font discovery, font fallback, layout, rasterization, and editing. Shaping utilizes
7//! harfrust, font discovery utilizes fontdb, and the rasterization is optional and utilizes
8//! swash. The other features are developed internal to this library.
9//!
10//! It is recommended that you start by creating a [`FontSystem`], after which you can create a
11//! [`Buffer`], provide it with some text, and then inspect the layout it produces. At this
12//! point, you can use the `SwashCache` to rasterize glyphs into either images or pixels.
13//!
14//! ```
15//! use cosmic_text::{Attrs, Color, FontSystem, SwashCache, Buffer, Metrics, Shaping};
16//!
17//! // A FontSystem provides access to detected system fonts, create one per application
18//! let mut font_system = FontSystem::new();
19//!
20//! // A SwashCache stores rasterized glyphs, create one per application
21//! let mut swash_cache = SwashCache::new();
22//!
23//! // Text metrics indicate the font size and line height of a buffer
24//! let metrics = Metrics::new(14.0, 20.0);
25//!
26//! // A Buffer provides shaping and layout for a UTF-8 string, create one per text widget
27//! let mut buffer = Buffer::new(&mut font_system, metrics);
28//!
29//! // Borrow buffer together with the font system for more convenient method calls
30//! let mut buffer = buffer.borrow_with(&mut font_system);
31//!
32//! // Attributes indicate what font to choose
33//! let attrs = Attrs::new();
34//!
35//! // Set size and text
36//! buffer.set_size(Some(80.0), Some(25.0));
37//! buffer.set_text("Hello, Rust! 🦀\n", &attrs, Shaping::Advanced, None);
38//!
39//! // Inspect the output runs
40//! for run in buffer.layout_runs() {
41//!     for glyph in run.glyphs.iter() {
42//!         println!("{:#?}", glyph);
43//!     }
44//! }
45//!
46//! // Create a default text color
47//! let text_color = Color::rgb(0xFF, 0xFF, 0xFF);
48//!
49//! // Draw the buffer (for performance, instead use SwashCache directly)
50//! buffer.draw(&mut swash_cache, text_color, |x, y, w, h, color| {
51//!     // Fill in your code here for drawing rectangles
52//! });
53//! ```
54
55// Not interested in these lints
56#![allow(clippy::new_without_default)]
57// TODO: address occurrences and then deny
58//
59// Overflows can produce unpredictable results and are only checked in debug builds
60#![allow(clippy::arithmetic_side_effects)]
61// Indexing a slice can cause panics and that is something we always want to avoid
62#![allow(clippy::indexing_slicing)]
63// Soundness issues
64//
65// Dereferencing unaligned pointers may be undefined behavior
66#![deny(clippy::cast_ptr_alignment)]
67// Avoid panicking in without information about the panic. Use expect
68#![deny(clippy::unwrap_used)]
69// Ensure all types have a debug impl
70#![deny(missing_debug_implementations)]
71// This is usually a serious issue - a missing import of a define where it is interpreted
72// as a catch-all variable in a match, for example
73#![deny(unreachable_patterns)]
74// Ensure that all must_use results are used
75#![deny(unused_must_use)]
76// Style issues
77//
78// Documentation not ideal
79#![warn(clippy::doc_markdown)]
80// Document possible errors
81#![warn(clippy::missing_errors_doc)]
82// Document possible panics
83#![warn(clippy::missing_panics_doc)]
84// Ensure semicolons are present
85#![warn(clippy::semicolon_if_nothing_returned)]
86// Ensure numbers are readable
87#![warn(clippy::unreadable_literal)]
88#![cfg_attr(not(feature = "std"), no_std)]
89extern crate alloc;
90
91#[cfg(not(any(feature = "std", feature = "no_std")))]
92compile_error!("Either the `std` or `no_std` feature must be enabled");
93
94pub use self::attrs::*;
95mod attrs;
96
97pub use self::bidi_para::*;
98mod bidi_para;
99
100pub use self::buffer::*;
101mod buffer;
102
103pub use self::buffer_line::*;
104mod buffer_line;
105
106pub use self::cached::*;
107mod cached;
108
109pub use self::glyph_cache::*;
110mod glyph_cache;
111
112pub use self::cursor::*;
113mod cursor;
114
115pub use self::edit::*;
116mod edit;
117
118pub use self::font::*;
119mod font;
120
121pub use self::layout::*;
122mod layout;
123
124pub use self::line_ending::*;
125mod line_ending;
126
127pub use self::render::*;
128mod render;
129
130pub use self::shape::*;
131mod shape;
132
133pub use self::shape_run_cache::*;
134mod shape_run_cache;
135
136#[cfg(feature = "swash")]
137pub use self::swash::*;
138#[cfg(feature = "swash")]
139mod swash;
140
141mod math;
142
143type BuildHasher = core::hash::BuildHasherDefault<rustc_hash::FxHasher>;
144
145#[cfg(feature = "std")]
146type HashMap<K, V> = std::collections::HashMap<K, V, BuildHasher>;
147#[cfg(not(feature = "std"))]
148type HashMap<K, V> = hashbrown::HashMap<K, V, BuildHasher>;
cosmic_text/lib.rs

cosmic_text/
lib.rs
