mirror of
https://github.com/ratatui-org/ratatui
synced 2025-02-16 14:08:44 +00:00
ed51c4b342
These are simple opinionated methods for creating a terminal that is
useful to use in most apps. The new init method creates a crossterm
backend writing to stdout, enables raw mode, enters the alternate
screen, and sets a panic handler that restores the terminal on panic.
A minimal hello world now looks a bit like:
```rust
use ratatui::{
crossterm::event::{self, Event},
text::Text,
Frame,
};
fn main() {
let mut terminal = ratatui::init();
loop {
terminal
.draw(|frame: &mut Frame| frame.render_widget(Text::raw("Hello World!"), frame.area()))
.expect("Failed to draw");
if matches!(event::read().expect("failed to read event"), Event::Key(_)) {
break;
}
}
ratatui::restore();
}
```
A type alias `DefaultTerminal` is added to represent this terminal
type and to simplify any cases where applications need to pass this
terminal around. It is equivalent to:
`Terminal<CrosstermBackend<Stdout>>`
We also added `ratatui::try_init()` and `try_restore()`, for situations
where you might want to handle initialization errors yourself instead
of letting the panic handler fire and cleanup. Simple Apps should
prefer the `init` and `restore` functions over these functions.
Corresponding functions to allow passing a `TerminalOptions` with
a `Viewport` (e.g. inline, fixed) are also available
(`init_with_options`,
and `try_init_with_options`).
The existing code to create a backend and terminal will remain and
is not deprecated by this approach. This just provides a simple one
line initialization using the common options.
---------
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
101 lines
3.2 KiB
Rust
101 lines
3.2 KiB
Rust
//! # [Ratatui] Hyperlink examplew
|
|
//!
|
|
//! Shows how to use [OSC 8] to create hyperlinks in the terminal.
|
|
//!
|
|
//! The latest version of this example is available in the [examples] folder in the repository.
|
|
//!
|
|
//! Please note that the examples are designed to be run against the `main` branch of the Github
|
|
//! repository. This means that you may not be able to compile with the latest release version on
|
|
//! crates.io, or the one that you have installed locally.
|
|
//!
|
|
//! See the [examples readme] for more information on finding examples that match the version of the
|
|
//! library you are using.
|
|
//!
|
|
//! [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
|
|
//! [Ratatui]: https://github.com/ratatui/ratatui
|
|
//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
|
|
//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
|
|
|
|
use color_eyre::Result;
|
|
use itertools::Itertools;
|
|
use ratatui::{
|
|
buffer::Buffer,
|
|
crossterm::event::{self, Event, KeyCode},
|
|
layout::Rect,
|
|
style::Stylize,
|
|
text::{Line, Text},
|
|
widgets::Widget,
|
|
DefaultTerminal,
|
|
};
|
|
|
|
fn main() -> Result<()> {
|
|
color_eyre::install()?;
|
|
let terminal = ratatui::init();
|
|
let app_result = App::new().run(terminal);
|
|
ratatui::restore();
|
|
app_result
|
|
}
|
|
|
|
struct App {
|
|
hyperlink: Hyperlink<'static>,
|
|
}
|
|
|
|
impl App {
|
|
fn new() -> Self {
|
|
let text = Line::from(vec!["Example ".into(), "hyperlink".blue()]);
|
|
let hyperlink = Hyperlink::new(text, "https://example.com");
|
|
Self { hyperlink }
|
|
}
|
|
|
|
fn run(self, mut terminal: DefaultTerminal) -> Result<()> {
|
|
loop {
|
|
terminal.draw(|frame| frame.render_widget(&self.hyperlink, frame.area()))?;
|
|
if let Event::Key(key) = event::read()? {
|
|
if matches!(key.code, KeyCode::Char('q') | KeyCode::Esc) {
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
Ok(())
|
|
}
|
|
}
|
|
|
|
/// A hyperlink widget that renders a hyperlink in the terminal using [OSC 8].
|
|
///
|
|
/// [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
|
|
struct Hyperlink<'content> {
|
|
text: Text<'content>,
|
|
url: String,
|
|
}
|
|
|
|
impl<'content> Hyperlink<'content> {
|
|
fn new(text: impl Into<Text<'content>>, url: impl Into<String>) -> Self {
|
|
Self {
|
|
text: text.into(),
|
|
url: url.into(),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl Widget for &Hyperlink<'_> {
|
|
fn render(self, area: Rect, buffer: &mut Buffer) {
|
|
(&self.text).render(area, buffer);
|
|
|
|
// this is a hacky workaround for https://github.com/ratatui/ratatui/issues/902, a bug
|
|
// in the terminal code that incorrectly calculates the width of ANSI escape sequences. It
|
|
// works by rendering the hyperlink as a series of 2-character chunks, which is the
|
|
// calculated width of the hyperlink text.
|
|
for (i, two_chars) in self
|
|
.text
|
|
.to_string()
|
|
.chars()
|
|
.chunks(2)
|
|
.into_iter()
|
|
.enumerate()
|
|
{
|
|
let text = two_chars.collect::<String>();
|
|
let hyperlink = format!("\x1B]8;;{}\x07{}\x1B]8;;\x07", self.url, text);
|
|
buffer[(area.x + i as u16 * 2, area.y)].set_symbol(hyperlink.as_str());
|
|
}
|
|
}
|
|
}
|