Show / Hide Table of Contents

# Class Application

A static, singelton class provding the main application driver for Terminal.Gui apps.

##### Inheritance

System.Object
Application

##### Inherited Members

System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.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();

### 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
--- | ---
System.Action |

##### Remarks

See also System.Threading.Timeout

#### Loaded

This event is fired once when the application is first loaded. The dimensions of the terminal are provided.

##### Declaration

    public static Action<Application.ResizedEventArgs> Loaded

##### Field Value

Type | Description
--- | ---
System.Action<Application.ResizedEventArgs> |

#### 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
--- | ---
System.Action<Application.ResizedEventArgs> |

#### RootMouseEvent

Merely a debugging aid to see the raw mouse events

##### Declaration

    public static Action<MouseEvent> RootMouseEvent

##### Field Value

Type | Description
--- | ---
System.Action<MouseEvent> |

#### UseSystemConsole

If set, it forces the use of the System.Console-based driver.

##### Declaration

    public static bool UseSystemConsole

##### Field Value

Type | Description
--- | ---
System.Boolean |

### Properties

#### Current

The current Toplevel object. This is updated when Run() enters and leaves to point to the current Toplevel .

##### Declaration

    public static Toplevel Current { get; }

##### Property Value

Type | Description
--- | ---
Toplevel | The current.

#### CurrentView

TThe current View object being redrawn.

##### Declaration

    public static View CurrentView { get; set; }

##### Property Value

Type | Description
--- | ---
View | The current.

#### MainLoop

The MainLoop driver for the applicaiton

##### Declaration

    public static MainLoop MainLoop { get; }

##### Property Value

Type | Description
--- | ---
MainLoop | The main loop.

#### Top

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

##### Declaration

    public static Toplevel Top { get; }

##### Property Value

Type | Description
--- | ---
Toplevel | The top.

### 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 | Toplevel to prepare execution for.

##### Returns

Type | Description
--- | ---
Application.RunState | The runstate handle that needs to be passed to the End(Application.RunState, Boolean) 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(Application.RunState, Boolean) method, and then the End(Application.RunState, Boolean) method upon termination which will undo these changes.

#### End(Application.RunState, Boolean)

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

##### Declaration

    public static void End(Application.RunState runState, bool closeDriver = true)

##### Parameters

Type | Name | Description
--- | --- | ---
Application.RunState | runState | The runstate returned by the Begin(Toplevel) method.
System.Boolean | closeDriver | If `true`, closes the application. If `false` closes the toplevels only.

#### 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 |
IMainLoopDriver | mainLoopDriver |

##### Remarks

Call this method once per instance (or after Shutdown(Boolean) has been called).

Loads the right ConsoleDriver for the platform.

Creates a Toplevel and assigns it to Top and CurrentView

#### 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.

#### Refresh()

Triggers a refresh of the entire display.

##### Declaration

    public static void Refresh()

#### RequestStop()

Stops running the most recent Toplevel.

##### Declaration

    public static void RequestStop()

##### Remarks

This will cause Run() to return.

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

#### Run()

Runs the application by calling Run(Toplevel, Boolean) with the value of Top

##### Declaration

    public static void Run()

#### Run(Toplevel, Boolean)

Runs the main loop on the given Toplevel container.

##### Declaration

    public static void Run(Toplevel view, bool closeDriver = true)

##### Parameters

Type | Name | Description
--- | --- | ---
Toplevel | view | The Toplevel tu run modally.
System.Boolean | closeDriver | Set to to cause the MainLoop to end when End(Application.RunState, Boolean) is called, clsing the toplevels only.

##### 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, Boolean) stop execution, call RequestStop().

Calling Run(Toplevel, Boolean) is equivalent to calling Begin(Toplevel), followed by RunLoop(Application.RunState, Boolean), and then calling End(Application.RunState, Boolean).

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(Application.RunState, Boolean) with the wait parameter set to false. By doing this the RunLoop(Application.RunState, Boolean) method will only process any pending events, timers, idle handlers and then return control immediately.

#### Run<T>()

Runs the application by calling Run(Toplevel, Boolean) with a new instance of the specified Toplevel-derived class

##### Declaration

    public static void Run<T>()

        where T : Toplevel, new()

##### Type Parameters

Name | Description
--- | ---
T |

#### RunLoop(Application.RunState, Boolean)

Building block API: Runs the main loop for the created dialog

##### Declaration

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

##### Parameters

Type | Name | Description
--- | --- | ---
Application.RunState | state | The state returned by the Begin method.
System.Boolean | wait | By default this is true which will execute the runloop waiting for events, if you pass false, you can use this method to run a single iteration of the events.

##### Remarks

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

#### Shutdown(Boolean)

Shutdown an application initialized with Init(ConsoleDriver, IMainLoopDriver)

##### Declaration

    public static void Shutdown(bool closeDriver = true)

##### Parameters

Type | Name | Description
--- | --- | ---
System.Boolean | closeDriver | `true`Closes the application.`false`Closes toplevels only.

#### UngrabMouse()

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

##### Declaration

    public static void UngrabMouse()