Class Application

A static, singleton class providing the main application driver for Terminal.Gui apps.

Inheritance

object

Application

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Terminal.Gui

Assembly: Terminal.Gui.dll

Syntax

public static class Application

Remarks

Creates a instance of MainLoop to process input events, handle timers and other sources of data. It is accessible via the MainLoop property.

You can hook up to the Iteration event to have your method invoked on each iteration of the MainLoop.

When invoked sets the SynchronizationContext to one that is tied to the mainloop, allowing user code to use async/await.

Examples

// A simple Terminal.Gui app that creates a window with a frame and title with 
// 5 rows/columns of padding.
Application.Init();
var win = new Window ("Hello World - CTRL-Q to quit") {
    X = 5,
    Y = 5,
    Width = Dim.Fill (5),
    Height = Dim.Fill (5)
};
Application.Top.Add(win);
Application.Run();
Application.Shutdown();

Fields

Driver

The current ConsoleDriver in use.

Declaration

public static ConsoleDriver Driver

Field Value

Type	Description
ConsoleDriver

Iteration

This event is raised on each iteration of the MainLoop.

Declaration

public static Action Iteration

Field Value

Type	Description
Action

Remarks

See also Timeout

Resized

Invoked when the terminal was resized. The new size of the terminal is provided.

Declaration

public static Action<Application.ResizedEventArgs> Resized

Field Value

Type	Description
Action<Application.ResizedEventArgs>

RootKeyEvent

Called for new KeyPress events before any processing is performed or views evaluate. Use for global key handling and/or debugging.

Return true to suppress the KeyPress event

Declaration

public static Func<KeyEvent, bool> RootKeyEvent

Field Value

Type	Description
Func<KeyEvent, bool>

RootMouseEvent

Merely a debugging aid to see the raw mouse events

Declaration

public static Action<MouseEvent> RootMouseEvent

Field Value

Type	Description
Action<MouseEvent>

Properties

AlternateBackwardKey

Alternative key to navigate backwards through views. Shift+Ctrl+Tab is the primary key.

Declaration

public static Key AlternateBackwardKey { get; set; }

Property Value

Type	Description
Key

AlternateForwardKey

Alternative key to navigate forwards through views. Ctrl+Tab is the primary key.

Declaration

public static Key AlternateForwardKey { get; set; }

Property Value

Type	Description
Key

Current

The current Toplevel object. This is updated when Run(Func<Exception, bool>) enters and leaves to point to the current Toplevel .

Declaration

public static Toplevel Current { get; }

Property Value

Type	Description
Toplevel	The current.

EnableConsoleScrolling

The current EnableConsoleScrolling used in the terminal.

Declaration

[Obsolete("This API is deprecated and has no impact when enabled.", false)]
public static bool EnableConsoleScrolling { get; set; }

Property Value

Type	Description
bool

Remarks

If false (the default) the height of the Terminal.Gui application (Rows) tracks to the height of the visible console view when the console is resized. In this case scrolling in the console will be disabled and all Rows will remain visible.

If true then height of the Terminal.Gui application Rows only tracks the height of the visible console view when the console is made larger (the application will only grow in height, never shrink). In this case console scrolling is enabled and the contents (Rows high) will scroll as the console scrolls.

This API is deprecated and has no impact when enabled.

This API was previously named 'HeightAsBuffer` but was renamed to make its purpose more clear.

ExitRunLoopAfterFirstIteration

Set to true to cause the RunLoop method to exit after the first iterations. Set to false (the default) to cause the RunLoop to continue running until Application.RequestStop() is called.

Declaration

public static bool ExitRunLoopAfterFirstIteration { get; set; }

Property Value

Type	Description
bool

HeightAsBuffer

This API is deprecated; use EnableConsoleScrolling instead.

Declaration

[Obsolete("This API is deprecated and has no impact when enabled.", false)]
public static bool HeightAsBuffer { get; set; }

Property Value

Type	Description
bool

IsMouseDisabled

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

Declaration

public static bool IsMouseDisabled { get; set; }

Property Value

Type	Description
bool

MainLoop

The MainLoop driver for the application

Declaration

public static MainLoop MainLoop { get; }

Property Value

Type	Description
MainLoop	The main loop.

MdiChildes

Gets all the Mdi childes which represent all the not modal Toplevel from the MdiTop.

Declaration

public static List<Toplevel> MdiChildes { get; }

Property Value

Type	Description
List<Toplevel>

MdiTop

The Toplevel object used for the application on startup which IsMdiContainer is true.

Declaration

public static Toplevel MdiTop { get; }

Property Value

Type	Description
Toplevel

MouseGrabView

The view that grabbed the mouse, to where will be routed all the mouse events.

Declaration

public static View MouseGrabView { get; }

Property Value

Type	Description
View

QuitKey

Gets or sets the key to quit the application.

Declaration

