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 renderables. You can find out more about the renderables here.

Cyclic Writers

Before this feature has been implemented, the interactive TUI feature consisted of just data arrays with two panes, which made cases that required something outside that scope unsolvable. The new feature promises to remove this limitation. Meanwhile, you can still use the older interactive TUI, which was first implemented in the Nitrocid KS 0.1.0 milestones in 2022, here.

In the class, there are several properties that you can modify at your discretion, such as the name and the refresh delay. You can use the following properties:

• Guid: Unique ID for the textual UI (reserved for future use)

• State: State of the textual UI, which is 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.

• Name: Display name of the textual UI (reserved for future use)

• 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.

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. Also, make sure that you don't place conflicting keybindings when trying to add them.

In addition to that, 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.

Examples

There are two examples as defined in the test application bundled with the source code of Terminaux:

Simple

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.

https://github.com/Aptivi/Terminaux/blob/main/Terminaux.Console/Fixtures/Cases/CaseData/TextualUiSimpleTestData.cs

//
// Terminaux  Copyright (C) 2023-2024  Aptivi
//
// This file is part of Terminaux
//
// Terminaux is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Terminaux is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY, without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//

using System;
using System.Text;
using Terminaux.Base;
using Terminaux.Colors.Data;
using Terminaux.Inputs.Interactive;
using Terminaux.Inputs.Pointer;
using Terminaux.Writer.CyclicWriters;
using Terminaux.Writer.CyclicWriters.Renderer.Tools;

namespace Terminaux.Console.Fixtures.Cases.CaseData
{
    internal class TextualUiSimpleTestData : TextualUI
    {
        private bool redBoxVisible = true;
        private bool greenBoxVisible = true;
        private bool blueBoxVisible = true;
        private readonly Keybinding[] bindings =
        [
            new Keybinding("Exit", ConsoleKey.Escape),
            new("Show/hide red box", ConsoleKey.R),
            new("Show/hide green box", ConsoleKey.G),
            new("Show/hide blue box", ConsoleKey.B),
        ];

        public override string Render()
        {
            StringBuilder builder = new();

            // Red box
            if (redBoxVisible)
            {
                int consoleHalf = ConsoleWrapper.WindowWidth / 2;
                int startX = consoleHalf - (consoleHalf * 3 / 4);
                int endX = consoleHalf + (consoleHalf / 4);
                int y = 2;
                int height = ConsoleWrapper.WindowHeight - y - 7;
                int width = endX - startX;
                var box = new Box()
                {
                    Left = startX,
                    Top = y,
                    InteriorWidth = width,
                    InteriorHeight = height,
                    Color = ConsoleColors.Red,
                };
                builder.Append(box.Render());
            }

            // Green box
            if (greenBoxVisible)
            {
                int consoleHalf = ConsoleWrapper.WindowWidth / 2;
                int startX = consoleHalf - (consoleHalf * 3 / 4) + 4;
                int endX = consoleHalf + (consoleHalf / 4) + 4;
                int y = 4;
                int height = ConsoleWrapper.WindowHeight - y - 5;
                int width = endX - startX;
                var box = new Box()
                {
                    Left = startX,
                    Top = y,
                    InteriorWidth = width,
                    InteriorHeight = height,
                    Color = ConsoleColors.Lime,
                };
                builder.Append(box.Render());
            }

            // Blue box
            if (blueBoxVisible)
            {
                int consoleHalf = ConsoleWrapper.WindowWidth / 2;
                int startX = consoleHalf - (consoleHalf * 3 / 4) + 8;
                int endX = consoleHalf + (consoleHalf / 4) + 8;
                int y = 6;
                int height = ConsoleWrapper.WindowHeight - y - 3;
                int width = endX - startX;
                var box = new Box()
                {
                    Left = startX,
                    Top = y,
                    InteriorWidth = width,
                    InteriorHeight = height,
                    Color = ConsoleColors.Blue,
                };
                builder.Append(box.Render());
            }

            // Keybindings
            builder.Append(new Keybindings()
            {
                KeybindingList = bindings,
                Top = ConsoleWrapper.WindowHeight - 1,
                Width = ConsoleWrapper.WindowWidth - 1,
            }.Render());

            // Return the result
            return builder.ToString();
        }

