Table of Contents

View Deep Dive

Hierarchy

  • @Terminal.Gui.View - The base class for implementing higher-level visual/interactive Terminal.Gui elements. Implemented in the View base class.

  • SubView - A View that is contained in another view and will be rendered as part of the containing view's ContentArea. SubViews are added to another view via the @"Terminal.Gui.ViewBase.View.Add(Terminal.Gui.View)" method. A View may only be a SubView of a single View. Each View has a SubViews property that is a list of all SubViews that have been added.

  • @Terminal.Gui.View.SuperView - The View that is a container for SubViews. Each View has a SuperView property that references it's SuperView after it has been added.

  • Child View - A view that holds a reference to another view in a parent/child relationship. Terminal.Gui uses the terms "Child" and "Parent" sparingly. Generally SubView/SuperView is preferred.

  • Parent View - A view that holds a reference to another view in a parent/child relationship, but is NOT a SuperView of the child. Terminal.Gui uses the terms "Child" and "Parent" sparingly. Generally SubView/SuperView is preferred.

Composition

View Composition Diagram

classDiagram
    class View {
        +Frame: Rectangle
        +Margin: Adornment - outermost
        +Border: Adornment - border lines and Title
        +Padding: Adornment - innermost - Scrollbars
        +Viewport: Rectangle describing portal into ContentArea
        +ContentArea: Rectangle with Location always 0,0
        +GetContentSize(): Size
        +SetContentSize(Size)
    }

    class Adornment {
        +Thickness: Thickness
    }

    class Thickness {
        +Top: int
        +Right: int
        +Bottom: int
        +Left: int
    }

    class Rectangle {
        +Location: Point
        +Size: Size
    }

    View --> Adornment : has
    Adornment --> Thickness : has
    View --> Rectangle : has

    note for View "Frame defines location and size relative to SuperView"
    note for Adornment "Separates Frame from Viewport"
    note for Rectangle "Defines location and size"

The diagram above shows the structure of a View's composition:

  1. Frame: The outermost rectangle defining the View's location and size
  2. Margin: Separates the View from other SubViews
  3. Border: Contains visual border and title
  4. Padding: Offsets the Viewport from the Border
  5. Viewport: The visible portion of the Content Area
  6. Content Area: Where the View's content is drawn (shown larger than Viewport to illustrate scrolling)

Each layer is defined by a Thickness that specifies the width of each side (top, right, bottom, left). The Content Area is shown as a separate container that the Viewport "looks into" - this illustrates how scrolling works. In this example, the Viewport is positioned at (5,5) relative to the Content Area, showing how scrolling works.

List of Built-In Views

See List of Built-In Views

Commands

See the Command Deep Dive.

Input

See the Keyboard Deep Dive and Mouse Deep Dive.

Layout and Arrangement

See the Layout Deep Dive and the Arrangement Deep Dive.

Drawing

See the Drawing Deep Dive.

See the Navigation Deep Dive.

Scrolling

See the Scrolling Deep Dive.

Views can either be Modal or Non-modal. Modal views take over all user input until the user closes the View. Examples of Modal Views are Toplevel, Dialog, and Wizard. Non-modal views can be used to create a new experience in your application, one where you would have a new top-level menu for example. Setting the Modal property on a View to true makes it modal.

To run any View (but especially Dialogs, Windows, or Toplevels) modally, invoke the Application.Run method on a Toplevel. Use the Application.RequestStop() method to terminate the modal execution.

There is no return value from running modally, so the modal view must have a mechanism to indicate the reason the modal was closed. In the case above, the okpressed value is set to true if the user pressed or selected the Ok button.

Dialogs

Dialogs are Modal Windows that are centered in the middle of 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 the application.

Dialogs expose an API for adding buttons and managing the layout such that buttons are at the bottom of the dialog (e.g. AddButton).

Example:

bool okpressed = false;
var ok = new Button() { Title = "Ok" };
var cancel = new Button() { Title = "Cancel" };
var dialog = new Dialog () { Text = "Are you sure you want to quit?", Title = "Quit", Buttons = { ok, cancel } };

Which will show something like this:

+- Quit -----------------------------------------------+
|            Are you sure you want to quit?            |
|                                                      |
|                  [ Ok ] [ Cancel ]                   |
+------------------------------------------------------+

Wizards

Wizards are Dialogs that let users step through a series of steps to complete a task.

╔╡Gandolf - The last step╞════════════════════════════════════╗
║                                     The wizard is complete! ║
║☐ Enable Final Final Step                                    ║
║                                     Press the Finish        ║
║                                     button to continue.     ║
║                                                             ║
║                                     Pressing ESC will       ║
║                                     cancel the wizard.      ║
║                                                             ║
║                                                             ║
║─────────────────────────────────────────────────────────────║
║⟦ Back ⟧                                         ⟦► Finish ◄⟧║
╚═════════════════════════════════════════════════════════════╝

Application Concepts

  • TopLevel - The v1 term used to describe a view that can have a MenuBar and/or StatusBar. In v2, we will delete the TopLevel class and ensure ANY View can have a menu bar and/or status bar (via Adornments).

    • NOTE: There will still be an Application.Top which is the View that is the root of the Application's view hierarchy.

  • Runnable - TBD

  • Modal - Modal - The term used when describing a View that was created using the Application.Run(view) or Application.Run<T> APIs. When a View is running as a modal, user input is restricted to just that View until Application.Run exits. A Modal View has its own RunState.

    • In v1, classes derived from Dialog were originally thought to only work modally. However, Wizard proved that a Dialog-based class can also work non-modally.
    • In v2, we will simplify the Dialog class, and let any class be run via Applicaiton.Run. The Modal property will be set by Application.Run so the class can detect it is running modally if it needs to.
Edit this page