Terminal.Gui v2 - What's New

This document provides an in-depth overview of the new features, improvements, and architectural changes in Terminal.Gui v2 compared to v1.

For migration guidance, see the v1 To v2 Migration Guide.

Overview
Architectural Overhaul
Instance-Based Application Model
IRunnable Architecture
Modern Look & Feel
Simplified API
View Improvements
New and Improved Views
Enhanced Input Handling
Configuration and Persistence
Debugging and Performance
Additional Features

Overview

Terminal.Gui v2 represents a fundamental redesign of the library's architecture, API, and capabilities. Key improvements include:

Instance-Based Application Model - Move from static singletons to IApplication instances
IRunnable Architecture - Interface-based pattern for type-safe, runnable views
Proper Resource Management - Full IDisposable pattern with automatic cleanup
Built-in Scrolling - Every view supports scrolling inherently
24-bit TrueColor - Full color spectrum by default
Enhanced Input - Modern keyboard and mouse APIs
Improved Layout - Simplified with adornments (Margin, Border, Padding)
Better Navigation - Decoupled focus and tab navigation
Configuration System - Persistent themes and settings
Logging and Metrics - Built-in debugging and performance tracking

Architectural Overhaul

Design Philosophy

Terminal.Gui v2 was designed with these core principles:

Separation of Concerns - Layout, focus, input, and drawing are cleanly decoupled
Performance - Reduced overhead in rendering and event handling
Modern .NET Practices - Standard patterns like EventHandler<T> and IDisposable
Testability - Views can be tested in isolation without global state
Accessibility - Improved keyboard navigation and visual feedback

Result

Thousands of lines of redundant or complex code removed
More modular and maintainable codebase
Better performance and predictability
Easier to extend and customize

Instance-Based Application Model

See the Application Deep Dive for complete details.

v2 introduces an instance-based architecture that eliminates global state and enables multiple application contexts.

Key Features

IApplication Interface:

Application.Create() returns an IApplication instance
Multiple applications can coexist (useful for testing)
Each instance manages its own driver, session stack, and resources

View.App Property:

Every view has an App property referencing its IApplication context
Views access application services through App (driver, session management, etc.)
Eliminates static dependencies, improving testability

Session Management:

SessionStack tracks all running sessions as a stack
TopRunnable property references the currently active session
Begin() and End() methods manage session lifecycle

Example

// Instance-based pattern (recommended)
IApplication app = Application.Create ().Init ();
Window window = new () { Title = "My App" };
app.Run (window);
window.Dispose ();
app.Dispose ();

// With using statement for automatic disposal
using (IApplication app = Application.Create ().Init ())
{
    Window window = new () { Title = "My App" };
    app.Run (window);
    window.Dispose ();
} // app.Dispose() called automatically

// Access from within a view
public class MyView : View
{
    public void DoWork ()
    {
        App?.Driver.Move (0, 0);
        App?.TopRunnableView?.SetNeedsDraw ();
    }
}

Benefits

Testability - Mock IApplication for unit tests
No Global State - Multiple contexts can coexist
Clear Ownership - Views explicitly know their context
Proper Cleanup - IDisposable ensures resources are released

Resource Management

v2 implements full IDisposable pattern:

// Recommended: using statement
using (IApplication app = Application.Create ().Init ())
{
    app.Run<MyDialog> ();
    MyResult? result = app.GetResult<MyResult> ();
}

// Ensures:
// - Input thread stopped cleanly
// - Driver resources released
// - No thread leaks in tests

Important Changes:

Shutdown() method is obsolete - use Dispose() instead
Always dispose applications (especially in tests)
Input thread runs at ~50 polls/second (20ms throttle) until disposed

IRunnable Architecture

See the Application Deep Dive for complete details.

v2 introduces IRunnable<TResult> - an interface-based pattern for runnable views with type-safe results.

Key Features

Interface-Based:

Implement IRunnable<TResult> without inheriting from Runnable
Any view can be runnable
Decouples runnability from view hierarchy

Type-Safe Results:

Generic TResult parameter provides compile-time type safety
null indicates cancellation/non-acceptance
Results extracted before disposal in lifecycle events

