Table of Contents

Drawing (Text, Lines, and Color)

Terminal.Gui provides a set of APIs for formatting text, line drawing, and character-based graphing.

Drawing Taxonomy & Lexicon

Term Meaning
Attribute Defines concrete visual styling for a visual element (Foreground color, Background color, TextStyle).
BackgroundColor A property of Attribute describing the background text color.
Color Base terminal color (supports TrueColor and named values like White, Black, Cyan, etc.).
ForegroundColor A property of Attribute describing the foreground text color.
Glyph A graphical representation of a character.
Rune Unicode character.
Scheme Maps VisualRole to Attribute, defining visual element appearance (color and style) based on semantic purpose.
Style Property of Attribute for font-like hints (bold, italic, underline).
VisualRole Semantic role/purpose of a visual element (Normal, Focus, HotFocus, Active, Disabled, ReadOnly).

View Drawing API

Terminal.Gui apps draw using the Move(int, int) and AddRune(Rune) APIs. Move selects the column and row of the cell and AddRune places the specified glyph in that cell using the Attribute that was most recently set via SetAttribute(Attribute). The ConsoleDriver caches all changed Cells and efficiently outputs them to the terminal each iteration of the Application. In other words, Terminal.Gui uses deferred rendering.

Coordinate System for Drawing

The View draw APIs all take coordinates specified in Viewport-Relative coordinates. That is, 0, 0 is the top-left cell visible to the user.

See Layout for more details of the Terminal.Gui coordinate system.

Outputting unformatted text

  1. Moving the draw cursor using Move(int, int).
  2. Setting the attributes using SetAttribute(Attribute).
  3. Outputting glyphs by calling AddRune(Rune) or AddStr(string) .

Outputting formatted text

  1. Adding the text to a TextFormatter object.
  2. Setting formatting options, such as Alignment.
  3. Calling Draw(Rectangle, Attribute, Attribute, Rectangle, IConsoleDriver?).

Line drawing

  1. Add the lines via LineCanvas
  2. Either render the line canvas via GetMap() or let the View do so automatically (which enables automatic line joining across Views).

When Drawing Occurs

The Application MainLoop will iterate over all Views in the view hierarchy performing the following steps:

  1. Determines if NeedsDraw or SubViewNeedsDraw are set. If neither is set, processing stops.
  2. Sets the clip to the view's Frame.
  3. Draws the Border and Padding (but NOT the Margin).
  4. Sets the clip to the view's Viewport.
  5. Sets the Normal color scheme.
  6. Calls Draw on any SubViews.
  7. Draws Text.
  8. Draws any non-text content (the base View does nothing.)
  9. Sets the clip back to the view's Frame.
  10. Draws LineCanvas (which may have been added to by any of the steps above).
  11. Draws the Border and Padding SubViews (just the subviews). (but NOT the Margin).
  12. The Clip at this point excludes all SubViews NOT INCLUDING their Margins. This clip is cached so Margin can be rendered later.
  13. DrawComplete is raised.
  14. The current View's Frame NOT INCLUDING the Margin is excluded from the current Clip region.

Most of the steps above can be overridden by developers using the standard Terminal.Gui Cancellable Work Pattern. For example, the base View always clears the viewport. To override this, a subclass can override OnClearingViewport() to simply return true. Or, a user of View can subscribe to the ClearingViewport event and set the Cancel argument to true.

Then, after the above steps have completed, the Mainloop will iterate through all views in the view hierarchy again, this time calling Draw on any Margin objects, using the cached Clip region mentioned above. This enables Margin to be transparent.

Declaring that drawing is needed

If a View need to redraw because something changed within it's Content Area it can call SetNeedsDraw(). If a View needs to be redrawn because something has changed the size of the Viewport, it can call SetNeedsLayout().

Clipping

Clipping enables better performance and features like transparent margins by ensuring regions of the terminal that need to be drawn actually get drawn by the ConsoleDriver. Terminal.Gui supports non-rectangular clip regions with Region. Clip is the application managed clip region and is managed by Application. Developers cannot change this directly, but can use SetClipToScreen(), SetClip(Region?), @Terminal.Gui.ViewBase.View.SetClipToFrame, etc...

Cell

The Cell class represents a single cell on the screen. It contains a character and an attribute. The character is of type Rune and the attribute is of type Attribute.

Cell is not exposed directly to the developer. Instead, the ConsoleDriver classes manage the Cell array that represents the screen.

To draw a Cell to the screen, use Move(int, int) to specify the row and column coordinates and then use the AddRune(int, int, Rune) method to draw a single glyph.

// ... existing code ...

Attribute

The Attribute class represents the formatting attributes of a Cell. It exposes properties for the foreground and background colors as well as the text style. The foreground and background colors are of type Color. Bold, underline, and other formatting attributes are supported via the Style property.

Use SetAttribute(Attribute) to indicate which Attribute subsequent AddRune(Rune) and AddStr(string) calls will use:

// This is for illustration only. Developers typically use SetAttributeForRole instead.
SetAttribute (new Attribute (Color.Red, Color.Black, Style.Underline));
AddStr ("Red on Black Underlined.");

