Namespace Terminal.Gui.App

Application lifecycle, initialization, and core runtime services.

The App namespace provides the application entry point and core runtime infrastructure for Terminal.Gui applications.

Key Types

Application - Static gateway class providing the main entry point
IApplication - Instance-based application interface for testability and multiple instances
ApplicationNavigation - Focus management and cursor positioning
Clipboard - Cross-platform clipboard access

Instance-Based Architecture

Terminal.Gui v2 uses an instance-based architecture where Application is a static gateway to IApplication instances:

// Recommended: Instance-based with automatic cleanup
using IApplication app = Application.Create ();
app.Init ();

using Window window = new () { Title = "Hello (Esc to quit)" };
app.Run (window);

// Legacy: Static API (supported, but not recommended)
Application.Init ();
Window window = new () { Title = "Hello (Esc to quit)" };
Application.Run (window);
window.Dispose ();
Application.Shutdown ();

The Application class provides static methods and properties for managing the application's lifecycle, configuration, and global events. It serves as the primary entry point for creating and running a Terminal.Gui application. The class includes methods for creating application instances, configuring global settings, and raising events related to application creation, initialization, and disposal.

It also provides properties for managing supported cultures and key bindings for common actions. The Application class is designed to support both a modern instance-based model (where developers create and manage their own IApplication instances) and a legacy static model (which is being phased out). The events in this class are thread-local, allowing for parallel test execution where each thread can independently monitor application instances created on that thread.

ApplicationMainLoop<TInputRecord>: The main application loop that runs Terminal.Gui's UI rendering and event processing.

ApplicationNavigation: Helper class for Application navigation and cursor handling. Held by Navigation

ApplicationPopover: Helper class for support of IPopoverView views for IApplication. Held by Popovers

CWPEventHelper: Provides helper methods for executing event-driven workflows in the Cancellable Work Pattern (CWP).

CWPPropertyHelper: Provides helper methods for executing property change workflows in the Cancellable Work Pattern (CWP).

CWPWorkflowHelper: Provides helper methods for executing single-phase and result-producing workflows in the Cancellable Work Pattern (CWP).

CancelEventArgs<T>: Provides data for events that can be cancelled without a changeable result in a cancellable workflow in the Cancellable Work Pattern (CWP).

Clipboard: Provides cut, copy, and paste support for the OS clipboard.

ClipboardBase: Shared abstract class to enforce rules from the implementation of the IClipboard interface.

EventArgs<T>: Provides data for events that convey the current value of a property or other value in a cancellable workflow (CWP).

GlobalResources: Provide static access to the ResourceManagerWrapper

LogarithmicTimeout: Implements a logarithmic increasing timeout.

Logging: Singleton logging instance class. Do not use console loggers with this class as it will interfere with Terminal.Gui screen output (i.e. use a file logger).

NotInitializedException: Thrown when user code attempts to access a property or perform a method Exception type thrown when trying to use a property or method that is only supported after initialization, e.g. of an IApplicationMainLoop<TInputRecord>

PopoverImpl: Abstract base class for popover views in Terminal.Gui. Implements IPopoverView.

Popover<TView, TResult>: A generic popover that hosts a view and optionally extracts a typed result.

ResultEventArgs<T>: Provides data for events that produce a result in a cancellable workflow in the Cancellable Work Pattern (CWP).

SessionToken: Represents a running session created by Begin(IRunnable). Wraps an IRunnable instance and is stored in SessionStack.

SessionTokenEventArgs: Event arguments for events about SessionToken

SmoothAcceleratingTimeout: Timeout which accelerates slowly at first then fast up to a maximum speed. Use AdvanceStage() to increment the stage of the timer (e.g. in your timer callback code).

TimedEvents

Manages scheduled timeouts (timed callbacks) for the application.

Allows scheduling of callbacks to be invoked after a specified delay, with optional repetition. Timeouts are stored in a sorted list by their scheduled execution time (high-resolution ticks). Thread-safe for concurrent access.

Typical usage:

<ol><li>Call <xref href="Terminal.Gui.App.TimedEvents.Add(System.TimeSpan%2cSystem.Func%7bSystem.Boolean%7d)" data-throw-if-not-resolved="false"></xref> to schedule a callback.</li><li>
            Call <xref href="Terminal.Gui.App.TimedEvents.RunTimers" data-throw-if-not-resolved="false"></xref> periodically (e.g., from the main loop) to execute due
            callbacks.
        </li><li>Call <xref href="Terminal.Gui.App.TimedEvents.Remove(System.Object)" data-throw-if-not-resolved="false"></xref> to cancel a scheduled timeout.</li></ol>

Timeout

Represents a scheduled timeout for use with timer management APIs.

Encapsulates a callback function to be invoked after a specified time interval. The callback can optionally indicate whether the timeout should repeat.

Used by ITimedEvents and related timer systems to manage timed operations in the application.

TimeoutEventArgs: EventArgs for timeout events (e.g. Added)

ValueChangedEventArgs<T>: Provides data for events that notify of a completed property change in the Cancellable Work Pattern (CWP).

ValueChangingEventArgs<T>: Provides data for events that allow modification or cancellation of a property change in the Cancellable Work Pattern (CWP).

Interfaces

IApplication: Interface for instances that provide backing functionality to static gateway class Application.

IApplicationMainLoop<TInputRecord>: Interface for the main application loop that runs the core Terminal.Gui UI rendering and event processing.

IClipboard: Definition to interact with the OS clipboard.

IKeyboard

Defines a contract for managing keyboard input and key bindings at the Application level.

This interface decouples keyboard handling state from the static App class, enabling parallelizable unit tests and better testability.

IMainLoopCoordinator: Interface for the main loop coordinator that manages UI loop initialization and threading.

IMouse

Defines a contract for mouse event handling and state management in a Terminal.Gui application.

This interface allows for decoupling of mouse-related functionality from the static App class, enabling better testability and parallel test execution.

IMouseGrabHandler: Defines a contract for tracking which View (if any) has 'grabbed' the mouse, giving it exclusive priority for mouse events such as movement, button presses, and release.

IPopover: Defines the contract for a popover view in Terminal.Gui.

IPopoverView: Interface for popover views that combines IPopover with View-level operations. Eliminates the need for casting IPopover to View at caller sites.

IRunnable: Non-generic base interface for runnable views. Provides common members without type parameter.

IRunnable<TResult>: Defines a view that can be run as an independent blocking session with Run(IRunnable, Func<Exception, bool>?), returning a typed result.

ITimedEvents: Manages timers.

Enums

ApplicationModelUsage: Defines the different application usage models.

Table of Contents

Namespace Terminal.Gui.App

Key Types

Instance-Based Architecture

See Also

Classes

Interfaces

Enums