+Terminal.Gui API Overview
+
+Terminal.Gui is a library intended to create console-based
+applications using C#. The framework has been designed to make it
+easy to write applications that will work on monochrome terminals, as
+well as modern color terminals with mouse support.
+This library works across Windows, Linux and MacOS.
+This library provides a text-based toolkit as works in a way similar
+to graphic toolkits. There are many controls that can be used to
+create your applications and it is event based, meaning that you
+create the user interface, hook up various events and then let the
+a processing loop run your application, and your code is invoked via
+one or more callbacks.
+The simplest application looks like this:
+using Terminal.Gui;
+
+class Demo {
+ static int Main ()
+ {
+ Application.Init ();
+
+ var n = MessageBox.Query (50, 7,
+ "Question", "Do you like console apps?", "Yes", "No");
+
+ return n;
+ }
+}
+
This example shows a prompt and returns an integer value depending on
+which value was selected by the user (Yes, No, or if they use chose
+not to make a decision and instead pressed the ESC key).
+More interesting user interfaces can be created by composing some of
+the various views that are included. In the following sections, you
+will see how applications are put together.
+In the example above, you can see that we have initialized the runtime by calling the
+Init method in the Application class - this sets up the environment, initializes the color
+schemes available for your application and clears the screen to start your application.
+The Application class, additionally creates an instance of the [Toplevel]((../api/Terminal.Gui/Terminal.Gui.Toplevel.html) class that is ready to be consumed,
+this instance is available in the Application.Top property, and can be used like this:
+using Terminal.Gui;
+
+class Demo {
+ static int Main ()
+ {
+ Application.Init ();
+
+ var label = new Label ("Hello World") {
+ X = Pos.Center (),
+ Y = Pos.Center (),
+ Height = 1,
+ };
+ Application.Top.Add (label);
+ Application.Run ();
+ }
+}
+
Typically, you will want your application to have more than a label, you might
+want a menu, and a region for your application to live in, the following code
+does this:
+using Terminal.Gui;
+
+class Demo {
+ static int Main ()
+ {
+ Application.Init ();
+ var menu = new MenuBar (new MenuBarItem [] {
+ new MenuBarItem ("_File", new MenuItem [] {
+ new MenuItem ("_Quit", "", () => {
+ Application.RequestStop ();
+ })
+ }),
+ });
+
+ var win = new Window ("Hello") {
+ X = 0,
+ Y = 1,
+ Width = Dim.Fill (),
+ Height = Dim.Fill () - 1
+ };
+
+ // Add both menu and win in a single call
+ Application.Top.Add (menu, win);
+ Application.Run ();
+ }
+}
+
Views
+All visible elements on 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.
+Every view can contain an arbitrary number of children views. These are called
+the Subviews. You can add a view to an existing view, by calling the
+Add method, for example, to add a couple of buttons to a UI, you can do this:
+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.
+There are many views that you can use to spice up your application:
+Buttons, Labels, Text entry, Text view, Radio buttons, Checkboxes, Dialog boxes, Message boxes, Windows, Menus, ListViews, Frames, ProgressBars, Scroll views and Scrollbars.
+Layout
+Terminal.Gui supports two different layout systems, absolute and computed \
+(controlled by the LayoutStyle
+property on the view.
+The absolute system is used when you want the view to be positioned exactly in
+one location and want to manually control where the view is. This is done
+by invoking your View constructor with an argument of type Rect. When you do this, to change the
+position of the View, you can change the Frame property on the View.
+The computed layout system offers a few additional capabilities, like automatic
+centering, expanding of dimensions and a handful of other features. To use
+this you construct your object without an initial Frame, but set the
+ X, Y, Width and Height properties after the object has been created.
+Examples:
+
+// Dynamically computed
+var label = new Label ("Hello") {
+ X = 1,
+ Y = Pos.Center (),
+ Width = Dim.Fill (),
+ Height = 1
+};
+
+// Absolute position using the provided rectangle
+var label2 = new Label (new Rect (1, 2, 20, 1), "World")
+
The computed layout system does not take integers, instead the X and Y properties are of type Pos and the Width and Height properties are of type Dim both which can be created implicitly from integer values.
+The Pos Type
+The Pos type on X and Y offers a few options:
+
+- Absolute position, by passing an integer
+- Percentage of the parent's view size -
Pos.Percent(n)
+- Anchored from the end of the dimension -
AnchorEnd(int margin=0)
+- Centered, using
Center()
+- Reference the Left (X), Top (Y), Bottom, Right positions of another view
+
+The Pos values can be added or subtracted, like this:
+// Set the X coordinate to 10 characters left from the center
+view.X = Pos.Center () - 10;
+
+view.Y = Pos.Percent (20);
+
+anotherView.X = AnchorEnd (10);
+anotherView.Width = 9;
+
+myView.X = Pos.X (view);
+myView.Y = Pos.Bottom (anotherView);
+
The Dim Type
+The Dim type is used for the Width and Height properties on the View and offers
+the following options:
+
+- Absolute size, by passing an integer
+- Percentage of the parent's view size -
Dim.Percent(n)
+- Fill to the end -
Dim.Fill ()
+- Reference the Width or Height of another view
+
+Like, Pos, objects of type Dim can be added an subtracted, like this:
+// Set the Width to be 10 characters less than filling
+// the remaining portion of the screen
+view.Width = Dim.Fill () - 10;
+
+view.Height = Dim.Percent(20) - 1;
+
+anotherView.Height = Dim.Height (view)+1
+
TopLevels, Windows and Dialogs.
+Among the many kinds of views, you typically will create a Toplevel view (or any of its subclasses,
+like Window or Dialog which is special kind of views
+that can be executed modally - that is, the view can take over all input and returns
+only when the user chooses to complete their work there.
+The following sections cover the differences.
+TopLevel Views
+Toplevel views have no visible user interface elements and occupy an arbitrary portion of the screen.
+You would use a toplevel Modal view for example to launch an entire new experience in your application, one where you would have a new top-level menu for example. You
+typically would add a Menu and a Window to your Toplevel, it would look like this:
+using Terminal.Gui;
+
+class Demo {
+ static void Edit (string filename)
+ {
+ var top = new Toplevel () {
+ X = 0,
+ Y = 0,
+ Width = Dim.Fill (),
+ Height = Dim.Fill ()
+ };
+ var menu = new MenuBar (new MenuBarItem [] {
+ new MenuBarItem ("_File", new MenuItem [] {
+ new MenuItem ("_Close", "", () => {
+ Application.RequestStop ();
+ })
+ }),
+ });
+
+ // nest a window for the editor
+ var win = new Window (filename) {
+ X = 0,
+ Y = 1,
+ Width = Dim.Fill (),
+ Height = Dim.Fill () - 1
+ };
+
+ var editor = new TextView () {
+ X = 0,
+ Y = 0,
+ Width = Dim.Fill (),
+ Height = Dim.Fill ()
+ };
+ editor.Text = System.IO.File.ReadAllText (filename);
+ win.Add (editor);
+
+ // Add both menu and win in a single call
+ top.Add (win, menu);
+ Application.Run (top);
+ }
+}
+
Window Views
+Window views extend the Toplevel view by providing a frame and a title around the toplevel - and can be moved on the screen with the mouse (caveat: code is currently disabled)
+From a user interface perspective, you might have more than one Window on the screen at a given time.
+Dialogs
+Dialog are Window objects that happen to be centered in the middle of the screen.
+Dialogs are instances of a Window that are centered in 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 your application.
+Dialogs are a subclass of Window and additionally expose the
+AddButton API which manages the layout
+of any button passed to it, ensuring that the buttons are at the bottom of the dialog.
+Example:
+bool okpressed = false;
+var ok = new Button("Ok");
+var cancel = new Button("Cancel");
+var dialog = new Dialog ("Quit", 60, 7, ok, cancel);
+
Which will show something like this:
++- Quit -----------------------------------------------+
+| |
+| |
+| [ Ok ] [ Cancel ] |
++------------------------------------------------------+
+
Running Modally
+To run your Dialog, Window or Toplevel modally, you will invoke the Application.Run
+method on the toplevel. It is up to your code and event handlers to invoke 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 your code will need to have a mechanism
+of indicating the reason that the execution of the modal dialog was completed, in the
+case above, the okpressed value is set to true if the user pressed or selected the Ok button.
+
+Every view has a focused view, and if that view has nested views, 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 binds the key Tab to focus the next logical view,
+and the Shift-Tab combination to focus the previous logical view.
+Keyboard processing is divided in three stages: HotKey processing, regular processing and
+cold key processing.
+
+Hot key processing happens first, and it gives all the views in the current
+toplevel a chance to monitor whether the key needs to be treated specially. This
+for example handles the scenarios where the user pressed Alt-o, and a view with a
+highlighted "o" is being displayed.
+If no view processed the hotkey, then the key is sent to the currently focused
+view.
+If the key was not processed by the normal processing, all views are given
+a chance to process the keystroke in their cold processing stage. Examples
+include the processing of the "return" key in a dialog when a button in the
+dialog has been flagged as the "default" action.
+
+The most common case is the normal processing, which sends the keystrokes to the
+currently focused view.
+Mouse events are processed in visual order, and the event will be sent to the
+view on the screen. The only exception is that no mouse events are delivered
+to background views when a modal view is running.
+More 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 defined color schemes for
+the normal views, the menu bar, popup dialog boxes and error dialog boxes, that you can use like this:
+
+Colors.BaseColors.MenuColors.DialogColors.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
+
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
+
MainLoop, Threads and Input Handling
+Detailed description of the mainlop is described on the Event Processing and the Application Main Loop document.
+