Class Application

Namespace: Terminal.Gui.App

Assembly: Terminal.Gui.dll

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.

public static class Application

Inheritance: object

Application

Inherited Members: object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Examples

Here's a simple example of how to create and run a Terminal.Gui application using the modern instance-based model:

IApplication app = Application.Create ().Init ();
using Window top = new ();
top.Add(myView);
app.Run(top);

Properties

Clipboard: Gets the clipboard for the application.

DefaultKeyBindings

Gets or sets the default key bindings for Application-level commands, optionally varying by platform. Each entry maps a Command to a PlatformKeyBinding that specifies the key strings for all platforms or specific ones.

IMPORTANT: This is a process-wide static property. Change with care. Do not set in parallelizable unit tests.

DefaultMaximumIterationsPerSecond: Gets the default maximum number of iterations per second for the main loop.

Driver: Gets or sets the console driver being used.

ForceDriver: Forces the use of the specified driver (DriverRegistry.Names). If not specified, the driver is selected based on the platform.

Initialized: Gets or sets whether the application has been initialized.

Instance: Gets the singleton IApplication instance used by the legacy static Application model.

IsMouseDisabled: Disable or enable the mouse. The mouse is enabled by default.

KeyBindings: Gets the Application-scoped key bindings.

Keyboard: Handles keyboard input and key bindings at the Application level.

MainThreadId: Gets or sets the main thread ID for the application.

MaximumIterationsPerSecond: Maximum number of iterations of the main loop (and hence draws) to allow to occur per second. Defaults to 25ms. Note that not every iteration draws (see NeedsDraw).

Mouse: Gets the IMouse instance that manages mouse event handling and state.

Navigation: Gets the ApplicationNavigation instance for the current Application.

Popovers: Gets the Application Popovers manager.

Screen: Gets or sets the size of the screen. By default, this is the size of the screen as reported by the IDriver.

StopAfterFirstIteration: Set to true to cause the session to stop running after first iteration.

SupportedCultures: Gets all cultures supported by the application without the invariant language.

TimedEvents: Handles recurring events. These are invoked on the main UI thread - allowing for safe updates to View instances.

TopRunnable: The View that is on the top of the SessionStack.

TopRunnableView: The View that is on the top of the SessionStack.

Methods

AddTimeout(TimeSpan, Func<bool>): Adds a timeout to the application.

Begin(IRunnable): Building block API: Creates a SessionToken and prepares the provided IRunnable for execution. Not usually called directly by applications. Use Run(IRunnable, Func<Exception, bool>?) instead.

Create(ITimeProvider?): Creates a new IApplication instance.

End(SessionToken): Building block API: Ends the session associated with the token and completes the execution of an IRunnable. Not usually called directly by applications. Run(IRunnable, Func<Exception, bool>?) will automatically call this method when the session is stopped.

GetDefaultKey(Command): Returns the first platform-resolved key for the specified command from DefaultKeyBindings, or Empty if none is configured.

GetDefaultKeys(Command): Returns all platform-resolved keys for the specified command from DefaultKeyBindings.

Init(string?): Initializes a new instance of Terminal.Gui Application.

Invoke(Action): Runs action on the main UI loop thread.

Invoke(Action<IApplication>): Runs action on the main UI loop thread.

LayoutAndDraw(bool): Causes any Runnables that need layout to be laid out, then draws any Runnables that need display. Only Views that need to be laid out (see NeedsLayout) will be laid out. Only Views that need to be drawn (see NeedsDraw) will be drawn.

RaiseKeyDownEvent(Key): Called when the user presses a key (by the IDriver). Raises the cancelable KeyDown event, then calls NewKeyDownEvent(Key) on all top level views, and finally if the key was not handled, invokes any Application-scoped KeyBindings.

RemoveTimeout(object): Removes a previously scheduled timeout.

RequestStop(IRunnable?): Requests that the specified runnable session stop.

Run(IRunnable, Func<Exception, bool>?): Runs a new Session with the provided runnable view.

Run<TRunnable>(Func<Exception, bool>?, string?): Runs a new Session creating a IRunnable-derived object of type TRunnable and calling Run(IRunnable, Func<Exception, bool>?). When the session is stopped, End(SessionToken) will be called.

Shutdown()

Events

DefaultKeyBindingsChanged

Raised when the DefaultKeyBindings property is replaced (i.e., a new dictionary is assigned).

Note: This event does not fire when individual entries are mutated (e.g., DefaultKeyBindings [Command.Quit] = ...). To ensure the event fires, assign a new dictionary or call the property setter.

ForceDriverChanged: Raised when ForceDriver changes.

InitializedChanged: This event is raised after the Init(string?) and Dispose() methods have been called.

InstanceCreated: Raised when an IApplication instance is created via Create(ITimeProvider?).

InstanceDisposed: Raised when an IApplication instance is disposed.

InstanceInitialized: Raised when an IApplication instance completes initialization.

IsMouseDisabledChanged: Raised when IsMouseDisabled changes.

Iteration: This event is raised on each iteration of the main loop.

KeyDown

Raised when the user presses a key.

Set Handled to true to indicate the key was handled and to prevent additional processing.

KeyUp

Raised when the user releases a key.