feat: re-export backends from the ratatui crate (#1151)

`crossterm`, `termion`, and `termwiz` can now be accessed as `ratatui::{crossterm, termion, termwiz}` respectively. This makes it possible to just add the Ratatui crate as a dependency and use the backend of choice without having to add the backend crates as dependencies. To update existing code, replace all instances of `crossterm::` with `ratatui::crossterm::`, `termion::` with `ratatui::termion::`, and `termwiz::` with `ratatui::termwiz::`.
ratatui · May 28, 2024 · 74a32af · 74a32af
1 parent 4ce67fc
commit 74a32af
Show file tree

Hide file tree

Showing 39 changed files with 295 additions and 234 deletions.
diff --git a/README.md b/README.md
@@ -43,10 +43,10 @@ Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its deve
 
 ## Installation
 
-Add `ratatui` and `crossterm` as dependencies to your cargo.toml:
+Add `ratatui` as a dependency to your cargo.toml:
 
 ```shell
-cargo add ratatui crossterm
+cargo add ratatui
 ```
 
 Ratatui uses [Crossterm] by default as it works on most platforms. See the [Installation]
@@ -110,7 +110,8 @@ module] and the [Backends] section of the [Ratatui Website] for more info.
 
 The drawing logic is delegated to a closure that takes a [`Frame`] instance as argument. The
 [`Frame`] provides the size of the area to draw to and allows the app to render any [`Widget`]
-using the provided [`render_widget`] method. See the [Widgets] section of the [Ratatui Website]
+using the provided [`render_widget`] method. After this closure returns, a diff is performed and
+only the changes are drawn to the terminal. See the [Widgets] section of the [Ratatui Website]
 for more info.
 
 ### Handling events
@@ -125,12 +126,17 @@ Website] for more info. For example, if you are using [Crossterm], you can use t
 ```rust
 use std::io::{self, stdout};
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{
+            disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+        },
+        ExecutableCommand,
+    },
+    prelude::*,
+    widgets::*,
 };
-use ratatui::{prelude::*, widgets::*};
 
 fn main() -> io::Result<()> {
     enable_raw_mode()?;
@@ -161,8 +167,7 @@ fn handle_events() -> io::Result<bool> {
 
 fn ui(frame: &mut Frame) {
     frame.render_widget(
-        Paragraph::new("Hello World!")
-            .block(Block::bordered().title("Greeting")),
+        Paragraph::new("Hello World!").block(Block::bordered().title("Greeting")),
         frame.size(),
     );
 }
@@ -206,14 +211,8 @@ fn ui(frame: &mut Frame) {
         [Constraint::Percentage(50), Constraint::Percentage(50)],
     )
     .split(main_layout[1]);
-    frame.render_widget(
-        Block::bordered().title("Left"),
-        inner_layout[0],
-    );
-    frame.render_widget(
-        Block::bordered().title("Right"),
-        inner_layout[1],
-    );
+    frame.render_widget(Block::bordered().title("Left"), inner_layout[0]);
+    frame.render_widget(Block::bordered().title("Right"), inner_layout[1]);
 }
 ```
 