Lifecycle Events (CWP-Compliant):

IsRunningChanging - Cancellable, before stack change
IsRunningChanged - Non-cancellable, after stack change
IsModalChanging - Cancellable, before modal state change
IsModalChanged - Non-cancellable, after modal state change

Example

public class FileDialog : Runnable<string?>
{
    private TextField _pathField;
    
    public FileDialog ()
    {
        Title = "Select File";
        _pathField = new () { Width = Dim.Fill () };
        Add (_pathField);
        
        Button okButton = new () { Text = "OK", IsDefault = true };
        okButton.Accepting += (s, e) =>
        {
            Result = _pathField.Text;
            Application.RequestStop ();
        };
        AddButton (okButton);
    }
    
    protected override bool OnIsRunningChanging (bool oldValue, bool newValue)
    {
        if (!newValue)  // Stopping - extract result before disposal
        {
            Result = _pathField?.Text;
            
            // Optionally cancel stop
            if (HasUnsavedChanges ())
            {
                return true; // Cancel
            }
        }
        return base.OnIsRunningChanging (oldValue, newValue);
    }
}

// Use with fluent API
using (IApplication app = Application.Create ().Init ())
{
    app.Run<FileDialog> ();
    string? path = app.GetResult<string> ();
    
    if (path is { })
    {
        OpenFile (path);
    }
}

Fluent API

v2 enables elegant method chaining:

// Concise and readable
using (IApplication app = Application.Create ().Init ())
{
    app.Run<ColorPickerDialog> ();
    Color? result = app.GetResult<Color> ();
}

Key Methods:

Init() - Returns IApplication for chaining
Run<TRunnable>() - Creates and runs runnable, returns IApplication
GetResult<T>() - Extract typed result after run
Dispose() - Release all resources

Disposal Semantics

"Whoever creates it, owns it":

Method	Creator	Owner	Disposal
`Run<TRunnable>()`	Framework	Framework	Automatic when returns
`Run(IRunnable)`	Caller	Caller	Manual by caller

// Framework ownership - automatic disposal
app.Run<MyDialog> (); // Dialog disposed automatically

// Caller ownership - manual disposal
MyDialog dialog = new ();
app.Run (dialog);
dialog.Dispose (); // Caller must dispose

Benefits

Type Safety - No casting, compile-time checking
Clean Lifecycle - CWP-compliant events
Automatic Disposal - Framework manages created runnables
Flexible - Works with any View, not just Toplevel

Modern Look & Feel

24-bit TrueColor Support

See the Drawing Deep Dive for complete details.

v2 provides full 24-bit color support by default:

Implementation: Attribute class handles RGB values
Fallback: Automatic 16-color mode for older terminals
Driver Support: IConsoleDriver.SupportsTrueColor detection

Usage: Direct RGB input via Color struct

// 24-bit RGB color
Color customColor = new (0xFF, 0x99, 0x00);

// Or use named colors (ANSI-compliant)
Color color = Color.Yellow; // Was "Brown" in v1

Enhanced Borders and Adornments

See the Layout Deep Dive for complete details.

v2 introduces a comprehensive Adornment system:

Margin - Transparent spacing outside the border
Border - Visual frame with title, multiple styles
Padding - Spacing inside the border

Border Features:

Multiple LineStyle options: Single, Double, Heavy, Rounded, Dashed, Dotted
Automatic line intersection handling via LineCanvas
Configurable thickness per side via Thickness

Title display with alignment options

view.BorderStyle = LineStyle.Double;
view.Border.Thickness = new (1);
view.Title = "My View";

view.Margin.Thickness = new (2);
view.Padding.Thickness = new (1);

User Configurable Themes

See the Configuration Deep Dive and Scheme Deep Dive for details.

v2 adds comprehensive theme support:

ConfigurationManager: Loads/saves color schemes from files
Schemes: Applied per-view or globally via Scheme
Text Styles: TextStyle supports Bold, Italic, Underline, Strikethrough, Blink, Reverse, Faint

User Customization: End-users can personalize without code changes