public static Key QuitKey { get; set; }

Property Value

Type	Description
Key

SupportedCultures

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

Declaration

public static List<CultureInfo> SupportedCultures { get; }

Property Value

Type	Description
List<CultureInfo>

Top

The Toplevel object used for the application on startup (Top)

Declaration

public static Toplevel Top { get; }

Property Value

Type	Description
Toplevel	The top.

UseSystemConsole

If true, forces the use of the System.Console-based (see NetDriver) driver. The default is false.

Declaration

public static bool UseSystemConsole { get; set; }

Property Value

Type	Description
bool

WantContinuousButtonPressedView

The current View object that wants continuous mouse button pressed events.

Declaration

public static View WantContinuousButtonPressedView { get; }

Property Value

Type	Description
View

Methods

Begin(Toplevel)

Building block API: Prepares the provided Toplevel for execution.

Declaration

public static Application.RunState Begin(Toplevel toplevel)

Parameters

Type	Name	Description
Toplevel	toplevel	The Toplevel to prepare execution for.

Returns

Type	Description
Application.RunState	The Application.RunState handle that needs to be passed to the End(RunState) method upon completion.

Remarks

This method prepares the provided toplevel for running with the focus, it adds this to the list of toplevels, sets up the mainloop to process the event, lays out the subviews, focuses the first element, and draws the toplevel in the screen. This is usually followed by executing the RunLoop(RunState, bool) method, and then the End(RunState) method upon termination which will undo these changes.

DoEvents()

Wakes up the mainloop that might be waiting on input, must be thread safe.

Declaration

public static void DoEvents()

End(RunState)

Building block API: completes the execution of a Toplevel that was started with Begin(Toplevel) .

Declaration

public static void End(Application.RunState runState)

Parameters

Type	Name	Description
Application.RunState	runState	The Application.RunState returned by the Begin(Toplevel) method.

EnsuresTopOnFront()

Ensures that the superview of the most focused view is on front.

Declaration

public static void EnsuresTopOnFront()

GrabMouse(View)

Grabs the mouse, forcing all mouse events to be routed to the specified view until UngrabMouse is called.

Declaration

public static void GrabMouse(View view)

Parameters

Type	Name	Description
View	view	View that will receive all mouse events until UngrabMouse is invoked.

Init(ConsoleDriver, IMainLoopDriver)

Initializes a new instance of Terminal.Gui Application.

Declaration

public static void Init(ConsoleDriver driver = null, IMainLoopDriver mainLoopDriver = null)

Parameters

Type	Name	Description
ConsoleDriver	driver	The ConsoleDriver to use. If not specified the default driver for the platform will be used (see WindowsDriver, CursesDriver, and NetDriver).
IMainLoopDriver	mainLoopDriver	Specifies the MainLoop to use. Must not be null if driver is not null.

MakeCenteredRect(Size)

Returns a rectangle that is centered in the screen for the provided size.

Declaration

public static Rect MakeCenteredRect(Size size)

Parameters

Type	Name	Description
Size	size	Size for the rectangle.

Returns

Type	Description
Rect	The centered rect.

MoveNext()

Move to the next Mdi child from the MdiTop.

Declaration

public static void MoveNext()

MovePrevious()

Move to the previous Mdi child from the MdiTop.

Declaration

public static void MovePrevious()

Refresh()

Triggers a refresh of the entire display.

Declaration

public static void Refresh()

RequestStop(Toplevel)

Stops running the most recent Toplevel or the top if provided.

Declaration

public static void RequestStop(Toplevel top = null)

Parameters

Type	Name	Description
Toplevel	top	The toplevel to request stop.

Remarks

This will cause Run(Func<Exception, bool>) to return.

Calling RequestStop(Toplevel) is equivalent to setting the Running property on the currently running Toplevel to false.

Run(Func<Exception, bool>)

Runs the application by calling Run(Toplevel, Func<Exception, bool>) with the value of Top.

Declaration

public static void Run(Func<Exception, bool> errorHandler = null)

Parameters

Type	Name	Description
Func<Exception, bool>	errorHandler

Remarks

See Run(Toplevel, Func<Exception, bool>) for more details.

Run(Toplevel, Func<Exception, bool>)

Runs the main loop on the given Toplevel container.

Declaration

public static void Run(Toplevel view, Func<Exception, bool> errorHandler = null)

Parameters

Type	Name	Description
Toplevel	view	The Toplevel to run modally.
Func<Exception, bool>	errorHandler	RELEASE builds only: Handler for any unhandled exceptions (resumes when returns true, rethrows when null).

Remarks

This method is used to start processing events for the main application, but it is also used to run other modal Views such as Dialog boxes.

To make a Run(Toplevel, Func<Exception, bool>) stop execution, call RequestStop(Toplevel).

Calling Run(Toplevel, Func<Exception, bool>) is equivalent to calling Begin(Toplevel), followed by RunLoop(RunState, bool), and then calling End(RunState).

