freya_terminal/
lib.rs

1//! # Freya Terminal 🖥️
2//!
3//! Terminal emulator integration for Freya applications.
4//!
5//! This crate provides a way to embed interactive terminal emulators in your Freya applications.
6//! It uses PTY (pseudo-terminal) to spawn shell processes and renders VT100-compatible terminal output
7//! with full 256-color support.
8//!
9//! ## Features
10//!
11//! - **PTY Integration**: Spawn and interact with shell processes
12//! - **VT100 Rendering**: Full terminal emulation with cursor, colors, and text attributes
13//! - **256-Color Support**: ANSI 16 colors, 6x6x6 RGB cube, and 24-level grayscale
14//! - **Keyboard Input**: Handle all standard terminal key sequences
15//! - **Auto-resize**: Terminal automatically resizes based on available space
16//!
17//! ## Basic Usage
18//!
19//! ```rust,no_run
20//! use freya::prelude::*;
21//! use freya_terminal::prelude::*;
22//!
23//! fn main() {
24//!     launch(LaunchConfig::new().with_window(WindowConfig::new(app)))
25//! }
26//!
27//! fn app() -> impl IntoElement {
28//!     let mut handle = use_state(|| {
29//!         let mut cmd = CommandBuilder::new("bash");
30//!         cmd.env("TERM", "xterm-256color");
31//!         TerminalHandle::new(TerminalId::new(), cmd, None).ok()
32//!     });
33//!
34//!     let focus = use_focus();
35//!
36//!     rect().expanded().background((30, 30, 30)).child(
37//!         if let Some(handle) = handle.read().clone() {
38//!             rect()
39//!                 .child(Terminal::new(handle.clone()))
40//!                 .expanded()
41//!                 .a11y_id(focus.a11y_id())
42//!                 .on_mouse_down(move |_| focus.request_focus())
43//!                 .on_key_down(move |e: Event<KeyboardEventData>| {
44//!                     if let Some(ch) = e.try_as_str() {
45//!                         let _ = handle.write(ch.as_bytes());
46//!                     } else {
47//!                         let _ = handle.write(match &e.key {
48//!                             Key::Named(NamedKey::Enter) => b"\n",
49//!                             Key::Named(NamedKey::Backspace) => &[0x7f],
50//!                             Key::Named(NamedKey::Tab) => b"\t",
51//!                             Key::Named(NamedKey::ArrowUp) => b"\x1b[A",
52//!                             Key::Named(NamedKey::ArrowDown) => b"\x1b[B",
53//!                             Key::Named(NamedKey::ArrowLeft) => b"\x1b[D",
54//!                             Key::Named(NamedKey::ArrowRight) => b"\x1b[C",
55//!                             _ => return,
56//!                         });
57//!                     }
58//!                 })
59//!                 .into_element()
60//!         } else {
61//!             "Failed to start Terminal.".into_element()
62//!         },
63//!     )
64//! }
65//! ```
66//!
67//! ## Handling Terminal Exit
68//!
69//! You can detect when the terminal/PTY closes using `TerminalHandle::closed`:
70//!
71//! ```rust,ignore
72//! use_future(move || async move {
73//!     terminal_handle.closed().await;
74//!     // Terminal has exited, update UI state
75//! });
76//! ```
77//!
78//! ## Advance usage
79//!
80//! Check the `feature_terminal.rs` example in the repository.
81pub mod buffer;
82pub mod colors;
83pub mod element;
84pub mod handle;
85pub mod parser;
86pub mod pty;
87
88/// Prelude module for convenient imports.
89pub mod prelude {
90    pub use portable_pty::CommandBuilder;
91
92    pub use crate::{
93        buffer::{
94            TerminalBuffer,
95            TerminalSelection,
96        },
97        element::Terminal,
98        handle::{
99            TerminalError,
100            TerminalHandle,
101            TerminalId,
102        },
103        parser::TerminalMouseButton,
104        pty::ScrollCommand,
105    };
106}
freya_terminal/lib.rs

freya_terminal/
lib.rs
