Terminal.Gui/docfx/docs/index.md

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.

(This is the v2 API documentation. For v1 go here: https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.html)

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.
• Extensible UI - 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.
• Keyboard and Mouse Input - The library handles all the details of input processing and provides a simple event-based API for applications to consume.
• Powerful Layout Engine - The layout engine makes it easy to lay out controls relative to each other and enables dynamic terminal UIs.
• Machine, User, and App-Level Configuration - Persistent configuration settings, including overriding default look & feel with Themes, keyboard bindings, and more via the ConfigurationManager class.
• Clipboard support - Cut, Copy, and Paste is provided through the [Clipboard] class.
• Multi-tasking - 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.

See What's New in V2 For more.

Conceptual Documentation

• Arrangement API
• Cancellable Work Pattern
• Configuration and Theme Manager
• Command Deep Dive
• Cursor Deep Dive
• Cross-platform Driver Model
• Dim.Auto Deep Dive
• Drawing
• Events Deep Dive
• Keyboard API
• Layout Engine
• Migrating from Terminal.Gui v1
• Mouse API
• Multi-tasking and the Application Main Loop
• Navigation
• Popovers
• View Deep Dive
• Views
• Scrolling Deep Dive
• TableView Deep Dive
• TreeView Deep Dive

The simplest application looks like this:

using Terminal.Gui;
ConfigurationManager.Enable(ConfigLocations.All);
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, @Terminal.Gui.Application.Init(Terminal.Gui.IConsoleDriver,System.String) 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;
ConfigurationManager.Enable(ConfigLocations.All);
Application.Init ();

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

var app = new Toplevel ();
app.Add (label);
Application.Run (app);
app.Dispose ();
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;

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

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

var app = new Toplevel ();
// Add both menu and win in a single call
top.Add (menu, button);
Application.Run (top);
top.Dispose ();
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 @Terminal.Gui.View.Add(View) to add a couple of buttons to a UI:

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

    var username = new TextField () {
        X = Pos.Right (label) + 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.

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.

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() { Title = "Ok" };
var cancel = new Button() { Title = "Cancel" };
var dialog = new Dialog () { Text = "Are you sure you want to quit?", Title = "Quit", Buttons = { ok, cancel } };

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 ◄⟧║
╚═════════════════════════════════════════════════════════════╝