@@ -331,17 +330,14 @@ Running this example produces the following output:
 [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
 [CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui/ci.yml?style=flat-square&logo=github
 [CI Workflow]: https://github.com/ratatui-org/ratatui/actions/workflows/ci.yml
-[Codecov Badge]:
-    https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
+[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui-org/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3&logoColor=C43AC3
 [Codecov]: https://app.codecov.io/gh/ratatui-org/ratatui
 [Deps.rs Badge]: https://deps.rs/repo/github/ratatui-org/ratatui/status.svg?style=flat-square
 [Deps.rs]: https://deps.rs/repo/github/ratatui-org/ratatui
-[Discord Badge]:
-    https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&color=1370D3&logoColor=1370D3
+[Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&color=1370D3&logoColor=1370D3
 [Discord Server]: https://discord.gg/pMCEU9hNEj
 [Docs Badge]: https://img.shields.io/docsrs/ratatui?logo=rust&style=flat-square&logoColor=E05D44
-[Matrix Badge]:
-    https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
+[Matrix Badge]: https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
 [Matrix]: https://matrix.to/#/#ratatui:matrix.org
 [Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui-org?logo=github&style=flat-square&color=1370D3
 

diff --git a/examples/barchart.rs b/examples/barchart.rs
@@ -19,12 +19,12 @@ use std::{
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use ratatui::{
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
     prelude::*,
     widgets::{Bar, BarChart, BarGroup, Block, Paragraph},
 };

diff --git a/examples/block.rs b/examples/block.rs
@@ -20,13 +20,13 @@ use std::{
     time::Duration,
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
 use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
     prelude::*,
     widgets::{
         block::{Position, Title},

diff --git a/examples/calendar.rs b/examples/calendar.rs
@@ -17,12 +17,15 @@
 
 use std::{error::Error, io};
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    prelude::*,
+    widgets::calendar::*,
 };
-use ratatui::{prelude::*, widgets::calendar::*};
 use time::{Date, Month, OffsetDateTime};
 
 fn main() -> Result<(), Box<dyn Error>> {

diff --git a/examples/canvas.rs b/examples/canvas.rs
@@ -20,12 +20,12 @@ use std::{
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
 use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
     prelude::*,
     widgets::{canvas::*, *},
 };

diff --git a/examples/chart.rs b/examples/chart.rs
@@ -19,12 +19,12 @@ use std::{
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use ratatui::{
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
     prelude::*,
     widgets::{block::Title, Axis, Block, Chart, Dataset, GraphType, LegendPosition},
 };

diff --git a/examples/colors.rs b/examples/colors.rs
@@ -23,13 +23,13 @@ use std::{
     time::Duration,
 };
 
-use crossterm::{
-    event::{self, Event, KeyCode},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-};
 use itertools::Itertools;
 use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
     prelude::*,
     widgets::{Block, Borders, Paragraph},
 };

diff --git a/examples/colors_rgb.rs b/examples/colors_rgb.rs
@@ -33,13 +33,15 @@ use std::{
 };
 
 use color_eyre::{config::HookBuilder, eyre, Result};
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
 use palette::{convert::FromColorUnclamped, Okhsv, Srgb};
-use ratatui::prelude::*;
+use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    prelude::*,
+};
 
 #[derive(Debug, Default)]
 struct App {

diff --git a/examples/constraint-explorer.rs b/examples/constraint-explorer.rs
@@ -18,13 +18,13 @@
 use std::io::{self, stdout};
 
 use color_eyre::{config::HookBuilder, Result};
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
-};
 use itertools::Itertools;
 use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
     layout::{Constraint::*, Flex},
     prelude::*,
     style::palette::tailwind::*,

diff --git a/examples/constraints.rs b/examples/constraints.rs
@@ -18,12 +18,17 @@
 use std::io::{self, stdout};
 
 use color_eyre::{config::HookBuilder, Result};
-use crossterm::{
-    event::{self, Event, KeyCode, KeyEventKind},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use ratatui::{
+    crossterm::{
+        event::{self, Event, KeyCode, KeyEventKind},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    layout::Constraint::*,
+    prelude::*,
+    style::palette::tailwind,
+    widgets::*,
 };
-use ratatui::{layout::Constraint::*, prelude::*, style::palette::tailwind, widgets::*};
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 const SPACER_HEIGHT: u16 = 0;

diff --git a/examples/custom_widget.rs b/examples/custom_widget.rs
@@ -15,15 +15,18 @@
 
 use std::{error::Error, io, ops::ControlFlow, time::Duration};
 
-use crossterm::{
-    event::{
-        self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
-        MouseEventKind,
+use ratatui::{
+    crossterm::{
+        event::{
+            self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, MouseButton, MouseEvent,
+            MouseEventKind,
+        },
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
     },
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    prelude::*,
+    widgets::Paragraph,
 };
-use ratatui::{prelude::*, widgets::Paragraph};
 
 /// A custom widget that renders a button with a label, theme and state.
 #[derive(Debug, Clone)]

diff --git a/examples/demo/crossterm.rs b/examples/demo/crossterm.rs
@@ -4,12 +4,14 @@ use std::{
     time::{Duration, Instant},
 };
 
-use crossterm::{
-    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
-    execute,
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+use ratatui::{
+    crossterm::{
+        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+        execute,
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    },
+    prelude::*,
 };
-use ratatui::prelude::*;
 
 use crate::{app::App, ui};
 

diff --git a/examples/demo/termion.rs b/examples/demo/termion.rs
@@ -1,11 +1,13 @@
 use std::{error::Error, io, sync::mpsc, thread, time::Duration};
 
-use ratatui::prelude::*;
-use termion::{
-    event::Key,
-    input::{MouseTerminal, TermRead},
-    raw::IntoRawMode,
-    screen::IntoAlternateScreen,
+use ratatui::{
+    prelude::*,
+    termion::{
+        event::Key,
+        input::{MouseTerminal, TermRead},
+        raw::IntoRawMode,
+        screen::IntoAlternateScreen,
+    },
 };
 
 use crate::{app::App, ui};

diff --git a/examples/demo/termwiz.rs b/examples/demo/termwiz.rs
@@ -3,10 +3,12 @@ use std::{
     time::{Duration, Instant},
 };
 
-use ratatui::prelude::*;
-use termwiz::{
-    input::{InputEvent, KeyCode},
-    terminal::Terminal as TermwizTerminal,
+use ratatui::{
+    prelude::*,
+    termwiz::{
+        input::{InputEvent, KeyCode},
+        terminal::Terminal as TermwizTerminal,
+    },
 };
 
 use crate::{app::App, ui};

diff --git a/examples/demo2/app.rs b/examples/demo2/app.rs
@@ -1,9 +1,12 @@
 use std::time::Duration;
 
 use color_eyre::{eyre::Context, Result};
-use crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind};
 use itertools::Itertools;
-use ratatui::{prelude::*, widgets::*};
+use ratatui::{
+    crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind},
+    prelude::*,
+    widgets::*,
+};
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 use crate::{destroy, tabs::*, term, THEME};

diff --git a/examples/demo2/term.rs b/examples/demo2/term.rs
@@ -4,12 +4,14 @@ use std::{
 };
 
 use color_eyre::{eyre::WrapErr, Result};
-use crossterm::{
-    event::{self, Event},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
-    ExecutableCommand,
+use ratatui::{
+    crossterm::{
+        event::{self, Event},
+        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+        ExecutableCommand,
+    },
+    prelude::*,
 };
-use ratatui::prelude::*;
 
 pub fn init() -> Result<Terminal<impl Backend>> {
     // this size is to match the size of the terminal when running the demo