Terminal.Gui/docfx/docs/View.md

View Deep Dive

View is the base class for all visible UI elements in Terminal.Gui. View provides core functionality for layout, drawing, input handling, navigation, and scrolling. All interactive controls, windows, and dialogs derive from View.

See the Views Overview for a catalog of all built-in View subclasses.

Table of Contents

• View Hierarchy
• View Composition
• Core Concepts
• View Lifecycle
• Subsystems
• Common View Patterns
• Modal Views

---

View Hierarchy

Terminology

• View - The base class for all visible UI elements
• SubView - A View that is contained in another View and rendered as part of the containing View's content area. SubViews are added via View.Add
• SuperView - The View that contains SubViews. Each View has a View.SuperView property that references its container
• Child View - A view that holds a reference to another view in a parent/child relationship (used sparingly; generally SubView/SuperView is preferred)
• Parent View - A view that holds a reference to another view but is NOT a SuperView (used sparingly)

Key Properties

• View.SubViews - Read-only list of all SubViews added to this View
• View.SuperView - The View's container (null if the View has no container)
• View.Id - Unique identifier for the View (should be unique among siblings)
• View.Data - Arbitrary data attached to the View
• View.App - The application context this View belongs to
• View.Driver - The driver used for rendering (derived from App). This is a shortcut to App.Driver for convenience.

---

View Composition

Views are composed of several nested layers that define how they are positioned, drawn, and scrolled:

[!INCLUDE View Composition]

The Layers

1. Frame - The outermost rectangle defining the View's location and size relative to the SuperView's content area
2. Margin - Adornment that provides spacing between the View and other SubViews
3. Border - Adornment that draws the visual border and title
4. Padding - Adornment that provides spacing between the border and the viewport
5. Viewport - Rectangle describing the visible portion of the content area
6. Content Area - The total area where content can be drawn (defined by View.GetContentSize)

See the Layout Deep Dive for complete details on View composition and layout.

---

Core Concepts

Frame vs. Viewport

• Frame - The View's location and size in SuperView-relative coordinates. Frame includes all adornments (Margin, Border, Padding)
• Viewport - The visible "window" into the View's content, located inside the adornments. Viewport coordinates are always relative to (0,0) of the content area

// Frame is SuperView-relative
view.Frame = new Rectangle(10, 5, 50, 20);

// Viewport is content-relative (the visible portal)
view.Viewport = new Rectangle(0, 0, 45, 15); // Adjusted for adornments

Content Area and Scrolling

The Content Area is where the View's content is drawn. By default, the content area size matches the Viewport size. To enable scrolling:

1. Call View.SetContentSize with a size larger than the Viewport
2. Change Viewport.Location to scroll the content

See the Scrolling Deep Dive for complete details.

Adornments

Adornments are special Views that surround the content:

• Margin - Transparent spacing outside the Border
• Border - Visual frame with LineStyle, title, and arrangement UI
• Padding - Spacing inside the Border, outside the Viewport

Each adornment has a Thickness that defines the width of each side (Top, Right, Bottom, Left).

See the Layout Deep Dive for complete details on adornments.

---

View Lifecycle

Initialization

Views implement ISupportInitializeNotification:

1. Constructor - Creates the View and sets up default state
2. BeginInit - Signals initialization is starting
3. EndInit - Signals initialization is complete; raises View.Initialized event
4. IsInitialized - Property indicating if initialization is complete

During initialization, View.App is set to reference the application context, enabling views to access application services like the driver and current session.

Disposal

Views are IDisposable:

• Call View.Dispose to clean up resources
• The View.Disposing event is raised when disposal begins
• Automatically disposes SubViews, adornments, and scroll bars

---

Subsystems

View is organized as a partial class across multiple files, each handling a specific subsystem:

Commands

See the Command Deep Dive.

• View.AddCommand - Declares commands the View supports
• View.InvokeCommand - Invokes a command
• Command enum - Standard set of commands (Accept, Select, HotKey, etc.)

Input Handling

Keyboard

See the Keyboard Deep Dive.

• View.KeyBindings - Maps keys to Commands
• View.HotKey - The hot key for the View
• View.HotKeySpecifier - Character used to denote hot keys in text (default: '_')
• Events: KeyDown, KeyUp, InvokingKeyBindings