        internal TextualUiSimpleTestData()
        {
            Keybindings.Add((new Keybinding("Exit", ConsoleKey.Escape), (ui, _, _) => TextualUITools.ExitTui(ui)));
            Keybindings.Add((new Keybinding("Show/hide red box", ConsoleKey.R), (ui, _, _) =>
            {
                redBoxVisible = !redBoxVisible;
                ui.uiScreen.RequireRefresh();
            }));
            Keybindings.Add((new Keybinding("Show/hide green box", ConsoleKey.G), (ui, _, _) =>
            {
                greenBoxVisible = !greenBoxVisible;
                ui.uiScreen.RequireRefresh();
            }));
            Keybindings.Add((new Keybinding("Show/hide blue box", ConsoleKey.B), (ui, _, _) =>
            {
                blueBoxVisible = !blueBoxVisible;
                ui.uiScreen.RequireRefresh();
            }));
        }
    }
}

Here's the companion code to start the interactive TUI for the above class:

https://github.com/Aptivi/Terminaux/blob/main/Terminaux.Console/Fixtures/Cases/Tui/TestScreenPartVisibilityTui.cs

//
// Terminaux  Copyright (C) 2023-2024  Aptivi
//
// This file is part of Terminaux
//
// Terminaux is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Terminaux is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY, without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//

using Terminaux.Console.Fixtures.Cases.CaseData;
using Terminaux.Inputs.Interactive;

namespace Terminaux.Console.Fixtures.Cases.Tui
{
    internal class TestScreenPartVisibilityTui : IFixture
    {
        public FixtureCategory Category => FixtureCategory.TextualUi;

        public void RunFixture()
        {
            var tui = new TextualUiSimpleTestData();
            TextualUITools.RunTui(tui);
        }
    }
}

Here's the resulting picture of the interactive TUI:

Refreshing

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.

https://github.com/Aptivi/Terminaux/blob/main/Terminaux.Console/Fixtures/Cases/CaseData/TextualUiRefreshTestData.cs

//
// Terminaux  Copyright (C) 2023-2024  Aptivi
//
// This file is part of Terminaux
//
// Terminaux is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Terminaux is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY, without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//

using System;
using System.Text;
using Terminaux.Base;
using Terminaux.Colors.Data;
using Terminaux.Inputs.Interactive;
using Terminaux.Inputs.Pointer;
using Terminaux.Writer.CyclicWriters;
using Terminaux.Writer.CyclicWriters.Renderer.Tools;

namespace Terminaux.Console.Fixtures.Cases.CaseData
{
    internal class TextualUiRefreshTestData : TextualUI
    {
        private bool redBoxVisible = true;
        private bool greenBoxVisible = true;
        private bool rgbBoxVisible = true;
        private long renders = 0;
        private bool paused = false;
        private readonly Keybinding[] bindings =
        [
            new("Exit", ConsoleKey.Escape),
            new("Show/hide red box", ConsoleKey.R),
            new("Show/hide green box", ConsoleKey.G),
            new("Show/hide RGB box", ConsoleKey.B),
            new("Increase FPS", ConsoleKey.UpArrow),
            new("Decrease FPS", ConsoleKey.DownArrow),
            new("Pause/Resume", ConsoleKey.Spacebar),
        ];

