tui_big_text/
lib.rs

1//! [tui-big-text] is a rust crate that renders large pixel text as a [Ratatui] widget using the
2//! glyphs from the [font8x8] crate.
3//!
4//! ![Demo](https://vhs.charm.sh/vhs-7DFJFGwBEnUjjLCFSqwEm9.gif)
5//!
6//! [![Crate badge]][tui-big-text]
7//! [![Docs.rs Badge]][API Docs]
8//! [![Deps.rs Badge]][Dependency Status]<br>
9//! [![License Badge]](./LICENSE-MIT)
10//! [![Codecov.io Badge]][Code Coverage]
11//! [![Discord Badge]][Ratatui Discord]
12//!
13//! [GitHub Repository] · [API Docs] · [Examples] · [Changelog] · [Contributing]
14//!
15//! # Installation
16//!
17//! ```shell
18//! cargo add ratatui tui-big-text
19//! ```
20//!
21//! # Usage
22//!
23//! Create a [`BigText`] widget using [`BigText::builder`] and pass it to [`render_widget`] to
24//! render be rendered. The builder allows you to customize the [`Style`] of the widget and the
25//! [`PixelSize`] of the glyphs.
26//!
27//! # Examples
28//!
29//! ```rust
30//! use ratatui::prelude::{Frame, Style, Stylize};
31//! use tui_big_text::{BigText, PixelSize};
32//!
33//! fn render(frame: &mut Frame) {
34//!     let big_text = BigText::builder()
35//!         .pixel_size(PixelSize::Full)
36//!         .style(Style::new().blue())
37//!         .lines(vec![
38//!             "Hello".red().into(),
39//!             "World".white().into(),
40//!             "~~~~~".into(),
41//!         ])
42//!         .build();
43//!     frame.render_widget(big_text, frame.size());
44//! }
45//! ```
46//!
47//! The [`PixelSize`] can be used to control how many character cells are used to represent a single
48//! pixel of the 8x8 font. It has six variants:
49//!
50//! - `Full` (default) - Each pixel is represented by a single character cell.
51//! - `HalfHeight` - Each pixel is represented by half the height of a character cell.
52//! - `HalfWidth` - Each pixel is represented by half the width of a character cell.
53//! - `Quadrant` - Each pixel is represented by a quarter of a character cell.
54//! - `ThirdHeight` - Each pixel is represented by a third of the height of a character cell.
55//! - `Sextant` - Each pixel is represented by a sixth of a character cell.
56//!
57//! ```rust
58//! # use tui_big_text::*;
59//! BigText::builder().pixel_size(PixelSize::Full);
60//! BigText::builder().pixel_size(PixelSize::HalfHeight);
61//! BigText::builder().pixel_size(PixelSize::Quadrant);
62//! ```
63//!
64//! ![Pixel Size](https://vhs.charm.sh/vhs-2E84yH6UJuX1pF7mXYUXxs.gif)
65//!
66//! Text can be aligned to the Left / Right / Center using the `alignment` methods.
67//!
68//! ```rust
69//! # use tui_big_text::*;
70//! BigText::builder().left_aligned();
71//! BigText::builder().centered();
72//! BigText::builder().right_aligned();
73//! ```
74//!
75//! ![Alignment Example](https://vhs.charm.sh/vhs-2GdJCPpXfnOCTsykSPr7AW.gif)
76//!
77//! [tui-big-text]: https://crates.io/crates/tui-big-text
78//! [Ratatui]: https://crates.io/crates/ratatui
79//! [font8x8]: https://crates.io/crates/font8x8
80//!
81//! <!-- Note that these links are sensitive to breaking with cargo-rdme -->
82//! [`BigText`]: crate::big_text::BigText
83//! [`BigText::builder`]: crate::big_text::BigText#method.builder
84//! [`PixelSize`]: crate::pixel_size::PixelSize
85//! [`render_widget`]: https://docs.rs/ratatui/latest/ratatui/struct.Frame.html#method.render_widget
86//! [`Style`]: https://docs.rs/ratatui/latest/ratatui/style/struct.Style.html
87//!
88//! [Crate badge]: https://img.shields.io/crates/v/tui-big-text?logo=rust&style=for-the-badge
89//! [Docs.rs Badge]: https://img.shields.io/docsrs/tui-big-text?logo=rust&style=for-the-badge
90//! [Deps.rs Badge]: https://deps.rs/repo/github/joshka/tui-big-text/status.svg?style=for-the-badge
91//! [License Badge]: https://img.shields.io/crates/l/tui-big-text?style=for-the-badge
92//! [Codecov.io Badge]: https://img.shields.io/codecov/c/github/joshka/tui-big-text?logo=codecov&style=for-the-badge&token=BAQ8SOKEST
93//! [Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=ratatui+discord&logo=discord&style=for-the-badge
94//!
95//! [API Docs]: https://docs.rs/crate/tui-big-text/
96//! [Dependency Status]: https://deps.rs/repo/github/joshka/tui-big-text
97//! [Code Coverage]: https://app.codecov.io/gh/joshka/tui-big-text
98//! [Ratatui Discord]: https://discord.gg/pMCEU9hNEj
99//!
100//! [GitHub Repository]: https://github.com/joshka/tui-widgets
101//! [Examples]: https://github.com/joshka/tui-widgets/tree/main/tui-big-text/examples
102//! [Changelog]: https://github.com/joshka/tui-widgets/blob/main/tui-big-text/CHANGELOG.md
103//! [Contributing]: https://github.com/joshka/tui-widgets/blob/main/CONTRIBUTING.md
104
105mod big_text;
106mod pixel_size;
107
108pub use big_text::{BigText, BigTextBuilder};
109pub use pixel_size::PixelSize;
tui_big_text/lib.rs

tui_big_text/
lib.rs