// Apply a theme
ConfigurationManager.Themes.Theme = "Dark";

// Customize text style
view.Scheme.Normal = new (
Color.White, 
Color.Black, 
TextStyle.Bold | TextStyle.Underline
);

LineCanvas

See the Drawing Deep Dive for complete details.

LineCanvas provides sophisticated line drawing:

Auto-joining lines at intersections
Multiple line styles (Single, Double, Heavy, etc.)
Automatic glyph selection for corners and T-junctions

Used by Border, Line, and custom views

// Line view uses LineCanvas
Line line = new () { Orientation = Orientation.Horizontal };
line.LineStyle = LineStyle.Double;

Gradients

See the Drawing Deep Dive for details.

v2 adds gradient support:

Gradient - Color transitions
GradientFill - Fill patterns
Uses TrueColor for smooth effects

Apply to borders, backgrounds, or custom elements

Gradient gradient = new (Color.Blue, Color.Cyan);
view.BackgroundGradient = new (gradient, Orientation.Vertical);

Simplified API

Consistency and Reduction

v2 consolidates redundant APIs:

Centralized Navigation: ApplicationNavigation replaces scattered focus methods
Standard Events: All events use EventHandler<T> pattern
Consistent Naming: Methods follow .NET conventions (e.g., OnHasFocusChanged)
Reduced Surface: Fewer but more powerful APIs

Example:

// v1 - Multiple scattered methods
View.MostFocused
View.EnsureFocus ()
View.FocusNext ()

// v2 - Centralized
Application.Navigation.GetFocused ()
view.SetFocus ()
view.AdvanceFocus ()

Modern .NET Standards

Events: EventHandler<EventArgs> instead of custom delegates
Properties: Consistent get/set patterns
Disposal: IDisposable throughout
Nullability: Enabled in core library files

Performance Optimizations

v2 reduces overhead through:

Smarter NeedsDraw system (only draw what changed)
Reduced allocations in hot paths (event handling, rendering)
Optimized layout calculations
Efficient input processing

Result: Snappier UIs, especially with many views or frequent updates

View Improvements

Deterministic Lifetime Management

v2 clarifies view ownership:

Explicit disposal rules enforced by unit tests
Application.Run manages Runnable lifecycle
SubViews disposed automatically with SuperView
Clear documentation of ownership semantics

Built-in Scrolling

See the Scrolling Deep Dive for complete details.

Every View supports scrolling inherently:

Viewport - Visible rectangle (can have non-zero location)
GetContentSize - Returns total content size
SetContentSize - Sets scrollable content size
ScrollVertical/ScrollHorizontal - Helper methods

No need for ScrollView wrapper!

// Enable scrolling
view.SetContentSize (new (100, 100));

// Scroll by changing Viewport location
view.ScrollVertical (5);
view.ScrollHorizontal (3);

// Built-in scrollbars
view.VerticalScrollBar.Visible = true;
view.HorizontalScrollBar.Visible = true;
view.VerticalScrollBar.AutoShow = true;

Enhanced ScrollBar

v2 replaces ScrollBarView with ScrollBar:

Cleaner implementation
Automatic show/hide
Proportional sizing with ScrollSlider
Integrated with View's scrolling system
Simple to add via View.VerticalScrollBar / View.HorizontalScrollBar

Advanced Layout Features

See the Layout Deep Dive and DimAuto Deep Dive for details.

Dim.Auto:

Automatically sizes views based on content or subviews
Reduces manual layout calculations
Supports multiple styles (Text, Content, Position)

Pos.AnchorEnd:

Anchor to right or bottom of SuperView
Enables flexible, responsive layouts

Pos.Align:

Align multiple views (Left, Center, Right)

Simplifies creating aligned layouts

// Auto-size based on text
label.Width = Dim.Auto ();
label.Height = Dim.Auto ();

// Anchor to bottom-right
button.X = Pos.AnchorEnd (10);
button.Y = Pos.AnchorEnd (2);

// Center align
label1.X = Pos.Center ();
label2.X = Pos.Center ();

View Arrangement

See the Arrangement Deep Dive for complete details.

