1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
use std::{
io::{self, Write},
time::Duration,
};
use futures_lite::StreamExt;
use tui::layout::Rect;
use crate::{
render::tui::{draw, ticker},
Root, Throughput, WeakRoot,
};
/// Configure the terminal user interface
#[derive(Clone)]
pub struct Options {
/// The initial title to show for the whole window.
///
/// Can be adjusted later by sending `Event::SetTitle(…)`
/// into the event stream, see see [`tui::render_with_input(…events)`](./fn.render_with_input.html) function.
pub title: String,
/// The amount of frames to draw per second. If below 1.0, it determines the amount of seconds between the frame.
///
/// *e.g.* 1.0/4.0 is one frame every 4 seconds.
pub frames_per_second: f32,
/// If true, (default false), we will keep track of the previous progress state to derive
/// continuous throughput information from. Throughput will only show for units which have
/// explicitly enabled it, it is opt-in.
///
/// This comes at the cost of additional memory and CPU time.
pub throughput: bool,
/// If set, recompute the column width of the task tree only every given frame. Otherwise the width will be recomputed every frame.
///
/// Use this if there are many short-running tasks with varying names paired with high refresh rates of multiple frames per second to
/// stabilize the appearance of the TUI.
///
/// For example, setting the value to 40 will with a frame rate of 20 per second will recompute the column width to fit all task names
/// every 2 seconds.
pub recompute_column_width_every_nth_frame: Option<usize>,
/// The initial window size.
///
/// If unset, it will be retrieved from the current terminal.
pub window_size: Option<Rect>,
/// If true (default: true), we will stop running the TUI once the progress isn't available anymore (went out of scope).
pub stop_if_progress_missing: bool,
}
impl Default for Options {
fn default() -> Self {
Options {
title: "Progress Dashboard".into(),
frames_per_second: 10.0,
throughput: false,
recompute_column_width_every_nth_frame: None,
window_size: None,
stop_if_progress_missing: true,
}
}
}
/// A line as used in [`Event::SetInformation`](./enum.Event.html#variant.SetInformation)
#[derive(Debug, Clone, Eq, PartialEq)]
pub enum Line {
/// Set a title with the given text
Title(String),
/// Set a line of text with the given content
Text(String),
}
/// The variants represented here allow the user to control when the GUI can be shutdown.
#[derive(Debug, Clone, Copy)]
pub enum Interrupt {
/// Immediately exit the GUI event loop when there is an interrupt request.
///
/// This is the default when the event loop is entered.
Instantly,
/// Instead of exiting the event loop instantly, wait until the next Interrupt::Instantly
/// event is coming in.
Deferred,
}
#[derive(Clone, Copy)]
pub(crate) enum InterruptDrawInfo {
Instantly,
/// Boolean signals if interrupt is requested
Deferred(bool),
}
#[cfg(not(any(feature = "render-tui-crossterm", feature = "render-tui-termion")))]
compile_error!(
"Please set either the 'render-tui-crossterm' or 'render-tui-termion' feature whne using the 'render-tui'"
);
use crosstermion::crossterm::event::{KeyCode, KeyEventKind, KeyModifiers};
use crosstermion::{
input::{key_input_stream, Key},
terminal::{tui::new_terminal, AlternateRawScreen},
};
/// An event to be sent in the [`tui::render_with_input(…events)`](./fn.render_with_input.html) stream.
///
/// This way, the TUI can be instructed to draw frames or change the information to be displayed.
#[derive(Debug, Clone)]
pub enum Event {
/// Draw a frame
Tick,
/// Send any key - can be used to simulate user input, and is typically generated by the TUI's own input loop.
Input(Key),
/// Change the size of the window to the given rectangle.
///
/// Useful to embed the TUI into other terminal user interfaces that can resize dynamically.
SetWindowSize(Rect),
/// Set the title of the progress dashboard
SetTitle(String),
/// Provide a list of titles and lines to populate the side bar on the right.
SetInformation(Vec<Line>),
/// The way the GUI will respond to interrupt requests. See `Interrupt` for more information.
SetInterruptMode(Interrupt),
}
/// Returns a future that draws the terminal user interface indefinitely.
///
/// * `progress` is the progress tree whose information to visualize.
/// It will usually be changing constantly while the TUI holds it.
/// * `options` are configuring the TUI.
/// * `events` is a stream of `Event`s which manipulate the TUI while it is running
///
/// Failure may occour if there is no terminal to draw into.
pub fn render_with_input(
out: impl std::io::Write,
progress: impl WeakRoot,
options: Options,
events: impl futures_core::Stream<Item = Event> + Send + Unpin,
) -> Result<impl std::future::Future<Output = ()>, std::io::Error> {
let Options {
title,
frames_per_second,
window_size,
recompute_column_width_every_nth_frame,
throughput,
stop_if_progress_missing,
} = options;
let mut terminal = new_terminal(AlternateRawScreen::try_from(out)?)?;
terminal.hide_cursor()?;
let duration_per_frame = Duration::from_secs_f32(1.0 / frames_per_second);
let key_receive = key_input_stream();
let render_fut = async move {
let mut state = draw::State {
title,
duration_per_frame,
..draw::State::default()
};
if throughput {
state.throughput = Some(Throughput::default());
}
let mut interrupt_mode = InterruptDrawInfo::Instantly;
let (entries_cap, messages_cap) = progress
.upgrade()
.map(|p| (p.num_tasks(), p.messages_capacity()))
.unwrap_or_default();
let mut entries = Vec::with_capacity(entries_cap);
let mut messages = Vec::with_capacity(messages_cap);
let mut events = ticker(duration_per_frame)
.map(|_| Event::Tick)
.or(key_receive.map(Event::Input))
.or(events);
let mut tick = 0usize;
let store_task_size_every = recompute_column_width_every_nth_frame.unwrap_or(1).max(1);
while let Some(event) = events.next().await {
let mut skip_redraw = false;
match event {
Event::Tick => {}
Event::Input(key) if key.kind != KeyEventKind::Release => match key.code {
KeyCode::Char('c') | KeyCode::Char('[') if key.modifiers.contains(KeyModifiers::CONTROL) => {
match interrupt_mode {
InterruptDrawInfo::Instantly => break,
InterruptDrawInfo::Deferred(_) => interrupt_mode = InterruptDrawInfo::Deferred(true),
}
}
KeyCode::Esc | KeyCode::Char('q') => match interrupt_mode {
InterruptDrawInfo::Instantly => break,
InterruptDrawInfo::Deferred(_) => interrupt_mode = InterruptDrawInfo::Deferred(true),
},
KeyCode::Char('`') => state.hide_messages = !state.hide_messages,
KeyCode::Char('~') => state.messages_fullscreen = !state.messages_fullscreen,
KeyCode::Char('J') => state.message_offset = state.message_offset.saturating_add(1),
KeyCode::Char('D') => state.message_offset = state.message_offset.saturating_add(10),
KeyCode::Char('j') => state.task_offset = state.task_offset.saturating_add(1),
KeyCode::Char('d') => state.task_offset = state.task_offset.saturating_add(10),
KeyCode::Char('K') => state.message_offset = state.message_offset.saturating_sub(1),
KeyCode::Char('U') => state.message_offset = state.message_offset.saturating_sub(10),
KeyCode::Char('k') => state.task_offset = state.task_offset.saturating_sub(1),
KeyCode::Char('u') => state.task_offset = state.task_offset.saturating_sub(10),
KeyCode::Char('[') => state.hide_info = !state.hide_info,
KeyCode::Char('{') => state.maximize_info = !state.maximize_info,
_ => skip_redraw = true,
},
Event::Input(_) => skip_redraw = true,
Event::SetWindowSize(bound) => state.user_provided_window_size = Some(bound),
Event::SetTitle(title) => state.title = title,
Event::SetInformation(info) => state.information = info,
Event::SetInterruptMode(mode) => {
interrupt_mode = match mode {
Interrupt::Instantly => {
if let InterruptDrawInfo::Deferred(true) = interrupt_mode {
break;
}
InterruptDrawInfo::Instantly
}
Interrupt::Deferred => InterruptDrawInfo::Deferred(match interrupt_mode {
InterruptDrawInfo::Deferred(interrupt_requested) => interrupt_requested,
_ => false,
}),
};
}
}
if !skip_redraw {
tick += 1;
let progress = match progress.upgrade() {
Some(progress) => progress,
None if stop_if_progress_missing => break,
None => continue,
};
progress.sorted_snapshot(&mut entries);
if stop_if_progress_missing && entries.is_empty() {
break;
}
let terminal_window_size = terminal.pre_render().expect("pre-render to work");
let window_size = state
.user_provided_window_size
.or(window_size)
.unwrap_or(terminal_window_size);
let buf = terminal.current_buffer_mut();
if !state.hide_messages {
progress.copy_messages(&mut messages);
}
draw::all(&mut state, interrupt_mode, &entries, &messages, window_size, buf);
if tick == 1 || tick % store_task_size_every == 0 || state.last_tree_column_width.unwrap_or(0) == 0 {
state.next_tree_column_width = state.last_tree_column_width;
}
terminal.post_render().expect("post render to work");
}
}
// Make sure the terminal responds right away when this future stops, to reset back to the 'non-alternate' buffer
drop(terminal);
io::stdout().flush().ok();
};
Ok(render_fut)
}
/// An easy-to-use version of `render_with_input(…)` that does not allow state manipulation via an event stream.
pub fn render(
out: impl std::io::Write,
progress: impl WeakRoot,
config: Options,
) -> Result<impl std::future::Future<Output = ()>, std::io::Error> {
render_with_input(out, progress, config, futures_lite::stream::pending())
}