egui_ratatui/lib.rs
1//! # egui_ratatui : egui widget + ratatui backend
2//!
3//! [](https://crates.io/crates/egui_ratatui)
4//! [](https://docs.rs/egui_ratatui/latest/egui_ratatui/)
5//! [](https://github.com/bevyengine/bevy/blob/master/LICENSE)
6//! [](https://crates.io/crates/egui_ratatui)
7//!
8//! `RataguiBackend` is a combined **ratatui Backend** and **egui Widget** that lets you render a full Ratatui
9//! terminal inside an egui UI. Because egui is WASM-friendly, this makes it easy to run terminal-style TUIs
10//! in desktop GUIs or in the browser.
11//!
12//! ## Highlights
13//!
14//! `egui_ratatui` builds on top of the [`soft_ratatui`](https://github.com/gold-silver-copper/soft_ratatui)
15//! library and inherits its features:
16//!
17//! * **Multiple font backends**: `embedded-graphics`, `embedded-ttf`, `bdf-parser`, `cosmic-text`.
18//! * **High performance**: optimized for real-time UIs (hundreds of FPS on normal workloads).
19//! * **WASM compatible**: run your ratatui apps in the browser via egui.
20//! * **Bevy & GUI friendly** — bevy and eframe examples included.
21//!
22//! ---
23//!
24//! ## Installation
25//!
26//! Add the crate to your project:
27//!
28//! ```bash
29//! cargo add egui_ratatui
30//! ```
31//!
32//! You will typically also add `soft_ratatui` (the rendering backends) and `ratatui`:
33//!
34//! ```bash
35//! cargo add soft_ratatui
36//! cargo add ratatui
37//! ```
38//!
39//! Or clone and run the included examples:
40//!
41//! ```bash
42//! git clone https://github.com/gold-silver-copper/egui_ratatui.git
43//! cd egui_ratatui
44//! cd bevy_example
45//! cargo run --release
46//! ```
47//!
48//! ---
49//!
50//! ## Quick usage
51//!
52//! ### Minimal example
53//!
54//! ```no_run
55//! use eframe::egui;
56//! use egui_ratatui::RataguiBackend;
57//! use ratatui::Terminal;
58//! use ratatui::prelude::Stylize;
59//! use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
60//! use soft_ratatui::embedded_graphics_unicodefonts::{
61//! mono_8x13_atlas, mono_8x13_bold_atlas, mono_8x13_italic_atlas,
62//! };
63//! use soft_ratatui::{EmbeddedGraphics, SoftBackend};
64//!
65//! fn main() -> eframe::Result {
66//! let options = eframe::NativeOptions {
67//! viewport: egui::ViewportBuilder::default().with_inner_size([320.0, 240.0]),
68//! ..Default::default()
69//! };
70//!
71//! let font_regular = mono_8x13_atlas();
72//! let font_italic = mono_8x13_italic_atlas();
73//! let font_bold = mono_8x13_bold_atlas();
74//! let soft_backend = SoftBackend::<EmbeddedGraphics>::new(
75//! 100,
76//! 50,
77//! font_regular,
78//! Some(font_bold),
79//! Some(font_italic),
80//! );
81//! let mut backend = RataguiBackend::new("soft_rat", soft_backend);
82//! let mut terminal = Terminal::new(backend).unwrap();
83//!
84//! eframe::run_simple_native("My egui App", options, move |ctx, _frame| {
85//! terminal
86//! .draw(|frame| {
87//! let area = frame.area();
88//! let textik = format!("Hello eframe! The window area is {}", area);
89//! frame.render_widget(
90//! Paragraph::new(textik)
91//! .block(Block::new().title("Ratatui").borders(Borders::ALL))
92//! .white()
93//! .on_blue()
94//! .wrap(Wrap { trim: false }),
95//! area,
96//! );
97//! })
98//! .expect("epic fail");
99//! egui::CentralPanel::default().show(ctx, |ui| {
100//! ui.add(terminal.backend_mut());
101//! });
102//! })
103//! }
104//! ```
105//!
106//! ---
107//!
108//! ## Feature Flags (set these on `soft_ratatui` dependency)
109//!
110//! | Feature | Enables | Description |
111//! | ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
112//! | `unicodefonts` | [`embedded_graphics_unicodefonts`](https://github.com/j-g00da/embedded-graphics-unicodefonts) | Embedded-graphics fonts with Unicode support. Automatically enables `embedded-graphics`. Enabled by default. |
113//! | `embedded-graphics` | [`embedded-graphics`](https://github.com/embedded-graphics/embedded-graphics) | Uses embedded-graphics font atlases for TUI rendering. |
114//! | `bdf-parser` | [`bdf-parser`](https://github.com/embedded-graphics/bdf) | Bitmap Distribution Format font support. |
115//! | `embedded-ttf` | [`embedded-ttf`](https://github.com/peckpeck/embedded-ttf) | TrueType font rendering via RustType. Automatically enables `embedded-graphics`. |
116//! | `cosmic-text` | [`cosmic-text`](https://github.com/pop-os/cosmic-text) | Advanced text shaping, layout, and Unicode support using CosmicText engine. |
117//!
118//! > Tip: Only enable the font backends you actually use in `Cargo.toml` to keep compile times and binary size down.
119//!
120//! ---
121//!
122//! ## Examples
123//!
124//! * `bevy_example/` — embedding Ratagui inside Bevy (with bevy_egui).
125//! * `eframe_example/` — minimal eframe example.
126//! * See the [`soft_ratatui`](https://github.com/gold-silver-copper/soft_ratatui) repo for font/backend-specific examples.
127//!
128//! ---
129//!
130//! ## Useful links
131//!
132//! * [`soft_ratatui`](https://github.com/gold-silver-copper/soft_ratatui) — software rendering backends used by egui_ratatui.
133//! * [`ratatui`](https://github.com/ratatui/ratatui) — terminal UI crate.
134//! * [`egui`](https://github.com/emilk/egui) — immediate mode GUI used to embed the widget.
135//! * [`bevy_ratatui`](https://github.com/cxreiff/bevy_ratatui) — Bevy integration for Ratatui.
136//! * [`mousefood`](https://github.com/j-g00da/mousefood) - a no-std embedded-graphics backend for Ratatui!
137//! * [`ratzilla`](https://github.com/orhun/ratzilla) - Build terminal-themed web applications with Rust and WebAssembly.
138//! * [`ratatui-wgpu`](https://github.com/Jesterhearts/ratatui-wgpu) - A wgpu based rendering backend for ratatui.
139//! * [`bevy_ratatui_camera`](https://github.com/cxreiff/bevy_ratatui_camera) - A bevy plugin for rendering your bevy app to the terminal using ratatui.
140//!
141//! WASM & platform guides:
142//!
143//! * [Bevy WASM guide](https://bevy-cheatbook.github.io/platforms/wasm.html)
144//! * [Macroquad WASM](https://macroquad.rs/articles/wasm/)
145//! * [eframe template](https://github.com/emilk/eframe_template)
146//!
147//! ---
148//!
149//! ## Cool BDF fonts
150//!
151//! * [`spleen`](https://github.com/fcambus/spleen) — many sizes, perfect block drawing.
152//! * [`cozette`](https://github.com/the-moonwitch/Cozette) — pretty font.
153//!
154//! ---
155//!
156//! ## License
157//!
158//! Dual-licensed under **MIT** or **Apache 2.0**.
159
160mod ratagui_backend;
161
162pub use ratagui_backend::RataguiBackend;