View Layout Arrangement

Terminal.Gui provides a feature of Layout known as Arrangement, which controls how the user can use the mouse and keyboard to arrange views and enables either Tiled or Overlapped layouts. Arrangement is a sub-topic of Layout.

Arrangement Taxonomy & Lexicon

Term	Meaning
Arrange Mode	Interactive mode activated via Ctrl+F5 that displays indicators on arrangeable views and allows keyboard-based arrangement.
Arrangement	The feature of Layout which controls how the user can use the mouse and keyboard to arrange views and enables either Tiled or Overlapped layouts.
Modal	A view run as an "application" via @Terminal.Gui.App.Application.Run where Modal == true. Has constrained z-order with modal view at z-order 1.
Movable	A View that can be moved by the user using keyboard or mouse. Enabled by setting Movable flag.
Overlapped	Layout where SubViews have overlapping Frames with Z-order determining visual stacking. Enabled by Overlapped flag.
Resizable	A View that can be resized by the user using keyboard or mouse. Enabled by setting Resizable flag.
Runnable	A view where Application.Run(Toplevel) is called. Each non-modal Runnable view has its own RunState and operates as a self-contained application.
Tiled	Layout where SubViews typically do not overlap, with no z-order. Default layout mode set to Fixed.

Arrangement

Describes the feature of Layout which controls how the user can use the mouse and keyboard to arrange views and enables either Tiled or Overlapped layouts. The Arrangement property controls the arrangement behavior for each view.

Arrange Mode

The Arrange Modes are set via the Arrangement property. When a user presses Ctrl+F5 (configurable via the ArrangeKey property) the application goes into Arrange Mode.

In this mode, indicators are displayed on an arrangeable view indicating which aspect of the View can be arranged:

• If Movable, a ◊ will be displayed in the top-left corner of the Border
• If Resizable, pressing Tab (or Shift+Tab) will cycle to an indicator in the bottom-right corner of the Border

The up/down/left/right cursor keys will act appropriately. Esc, Ctrl+F5 or clicking outside of the Border will exit Arrange Mode.

Modal

A modal view is one that is run as an "application" via Run(Func<Exception, bool>?, IConsoleDriver?) where Modal == true.

Dialog, MessageBox, and Wizard are the prototypical examples. When run this way, there IS a z-order but it is highly-constrained: the modal view has a z-order of 1 and everything else is at 0.

Movable

Describes a View that can be moved by the user using the keyboard or mouse. Movable is enabled on a per-View basis by setting the Movable flag on Arrangement.

Dragging on the top Border of a View will move such a view. Pressing Ctrl+F5 will activate Arrange Mode letting the user move the view with the up/down/left/right cursor keys.

Overlapped

A form of layout where SubViews of a View are visually arranged such that their Frames overlap. In Overlap view arrangements there is a Z-axis (Z-order) in addition to the X and Y dimension. The Z-order indicates which Views are shown above other views.

Overlapped is enabled on a per-View basis by setting the Overlapped flag on Arrangement.

Resizable

Describes a View that can be sized by the user using the keyboard or mouse. Resizable is enabled on a per-View basis by setting the Resizable flag on Arrangement.

Dragging on the left, right, or bottom Border of a View will size that side of such a view. Pressing Ctrl+F5 will activate Arrange Mode letting the user size the view with the up/down/left/right cursor keys.

Tiled

A form of layout where SubViews of a View are visually arranged such that their Frames do not typically overlap. With Tiled views, there is no 'z-order` to the SubViews of a View.

In most use-cases, subviews do not overlap with each other (the exception being when it's done intentionally to create some visual effect). As a result, the default layout for most TUI apps is "tiled", and by default Arrangement is set to Fixed.

Runnable

Today, Overlapped and Runnable are intrinsically linked. A runnable view is one where Application.Run(Toplevel) is called. Each Runnable view where (Modal == false) has it's own RunState and is, effectively, a self-contained "application".

Application.Run() non-preemptively dispatches events (screen, keyboard, mouse, Timers, and Idle handlers) to the associated Toplevel. It is possible for such a Toplevel to create a thread and call Application.Run(someotherToplevel) on that thread, enabling pre-emptive user-interface multitasking (BackgroundWorkerCollection does this).