Terminal.Gui v2 Overview

A toolkit for building rich Terminal User Interface (TUI) apps with .NET that run on Windows, the Mac, and Linux/Unix.

Features

Cross Platform - Windows, Mac, and Linux. Terminal drivers for Curses, Windows, and the .NET Console mean apps will work well on both color and monochrome terminals. Apps also work over SSH.
Templates - The dotnet new command can be used to create a new Terminal.Gui app.
Keyboard and Mouse Input - The library handles all the details of input processing and provides a simple event-based API for applications to consume.
Extensible Widgets - All visible UI elements are subclasses of the View class, and these in turn can contain an arbitrary number of sub-views. Dozens of Built-in Views are provided.
Flexible Layout - Computed Layout makes it easy to lay out controls relative to each other and enables dynamic terminal UIs. Absolute Layout allows for precise control over the position and size of controls.
Clipboard support - Cut, Copy, and Paste is provided through the [Clipboard] class.
Advanced App Features - The Mainloop supports processing events, idle handlers, and timers. Most classes are safe for threading.
Reactive Extensions - Use reactive extensions and benefit from increased code readability, and the ability to apply the MVVM pattern and ReactiveUI data bindings. See the source code of a sample app.

Conceptual Documentation

The simplest application looks like this:

using Terminal.Gui;
Application.Init ();
var n = MessageBox.Query (50, 5, "Question", "Do you like TUI apps?", "Yes", "No");
Application.Shutdown ();
return n;

This example shows a prompt and returns an integer value depending on which value was selected by the user.

More interesting user interfaces can be created by composing some of the various View classes that are included.

In the example above, Applicaton.Init sets up the environment, initializes the color schemes, and clears the screen to start the application.

The Application class additionally creates an instance of the Toplevel View available in the Application.Top property, and can be used like this:

using Terminal.Gui;
Application.Init ();

var label = new Label ("Hello World") {
    X = Pos.Center (),
    Y = Pos.Center (),
    Height = 1,
};

Application.Top.Add (label);
Application.Run ();
Application.Shutdown ();

This example includes a menu bar at the top of the screen and a button that shows a message box when clicked:

using Terminal.Gui;

Application.Init ();
var menu = new MenuBar (new MenuBarItem [] {
    new MenuBarItem ("_File", new MenuItem [] {
        new MenuItem ("_Quit", "", () => { 
            Application.RequestStop (); 
        })
    }),
});

var button = new Button ("_Hello") {
    X = 0,
    Y = Pos.Bottom (menu),
    Width = Dim.Fill (),
    Height = Dim.Fill () - 1
};
button.Clicked += () => {
    MessageBox.Query (50, 5, "Hi", "Hello World! This is a message box", "Ok");
};

// Add both menu and win in a single call
Application.Top.Add (menu, button);
Application.Run ();
Application.Shutdown ();

Views

All visible elements in a Terminal.Gui application are implemented as Views. Views are self-contained objects that take care of displaying themselves, can receive keyboard and mouse input and participate in the focus mechanism.

See the full list of Views provided by the Terminal.Gui library here.

Every view can contain an arbitrary number of child views, called SubViews. Call the View.Add method to add a couple of buttons to a UI:

void SetupMyView (View myView)
{
    var label = new Label ("Username: ") {
        X = 1,
        Y = 1,
        Width = 20,
        Height = 1
    };
    myView.Add (label);

    var username = new TextField ("") {
        X = 1,
        Y = 2,
        Width = 30,
        Height = 1
    };
    myView.Add (username);
}

The container of a given view is called the SuperView and it is a property of every View.

Layout

Terminal.Gui v2 supports the following View layout systems (controlled by the View.LayoutStyle):

Absolute - Used to have the View positioned exactly in a location, with a fixed size. Absolute layout is accomplished by constructing a View with an argument of type Rect or directly changing the Frame property on the View.
Computed - The Computed Layout system provides automatic aligning of Views with other Views, automatic centering, and automatic sizing. To use Computed layout set the X, Y, Width and Height properties after the object has been created. Views laid out using the Computed Layout system can be resized with the mouse or keyboard, enabling tiled window managers and dynamic terminal UIs.
Overlapped - New in V2 (But not yet) - Overlapped layout enables views to be positioned on top of each other. Overlapped Views are movable and sizable with both the keyboard and the mouse.

