Terminal.Gui/docfx/index.md

Terminal.Gui Documentation

Welcome to the official documentation for Terminal.Gui, a cross-platform UI toolkit for creating console-based graphical user interfaces in .NET.

Key Resources

• Getting Started - Learn how to start using Terminal.Gui.
• Events Deep Dive - Detailed guide on event handling and the Cancellable Work Pattern.
• View Documentation - Information on creating and customizing views.
• Keyboard Handling - Guide to managing keyboard input.
• Mouse Support - Details on implementing mouse interactions.
• Showcase - Explore applications and examples built with Terminal.Gui.

Terminal.Gui v2 - Cross Platform Terminal UI toolkit for .NET

A toolkit for building rich console apps for .NET that run on Windows, the Mac, and Linux.

Note

v2 is still in development (see the v2_develop branch). The current stable version of v1 is in the develop branch.

Note

This is the v2 API documentation. For v1 go here: https://gui-cs.github.io/Terminal.GuiV1Docs/

Features

• Dozens of Built-in Views - The library provides a rich set of built-in views that can be used to build complex user interfaces.

• Cross Platform - Windows, Mac, and Linux. Terminal drivers for Unix, Windows, and the .NET 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.

Examples

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, @Terminal.Gui.App.Application.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 () {
    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;
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 ();

UI Catalog

UI Catalog is a comprehensive sample library for Terminal.Gui. It provides a simple UI for adding to the catalog of scenarios.

• UI Catalog Source

More examples can be found in the Examples directory.

More Information

See the Deep Dives for deep dives into the various features of the library.