10 releases
0.3.4 | Sep 10, 2023 |
---|---|
0.3.3 | Apr 21, 2023 |
0.3.2 | Mar 6, 2023 |
0.3.0 | Feb 8, 2023 |
0.1.1 | Oct 5, 2022 |
#138 in Command-line interface
380 downloads per month
Used in r3bl_rs_utils
1.5MB
22K
SLoC
Context
R3BL TUI library & suite of apps focused on developer productivity
We are working on building command line apps in Rust which have rich text user interfaces (TUI). We want to lean into the terminal as a place of productivity, and build all kinds of awesome apps for it.
-
๐ฎ Instead of just building one app, we are building a library to enable any kind of rich TUI development w/ a twist: taking concepts that work really well for the frontend mobile and web development world and re-imagining them for TUI & Rust.
- Taking things like React, JSX, CSS, and Redux, but making everything async (they can be run in parallel & concurrent via Tokio).
- Even the thread running the main event loop doesn't block since it is async.
- Using proc macros to create DSLs to implement CSS & JSX.
-
๐ We are building apps to enhance developer productivity & workflows.
- The idea here is not to rebuild tmux in Rust (separate processes mux'd onto a single terminal window). Rather it is to build a set of integrated "apps" (or "tasks") that run in the same process that renders to one terminal window.
- Inside of this terminal window, we can implement things like "app" switching, routing, tiling layout, stacking layout, etc. so that we can manage a lot of TUI apps (which are tightly integrated) that are running in the same process, in the same window. So you can imagine that all these "app"s have shared application state (that is in a Redux store). Each "app" may also have its own Redux store.
- Here are some examples of the types of "app"s we want to build:
- multi user text editors w/ syntax highlighting
- integrations w/ github issues
- integrations w/ calendar, email, contacts APIs
r3bl_tui crate
This crate is related to the first thing that's described above. It provides lots of useful functionality to help you build TUI (text user interface) apps, along w/ general niceties & ergonomics that all Rustaceans ๐ฆ can enjoy ๐:
- Text User Interface engine for Rust
- Examples to get you started
- How does layout, rendering, and event handling work in general?
- Life of an input event
- The window
- Layout and styling
- Component, ComponentRegistry, focus management, and event routing
- Input event specificity
- Rendering and painting
- Redux for state management
- How does the editor component work?
- How do modal dialog boxes work?
- Grapheme support
- Lolcat support
- Other crates that depend on this
- Issues, comments, feedback, and PRs
Text User Interface engine for Rust
You can build fully async TUI (text user interface) apps with a modern API that brings the best of the web frontend development ideas to TUI apps written in Rust:
- Reactive & unidirectional data flow architecture from frontend web development (React, Redux).
- Responsive design w/ CSS, flexbox like concepts.
- Declarative style of expressing styling and layouts.
And since this is using Rust and Tokio you get the advantages of concurrency and parallelism built-in. No more blocking the main thread for user input, for async middleware, or even rendering ๐.
This framework is loosely coupled and strongly coherent meaning that you can pick and choose whatever pieces you would like to use w/out having the cognitive load of having to grok all the things in the codebase. Its more like a collection of mostly independent modules that work well w/ each other, but know very little about each other.
Here are some framework highlights:
- An easy to use and approachable API that is inspired by React, JSX, CSS, and Redux. Lots of
components and things are provided for you so you don't have to build them from scratch. This is a
full featured component library including:
- Redux for state management (fully async, concurrent & parallel).
- CSS like declarative styling engine.
- CSS flexbox like declarative layout engine which is fully responsive. You can resize your terminal window and everything will be laid out correctly.
- A terminal independent underlying rendering and painting engine (can use crossterm or termion or whatever you want).
- Markdown text editor w/ syntax highlighting support, metadata (tags, title, author, date), smart lists. This uses a custom Markdown parser and custom syntax highligther. Syntax highlighting for code blocks is provided by the syntect crate.
- Modal dialog boxes. And autocompletion dialog boxes.
- Lolcat (color gradients) implementation w/ a rainbow color-wheel palette. All the color output is sensitive to the capabilities of the terminal. Colors are gracefully downgraded from truecolor, to ANSI256, to grayscale.
- Support for Unicode grapheme clusters in strings. You can safely use emojis, and other Unicode characters in your TUI apps.
- Support for mouse events.
- The entire TUI framework itself supports concurrency & parallelism (user input, rendering, etc. are generally non blocking).
- It is fast! There are no needless re-renders, or flickering. Animations and color changes are smooth (check this out for yourself by running the examples). You can even build your TUI in layers (like z-order in a browser's DOM).
Examples to get you started
Video of the demo in action
Here's a video of a prototype of R3BL CMDR app built using this TUI engine.
Run the demo locally
Once you've cloned the repo to a folder on your computer, you can run the examples you see in the video with the following commands:
cd tui/examples
cargo run --release --example demo
These examples cover the entire surface area of the TUI API. You can also take a look at the
tests in the source (tui/src/
) as well. A lot of
fish
scripts are provided at the
top level directory of the repo which allow you to easily:
run-release.fish
: This will simply run the examples w/ the release build (so it will be fast). You can watch the logs by runninglog.fish
.run.fish
: This will simply run the examples. You can watch the logs by runninglog.fish
.test.fish
: Run all the tests (in all crates in the Rust workspace).build.fish
: build the code in all the crates in the Rust workspace.log.fish
: Run the logger to see log output.run-with-flamegraph-profiling.fish
: This will run the examples and generate a flamegraph at the end so you can see profile the performance of the app.run-with-crash-reporting.fish
: This will run the examples and generate acrash_log.txt
file (in thetui
folder) in case the app crashes. This is useful for debugging.
How does layout, rendering, and event handling work in general?
- The
App
trait impl is the main entry point for laying out the entire application. And this is where thecomponent_registry
lives and all theComponent
s are created and added to the registry. - When an
App
trait impl is created by a call toApp::new_shared()
, then theinit()
method is called, which should populate thecomponent_registry
with all theComponent
s that will be used in the application. - This sets everything up so that
app_render()
andapp_handle_event()
can be called at a later time. - The
app_render()
method is responsible for creating the layout by usingSurface
andFlexBox
to arrange whateverComponent
s are in thecomponent_registry
. - The
app_handle_event()
method is responsible for handling events that are sent to theApp
trait when user input is detected from the keyboard or mouse.
Life of an input event
There is a clear separation of concerns in this module. To illustrate what goes where, and how things work let's look at an example that puts the main event loop front and center & deals w/ how the system handles an input event (key press or mouse).
- The diagram below shows an app that has 3 [Component]s for (flexbox like) layout & (CSS like) styling.
- Let's say that you run this app (by hypothetically executing
cargo run
). - And then you click or type something in the terminal window that you're running this app in.
๐งโจ๏ธ๐ฑ๏ธ
input โ [TerminalWindow]
event โ โ [ComponentRegistry] creates
โ [App] โโโโโโโโโโโโ [Component]s at 1st render
โ โ
โ โ โโโโโโโโ id=1 has focus
โ โ โ
โ โโ [Component] id=1 โโโโ
โ โโ [Component] id=2 โ
โ โโ [Component] id=3 โ
default โ
handler โโโโโโโโโโโโโโโโโโโโโโโโโ
Let's trace the journey through the diagram when an input even is generated by the user (eg: a key
press, or mouse event). When the app is started via cargo run
it sets up a main loop, and lays out
all the 3 components, sizes, positions, and then paints them. Then it asynchronously listens for
input events (no threads are blocked). When the user types something, this input is processed by the
main loop of [TerminalWindow].
- The [Component] that is in [FlexBox] w/
id=1
currently has focus. - When an input event comes in from the user (key press or mouse input) it is routed to the [App] first, before [TerminalWindow] looks at the event.
- The specificity of the event handler in [App] is higher than the default input handler in [TerminalWindow]. Further, the specificity of the [Component] that currently has focus is the highest. In other words, the input event gets routed by the [App] to the [Component] that currently has focus ([Component] id=1 in our example).
- Since it is not guaranteed that some [Component] will have focus, this input event can then be handled by [App], and if not, then by [TerminalWindow]'s default handler. If the default handler doesn't process it, then it is simply ignored.
- In this journey, as the input event is moved between all these different entities, each entity decides whether it wants to handle the input event or not. If it does, then it returns an enum indicating that the event has been consumed, else, it returns an enum that indicates the event should be propagated.
Now that we have seen this whirlwind overview of the life of an input event, let's look at the details in each of the sections below.
Here's an architecture diagram that will be useful to keep in mind as we go through the details of the following sections:
The window
The main building blocks of a TUI app are:
- [TerminalWindow] - You can think of this as the main "window" of the app. All the content of your app is painted inside of this "window". And the "window" conceptually maps to the screen that is contained inside your terminal emulator program (eg: tilix, Terminal.app, etc). Your TUI app will end up taking up 100% of the screen space of this terminal emulator. It will also enter raw mode, and paint to an alternate screen buffer, leaving your original scroll back buffer and history intact. When you exit this TUI app, it will return your terminal to where you'd left off. You don't write this code, this is something that you use.
- [App] - This is where you write your code. You pass in a [App] to the [TerminalWindow] to bootstrap your TUI app. You can just use [App] to build your app, if it is a simple one & you don't really need any sophisticated layout or styling. But if you want layout and styling, now we have to deal with [FlexBox], [Component], and crate::Style.
Layout and styling
Inside of your [App] if you want to use flexbox like layout and CSS like styling you can think of composing your code in the following way:
- [App] is like a box or container. You can attach styles and an id here. The id has to be unique, and you can reference as many styles as you want from your stylesheet. Yes, cascading styles are supported! ๐ You can put boxes inside of boxes. You can make a container box and inside of that you can add other boxes (you can give them a direction and even relative sizing out of 100%).
- As you approach the "leaf" nodes of your layout, you will find [Component] trait objects. These are black boxes which are sized, positioned, and painted relative to their parent box. They get to handle input events and render [RenderOp]s into a [RenderPipeline]. This is kind of like virtual DOM in React. This queue of commands is collected from all the components and ultimately painted to the screen, for each render! You can also use Redux to maintain your app's state, and dispatch actions to the store, and even have async middleware!
Component, ComponentRegistry, focus management, and event routing
Typically your [App] will look like this:
/// Async trait object that implements the [App] trait.
#[derive(Default)]
pub struct AppWithLayout {
pub component_registry: ComponentRegistry<AppWithLayoutState, AppWithLayoutAction>,
pub has_focus: HasFocus,
}
As we look at [Component] & [App] more closely we will find a curious thing [ComponentRegistry] (that is managed by the [App]). The reason this exists is for input event routing. The input events are routed to the [Component] that currently has focus.
The [HasFocus] struct takes care of this. This provides 2 things:
- It holds an
id
of a [FlexBox] / [Component] that has focus. - It also holds a map that holds a crate::Position for each
id
. This is used to represent a cursor (whatever that means to your app & component). This cursor is maintained for eachid
. This allows a separate cursor for each [Component] that has focus. This is needed to build apps like editors and viewers that maintains a cursor position between focus switches.
Another thing to keep in mind is that the [App] and [TerminalWindow] is persistent between re-renders. The Redux store is also persistent between re-renders.
Input event specificity
[TerminalWindow] gives [Component] first dibs when it comes to handling input events. If it punts handling this event, it will be handled by the default input event handler. And if nothing there matches this event, then it is simply dropped.
Rendering and painting
The R3BL TUI engine uses a high performance compositor to render the UI to the terminal. This
ensures that only "pixels" that have changed are painted to the terminal. This is done by creating a
concept of PixelChar
which represents a single "pixel" in the terminal screen at a given col and
row index position. There are only as many PixelChar
s as there are rows and cols in a terminal
screen. And the index maps directly to the position of the pixel in the terminal screen.
Offscreen buffer
Here is an example of what a single row of rendered output might look like in a row of the
OffscreenBuffer
. This diagram shows each PixelChar
in row_index: 1
of the OffscreenBuffer
.
In this example, there are 80 columns in the terminal screen. This actual log output generated by
the TUI engine when logging is enabled.
row_index: 1
000 S โโโโโโโโณโโโโโโโโ001 P 'j'โfgโbg 002 P 'a'โfgโbg 003 P 'l'โfgโbg 004 P 'd'โfgโbg 005 P 'k'โfgโbg
006 P 'f'โfgโbg 007 P 'j'โfgโbg 008 P 'a'โfgโbg 009 P 'l'โfgโbg 010 P 'd'โfgโbg 011 P 'k'โfgโbg
012 P 'f'โfgโbg 013 P 'j'โfgโbg 014 P 'a'โfgโbg 015 P 'โ'โrev 016 S โโโโโโโโณโโโโโโโโ017 S โโโโโโโโณโโโโโโโโ
018 S โโโโโโโโณโโโโโโโโ019 S โโโโโโโโณโโโโโโโโ020 S โโโโโโโโณโโโโโโโโ021 S โโโโโโโโณโโโโโโโโ022 S โโโโโโโโณโโโโโโโโ023 S โโโโโโโโณโโโโโโโโ
024 S โโโโโโโโณโโโโโโโโ025 S โโโโโโโโณโโโโโโโโ026 S โโโโโโโโณโโโโโโโโ027 S โโโโโโโโณโโโโโโโโ028 S โโโโโโโโณโโโโโโโโ029 S โโโโโโโโณโโโโโโโโ
030 S โโโโโโโโณโโโโโโโโ031 S โโโโโโโโณโโโโโโโโ032 S โโโโโโโโณโโโโโโโโ033 S โโโโโโโโณโโโโโโโโ034 S โโโโโโโโณโโโโโโโโ035 S โโโโโโโโณโโโโโโโโ
036 S โโโโโโโโณโโโโโโโโ037 S โโโโโโโโณโโโโโโโโ038 S โโโโโโโโณโโโโโโโโ039 S โโโโโโโโณโโโโโโโโ040 S โโโโโโโโณโโโโโโโโ041 S โโโโโโโโณโโโโโโโโ
042 S โโโโโโโโณโโโโโโโโ043 S โโโโโโโโณโโโโโโโโ044 S โโโโโโโโณโโโโโโโโ045 S โโโโโโโโณโโโโโโโโ046 S โโโโโโโโณโโโโโโโโ047 S โโโโโโโโณโโโโโโโโ
048 S โโโโโโโโณโโโโโโโโ049 S โโโโโโโโณโโโโโโโโ050 S โโโโโโโโณโโโโโโโโ051 S โโโโโโโโณโโโโโโโโ052 S โโโโโโโโณโโโโโโโโ053 S โโโโโโโโณโโโโโโโโ
054 S โโโโโโโโณโโโโโโโโ055 S โโโโโโโโณโโโโโโโโ056 S โโโโโโโโณโโโโโโโโ057 S โโโโโโโโณโโโโโโโโ058 S โโโโโโโโณโโโโโโโโ059 S โโโโโโโโณโโโโโโโโ
060 S โโโโโโโโณโโโโโโโโ061 S โโโโโโโโณโโโโโโโโ062 S โโโโโโโโณโโโโโโโโ063 S โโโโโโโโณโโโโโโโโ064 S โโโโโโโโณโโโโโโโโ065 S โโโโโโโโณโโโโโโโโ
066 S โโโโโโโโณโโโโโโโโ067 S โโโโโโโโณโโโโโโโโ068 S โโโโโโโโณโโโโโโโโ069 S โโโโโโโโณโโโโโโโโ070 S โโโโโโโโณโโโโโโโโ071 S โโโโโโโโณโโโโโโโโ
072 S โโโโโโโโณโโโโโโโโ073 S โโโโโโโโณโโโโโโโโ074 S โโโโโโโโณโโโโโโโโ075 S โโโโโโโโณโโโโโโโโ076 S โโโโโโโโณโโโโโโโโ077 S โโโโโโโโณโโโโโโโโ
078 S โโโโโโโโณโโโโโโโโ079 S โโโโโโโโณโโโโโโโโ080 S โโโโโโโโณโโโโโโโโspacer [ 0, 16-80 ]
When RenderOps
are executed and used to create an OffscreenBuffer
that maps to the size of the
terminal window, clipping is performed automatically. This means that it isn't possible to move the
caret outside of the bounds of the viewport (terminal window size). And it isn't possible to paint
text that is larger than the size of the offscreen buffer. The buffer really represents the current
state of the viewport. Scrolling has to be handled by the component itself (an example of this is
the editor component).
Each PixelChar
can be one of 4 things:
- Space. This is just an empty space. There is no flickering in the TUI engine. When a new offscreen buffer is created, it is fulled w/ spaces. Then components paint over the spaces. Then the diffing algorithm only paints over the pixels that have changed. You don't have to worry about clearing the screen and painting, which typically will cause flickering in terminals. You also don't have to worry about printing empty spaces over areas that you would like to clear between renders. All of this handled by the TUI engine.
- Void. This is a special pixel that is used to indicate that the pixel should be ignored. It is used to indicate a wide emoji is to the left somewhere. Most terminals don't support emojis, so there's a discrepancy between the display width of the character and its index in the string.
- Plain text. This is a normal pixel which wraps a single character that maybe a grapheme
cluster segment. Styling information is encoded in each
PixelChar::PlainText
and is used to paint the screen via the diffing algorithm which is smart enough to "stack" styles that appear beside each other for quicker rendering in terminals. - ANSI text. Styling information in not available w/ these characters because the styling
information is encoded in the ANSI escape codes.
lolcat_api.rs
generates these ANSI strings for the rainbow effect. An example of this is the outline around a modal dialog box.
Render pipeline
The following diagram provides a high level overview of how apps (that contain components, which may contain components, and so on) are rendered to the terminal screen.
Each component produces a RenderPipeline
, which is a map of ZOrder
and Vec<RenderOps>
.
RenderOps
are the instructions that are grouped together, such as move the caret to a position,
set a color, and paint some text.
Inside of each RenderOps
the caret is stateful, meaning that the caret position is remembered
after each RenderOp
is executed. However, once a new RenderOps
is executed, the caret position
reset just for that RenderOps
. Caret position is not stored globally. You should read more about
"atomic paint operations" in the RenderOp
documentation.
Once a set of these RenderPipeline
s have been generated, typically after the user enters some
input event, and that produces a new state which then has to be rendered, they are combined and
painted into an OffscreenBuffer
.
First render
The paint.rs
file contains the paint
function, which is the entry point for all rendering. Once
the first render occurs, the OffscreenBuffer
that is generated is saved to GlobalSharedState
.
The following table shows the various tasks that have to be performed in order to render to an
OffscreenBuffer
. There is a different code path that is taken for ANSI text and plain text (which
includes StyledText
which is just plain text with a color). Syntax highlighted text is also just
StyledText
. The ANSI text is an example of text that is generated by the lolcat_api.rs
.
UTF-8 | ANSI | Task |
---|---|---|
Y | Y | convert RenderPipeline to List<List<PixelChar>> (OffscreenBuffer ) |
Y | Y | paint each PixelChar in List<List<PixelChar>> to stdout using OffscreenBufferPainterImplCrossterm |
Y | Y | save the List<List<PixelChar>> to GlobalSharedState |
Currently only crossterm
is supported for actually painting to the terminal. But this process is
really simple making it very easy to swap out other terminal libraries such as termion
, or even a
GUI backend, or some other custom output driver.
Subsequent render
Since the OffscreenBuffer
is cached in GlobalSharedState
a diff to be performed for subsequent
renders. And only those diff chunks are painted to the screen. This ensures that there is no flicker
when the content of the screen changes. It also minimizes the amount of work that the terminal or
terminal emulator has to do put the PixelChar
s on the screen.
Redux for state management
If you use Redux for state management, then you will create a crate::redux crate::Store that is
passed into the [TerminalWindow]. For more detailed information on Redux, please read the
docs for the r3bl_redux
create.
Here's an example of this.
use crossterm::event::*;
use r3bl_rs_utils::*;
use super::*;
const DEBUG: bool = true;
pub async fn run_app() -> CommonResult<()> {
throws!({
if DEBUG {
try_to_set_log_level(log::LevelFilter::Trace)?;
} else {
try_to_set_log_level(log::LevelFilter::Off)?;
}
// Create store.
let store = create_store().await;
// Create an App (renders & responds to user input).
let shared_app = AppWithLayout::new_shared();
// Exit if these keys are pressed.
let exit_keys: Vec<KeyEvent> = vec![KeyEvent {
code: KeyCode::Char('q'),
modifiers: KeyModifiers::CONTROL,
}];
// Create a window.
TerminalWindow::main_event_loop(store, shared_app, exit_keys).await?
});
}
async fn create_store() -> Store<AppWithLayoutState, AppWithLayoutAction> {
let mut store: Store<AppWithLayoutState, AppWithLayoutAction> = Store::default();
store.add_reducer(MyReducer::default()).await;
store
}
/// Action enum.
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum Action {
Add(i32, i32),
AddPop(i32),
Clear,
MiddlewareCreateClearAction,
Noop,
}
impl Default for Action {
fn default() -> Self {
Action::Noop
}
}
/// State.
#[derive(Clone, Default, PartialEq, Debug)]
pub struct State {
pub stack: Vec<i32>,
}
/// Reducer function (pure).
#[derive(Default)]
struct MyReducer;
#[async_trait]
impl AsyncReducer<State, Action> for MyReducer {
async fn run(
&self,
action: &Action,
state: &mut State,
) {
match action {
Action::Add(a, b) => {
let sum = a + b;
state.stack = vec![sum];
}
Action::AddPop(a) => {
let sum = a + state.stack[0];
state.stack = vec![sum];
}
Action::Clear => State {
state.stack.clear();
},
_ => {}
}
}
}
How does the editor component work?
The EditorComponent
struct can hold data in its own memory, in addition to relying on the state.
- It has an
EditorEngine
which holds syntax highlighting information, and configuration options for the editor (such as multiline mode enabled or not, syntax highlighting enabled or not, etc.). Note that this information lives outside of the state. - It also implements the
Component<S,A>
trait. - However, for the reusable editor component we need the data representing the document being edited
to be stored in the state (
EditorBuffer
) and not inside of theEditorComponent
itself.- This is why the state must implement the trait
HasEditorBuffers
which is where the document data is stored (the key is the id of the flex box in which the editor component is placed). - The
EditorBuffer
contains the text content in aVec
ofUnicodeString
. Where each line is represented by aUnicodeString
. It also contains the scroll offset, caret position, and file extension for syntax highlighting.
- This is why the state must implement the trait
In other words,
EditorEngine
-> This goes inEditorComponent
- Contains the logic to process keypresses and modify an editor buffer.
EditorBuffer
-> This goes in theState
- Contains the data that represents the document being edited. This contains the caret (insertion point) position and scroll position. And in the future can contain lots of other information such as undo / redo history, etc.
Here are the connection points w/ the impl of Component<S,A>
in EditorComponent
:
handle_event(input_event: &InputEvent, state: &S, shared_store: &SharedStore<S, A>)
- Can simply relay the arguments to
EditorEngine::apply(state.editor_buffer, input_event)
which will return anotherEditorBuffer
. - Return value can be dispatched to the store via an action
UpdateEditorBuffer(EditorBuffer)
.
- Can simply relay the arguments to
render(has_focus: &HasFocus, current_box: &FlexBox, state: &S, shared_store: &SharedStore<S,A>)
- Can simply relay the arguments to
EditorEngine::render(state.editor_buffer)
- Which will return a
RenderPipeline
.
- Can simply relay the arguments to
Painting the caret
Definitions
Caret
- the block that is visually displayed in a terminal which represents the insertion point for whatever is in focus. While only one insertion point is editable for the local user, there may be multiple of them, in which case there has to be a way to distinguish a local caret from a remote one (this can be done w/ bg color).
Cursor
- the global "thing" provided in terminals that shows by blinking usually where the cursor is. This cursor is moved around and then paint operations are performed on various different areas in a terminal window to paint the output of render operations.
There are two ways of showing cursors which are quite different (each w/ very different constraints).
-
Using a global terminal cursor (we don't use this).
- Both termion::cursor and crossterm::cursor support this. The cursor has lots of effects like blink, etc.
- The downside is that there is one global cursor for any given terminal window. And this cursor
is constantly moved around in order to paint anything (eg:
MoveTo(col, row), SetColor, PaintText(...)
sequence).
-
Paint the character at the cursor w/ the colors inverted (or some other bg color) giving the visual effect of a cursor.
- This has the benefit that we can display multiple cursors in the app, since this is not global, rather it is component specific. For the use case requiring google docs style multi user editing where multiple cursors need to be shown, this approach can be used in order to implement that. Each user for eg can get a different caret background color to differentiate their caret from others.
- The downside is that it isn't possible to blink the cursor or have all the other "standard" cursor features that are provided by the actual global cursor (discussed above).
How do modal dialog boxes work?
A modal dialog box is different than a normal reusable component. This is because:
- It paints on top of the entire screen (in front of all other components, in ZOrder::Glass, and
outside of any layouts using
FlexBox
es). - Is "activated" by a keyboard shortcut (hidden otherwise). Once activated, the user can accept or cancel the dialog box. And this results in a callback being called w/ the result.
So this activation trigger must be done at the App
trait impl level (in the app_handle_event()
method). Also, when this trigger is detected it has to:
- Set the focus to the dialog box, so that it will appear on the next render. When trigger is
detected it will return a
EventPropagation::Consumed
which won't force a render. - Set the title and text via a dispatch of the action
SetDialogBoxTitleAndText
. This will force a render, and the title and text in the dialog box on next render.
There is a question about where does the response from the user (once a dialog is shown) go? This
seems as though it would be different in nature from an EditorComponent
but it is the same. Here's
why:
- The
EditorComponent
is always updating its buffer based on user input, and there's no "handler" for when the user performs some action on the editor. The editor needs to save all the changes to the buffer to the state. This requires the trait boundHasEditorBuffers
to be implemented by the state. - The dialog box seems different in that you would think that it doesn't always updating its state
and that the only time we really care about what state the dialog box has is when the user has
accepted something they've typed into the dialog box and this needs to be sent to the callback
function that was passed in when the component was created. However, due to the reactive nature of
the TUI engine, even before the callback is called (due to the user accepting or cancelling),
while the user is typing things into the dialog box, it has to be updating the state, otherwise,
re-rendering the dialog box won't be triggered and the user won't see what they're typing. This
means that even intermediate information needs to be recorded into the state via the
HasDialogBuffers
trait bound. This will hold stale data once the dialog is dismissed or accepted, but that's ok since the title and text should always be set before it is shown.- Note: it might be possible to save this type of intermediate data in
ComponentRegistry::user_data
. And it is possible forhandle_event()
to return aEventPropagation::ConsumedRerender
to make sure that changes are re-rendered. This approach may have other issues related to having both immutable and mutable borrows at the same time to some portion of the component registry if one is not careful.
- Note: it might be possible to save this type of intermediate data in
Two callback functions
When creating a new dialog box component, two callback functions are passed in:
on_dialog_press_handler()
- this will be called if the user choose no, or yes (w/ their typed text).on_dialog_editors_changed_handler()
- this will be called if the user types something into the editor.
How to use this dialog to make an HTTP request & pipe the results into a selection area?
So far we have covered the use case for a simple modal dialog box. In order to provide
auto-completion capabilities, via some kind of web service, there needs to be a slightly more
complex version of this. This is where the DialogEngineConfigOptions
struct comes in. It allows us
to create a dialog component and engine to be configured w/ the appropriate mode - simple or
autocomplete.
In autocomplete mode, an extra "results panel" is displayed, and the layout of the dialog is different on the screen. Instead of being in the middle of the screen, it starts at the top of the screen. The callbacks are the same.
How to make HTTP requests
Instead of using the reqwest
crate, we should use the hyper
crate (which is part of Tokio) and
drop support for reqwest
in all our crates.
Grapheme support
Unicode is supported (to an extent). There are some caveats. The crate::UnicodeStringExt trait has lots of great information on this graphemes and what is supported and what is not.
Lolcat support
An implementation of crate::lolcat::cat w/ a color wheel is provided.
Other crates that depend on this
This crate is a dependency of the following crates:
r3bl_rs_utils
crates (the "main" library)
Issues, comments, feedback, and PRs
Please report any issues to the issue tracker. And if you have any feature requests, feel free to add them there too ๐.
Dependencies
~15โ32MB
~486K SLoC