Console Screen

Your screen in front of you.

Terminaux offers the console screen feature, which allows you to define a screen for your interactive console application. This guarantees you a dynamic terminal sequence generation that you can print to the console, including VT sequences.

---

Screen Instance

You can get started by making a new instance of the Screen class and using it to add a new ScreenPart instance with its name to make a layer for your rendering sequences. This facilitates buffering the screens to the console.

The screen part instance allows you to add text and sequences in different ways:

Function/property	Description
AddText()	Adds a simple and static text to the buffer
AddTextLine()	Adds a simple and static text to the buffer with the extra new line
AddDynamicText()	This is the key of the Screen feature. It allows you to define a function delegate that generates text dynamically. It's useful for displaying anything that changes.
Clear()	Clears the whole buffer
GetBuffer()	Gets the resulting buffer
RequireRefresh()	Tells the screen system to require a refresh
Visible	Whether this part is visible or not

You can require refresh using the RequireRefresh() function on the screen instance, and your renderer can use NeedsRefresh to check to see whether we need to refresh the entire screen or not.

During the render process, if NeedsRefresh was true, the refresh manager would set the "refresh was done" flag to true, causing all dynamic text renderers to understand that the refresh was done. From there, you can use the RefreshWasDone flag to change the behavior of the renderer function.

---

The structure

The screen feature contains the following classes for different purposes:

Screen

The screen class hosts an array of screen parts that you can add, edit, or remove using the following functions:

• AddBufferedPart()

• EditBufferedPart()

• RemoveBufferedPart()

You are required to provide a name or a GUID for the specific screen part. This is to easily identify different screen parts, because if you're just looking for final buffer results, you might not be able to tell which part was for which.

You can use either the buffered part index number or the part name when using any of the following querying functions (in addition to the last two functions):

• GetBufferedPart()

• CheckBufferedPart()

You can also clear the entire buffered parts queue using the RemoveBufferedParts() function.

By default, when the screen feature detects a resize, it'll re-render the current screen. It will, by default, reset the resize state, causing some programs to behave incorrectly.

If you want Terminaux not to reset the resize state when the screen is resized, use the ResetResize property to set it to false.

Screen Part

The screen part hosts a list of dynamic buffers to generate a working text sequence for the console plain writer to write it to the terminal to show you its contents. You can also call the screen parts as "layers" to more easily understand the motive behind these "layers."

In order to uniquely identify each screen part without any ambiguity, you can use the Id property that is populated each time you make a new screen part.

Adding simple or dynamic text

You can use the following functions to add simple or dynamic text to the buffer queue:

• AddText(): Adds a simple text without the newline.

• AddTextLine(): Adds a simple text with the newline.

• AddDynamicText(): This is the key of all the resizable console TUIs. You need to provide a lambda or a function that hosts the entire rendering sequence.

If you want to clear the queue list without printing the buffers to the console, you can clear the list of dynamic buffers using the Clear() function. You can also control its visibility using the Visible property.

Ordering screen parts

You can order them using the Order property when creating them. However, TermRead renders all the screen parts from the least important (the smallest Order values) to the most important (the largest Order values). This is useful for layering if you don't feel comfortable adding dynamic texts that represent layers.

var orderedPart = new ScreenPart() { Order = 1 };
var importantPart = new ScreenPart() { Order = 100 };

---

Screen Tools

The screen feature contains a set of tools that allow you to manipulate with a screen and its associated parts, along with extra features.

Setting the current screen

Setting a current screen requires you to provide SetCurrent() with a console screen instance once you're done making your own screen and filling it with necessary printing strings, such as an interactive TUI or a simple two rulers resizable application as provided in the example at the top of the page.

Once the current screen is set, CurrentScreen returns your screen instance. This means that you've made that screen the current screen. You can easily access the list of screens via the Screens property, with the current screen being the last one.

When this is done, the screensaver manager and the console resize listener will refresh and redraw your screen, taking new console window dimensions to account. This reaction makes your interactive console applications that use screens responsive to the resize events.

CurrentScreen returns null upon calling it with no screen set. Therefore, it's advisable to check for this case when trying to access it if you don't set more than one screen as a default. The easy way to perform such a check is using IsOnScreen.

Rendering the screen

You can render your screen using:

• Render(): Renders your current screen. Throws if you didn't set your current screen before calling this version of the function.

• Render(screen): Renders your screen instance to the console.

However, for Render() to work, you need to add your screen instance to the list of tracked screens in the screen manager. This can be done by calling the SetCurrent() function on your screen instance.

Unsetting the current screen

To unset the screen, you'll have to call UnsetCurrent() with the screen instance that you've set it as the default before. This removes the screen from the list of tracked screens.