        public override string Render()
        {
            StringBuilder builder = new();

            // Red box
            if (redBoxVisible)
            {
                int consoleHalf = ConsoleWrapper.WindowWidth / 2;
                int startX = consoleHalf - (consoleHalf * 3 / 4);
                int endX = consoleHalf + (consoleHalf / 4);
                int y = 2;
                int height = ConsoleWrapper.WindowHeight - y - 7;
                int width = endX - startX;
                var box = new Box()
                {
                    Left = startX,
                    Top = y,
                    InteriorWidth = width,
                    InteriorHeight = height,
                    Color = ConsoleColors.Red,
                };
                builder.Append(box.Render());
            }

            // Green box
            if (greenBoxVisible)
            {
                int consoleHalf = ConsoleWrapper.WindowWidth / 2;
                int startX = consoleHalf - (consoleHalf * 3 / 4) + 4;
                int endX = consoleHalf + (consoleHalf / 4) + 4;
                int y = 4;
                int height = ConsoleWrapper.WindowHeight - y - 5;
                int width = endX - startX;
                var box = new Box()
                {
                    Left = startX,
                    Top = y,
                    InteriorWidth = width,
                    InteriorHeight = height,
                    Color = ConsoleColors.Lime,
                };
                builder.Append(box.Render());
            }

            // RGB box
            if (rgbBoxVisible)
            {
                int consoleHalf = ConsoleWrapper.WindowWidth / 2;
                int startX = consoleHalf - (consoleHalf * 3 / 4) + 8;
                int endX = consoleHalf + (consoleHalf / 4) + 8;
                int y = 6;
                int height = ConsoleWrapper.WindowHeight - y - 3;
                int width = endX - startX;
                var box = new Box()
                {
                    Left = startX,
                    Top = y,
                    InteriorWidth = width,
                    InteriorHeight = height,
                    Color = new($"hsl:{renders % 360};50;50"),
                };
                builder.Append(box.Render());
            }

            // Keybindings
            builder.Append(new Keybindings()
            {
                KeybindingList = bindings,
                Top = ConsoleWrapper.WindowHeight - 1,
                Width = ConsoleWrapper.WindowWidth - 1,
            }.Render());

            // Refresh rate and frame number count
            builder.Append(new AlignedText($"Delay: [Lime]{RefreshDelay}[/] ms, frame [Lime]{renders}[/]")
            {
                Top = 0,
                Settings = new() { Alignment = TextAlignment.Middle }
            }.Render());

            // Return the result
            renders++;
            return builder.ToString();
        }

        internal TextualUiRefreshTestData()
        {
            Keybindings.Add((bindings[0], (ui, _, _) => TextualUITools.ExitTui(ui)));
            Keybindings.Add((bindings[1], (ui, _, _) =>
            {
                redBoxVisible = !redBoxVisible;
                ui.uiScreen.RequireRefresh();
            }
            ));
            Keybindings.Add((bindings[2], (ui, _, _) =>
            {
                greenBoxVisible = !greenBoxVisible;
                ui.uiScreen.RequireRefresh();
            }
            ));
            Keybindings.Add((bindings[3], (ui, _, _) =>
            {
                rgbBoxVisible = !rgbBoxVisible;
                ui.uiScreen.RequireRefresh();
            }
            ));
            Keybindings.Add((bindings[4], (_, _, _) =>
            {
                if (paused)
                    return;
                RefreshDelay--;
                if (RefreshDelay <= 20)
                    RefreshDelay = 20;
            }
            ));
            Keybindings.Add((bindings[5], (_, _, _) =>
            {
                if (paused)
                    return;
                RefreshDelay++;
                if (RefreshDelay >= 1000)
                    RefreshDelay = 1000;
            }
            ));
            Keybindings.Add((bindings[6], (_, _, _) =>
            {
                paused = !paused;
                if (paused)
                    RefreshDelay = 0;
                else
                    RefreshDelay = 40;
            }
            ));
            RefreshDelay = 40;
        }
    }
}

Here's the companion code that executes the above TUI class:

https://github.com/Aptivi/Terminaux/blob/main/Terminaux.Console/Fixtures/Cases/Tui/TestScreenPartVisibilityRefreshTui.cs

//
// Terminaux  Copyright (C) 2023-2024  Aptivi
//
// This file is part of Terminaux
//
// Terminaux is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Terminaux is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY, without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//

using Terminaux.Console.Fixtures.Cases.CaseData;
using Terminaux.Inputs.Interactive;

namespace Terminaux.Console.Fixtures.Cases.Tui
{
    internal class TestScreenPartVisibilityRefreshTui : IFixture
    {
        public FixtureCategory Category => FixtureCategory.TextualUi;

        public void RunFixture()
        {
            var tui = new TextualUiRefreshTestData();
            TextualUITools.RunTui(tui);
        }
    }
}

Here's the resulting picture for the TUI:

Defining Keybindings

When defining keybindings, it's recommended to do so from either the constructor of the interactive TUI or in the overridden value of the Keybindings list, except if you want this keybinding list to always change during the runtime of the textual UI, such as the color selector. We also recommend to define their actions in separate private functions, passing in the parameters as needed.

• To define a keybinding in your interactive TUI, use the Keybindings.Add() statement to pass in a tuple of the following two variables:

  • A Keybinding instance 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.

• 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.