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 ();

See Also

Classes

Application: A static, singleton class representing the application. This class is the entry point for the application.

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 IPopover views for IApplication. Held by Popover

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>

PopoverBaseImpl: Abstract base class for popover views in Terminal.Gui. Implements IPopover.

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:

Call Add(TimeSpan, Func<bool>) to schedule a callback.
Call RunTimers() periodically (e.g., from the main loop) to execute due callbacks.
Call Remove(object) to cancel a scheduled 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.

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.

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.

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.

Edit this page