Mouse

See the Mouse Deep Dive.

• View.MouseBindings - Maps mouse events to Commands
• View.WantContinuousButtonPresses - Enables continuous button press events
• View.Highlight - Event for visual feedback on mouse hover/click
• View.HighlightStyle - Visual style when highlighted
• Events: MouseEnter, MouseLeave, MouseClick, MouseEvent

Layout and Arrangement

See the Layout Deep Dive and Arrangement Deep Dive.

Position and Size

• View.X - Horizontal position using Pos
• View.Y - Vertical position using Pos
• View.Width - Width using Dim
• View.Height - Height using Dim

Layout Features

• Dim.Auto - Automatic sizing based on content
• Pos.AnchorEnd - Anchor to right/bottom edges
• Pos.Align - Align views relative to each other
• Pos.Center - Center within SuperView
• Dim.Fill - Fill available space

Arrangement

• View.Arrangement - Controls if View is movable/resizable
• ViewArrangement - Flags: Fixed, Movable, Resizable, Overlapped

Events

• LayoutStarted - Before layout begins
• LayoutComplete - After layout completes
• FrameChanged - When Frame changes
• ViewportChanged - When Viewport changes

Drawing

See the Drawing Deep Dive.

Color and Style

• View.Scheme - Color scheme for the View
• View.SetAttribute - Sets the attribute for subsequent drawing
• View.SetAttributeForRole - Sets attribute based on VisualRole

See the Scheme Deep Dive for details on color theming.

Drawing Methods

• View.Draw - Main drawing method
• View.AddRune - Draws a single Rune
• View.AddStr - Draws a string
• View.Move - Positions the cursor
• View.Clear - Clears the View's content

Drawing Events

• DrawingContent - Before content is drawn
• DrawingContentComplete - After content is drawn
• DrawingAdornments - Before adornments are drawn
• DrawingAdornmentsComplete - After adornments are drawn

Invalidation

• View.SetNeedsDraw - Marks View as needing redraw
• View.NeedsDraw - Property indicating if View needs redraw

Navigation

See the Navigation Deep Dive.

• View.CanFocus - Whether the View can receive keyboard focus
• View.HasFocus - Whether the View currently has focus
• View.TabStop - TabBehavior for tab navigation
• View.TabIndex - Order in tab navigation
• View.SetFocus - Gives focus to the View

Events:

• HasFocusChanging - Before focus changes (cancellable)
• HasFocusChanged - After focus changes
• Accepting - When Command.Accept is invoked (typically Enter key)
• Accepted - After Command.Accept completes
• Selecting - When Command.Select is invoked (typically Space or mouse click)
• Selected - After Command.Select completes

Scrolling

See the Scrolling Deep Dive.

• View.Viewport - Visible portion of the content area
• View.GetContentSize - Returns size of scrollable content
• View.SetContentSize - Sets size of scrollable content
• View.ScrollHorizontal - Scrolls content horizontally
• View.ScrollVertical - Scrolls content vertically
• View.VerticalScrollBar - Built-in vertical scrollbar
• View.HorizontalScrollBar - Built-in horizontal scrollbar
• View.ViewportSettings - ViewportSettingsFlags controlling scroll behavior

Text

• View.Text - The View's text content
• View.Title - The View's title (shown in Border)
• View.TextFormatter - Handles text formatting and alignment
• View.TextDirection - Text direction (LeftRight, RightToLeft, TopToBottom)
• View.TextAlignment - Text alignment (Left, Centered, Right, Justified)
• View.VerticalTextAlignment - Vertical alignment (Top, Middle, Bottom, Justified)

---

View Lifecycle

1. Creation

View view = new ()
{
    X = Pos.Center(),
    Y = Pos.Center(),
    Width = Dim.Percent(50),
    Height = Dim.Fill()
};

2. Initialization

When a View is added to a SuperView or when Application.Run is called:

1. BeginInit is called
2. EndInit is called
3. IsInitialized becomes true
4. Initialized event is raised

3. Layout

Layout happens automatically when needed:

1. View.SetNeedsLayout marks View as needing layout
2. View.Layout calculates position and size
3. LayoutStarted event is raised
4. Frame and Viewport are calculated based on X, Y, Width, Height
5. SubViews are laid out
6. LayoutComplete event is raised