See the full Layout documentation here.

Modal Views

Views can either be Modal or Non-modal. Modal views take over all user input until the user closes the View. Examples of Modal Views are Toplevel, Dialog, and Wizard. Non-modal views can be used to create a new experience in your application, one where you would have a new top-level menu for example. Setting the Modal property on a View to true makes it modal.

To run any View (but especially Dialogs, Windows, or Toplevels) modally, invoke the Application.Run method on a Toplevel. Use the Application.RequestStop() method to terminate the modal execution.

bool okpressed = false;
var ok = new Button(3, 14, "Ok") { 
    Clicked = () => { Application.RequestStop (); okpressed = true; }
};
var cancel = new Button(10, 14, "Cancel") {
    Clicked = () => Application.RequestStop () 
};
var dialog = new Dialog ("Login", 60, 18, ok, cancel);

var entry = new TextField () {
    X = 1, 
    Y = 1,
    Width = Dim.Fill (),
    Height = 1
};
dialog.Add (entry);
Application.Run (dialog);
if (okpressed)
    Console.WriteLine ("The user entered: " + entry.Text);

There is no return value from running modally, so the modal view must have a mechanism to indicate the reason the modal was closed. In the case above, the okpressed value is set to true if the user pressed or selected the Ok button.

Windows

Window is a view used in Overlapped layouts, providing a frame and a title - and can be moved and sized with the keyboard or mouse.

Dialogs

Dialogs are Modal Windows that are centered in the middle of the screen and are intended to be used modally - that is, they run, and they are expected to return a result before resuming execution of the application.

Dialogs expose an API for adding buttons and managing the layout such that buttons are at the bottom of the dialog (e.g. AddButton).

Example:

bool okpressed = false;
var ok = new Button("Ok");
var cancel = new Button("Cancel");
var dialog = new Dialog ("Quit", ok, cancel) { Text = "Are you sure you want to quit?" };

Which will show something like this:

+- Quit -----------------------------------------------+
|            Are you sure you want to quit?            |
|                                                      |
|                  [ Ok ] [ Cancel ]                   |
+------------------------------------------------------+

Wizards

Wizards are Dialogs that let users step through a series of steps to complete a task.

╔╡Gandolf - The last step╞════════════════════════════════════╗
║                                     The wizard is complete! ║
║☐ Enable Final Final Step                                    ║
║                                     Press the Finish        ║
║                                     button to continue.     ║
║                                                             ║
║                                     Pressing ESC will       ║
║                                     cancel the wizard.      ║
║                                                             ║
║                                                             ║
║─────────────────────────────────────────────────────────────║
║⟦ Back ⟧                                         ⟦► Finish ◄⟧║
╚═════════════════════════════════════════════════════════════╝

Input Handling

Every view has a focused view, and if that view has nested SubViews, one of those is the focused view. This is called the focus chain, and at any given time, only one View has the [Focus]().

The library provides a default focus mechanism that can be used to navigate the focus chain. The default focus mechanism is based on the Tab key, and the Shift-Tab key combination

Keyboard processing details are available on the Keyboard Event Processing document.

Colors and Color Schemes

All views have been configured with a color scheme that will work both in color terminals as well as the more limited black and white terminals.

The various styles are captured in the Colors class which defines color schemes for Toplevel, the normal views (Base), the menu bar, dialog boxes, and error UI::

Colors.Toplevel
Colors.Base
Colors.Menu
Colors.Dialog
Colors.Error

You can use them for example like this to set the colors for a new Window:

var w = new Window ("Hello");
w.ColorScheme = Colors.Error

ColorSchemes can be configured with the Configuration and Theme Manager.

The ColorScheme represents four values, the color used for Normal text, the color used for normal text when a view is focused an the colors for the hot-keys both in focused and unfocused modes.

By using ColorSchemes you ensure that your application will work correctbly both in color and black and white terminals.

Some views support setting individual color attributes, you create an attribute for a particular pair of Foreground/Background like this:

var myColor = Application.Driver.MakeAttribute (Color.Blue, Color.Red);
var label = new Label (...);
label.TextColor = myColor

Learn more about colors in the Drawing overview.

MainLoop, Threads and Input Handling

The Main Loop, threading, and timers are described on the Event Processing and the Application Main Loop document.

Cross-Platform Drivers

See Cross-platform Driver Model.

index.md 12 KB History Raw