tui_big_text/
lib.rs

1//! A [Ratatui] widget to render gloriously oversized pixel text using glyphs from the [font8x8]
2//! crate. Part of the [tui-widgets] suite by [Joshka].
3//!
4//! ![Demo](https://vhs.charm.sh/vhs-7DFJFGwBEnUjjLCFSqwEm9.gif)
5//!
6//! [![Crate badge]][Crate]
7//! [![Docs Badge]][Docs]
8//! [![Deps Badge]][Dependency Status]
9//! [![License Badge]][License]
10//! [![Coverage Badge]][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`]. The
24//! builder allows you to customize the [`Style`] of the widget and the [`PixelSize`] of the
25//! 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//! - `QuarterHeight` - Each pixel is represented by a quarter of the height of a character cell.
57//! - `Octant` - Each pixel is represented by an eighth of a character cell.
58//!
59//! ```rust
60//! # use tui_big_text::*;
61//! BigText::builder().pixel_size(PixelSize::Full);
62//! BigText::builder().pixel_size(PixelSize::HalfHeight);
63//! BigText::builder().pixel_size(PixelSize::Quadrant);
64//! ```
65//!
66//! ![Pixel Size](https://vhs.charm.sh/vhs-6xzOJiPofPMWtUypzw1tg7.gif)
67//!
68//! Text can be aligned to the Left / Right / Center using the `alignment` methods.
69//!
70//! ```rust
71//! # use tui_big_text::*;
72//! BigText::builder().left_aligned();
73//! BigText::builder().centered();
74//! BigText::builder().right_aligned();
75//! ```
76//!
77//! ![Alignment Example](https://vhs.charm.sh/vhs-2GdJCPpXfnOCTsykSPr7AW.gif)
78//!
79//! # More widgets
80//!
81//! For the full suite of widgets, see [tui-widgets].
82//!
83//! [tui-big-text]: https://crates.io/crates/tui-big-text
84//! [Ratatui]: https://crates.io/crates/ratatui
85//! [font8x8]: https://crates.io/crates/font8x8
86//!
87//! <!-- Note that these links are sensitive to breaking with cargo-rdme -->
88//! [`BigText`]: https://docs.rs/tui-big-text/tui_big_text/big_text/struct.BigText.html
89//! [`BigText::builder`]:
90//!     https://docs.rs/tui-big-text/tui_big_text/big_text/struct.BigText.html#method.builder
91//! [`PixelSize`]: https://docs.rs/tui-big-text/tui_big_text/pixel_size/enum.PixelSize.html
92//! [`render_widget`]: https://docs.rs/ratatui/ratatui/struct.Frame.html#method.render_widget
93//! [`Style`]: https://docs.rs/ratatui/ratatui/style/struct.Style.html
94//!
95//! [Crate]: https://crates.io/crates/tui-big-text
96//! [Docs]: https://docs.rs/tui-big-text/
97//! [Dependency Status]: https://deps.rs/repo/github/joshka/tui-widgets
98//! [Coverage]: https://app.codecov.io/gh/joshka/tui-widgets
99//! [Ratatui Discord]: https://discord.gg/pMCEU9hNEj
100//! [Crate badge]: https://img.shields.io/crates/v/tui-big-text?logo=rust&style=flat
101//! [Docs Badge]: https://img.shields.io/docsrs/tui-big-text?logo=rust&style=flat
102//! [Deps Badge]: https://deps.rs/repo/github/joshka/tui-widgets/status.svg?style=flat
103//! [License Badge]: https://img.shields.io/crates/l/tui-big-text?style=flat
104//! [License]: https://github.com/joshka/tui-widgets/blob/main/LICENSE-MIT
105//! [Coverage Badge]:
106//!     https://img.shields.io/codecov/c/github/joshka/tui-widgets?logo=codecov&style=flat
107//! [Discord Badge]: https://img.shields.io/discord/1070692720437383208?logo=discord&style=flat
108//!
109//! [GitHub Repository]: https://github.com/joshka/tui-widgets
110//! [API Docs]: https://docs.rs/tui-big-text/
111//! [Examples]: https://github.com/joshka/tui-widgets/tree/main/tui-big-text/examples
112//! [Changelog]: https://github.com/joshka/tui-widgets/blob/main/tui-big-text/CHANGELOG.md
113//! [Contributing]: https://github.com/joshka/tui-widgets/blob/main/CONTRIBUTING.md
114//!
115//! [Joshka]: https://github.com/joshka
116//! [tui-widgets]: https://crates.io/crates/tui-widgets
117
118mod big_text;
119mod pixel_size;
120
121pub use big_text::{BigText, BigTextBuilder};
122pub use pixel_size::PixelSize;
tui_big_text/lib.rs

tui_big_text/
lib.rs