If you've called the above function with two or more screens, CurrentScreen doesn't return null, but returns the last screen found in the list.

Don't forget to remove your screen from the list of tracked screens once you're done using it. You can call UnsetCurrent() to make this happen.

If your application contains a main loop wrapped in a try and catch block, you must create a finally block (if not done) and call UnsetCurrent() on your screen instance. It may be necessary to move your screen instance declaration in your code outside the try and catch block.

Screen overlays

Screen overlays render on top of whatever gets rendered on the screen to act as an overlay, and uses a completely independent screen part as the overlay, but there are two types of screen overlays:

• Screen-specific overlays (OverlayPart): These overlays are specific to a screen instance, and you can choose a screen part that will act as an overlay.

• Global screen overlays (GlobalOverlayPart): These overlays are just a single overlay for all screen instances, and there can only be one screen part that can act as this overlay. Global screen overlays also act as an overlay on top of screen-specific overlays.

You can set a screen overlay by setting any of the two properties in the screen instance, knowing that you'll have to refer to a base screen class for the global overlay.

// Screen-specific overlays
stickScreen.OverlayPart = pinkOverlayBox;

// Global screen overlays
Screen.GlobalOverlayPart = cyanOverlayBox;

Cyclic screens

Cyclic screens are screens that get rendered for each specified amount of milliseconds. This is useful for screens that show dynamic data that change, while holding Terminaux responsibility for the refresh of the screen.

You can make the screen cyclic by specifying the amount of milliseconds that describes the frequency of the cyclic screen. This is achieved using the CycleFrequency property.

Before the cyclic screen gets rendered in a loop, you must first set it as a default cyclic screen using the SetCurrentCyclic() function and render it using the StartCyclicScreen() function instead of the usual Render() function.

When you're done rendering this screen, for example, exiting from a specific screen, use the StopCyclicScreen() function. Afterwards, you can use the UnsetCurrentCyclic() function to unset the current cyclic screen.

You can't override the current cyclic screen until the thread that renders the chosen cyclic screen stops. You can check to see if this thread is running using the CyclicScreenRunning() function.

---

An example

The interactive testing system allows you to try the demonstration of this feature out to show you the concept of what happens when you try to resize the console.

The screen instance in question shows you two rulers:

• A horizontal ruler that shows you the width of the console window

• A vertical ruler that shows you the height of the console window

https://github.com/Aptivi/Terminaux/blob/main/private/Terminaux.Console/Fixtures/Cases/Screens/TestScreen.cs

//
// Terminaux  Copyright (C) 2023-2026  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.Base.Buffered;
using Colorimetry;
using Colorimetry.Data;
using Terminaux.Inputs.Styles.Infobox;
using Terminaux.Inputs;
using Terminaux.Sequences.Builder.Types;
using Terminaux.Base.Extensions;

namespace Terminaux.Console.Fixtures.Cases.Screens
{
    internal class TestScreen : IFixture
    {
        public FixtureCategory Category => FixtureCategory.Screen;

        public void RunFixture()
        {
            // Show the screen measurement sticks
            var stickScreen = new Screen();
            try
            {
                // First, clear the screen
                ConsoleColoring.LoadBack();

                // Then, show the resizable sticks
                var stickScreenPart = new ScreenPart();
                stickScreenPart.AddDynamicText(() =>
                {
                    var builder = new StringBuilder();
                    builder.Append(
                        ConsolePositioning.RenderChangePosition(0, 1) +
                        ConsoleColoring.RenderSetConsoleColor(new Color(ConsoleColors.Silver), true) +
                        GenerateWidthStick() + GenerateHeightStick() +
                        ConsoleColoring.RenderResetColors()
                    );
                    return builder.ToString();
                });
                stickScreen.AddBufferedPart("Test", stickScreenPart);
                ScreenTools.SetCurrent(stickScreen);
                ScreenTools.Render();
                Input.ReadKey();
            }
            catch (Exception ex)
            {
                InfoBoxModalColor.WriteInfoBoxModal($"Screen failed to render: {ex.Message}");
            }
            finally
            {
                ScreenTools.UnsetCurrent(stickScreen);
                ConsoleColoring.LoadBack();
            }
        }

        private static string GenerateWidthStick() =>
            new(' ', ConsoleWrapper.WindowWidth);

        private static string GenerateHeightStick()
        {
            var stick = new StringBuilder();
            for (int i = 0; i < ConsoleWrapper.WindowHeight; i++)
            {
                stick.Append(CsiSequences.GenerateCsiCursorPosition(2, i));
                stick.Append(' ');
            }
            return stick.ToString();
        }
    }
}