4. Drawing

Drawing happens automatically when needed:

1. View.SetNeedsDraw marks View as needing redraw
2. View.Draw renders the View
3. DrawingContent event is raised
4. View.OnDrawingContent is called (override to draw custom content)
5. DrawingContentComplete event is raised
6. Adornments are drawn
7. SubViews are drawn

5. Input Processing

Input is processed in this order:

1. Keyboard: Key → KeyBindings → Command → Command Handlers → Events
2. Mouse: MouseEvent → MouseBindings → Command → Command Handlers → Events

6. Disposal

view.Dispose();

• Raises View.Disposing event
• Disposes adornments, scrollbars, SubViews
• Cleans up event handlers and resources

---

Subsystems

Commands

See the Command Deep Dive for complete details.

Views use a command pattern for handling input:

// Add a command the view supports
view.AddCommand (Command.Accept, () => 
{
    // Handle the Accept command
    return true;
});

// Bind a key to the command
view.KeyBindings.Add (Key.Enter, Command.Accept);

// Bind a mouse action to the command
view.MouseBindings.Add (MouseFlags.Button1Clicked, Command.Select);

Input

Keyboard

See the Keyboard Deep Dive for complete details.

The keyboard subsystem processes key presses through:

1. View.KeyDown event (cancellable)
2. View.OnKeyDown virtual method
3. View.KeyBindings - Converts keys to commands
4. Command handlers (registered via View.AddCommand)
5. View.KeyUp event

Mouse

See the Mouse Deep Dive for complete details.

The mouse subsystem processes mouse events through:

1. View.MouseEvent event (low-level)
2. View.OnMouseEvent virtual method
3. View.MouseEnter / View.MouseLeave events
4. View.MouseBindings - Converts mouse actions to commands
5. Command handlers
6. View.MouseClick event (high-level)

Layout

See the Layout Deep Dive for complete details.

Layout is declarative using Pos and Dim:

var label = new Label { Text = "Name:" };
var textField = new TextField 
{ 
    X = Pos.Right(label) + 1,
    Y = Pos.Top(label),
    Width = Dim.Fill()
};

The layout system automatically:

• Calculates Frame based on X, Y, Width, Height
• Handles Adornment thickness
• Calculates Viewport
• Lays out SubViews recursively

Drawing

See the Drawing Deep Dive for complete details.

Views draw themselves using viewport-relative coordinates:

protected override bool OnDrawingContent()
{
    // Draw at viewport coordinates (0,0)
    Move(0, 0);
    SetAttribute(new Attribute(Color.White, Color.Blue));
    AddStr("Hello, Terminal.Gui!");
    
    return true;
}

Key drawing concepts:

• LineCanvas - For drawing lines with auto-joining
• Attribute - Color and text style
• TextStyle - Bold, Italic, Underline, etc.
• Gradient / GradientFill - Color gradients

Navigation

See the Navigation Deep Dive for complete details.

Navigation controls keyboard focus movement:

• View.CanFocus - Whether View can receive focus
• View.TabStop - TabBehavior (NoStop, TabStop, TabGroup)
• View.TabIndex - Tab order within SuperView
• View.SetFocus - Requests focus
• View.AdvanceFocus - Moves focus to next/previous View

Scrolling

See the Scrolling Deep Dive for complete details.

Scrolling is built into every View:

// Set content size larger than viewport
view.SetContentSize(new Size(100, 100));

// Scroll the content
view.Viewport = view.Viewport with { Location = new Point(10, 10) };

// Or use helper methods
view.ScrollVertical(5);
view.ScrollHorizontal(3);

// Enable scrollbars
view.VerticalScrollBar.Visible = true;
view.HorizontalScrollBar.Visible = true;

---

Common View Patterns

Creating a Custom View

public class MyCustomView : View
{
    public MyCustomView()
    {
        // Set up default size
        Width = Dim.Auto();
        Height = Dim.Auto();
        
        // Can receive focus
        CanFocus = true;
        
        // Add supported commands
        AddCommand(Command.Accept, HandleAccept);
        
        // Configure key bindings
        KeyBindings.Add(Key.Enter, Command.Accept);
    }
    