Alternatively, to have a program control the main loop and process events manually, call Begin(Toplevel) to set things up manually and then repeatedly call RunLoop(RunState, bool) with the wait parameter set to false. By doing this the RunLoop(RunState, bool) method will only process any pending events, timers, idle handlers and then return control immediately.

RELEASE builds only: When errorHandler is null any exeptions will be rethrown. Otheriwse, if errorHandler will be called. If errorHandler returns true the RunLoop(RunState, bool) will resume; otherwise this method will exit.

RunLoop(RunState, bool)

Building block API: Runs the MainLoop for the created Toplevel.

Declaration

public static void RunLoop(Application.RunState state, bool wait = true)

Parameters

Type	Name	Description
Application.RunState	state	The state returned by the Begin(Toplevel) method.
bool	wait	By default this is true which will execute the runloop waiting for events, if set to false, a single iteration will execute.

Remarks

Use the wait parameter to control whether this is a blocking or non-blocking call.

RunMainLoopIteration(ref RunState, bool, ref bool)

Run one iteration of the MainLoop.

Declaration

public static void RunMainLoopIteration(ref Application.RunState state, bool wait, ref bool firstIteration)

Parameters

Type	Name	Description
Application.RunState	state	The state returned by Begin(Toplevel).
bool	wait	If true will execute the runloop waiting for events. If true will return after a single iteration.
bool	firstIteration	Set to true if this is the first run loop iteration. Upon return, it will be set to false if at least one iteration happened.

Run<T>(Func<Exception, bool>, ConsoleDriver, IMainLoopDriver)

Runs the application by calling Run(Toplevel, Func<Exception, bool>) with a new instance of the specified Toplevel-derived class.

Calling Init(ConsoleDriver, IMainLoopDriver) first is not needed as this function will initialze the application.

Shutdown() must be called when the application is closing (typically after Run> has returned) to ensure resources are cleaned up and terminal settings restored.

Declaration

public static void Run<T>(Func<Exception, bool> errorHandler = null, ConsoleDriver driver = null, IMainLoopDriver mainLoopDriver = null) where T : Toplevel, new()

Parameters

Type	Name	Description
Func<Exception, bool>	errorHandler
ConsoleDriver	driver	The ConsoleDriver to use. If not specified the default driver for the platform will be used (WindowsDriver, CursesDriver, or NetDriver). This parameteter must be null if Init(ConsoleDriver, IMainLoopDriver) has already been called.
IMainLoopDriver	mainLoopDriver	Specifies the MainLoop to use.

Type Parameters

Name	Description
T

Remarks

See Run(Toplevel, Func<Exception, bool>) for more details.

Shutdown()

Shutdown an application initialized with Init(ConsoleDriver, IMainLoopDriver).

Declaration

public static void Shutdown()

Remarks

Shutdown must be called for every call to Init(ConsoleDriver, IMainLoopDriver) or Run(Toplevel, Func<Exception, bool>) to ensure all resources are cleaned up (Disposed) and terminal settings are restored.

UngrabMouse()

Releases the mouse grab, so mouse events will be routed to the view on which the mouse is.

Declaration

public static void UngrabMouse()

Events

GrabbedMouse

Event to be invoked when a view grab the mouse.

Declaration

public static event Action<View> GrabbedMouse

Event Type

Type	Description
Action<View>

GrabbingMouse

Invoked when a view wants to grab the mouse; can be canceled.

Declaration

public static event Func<View, bool> GrabbingMouse

Event Type

Type	Description
Func<View, bool>

NotifyNewRunState

Notify that a new Application.RunState was created (Begin(Toplevel) was called). The token is created in Begin(Toplevel) and this event will be fired before that function exits.

Declaration

public static event Action<Application.RunState> NotifyNewRunState

Event Type

Type	Description
Action<Application.RunState>

Remarks

If ExitRunLoopAfterFirstIteration is true callers to Begin(Toplevel) must also subscribe to NotifyStopRunState and manually dispose of the Application.RunState token when the application is done.

NotifyStopRunState

Notify that a existent Application.RunState is stopping (End(RunState) was called).

Declaration

public static event Action<Toplevel> NotifyStopRunState

Event Type

Type	Description
Action<Toplevel>

Remarks

If ExitRunLoopAfterFirstIteration is true callers to Begin(Toplevel) must also subscribe to NotifyStopRunState and manually dispose of the Application.RunState token when the application is done.

UnGrabbedMouse

Event to be invoked when a view ungrab the mouse.

Declaration

public static event Action<View> UnGrabbedMouse

Event Type

Type	Description
Action<View>

UnGrabbingMouse

Invoked when a view wants ungrab the mouse; can be canceled.

Declaration

public static event Func<View, bool> UnGrabbingMouse

Event Type

Type	Description
Func<View, bool>