In the above example a hard-coded Attribute is set. Normally, developers will use SetAttributeForRole(VisualRole) to have the system use the Attributes associated with a VisualRole (see below).

// Modify the View's Scheme such that Focus is Red on Black Underlined
SetScheme (new Scheme (Scheme)
    {
        Focus = new Attribute (Color.Red, Color.Black, Style.Underline)
    });
    
SetAttributeForRole (VisualRole.Focus);
AddStr ("Red on Black Underlined.");

// ... existing code ...

VisualRole

Represents the semantic visual role of a visual element rendered by a View (e.g., Normal text, Focused item, Active selection).

VisualRole provides a set of predefined VisualRoles:

namespace Terminal.Gui.Drawing;

/// <summary>
///     Represents the semantic visual role of a visual element rendered by a <see cref="View"/>. Each VisualRole maps to
///     a property of <see cref="Scheme"/> (e.g., <see cref="Scheme.Normal"/>).
/// </summary>
/// <remarks>
///     A single View may render as one or multiple elements. Each element can be associated with a different
///     <see cref="VisualRole"/>.
/// </remarks>
public enum VisualRole
{
    /// <summary>
    ///     The default visual role for unfocused, unselected, enabled elements.
    /// </summary>
    Normal,

    /// <summary>
    ///     The visual role for <see cref="Normal"/> elements with a <see cref="View.HotKey"/> indicator.
    /// </summary>
    HotNormal,

    /// <summary>
    ///     The visual role when the element is focused.
    /// </summary>
    Focus,

    /// <summary>
    ///     The visual role for <see cref="Focus"/> elements with a <see cref="View.HotKey"/> indicator.
    /// </summary>
    HotFocus,

    /// <summary>
    ///     The visual role for elements that are active or selected (e.g., selected item in a <see cref="ListView"/>). Also
    ///     used
    ///     for headers in, <see cref="HexView"/>, <see cref="CharMap"/> and  <see cref="TabView"/>.
    /// </summary>
    Active,

    /// <summary>
    ///     The visual role for <see cref="Active"/> elements with a <see cref="View.HotKey"/> indicator.
    /// </summary>
    HotActive,

    /// <summary>
    ///     The visual role for elements that are highlighted (e.g., when the mouse is inside over a <see cref="Button"/>).
    /// </summary>
    Highlight,

    /// <summary>
    ///     The visual role for elements that are disabled and not interactable.
    /// </summary>
    Disabled,

    /// <summary>
    ///     The visual role for elements that are editable (e.g., <see cref="TextField"/> and <see cref="TextView"/>).
    /// </summary>
    Editable,

    /// <summary>
    ///     The visual role for elements that are normally editable but currently read-only.
    /// </summary>
    ReadOnly
}

Schemes

A Scheme is named a mapping from VisualRoles (e.g. VisualRole.Focus) to Attributes, defining how a View should look based on its purpose (e.g. Menu or Dialog). @Terminal.Gui.SchemeManager.Schemes is a dictionary of Schemes, indexed by name.

A Scheme defines how Views look based on their semantic purpose. The following schemes are supported:

Scheme Name Description
Base The base scheme used for most Views.
Dialog The dialog scheme; used for Dialog, MessageBox, and other views dialog-like views.
Error The scheme for showing errors, such as in ErrorQuery.
Menu The menu scheme; used for Terminal.Gui.Menu, MenuBar, and StatusBar.
TopLevel The application TopLevel scheme; used for the TopLevel View.

@Terminal.Gui.SchemeManager manages the set of available schemes and provides a set of convenience methods for getting the current scheme and for overriding the default values for these schemes.

Scheme dialogScheme = SchemeManager.GetScheme (Schemes.Dialog);

ConfigurationManager can be used to override the default values for these schemes and add additional schemes.

See Scheme Deep Dive for more details.

Text Formatting

Terminal.Gui supports text formatting using TextFormatter. TextFormatter provides methods for formatting text using the following formatting options:

  • Horizontal Alignment - Left, Center, Right
  • Vertical Alignment - Top, Middle, Bottom
  • Word Wrap - Enabled or Disabled
  • Formatting Hot Keys

Glyphs

The Glyphs class defines the common set of glyphs used to draw checkboxes, lines, borders, etc... The default glyphs can be changed per-ThemeScope via ConfigurationManager.

Line Drawing

Terminal.Gui supports drawing lines and shapes using box-drawing glyphs. The LineCanvas class provides auto join, a smart TUI drawing system that automatically selects the correct line/box drawing glyphs for intersections making drawing complex shapes easy. See LineCanvas.

Thickness

Describes the thickness of a frame around a rectangle. The thickness is specified for each side of the rectangle using a Thickness object. The Thickness class contains properties for the left, top, right, and bottom thickness. The Adornment class uses Thickness to support drawing the frame around a view.

See View Deep Dive for details.

Diagnostics

The DrawIndicator flag can be set on Diagnostics to cause an animated glyph to appear in the Border of each View. The glyph will animate each time that View's Draw method is called where either NeedsDraw or SubViewNeedsDraw is set.

Edit this page