    protected override bool OnDrawingContent()
    {
        // Draw custom content using viewport coordinates
        Move(0, 0);
        SetAttributeForRole(VisualRole.Normal);
        AddStr("My custom content");
        
        return true; // Handled
    }
    
    private bool HandleAccept()
    {
        // Handle the Accept command
        // Raise events, update state, etc.
        return true; // Handled
    }
}

Adding SubViews

var container = new View
{
    Width = Dim.Fill(),
    Height = Dim.Fill()
};

var button1 = new Button { Text = "OK", X = 2, Y = 2 };
var button2 = new Button { Text = "Cancel", X = Pos.Right(button1) + 2, Y = 2 };

container.Add(button1, button2);

Using Adornments

var view = new View
{
    BorderStyle = LineStyle.Double,
    Title = "My View"
};

// Configure border
view.Border.Thickness = new Thickness(1);
view.Border.Settings = BorderSettings.Title;

// Add padding
view.Padding.Thickness = new Thickness(1);

// Add margin
view.Margin.Thickness = new Thickness(2);

Implementing Scrolling

var view = new View
{
    Width = 40,
    Height = 20
};

// Set content larger than viewport
view.SetContentSize(new Size(100, 100));

// Enable scrollbars with auto-show
view.VerticalScrollBar.AutoShow = true;
view.HorizontalScrollBar.AutoShow = true;

// Add key bindings for scrolling
view.KeyBindings.Add(Key.CursorUp, Command.ScrollUp);
view.KeyBindings.Add(Key.CursorDown, Command.ScrollDown);
view.KeyBindings.Add(Key.CursorLeft, Command.ScrollLeft);
view.KeyBindings.Add(Key.CursorRight, Command.ScrollRight);

// Add command handlers
view.AddCommand(Command.ScrollUp, () => { view.ScrollVertical(-1); return true; });
view.AddCommand(Command.ScrollDown, () => { view.ScrollVertical(1); return true; });

---

Runnable Views (IRunnable)

Views can implement IRunnable to run as independent, blocking sessions with typed results. This decouples runnability from inheritance, allowing any View to participate in session management.

IRunnable Architecture

The IRunnable pattern provides:

• Interface-Based: Implement IRunnable<TResult> instead of inheriting from Toplevel
• Type-Safe Results: Generic TResult parameter for compile-time type safety
• Fluent API: Chain Init(), Run(), and Shutdown() for concise code
• Automatic Disposal: Framework manages lifecycle of created runnables
• CWP Lifecycle Events: IsRunningChanging/Changed, IsModalChanging/Changed

Creating a Runnable View

Derive from Runnable or implement IRunnable:

public class ColorPickerDialog : Runnable<Color?>
{
    private ColorPicker16 _colorPicker;
    
    public ColorPickerDialog()
    {
        Title = "Select a Color";
        
        _colorPicker = new ColorPicker16 { X = Pos.Center(), Y = 2 };
        
        var okButton = new Button { Text = "OK", IsDefault = true };
        okButton.Accepting += (s, e) => {
            Result = _colorPicker.SelectedColor;
            Application.RequestStop();
        };
        
        Add(_colorPicker, okButton);
    }
}

Running with Fluent API

The fluent API enables elegant, concise code with automatic disposal:

// Framework creates, runs, and disposes the runnable automatically
Color? result = Application.Create()
                           .Init()
                           .Run<ColorPickerDialog>()
                           .Shutdown() as Color?;

if (result is { })
{
    Console.WriteLine($"Selected: {result}");
}

Running with Explicit Control

For more control over the lifecycle:

var app = Application.Create();
app.Init();

var dialog = new ColorPickerDialog();
app.Run(dialog);

// Extract result after Run returns
Color? result = dialog.Result;

// Caller is responsible for disposal
dialog.Dispose();

app.Shutdown();

Disposal Semantics

"Whoever creates it, owns it":

• Run<TRunnable>(): Framework creates → Framework disposes (in Shutdown())
• Run(IRunnable): Caller creates → Caller disposes

Result Extraction

Extract the result in OnIsRunningChanging when stopping:

protected override bool OnIsRunningChanging(bool oldIsRunning, bool newIsRunning)
{
    if (!newIsRunning)  // Stopping - extract result before disposal
    {
        Result = _colorPicker.SelectedColor;
        
        // Optionally cancel stop (e.g., prompt to save)
        if (HasUnsavedChanges())
        {
            return true;  // Cancel stop
        }
    }
    
    return base.OnIsRunningChanging(oldIsRunning, newIsRunning);
}