View.Arrangement enables interactive UI:

ViewArrangement.Movable - Drag with mouse or move with keyboard
ViewArrangement.Resizable - Resize edges with mouse or keyboard
ViewArrangement.Overlapped - Z-order management for overlapping views

Arrangement Key: Press Ctrl+F5 (configurable via Application.ArrangeKey) to enter arrange mode

// Movable and resizable window
window.Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable;

// Overlapped windows
container.Arrangement = ViewArrangement.Overlapped;

Enhanced Navigation

See the Navigation Deep Dive for complete details.

v2 decouples navigation concepts:

CanFocus - Whether view can receive focus (defaults to false in v2)
TabStop - TabBehavior enum (TabStop, TabGroup, NoStop)
ApplicationNavigation - Centralized navigation logic

Navigation Keys (Configurable):

Tab / Shift+Tab - Next/previous TabStop
F6 / Shift+F6 - Next/previous TabGroup

Arrow keys - Same as Tab navigation

// Configure navigation keys
Application.NextTabStopKey = Key.Tab;
Application.PrevTabStopKey = Key.Tab.WithShift;
Application.NextTabGroupKey = Key.F6;
Application.PrevTabGroupKey = Key.F6.WithShift;

// Set tab behavior
view.CanFocus = true;
view.TabStop = TabBehavior.TabStop; // Normal tab navigation

New and Improved Views

See the Views Overview for a complete catalog.

New Views in v2

Bar - Foundation for StatusBar, MenuBar, PopoverMenu
CharMap - Scrollable Unicode character map with UCD support
ColorPicker - TrueColor selection with multiple color models
DatePicker - Calendar-based date selection
FlagSelector - Non-mutually-exclusive flag selection
GraphView - Data visualization (bar, scatter, line graphs)
Line - Single lines with LineCanvas integration
NumericUpDown - Type-safe numeric input
OptionSelector - Mutually-exclusive option selection
Shortcut - Command display with key bindings
Slider - Sophisticated range selection control
SpinnerView - Animated progress indicators

Significantly Improved Views

FileDialog - TreeView navigation, Unicode icons, search, history
ScrollBar - Clean implementation with auto-show
StatusBar - Rebuilt on Bar infrastructure
TableView - Generic collections, checkboxes, tree structures, custom rendering
MenuBar / PopoverMenu - Redesigned menu system

Enhanced Input Handling

Keyboard API

See the Keyboard Deep Dive and Command Deep Dive for details.

Key Class:

Replaces v1's KeyEvent struct
High-level abstraction over raw key codes
Properties for modifiers and key type

Platform-independent

// Check keys
if (key == Key.Enter) { }
if (key == Key.C.WithCtrl) { }

// Modifiers
if (key.Shift) { }
if (key.Ctrl) { }

Key Bindings:

Map keys to Command enums
Scopes: Application, Focused, HotKey

Views declare supported commands via View.AddCommand

// Add command handler
view.AddCommand (Command.Accept, HandleAccept);

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

private bool HandleAccept ()
{
// Handle command
return true; // Handled
}

Configurable Keys:

Application.QuitKey - Close app (default: Esc)
Application.ArrangeKey - Arrange mode (default: Ctrl+F5)
Navigation keys (Tab, F6, arrows)

Mouse API

See the Mouse Deep Dive for complete details.

MouseEventArgs:

Replaces v1's MouseEventEventArgs
Cleaner structure for mouse data
MouseFlags for button states

Granular Events:

View.MouseClick - High-level click events
Double-click support
Mouse movement tracking
Viewport-relative coordinates (not screen-relative)

Highlight and Continuous Presses:

View.Highlight - Visual feedback on hover/click
View.HighlightStyle - Configure highlight appearance

View.WantContinuousButtonPresses - Repeat Command.Accept during button hold

// Highlight on hover
view.Highlight += (s, e) => { /* Visual feedback */ };
view.HighlightStyle = HighlightStyle.Hover;

// Continuous button presses
view.WantContinuousButtonPresses = true;

Configuration and Persistence

See the Configuration Deep Dive for complete details.

ConfigurationManager

