Terminal.Gui/docfx/docs/layout.md

Layout

Tenets for Terminal.Gui View Layout (Unless you know better ones...)

Tenets higher in the list have precedence over tenets lower in the list.

• Users Have Control - Terminal.Gui provides default key bindings consistent with these tenets, but those defaults are configurable by the user. For example, ConfigurationManager allows users to redefine key bindings for the system, a user, or an application.

• More Editor than Command Line - Once a Terminal.Gui app starts, the user is no longer using the command line. Users expect keyboard idioms in TUI apps to be consistent with GUI apps (such as VS Code, Vim, and Emacs). For example, in almost all GUI apps, Ctrl-V is Paste. But the Linux shells often use Shift-Insert. Terminal.Gui binds Ctrl-V by default.

• Be Consistent With the User's Platform - Users get to choose the platform they run Terminal.Gui apps on and those apps should respond to keyboard input in a way that is consistent with the platform. For example, on Windows to erase a word to the left, users press Ctrl-Backspace. But on Linux, Ctrl-W is used.

• The Source of Truth is Wikipedia - We use this Wikipedia article as our guide for default key bindings.

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