ratatui_splash_screen/
lib.rs

1//! A [Ratatui] widget to turn any image to a splash screen in your terminal ✨
2//!
3//! ![demo](https://github.com/orhun/ratatui-splash-screen/assets/24392180/3a094217-2825-4962-b22e-476dc4fbce55)
4//!
5//! [![crates.io badge]][ratatui-splash-screen-crate]
6//! [![docs.rs badge]][ratatui-splash-screen-docs]
7//! [![license badge]](./LICENSE-MIT)
8//! [![codecov.io badge]][Code Coverage]
9//! [![discord badge]][Ratatui Discord]
10//!
11//! See the demo of [gpg-tui] for a real world example.
12//!
13//! ## Features
14//!
15//! - Turn any image (`jpg`, `png`) into a splash screen!
16//! - Verifies the file integrity via checking SHA checksum (optional)
17//! - Supports grayscaling
18//!
19//! ## Installation
20//!
21//! [![deps.rs badge]][Dependency Status]
22//!
23//! ```shell
24//! cargo add ratatui ratatui-splash-screen
25//! ```
26//!
27//! ## Usage
28//!
29//! Create a [`SplashConfig`] and construct a [`SplashScreen`] widget with it.
30//! Then render the widget in a loop using the [`render`] function.
31//! You can check if the splash screen is done rendering by calling [`is_rendered`].
32//!
33//! ## Examples
34//!
35//! ```no_run
36//! use std::error::Error;
37//! use std::io::stdout;
38//! use std::time::Duration;
39//!
40//! use ratatui::prelude::*;
41//! use ratatui_splash_screen::{SplashConfig, SplashScreen, SplashError};
42//!
43//! static SPLASH_CONFIG: SplashConfig = SplashConfig {
44//!     image_data: include_bytes!("../assets/splash.png"),
45//!     sha256sum: Some("c692ae1f9bd4a03cb6fc74a71cb585a8d70c2eacda8ec95e26aa0d6a0670cffd"),
46//!     render_steps: 12,
47//!     use_colors: true,
48//! };
49//!
50//! fn main() -> Result<(), Box<dyn Error>> {
51//!     // create a terminal
52//!     let backend = CrosstermBackend::new(stdout());
53//!     let mut terminal = Terminal::new(backend)?;
54//!
55//!     // render splash screen
56//!     let mut splash_screen = SplashScreen::new(SPLASH_CONFIG)?;
57//!     while !splash_screen.is_rendered() {
58//!         terminal.draw(|frame| {
59//!             frame.render_widget(&mut splash_screen, frame.size());
60//!         })?;
61//!         std::thread::sleep(Duration::from_millis(100));
62//!     }
63//!
64//!     Ok(())
65//! }
66//! ```
67//!
68//! See the full example [here](https://github.com/orhun/ratatui-splash-screen/blob/main/examples/demo.rs).
69//!
70//! ## Tips
71//!
72//! - Use small images (such as 200x200) for a better experience.
73//! - You can tweak the [`render_steps`] value for smoother rendering.
74//! - Run [`sha256sum(1)`] command on your system to find out the SHA value. You can set it to `None` if you don't want to check integrity.
75//!
76//! [ratatui-splash-screen]: https://github.com/orhun/ratatui-splash-screen
77//! [ratatui-splash-screen-crate]: https://crates.io/crates/ratatui-splash-screen
78//! [ratatui-splash-screen-docs]: https://docs.rs/ratatui-splash-screen
79//! [ratatui]: https://ratatui.rs
80//! [`sha256sum(1)`]: https://linux.die.net/man/1/sha256sum
81//! [gpg-tui]: https://github.com/orhun/gpg-tui
82//!
83//! [`SplashConfig`]: crate::config::SplashConfig
84//! [`SplashScreen`]: crate::splash_screen::SplashScreen
85//! [`is_rendered`]: crate::splash_screen::SplashScreen::is_rendered
86//! [`render_steps`]: crate::config::SplashConfig#structfield.render_steps
87//! [`render`]: https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html#tymethod.render
88//!
89//! [crates.io badge]:
90//! https://img.shields.io/crates/v/ratatui-splash-screen?style=flat&logo=Rust&color=666&labelColor=1c1c24
91//! [docs.rs badge]: https://img.shields.io/docsrs/ratatui-splash-screen?logo=rust&style=flat&color=666&labelColor=1c1c24
92//! [deps.rs badge]: https://deps.rs/repo/github/orhun/ratatui-splash-screen/status.svg?style=flat&color=666&labelColor=1c1c24
93//! [license badge]: https://img.shields.io/crates/l/ratatui-splash-screen?style=flat&color=666&labelColor=1c1c24&logo=github
94//! [codecov.io badge]: https://img.shields.io/codecov/c/github/orhun/ratatui-splash-screen?logo=codecov&style=flat&color=666&labelColor=1c1c24&logoColor=white
95//! [discord badge]: https://img.shields.io/discord/1070692720437383208?label=Ratatui+Discord&logo=discord&style=flat&color=666&labelColor=1c1c24&logoColor=white
96//!
97//! [Dependency Status]: https://deps.rs/repo/github/orhun/ratatui-splash-screen
98//! [Code Coverage]: https://app.codecov.io/gh/orhun/ratatui-splash-screen
99//! [Ratatui Discord]: https://discord.gg/pMCEU9hNEj
100
101#![warn(missing_docs, clippy::unwrap_used)]
102
103mod config;
104mod error;
105mod splash_screen;
106
107pub use config::SplashConfig;
108pub use error::SplashError;
109pub use splash_screen::SplashScreen;
ratatui_splash_screen/lib.rs

ratatui_splash_screen/
lib.rs