ConfigurationManager provides:

JSON-based persistence
Theme management
Key binding customization
View property persistence
SettingsScope - User, Application, Machine levels

ConfigLocations - Where to search for configs

// Enable configuration
ConfigurationManager.Enable (ConfigLocations.All);

// Load a theme
ConfigurationManager.Themes.Theme = "Dark";

// Save current configuration
ConfigurationManager.Save ();

User Customization:

End-users can personalize themes, colors, text styles
Key bindings can be remapped
No code changes required
JSON files easily editable

Debugging and Performance

See the Logging Deep Dive for complete details.

Logging System

Logging integrates with Microsoft.Extensions.Logging:

Multi-level logging (Trace, Debug, Info, Warning, Error)
Internal operation tracking (rendering, input, layout)

Works with standard .NET logging frameworks (Serilog, NLog, etc.)

// Configure logging
Logging.ConfigureLogging ("myapp.log", LogLevel.Debug);

// Use in code
Logging.Debug ("Rendering view {ViewId}", view.Id);

Metrics

Logging.Meter provides performance metrics:

Frame rate tracking
Redraw times
Iteration timing
Input processing overhead

Tools: Use dotnet-counters or other metrics tools to monitor

dotnet counters monitor --name MyApp Terminal.Gui

Additional Features

Sixel Image Support

v2 supports the Sixel protocol for rendering images:

SixelEncoder - Encode images as Sixel data
SixelSupportDetector - Detect terminal support
SixelToRender - Render Sixel images
Compatible terminals: Windows Terminal, xterm, others

Use Cases: Image previews, graphics in terminal apps

AOT Support

v2 ensures compatibility with Ahead-of-Time compilation:

Avoid reflection patterns problematic for AOT
Source generators for JSON serialization via SourceGenerationContext
Single-file deployment support
Faster startup, reduced runtime overhead

Example: See Examples/NativeAot for AOT deployment

Enhanced Unicode Support

Correctly manages wide characters (CJK scripts)
TextFormatter accounts for Unicode width
Fixes v1 layout issues with wide characters
International application support

Conclusion

Terminal.Gui v2 represents a comprehensive modernization:

Architecture:

Instance-based application model
IRunnable architecture with type-safe results
Proper resource management (IDisposable)
Decoupled concerns (layout, focus, input)

Features:

24-bit TrueColor
Built-in scrolling
Enhanced adornments (Margin, Border, Padding)
Modern keyboard and mouse APIs
Configuration and themes
Logging and metrics

API:

Simplified and consistent
Modern .NET patterns
Better performance
Improved testability

Views:

Many new views (CharMap, ColorPicker, GraphView, etc.)
Significantly improved existing views
Easier to create custom views

v2 provides a robust foundation for building sophisticated, maintainable, and user-friendly terminal applications. The architectural improvements, combined with new features and enhanced APIs, enable developers to create modern terminal UIs that feel responsive and polished.

For detailed migration guidance, see the v1 To v2 Migration Guide.

newinv2.md 25 KB Geçmiş Ham

Terminal.Gui v2 - What's New

Table of Contents

Overview

Architectural Overhaul

Design Philosophy

Result

Instance-Based Application Model

Key Features

Example

Benefits

Resource Management

IRunnable Architecture

Key Features

Example

Fluent API

Disposal Semantics

Benefits

Modern Look & Feel

24-bit TrueColor Support

Enhanced Borders and Adornments

User Configurable Themes

LineCanvas

Gradients

Simplified API

Consistency and Reduction

Modern .NET Standards

Performance Optimizations

View Improvements

Deterministic Lifetime Management

Built-in Scrolling

Enhanced ScrollBar

Advanced Layout Features

View Arrangement

Enhanced Navigation

New and Improved Views

New Views in v2

Significantly Improved Views

Enhanced Input Handling

Keyboard API

Mouse API

Configuration and Persistence

ConfigurationManager

Debugging and Performance

Logging System

Metrics

Additional Features

Sixel Image Support

AOT Support

Enhanced Unicode Support

Conclusion

newinv2.md 25 KB

Geçmiş Ham