Lifecycle Properties

• IsRunning - True when on the RunnableSessionStack
• IsModal - True when at the top of the stack (receiving all input)
• Result - The typed result value (set before stopping)

Lifecycle Events (CWP-Compliant)

• IsRunningChanging - Cancellable event before added/removed from stack
• IsRunningChanged - Non-cancellable event after stack change
• IsModalChanging - Cancellable event before becoming/leaving top of stack
• IsModalChanged - Non-cancellable event after modal state change

---

Modal Views (Legacy)

Views can run modally (exclusively capturing all input until closed). See Toplevel for the legacy pattern.

Note: New code should use IRunnable<TResult> pattern (see above) for better type safety and lifecycle management.

Running a View Modally (Legacy)

var dialog = new Dialog
{
    Title = "Confirmation",
    Width = Dim.Percent(50),
    Height = Dim.Percent(50)
};

// Add content...
var label = new Label { Text = "Are you sure?", X = Pos.Center(), Y = 1 };
dialog.Add(label);

// Run modally - blocks until closed
Application.Run(dialog);

// Dialog has been closed
dialog.Dispose();

Modal View Types (Legacy)

• Toplevel - Base class for modal views, can fill entire screen
• Window - Overlapped container with border and title
• Dialog - Modal Window, centered with button support
• Wizard - Multi-step modal dialog

Dialog Example (Legacy)

Dialogs are Modal Windows centered on screen:

bool okPressed = false;
var ok = new Button { Text = "Ok" };
ok.Accepting += (s, e) => { okPressed = true; Application.RequestStop(); };

var cancel = new Button { Text = "Cancel" };
cancel.Accepting += (s, e) => Application.RequestStop();

var dialog = new Dialog 
{ 
    Title = "Quit",
    Width = 50,
    Height = 10
};
dialog.Add(new Label { Text = "Are you sure you want to quit?", X = Pos.Center(), Y = 2 });
dialog.AddButton(ok);
dialog.AddButton(cancel);

Application.Run(dialog);

if (okPressed)
{
    // User clicked OK
}

Which displays:

╔═ Quit ═══════════════════════════════════════════╗
║                                                  ║
║          Are you sure you want to quit?         ║
║                                                  ║
║                                                  ║
║                                                  ║
║                [ Ok ]  [ Cancel ]                ║
╚══════════════════════════════════════════════════╝

Wizard Example

Wizards let users step through multiple pages:

var wizard = new Wizard { Title = "Setup Wizard" };

var step1 = new WizardStep { Title = "Welcome" };
step1.Add(new Label { Text = "Welcome to the wizard!", X = 1, Y = 1 });

var step2 = new WizardStep { Title = "Configuration" };
step2.Add(new TextField { X = 1, Y = 1, Width = 30 });

wizard.AddStep(step1);
wizard.AddStep(step2);

Application.Run(wizard);

---

Advanced Topics

View Diagnostics

View.Diagnostics - ViewDiagnosticFlags for debugging:

• Ruler - Shows a ruler around the View
• DrawIndicator - Shows an animated indicator when drawing
• FramePadding - Highlights the Frame with color

View States

• View.Enabled - Whether the View is enabled
• View.Visible - Whether the View is visible
• View.CanFocus - Whether the View can receive focus
• View.HasFocus - Whether the View currently has focus

Shadow Effects

View.ShadowStyle - ShadowStyle for drop shadows:

view.ShadowStyle = ShadowStyle.Transparent;

---

See Also

• Application Deep Dive - Instance-based application architecture
• Views Overview - Complete list of all built-in Views
• Layout Deep Dive - Detailed layout system documentation
• Drawing Deep Dive - Drawing system and color management
• Keyboard Deep Dive - Keyboard input handling
• Mouse Deep Dive - Mouse input handling
• Navigation Deep Dive - Focus and navigation system
• Scrolling Deep Dive - Scrolling and viewport management
• Command Deep Dive - Command pattern and bindings
• Arrangement Deep Dive - Movable and resizable views
• Configuration Deep Dive - Configuration and persistence
• Scheme Deep Dive - Color theming