Textual UI
More control in your TUIs!
This feature is the new form of interactive TUIs that not only allow you to make an interactive TUI based on a set of data for either a single pane or two panes, but you can also make your own interactive applications seamlessly by separating the rendering code and the key handling code into small functions. This achieves the goal of making textual UI code maintenance easier, while providing the most dynamic UI setup along with support for resize thanks to the screen feature.
To get started using this awesome feature, you can create a new class that implements the TextualUI abstract class and overrides the Render() function. Inside the function, you can return a string that consists of VT sequences resulting from several console writers, especially the cyclic writers.
Textual UI properties
In the class, there are several properties that you can modify at your discretion, such as the name and the refresh delay. This allows you to customize its behavior.
You can use the following properties:
Guid
Unique ID for the textual UI
State
State of the textual UI
Name
Display name of the textual UI
RefreshDelay
Sets the refresh delay in milliseconds. If set to zero or less than zero, this TUI doesn't refresh.
Keybindings
List of keybindings that you can use within the TUI
Fallback
Fallback binding in case a key doesn't bind to anything
Renderables
List of renderables that get rendered on top of what the Render() function has rendered
HelpPages
List of help pages for the interactive TUI
For the help pages, you'll have to override the HelpPages property with an array of InteractiveTuiHelpPage classes, which consist of a title, a description, and a body text.
Textual UI states
State of the textual UI can be one of the following:
Ready
This textual UI is ready, but hasn't started yet.
Rendering
This textual UI is waiting for the render code to complete.
Waiting
This textual UI is waiting for user input.
Busy
This textual UI is busy because it's processing user input.
Bailing
This textual UI is about to exit and go back to the Ready state.
Textual UI tools
Some of the textual UI tools are available to help build interactive applications. You can also access the TextualUITools class to perform the following operations:
RunTui()
Starts the TUI main loop, clears the screen, waits for user input, and processes it until the TUI has been requested to exit.
ExitTui()
Sets the state of the interactive TUI to Bailing so that the TUI can exit gracefully.
RequireRefresh()
Tells the TUI to refresh on the next render.
Defining Keybindings
When defining keybindings, you can edit the Keybindings property to add your custom keybindings, but it's preferrable to either place them in a constructor or in the overridden value, and to define the delegates in separate private functions inside the UI class.
Defining keybindings
To define a keybinding in your interactive TUI, use the Keybindings.Add() statement to pass in a tuple of the following two variables:
A
Keybindinginstance that matches the key and its modifiers (mouse or keyboard) that you want to bind a specific action to.An action delegate or lambda function that tells the interactive TUI what to do.
The following four arguments are optional for lambda expressions, but required for delegates:
Interactive TUI instance that specifies the running TUI.
Keyboard press info defined by the ConsoleKeyInfo struct.
Mouse event info defined by the PointerEventContext class.
Removing keybindings
To remove a keybinding in your interactive TUI, use the Keybindings.RemoveAt() function.
To remove all keybindings in your interactive TUI, use the Keybindings.Clear() function.
Make sure that keybindings don't conflict when adding a new keybinding.
Examples
There are two examples as defined in the test application bundled with the source code of Terminaux:
This example provides you with a simple interactive TUI showing three boxes that you can control using the keybindings defined in the constructor of the interactive TUI.
Here's the companion code to start the interactive TUI for the above class:
Here's the resulting picture of the interactive TUI:
This example provides you with a refreshing interactive TUI showing three boxes, one of which is constantly changing color according to the number of frames rendered, that you can control using the keybindings defined in the constructor of the interactive TUI.
Here's the companion code that executes the above TUI class:
Here's the resulting picture for the TUI:
Last updated