Layout | Terminal.Gui v2 (original) (raw)

Terminal.Gui provides a rich system for how View objects are laid out relative to each other. The layout system also defines how coordinates are specified.

See View Deep Dive, Arrangement Deep Dive, Scrolling Deep Dive, and Drawing Deep Dive for more.

Lexicon & Taxonomy

Coordinates

View Composition

view.X = Pos.Right (otherView) + 1;  
view.Y = Pos.Bottom (otherView) + 1;

is equivalent to 

otherView.Margin.Thickness = new Thickness (0, 0, 1, 1);  
view.X = Pos.Right (otherView);  
view.Y = Pos.Bottom (otherView);

Arrangement Modes

See Arrangement Deep Dive for more.

The Frame

The Frame property of a View is a rectangle that describes the current location and size of the view relative to the Superview's content area. The Frame has a Location and Size. The Location describes the top-left corner of the view relative to the SuperView's content area. The Size describes the width and height of the view. The Frame is used to determine where the view is drawn on the screen and is used to calculate the Viewport and content size.

The Content Area

The content area is the area where the view's content is drawn. Content can be any combination of the Text property, SubViews, and other content drawn by the View. The GetContentSize() method gets the size of the content area of the view. Content Area refers to the rectangle with a location of 0,0 with the size returned by GetContentSize().

The Content Area size tracks the size of the Viewport by default. If the content size is set via @Terminal.Gui.View.SetContentSize, the content area is the provided size. If the content size is larger than the Viewport, scrolling is enabled.

The Viewport

The Viewport (@Terminal.Gui.View.Viewport) is a rectangle describing the portion of the Content Area that is currently visible to the user. It is a "portal" into the content. The Viewport.Location is relative to the top-left corner of the inner rectangle of View.Padding. If Viewport.Size is the same as View.GetContentSize(), Viewport.Location will be 0,0.

To enable scrolling call View.SetContentSize() and then set Viewport.Location to positive values. Making Viewport.Location positive moves the Viewport down and to the right in the content.

See the Scrolling Deep Dive for details on how to enable scrolling.

The ViewportSettings property controls how the Viewport is constrained. By default, the ViewportSettings is set to ViewportSettings.None. To enable the viewport to be moved up-and-to-the-left of the content, use ViewportSettings.AllowNegativeX and or ViewportSettings.AllowNegativeY.

The default ViewportSettings also constrains the Viewport to the size of the content, ensuring the right-most column or bottom-most row of the content will always be visible (in v1 the equivalent concept was ScrollBarView.AlwaysKeepContentInViewport). To allow the Viewport to be smaller than the content, set ViewportSettings.AllowXGreaterThanContentWidth and/or ViewportSettings.AllowXGreaterThanContentHeight.

Layout

Terminal.Gui provides a rich system for how views are laid out relative to each other. The position of a view is set by setting the X and Y properties, which are of time Pos. The size is set via Width and Height, which are of type Dim.

var label1 = new Label () { X = 1, Y = 2, Width = 3, Height = 4, Title = "Absolute")

var label2 = new Label () {
    Title = "Computed",
    X = Pos.Right (otherView),
    Y = Pos.Center (),
    Width = Dim.Fill (),
    Height = Dim.Percent (50)
};

The Frame property is a rectangle that provides the current location and size of the view relative to the View's Superview's Content area.

The Pos Type

The Pos is the type of View.X and View.Y and supports the following sub-types:

All Pos coordinates are relative to the SuperView's content area.

Pos values can be combined using addition or subtraction:

// 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) + 5;

The Dim Type

The Dim is the type of View.Width and View.Height and supports the following sub-types:

All Dim dimensions are relative to the SuperView's content area.

Like, Pos, objects of type Dim can be combined using addition or subtraction, 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;