Class Toplevel

Toplevel views can be modally executed.
Inheritance
System.Object
Responder
View
Toplevel
Window
Implements
System.IDisposable
System.ComponentModel.ISupportInitializeNotification
System.ComponentModel.ISupportInitialize
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)
Namespace: Terminal.Gui
Assembly: Terminal.Gui.dll
Syntax
public class Toplevel : View, IDisposable, ISupportInitializeNotification, ISupportInitialize
Remarks

Toplevels can be modally executing views, started by calling Run(Toplevel). They return control to the caller when RequestStop() has been called (which sets the Running property to false).

A Toplevel is created when an application initialzies Terminal.Gui by callling Init(ConsoleDriver, IMainLoopDriver). The application Toplevel can be accessed via Top. Additional Toplevels can be created and run (e.g. Dialogs. To run a Toplevel, create the Toplevel and call Run(Toplevel).

Toplevels can also opt-in to more sophisticated initialization by implementing System.ComponentModel.ISupportInitialize. When they do so, the System.ComponentModel.ISupportInitialize.BeginInit() and System.ComponentModel.ISupportInitialize.EndInit() methods will be called before running the view. If first-run-only initialization is preferred, the System.ComponentModel.ISupportInitializeNotification can be implemented too, in which case the System.ComponentModel.ISupportInitialize methods will only be called if System.ComponentModel.ISupportInitializeNotification.IsInitialized is false. This allows proper View inheritance hierarchies to override base class layout code optimally by doing so only on first run, instead of on every run.

Constructors

Toplevel()

Initializes a new instance of the Toplevel class with Computed layout, defaulting to full screen.
Declaration
public Toplevel()

Toplevel(Rect)

Initializes a new instance of the Toplevel class with the specified absolute layout.
Declaration
public Toplevel(Rect frame)
Parameters
Type Name Description
Rect frame A superview-relative rectangle specifying the location and size for the new Toplevel

Properties

CanFocus

Gets or sets a value indicating whether this Toplevel can focus.
Declaration
public override bool CanFocus { get; }
Property Value
Type Description
System.Boolean true if can focus; otherwise, false.
Overrides

MenuBar

Gets or sets the menu for this Toplevel
Declaration
public MenuBar MenuBar { get; set; }
Property Value
Type Description
MenuBar

Modal

Determines whether the Toplevel is modal or not. Causes ProcessKey(KeyEvent) to propagate keys upwards by default unless set to true.
Declaration
public bool Modal { get; set; }
Property Value
Type Description
System.Boolean

Running

Gets or sets whether the MainLoop for this Toplevel is running or not.
Declaration
public bool Running { get; set; }
Property Value
Type Description
System.Boolean
Remarks
Setting this property directly is discouraged. Use RequestStop() instead.

StatusBar

Gets or sets the status bar for this Toplevel
Declaration
public StatusBar StatusBar { get; set; }
Property Value
Type Description
StatusBar

Methods

Add(View)

Adds a subview (child) to this view.
Declaration
public override void Add(View view)
Parameters
Type Name Description
View view
Overrides
Remarks
The Views that have been added to this view can be retrieved via the Subviews property. See also Remove(View) RemoveAll()

Create()

Convenience factory method that creates a new Toplevel with the current terminal dimensions.
Declaration
public static Toplevel Create()
Returns
Type Description
Toplevel The create.

OnKeyDown(KeyEvent)

Declaration
public override bool OnKeyDown(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides

OnKeyUp(KeyEvent)

Declaration
public override bool OnKeyUp(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides

ProcessColdKey(KeyEvent)

This method can be overwritten by views that want to provide accelerator functionality (Alt-key for example), but without interefering with normal ProcessKey behavior.
Declaration
public override bool ProcessColdKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides
Remarks

After keys are sent to the subviews on the current view, all the view are processed and the key is passed to the views to allow some of them to process the keystroke as a cold-key.

This functionality is used, for example, by default buttons to act on the enter key. Processing this as a hot-key would prevent non-default buttons from consuming the enter keypress when they have the focus.

ProcessKey(KeyEvent)

If the view is focused, gives the view a chance to process the keystroke.
Declaration
public override bool ProcessKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides
Remarks

Views can override this method if they are interested in processing the given keystroke. If they consume the keystroke, they must return true to stop the keystroke from being processed by other widgets or consumed by the widget engine. If they return false, the keystroke will be passed using the ProcessColdKey method to other views to process.

The View implementation does nothing but return false, so it is not necessary to call base.ProcessKey if you derive directly from View, but you should if you derive other View subclasses.

Redraw(Rect)

Redraws this view and its subviews; only redraws the views that have been flagged for a re-display.
Declaration
public override void Redraw(Rect bounds)
Parameters
Type Name Description
Rect bounds The bounds (view-relative region) to redraw.
Overrides
Remarks

Always use Bounds (view-relative) when calling Redraw(Rect), NOT Frame (superview-relative).

Views should set the color that they want to use on entry, as otherwise this will inherit the last color that was set globally on the driver.

Overrides of Redraw(Rect) must ensure they do not set Driver.Clip to a clip region larger than the region parameter.

Remove(View)

Removes a subview added via Add(View) or Add(View[]) from this View.
Declaration
public override void Remove(View view)
Parameters
Type Name Description
View view
Overrides
Remarks

RemoveAll()

Removes all subviews (children) added via Add(View) or Add(View[]) from this View.
Declaration
public override void RemoveAll()
Overrides

WillPresent()

Invoked by Begin(Toplevel) as part of the Run(Toplevel) after the views have been laid out, and before the views are drawn for the first time.
Declaration
public virtual void WillPresent()

Events

Loaded

Fired once the Toplevel's Application.RunState has begin loaded. A Loaded event handler is a good place to finalize initialization before calling `RunLoop(Application.RunState, Boolean).
Declaration
public event Action Loaded
Event Type
Type Description
System.Action

Ready

Fired once the Toplevel's MainLoop has started it's first iteration. Subscribe to this event to perform tasks when the Toplevel has been laid out and focus has been set. changes. A Ready event handler is a good place to finalize initialization after calling `Run()(topLevel)`.
Declaration
public event Action Ready
Event Type
Type Description
System.Action

Unloaded

Fired once the Toplevel's Application.RunState has begin unloaded. A Unloaded event handler is a good place to disposing after calling `End(Application.RunState).
Declaration
public event Action Unloaded
Event Type
Type Description
System.Action

Implements

System.IDisposable
System.ComponentModel.ISupportInitializeNotification
System.ComponentModel.ISupportInitialize