Mirrors/ratatui
2
0
Fork 0
mirror of https://github.com/ratatui-org/ratatui synced 2024-11-25 22:20:31 +00:00
Code Issues Projects Releases Packages Wiki Activity

refactor(colors_rgb): impl widget on mutable refs (#865)

Browse source 
This commit refactors the colors_rgb example to implement the Widget
trait on mutable references to the app and its sub-widgets. This allows
the app to update its state while it is being rendered.

Additionally the main and run functions are refactored to be similar to
the other recent examples. This uses a pattern where the App struct has
a `run` method that takes a terminal as an argument, and the main
function is in control of initializing and restoring the terminal and
installing the error hooks.
This commit is contained in:
Josh McKinney 2024-01-24 07:13:11 -08:00 committed by GitHub
parent d7132011f9
commit 7f42ec9713
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 184 additions and 136 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

320
examples/colors_rgb.rs
View file

@ -1,12 +1,22 @@
/// This example shows the full range of RGB colors that can be displayed in the terminal.
///
/// Requires a terminal that supports 24-bit color (true color) and unicode.
///
/// This example also demonstrates how implementing the Widget trait on a mutable reference
/// allows the widget to update its state while it is being rendered. This allows the fps
/// widget to update the fps calculation and the colors widget to update a cached version of
/// the colors to render instead of recalculating them every frame.
///
/// This is an alternative to using the StatefulWidget trait and a separate state struct. It is
/// useful when the state is only used by the widget and doesn't need to be shared with other
/// widgets.
use std::{
io::stdout,
panic,
time::{Duration, Instant},
};
use color_eyre::config::HookBuilder;
use color_eyre::{config::HookBuilder, eyre, Result};
use crossterm::{
event::{self, Event, KeyCode, KeyEventKind},
terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
@ -15,93 +25,204 @@ use crossterm::{
use palette::{convert::FromColorUnclamped, Okhsv, Srgb};
use ratatui::{prelude::*, widgets::*};
fn main() -> color_eyre::Result<()> {
App::run()
}
#[derive(Debug, Default)]
struct App {
should_quit: bool,
// a 2d vec of the colors to render, calculated when the size changes as this is expensive
// to calculate every frame
colors: Vec<Vec<Color>>,
last_size: Rect,
fps: Fps,
frame_count: usize,
/// The current state of the app (running or quit)
state: AppState,
/// A widget that displays the current frames per second
fps_widget: FpsWidget,
/// A widget that displays the full range of RGB colors that can be displayed in the terminal.
colors_widget: ColorsWidget,
}
#[derive(Debug, Default, PartialEq, Eq)]
enum AppState {
/// The app is running
#[default]
Running,
/// The user has requested the app to quit
Quit,
}
/// A widget that displays the current frames per second
#[derive(Debug)]
struct Fps {
struct FpsWidget {
/// The number of elapsed frames that have passed - used to calculate the fps
frame_count: usize,
/// The last instant that the fps was calculated
last_instant: Instant,
/// The current frames per second
fps: Option<f32>,
}
struct AppWidget<'a> {
title: Paragraph<'a>,
fps_widget: FpsWidget<'a>,
rgb_colors_widget: RgbColorsWidget<'a>,
}
/// A widget that displays the full range of RGB colors that can be displayed in the terminal.
///
/// This widget is animated and will change colors over time.
#[derive(Debug, Default)]
struct ColorsWidget {
/// The colors to render - should be double the height of the area as we render two rows of
/// pixels for each row of the widget using the half block character. This is computed any time
/// the size of the widget changes.
colors: Vec<Vec<Color>>,
struct FpsWidget<'a> {
fps: &'a Fps,
}
struct RgbColorsWidget<'a> {
/// The colors to render - should be double the height of the area
colors: &'a Vec<Vec<Color>>,
/// the number of elapsed frames that have passed - used to animate the colors
/// the number of elapsed frames that have passed - used to animate the colors by shifting the
/// x index by the frame number
frame_count: usize,
}
fn main() -> Result<()> {
install_error_hooks()?;
let terminal = init_terminal()?;
App::default().run(terminal)?;
restore_terminal()?;
Ok(())
}
impl App {
pub fn run() -> color_eyre::Result<()> {
install_panic_hook()?;
let mut terminal = init_terminal()?;
let mut app = Self::default();
while !app.should_quit {
app.tick();
terminal.draw(|frame| {
let size = frame.size();
app.setup_colors(size);
frame.render_widget(AppWidget::new(&app), size);
})?;
app.handle_events()?;
/// Run the app
///
/// This is the main event loop for the app.
pub fn run(mut self, mut terminal: Terminal<impl Backend>) -> Result<()> {
while self.is_running() {
terminal.draw(|frame| frame.render_widget(&mut self, frame.size()))?;
self.handle_events()?;
}
restore_terminal()?;
Ok(())
}
fn tick(&mut self) {
self.frame_count += 1;
self.fps.tick();
fn is_running(&self) -> bool {
matches!(self.state, AppState::Running)
}
fn handle_events(&mut self) -> color_eyre::Result<()> {
if event::poll(Duration::from_secs_f32(1.0 / 60.0))? {
/// Handle any events that have occurred since the last time the app was rendered.
///
/// Currently, this only handles the q key to quit the app.
fn handle_events(&mut self) -> Result<()> {
// Ensure that the app only blocks for a period that allows the app to render at
// approximately 60 FPS (this doesn't account for the time to render the frame, and will
// also update the app immediately any time an event occurs)
let timeout = Duration::from_secs_f32(1.0 / 60.0);
if event::poll(timeout)? {
if let Event::Key(key) = event::read()? {
if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
self.should_quit = true;
self.state = AppState::Quit;
};
}
}
Ok(())
}
}
fn setup_colors(&mut self, size: Rect) {
// only update the colors if the size has changed since the last time we rendered
if self.last_size.width == size.width && self.last_size.height == size.height {
return;
/// Implement the Widget trait for &mut App so that it can be rendered
///
/// This is implemented on a mutable reference so that the app can update its state while it is
/// being rendered. This allows the fps widget to update the fps calculation and the colors widget
/// to update the colors to render.
impl Widget for &mut App {
fn render(self, area: Rect, buf: &mut Buffer) {
use Constraint::*;
let [top, colors] = area.split(&Layout::vertical([Length(1), Min(0)]));
let [title, fps] = top.split(&Layout::horizontal([Min(0), Length(8)]));
Text::from("colors_rgb example. Press q to quit")
.centered()
.render(title, buf);
self.fps_widget.render(fps, buf);
self.colors_widget.render(colors, buf);
}
}
/// Default impl for FpsWidget
///
/// Manual impl is required because we need to initialize the last_instant field to the current
/// instant.
impl Default for FpsWidget {
fn default() -> Self {
Self {
frame_count: 0,
last_instant: Instant::now(),
fps: None,
}
self.last_size = size;
}
}
/// Widget impl for FpsWidget
///
/// This is implemented on a mutable reference so that we can update the frame count and fps
/// calculation while rendering.
impl Widget for &mut FpsWidget {
fn render(self, area: Rect, buf: &mut Buffer) {
self.calculate_fps();
if let Some(fps) = self.fps {
let text = format!("{:.1} fps", fps);
Text::from(text).render(area, buf);
}
}
}
impl FpsWidget {
/// Update the fps calculation.
///
/// This updates the fps once a second, but only if the widget has rendered at least 2 frames
/// since the last calculation. This avoids noise in the fps calculation when rendering on slow
/// machines that can't render at least 2 frames per second.
fn calculate_fps(&mut self) {
self.frame_count += 1;
let elapsed = self.last_instant.elapsed();
if elapsed > Duration::from_secs(1) && self.frame_count > 2 {
self.fps = Some(self.frame_count as f32 / elapsed.as_secs_f32());
self.frame_count = 0;
self.last_instant = Instant::now();
}
}
}
/// Widget impl for ColorsWidget
///
/// This is implemented on a mutable reference so that we can update the frame count and store a
/// cached version of the colors to render instead of recalculating them every frame.
impl Widget for &mut ColorsWidget {
/// Render the widget
fn render(self, area: Rect, buf: &mut Buffer) {
self.setup_colors(area);
let colors = &self.colors;
for (xi, x) in (area.left()..area.right()).enumerate() {
// animate the colors by shifting the x index by the frame number
let xi = (xi + self.frame_count) % (area.width as usize);
for (yi, y) in (area.top()..area.bottom()).enumerate() {
// render a half block character for each row of pixels with the foreground color
// set to the color of the pixel and the background color set to the color of the
// pixel below it
let fg = colors[yi * 2][xi];
let bg = colors[yi * 2 + 1][xi];
buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
}
}
self.frame_count += 1;
}
}
impl ColorsWidget {
/// Setup the colors to render.
///
/// This is called once per frame to setup the colors to render. It caches the colors so that
/// they don't need to be recalculated every frame.
fn setup_colors(&mut self, size: Rect) {
let Rect { width, height, .. } = size;
// double the height because each screen row has two rows of half block pixels
let height = height * 2;
self.colors.clear();
let height = height as usize * 2;
let width = width as usize;
// only update the colors if the size has changed since the last time we rendered
if self.colors.len() == height && self.colors[0].len() == width {
return;
}
self.colors = Vec::with_capacity(height);
for y in 0..height {
let mut row = Vec::new();
let mut row = Vec::with_capacity(width);
for x in 0..width {
let hue = x as f32 * 360.0 / width as f32;
let value = (height - y) as f32 / height as f32;
@ -117,98 +238,25 @@ impl App {
}
}
impl Fps {
fn tick(&mut self) {
self.frame_count += 1;
let elapsed = self.last_instant.elapsed();
// update the fps every second, but only if we've rendered at least 2 frames (to avoid
// noise in the fps calculation)
if elapsed > Duration::from_secs(1) && self.frame_count > 2 {
self.fps = Some(self.frame_count as f32 / elapsed.as_secs_f32());
self.frame_count = 0;
self.last_instant = Instant::now();
}
}
}
impl Default for Fps {
fn default() -> Self {
Self {
frame_count: 0,
last_instant: Instant::now(),
fps: None,
}
}
}
impl<'a> AppWidget<'a> {
fn new(app: &'a App) -> Self {
let title = Paragraph::new("colors_rgb example. Press q to quit").centered();
Self {
title,
fps_widget: FpsWidget { fps: &app.fps },
rgb_colors_widget: RgbColorsWidget {
colors: &app.colors,
frame_count: app.frame_count,
},
}
}
}
impl Widget for AppWidget<'_> {
fn render(self, area: Rect, buf: &mut Buffer) {
let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
let horizontal = Layout::horizontal([Constraint::Min(0), Constraint::Length(8)]);
let [top, colors] = area.split(&vertical);
let [title, fps] = top.split(&horizontal);
self.title.render(title, buf);
self.fps_widget.render(fps, buf);
self.rgb_colors_widget.render(colors, buf);
}
}
impl Widget for RgbColorsWidget<'_> {
fn render(self, area: Rect, buf: &mut Buffer) {
let colors = self.colors;
for (xi, x) in (area.left()..area.right()).enumerate() {
// animate the colors by shifting the x index by the frame number
let xi = (xi + self.frame_count) % (area.width as usize);
for (yi, y) in (area.top()..area.bottom()).enumerate() {
let fg = colors[yi * 2][xi];
let bg = colors[yi * 2 + 1][xi];
buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
}
}
}
}
impl<'a> Widget for FpsWidget<'a> {
fn render(self, area: Rect, buf: &mut Buffer) {
if let Some(fps) = self.fps.fps {
let text = format!("{:.1} fps", fps);
Paragraph::new(text).render(area, buf);
}
}
}
/// Install a panic hook that restores the terminal before panicking.
fn install_panic_hook() -> color_eyre::Result<()> {
/// Install color_eyre panic and error hooks
///
/// The hooks restore the terminal to a usable state before printing the error message.
fn install_error_hooks() -> Result<()> {
let (panic, error) = HookBuilder::default().into_hooks();
let panic = panic.into_panic_hook();
let error = error.into_eyre_hook();
color_eyre::eyre::set_hook(Box::new(move |e| {
eyre::set_hook(Box::new(move |e| {
let _ = restore_terminal();
error(e)
}))?;
std::panic::set_hook(Box::new(move |info| {
panic::set_hook(Box::new(move |info| {
let _ = restore_terminal();
panic(info)
}));
Ok(())
}
fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
fn init_terminal() -> Result<Terminal<impl Backend>> {
enable_raw_mode()?;
stdout().execute(EnterAlternateScreen)?;
let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
@ -217,7 +265,7 @@ fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
Ok(terminal)
}
fn restore_terminal() -> color_eyre::Result<()> {
fn restore_terminal() -> Result<()> {
disable_raw_mode()?;
stdout().execute(LeaveAlternateScreen)?;
Ok(())