Migrating From v1 To v2 | Terminal.Gui v2 (original) (raw)

This document provides an overview of the changes between Terminal.Gui v1 and v2. It is intended to help developers migrate their applications from v1 to v2.

For detailed breaking change documentation check out this Discussion: https://github.com/gui-cs/Terminal.Gui/discussions/2448

View Constructors -> Initializers

In v1, View and most sub-classes had multiple constructors that took a variety of parameters. In v2, the constructors have been replaced with initializers. This change was made to simplify the API and make it easier to use. In addition, the v1 constructors drove a false (and needlessly complex) distinction between "Absolute" and "Computed" layout. In v2, the layout system is much simpler and more intuitive.

How to Fix

Replace the constructor calls with initializer calls.

- var myView = new View (new Rect (10, 10, 40, 10));
+ var myView = new View { X = 10, Y = 10, Width = 40, Height = 10 };

TrueColor Support - 24-bit Color is the default

Terminal.Gui v2 now supports 24-bit color by default. This means that the colors you use in your application will be more accurate and vibrant. If you are using custom colors in your application, you may need to update them to use the new 24-bit color format.

The Attribute class has been simplified. Color names now match the ANSI standard ('Brown' is now called 'Yellow')

How to Fix

Static class Attribute.Make has been removed. Use constructor instead

- var c = Attribute.Make(Color.BrightMagenta, Color.Blue);
+ var c = new Attribute(Color.BrightMagenta, Color.Blue);

- var c = Color.Brown;
+ var c = Color.Yellow;

Low-Level Type Changes

How to Fix

NStack.string has been removed. Use System.Rune instead.

See Unicode for details.

How to Fix

Replace using statements with the System.Text namespace

- using NStack;
+ using System.Text;

Anywhere you have an implicit cast from char to Rune, replace with a constructor call

- myView.AddRune(col, row, '▄');
+ myView.AddRune(col, row, new Rune('▄'));

When measuring the screen space taken up by a Rune use GetColumns()

- Rune.ColumnWidth(rune);
+ rune.GetColumns();

When measuring the screen space taken up by a string you can use the extension method GetColumns()

- myString.Sum(c=>Rune.ColumnWidth(c));
+ myString.GetColumns();

`View Life Cycle Management

In v1, View was derived from Responder which supported IDisposable. In v2, Responder has been removed and View is the base-class supporting IDisposable.

In v1, @Terminal.Gui./Terminal.Gui.Application.Init) automatically created a toplevel view and set [Application.Top](~/api/Terminal.Gui.Application.Top. In v2, @Terminal.Gui.Application.Init no longer automatically creates a toplevel or sets Top; app developers must explicitly create the toplevel view and pass it to @Terminal.Gui.Application.Run (or use Application.Run<myTopLevel>). Developers are responsible for calling Dispose on any toplevel they create before exiting.

How to Fix

Pos and Dim types now adhere to standard C# idioms

How to Fix

Layout Improvements

In v2, the layout system has been improved to make it easier to create complex user interfaces. If you are using custom layouts in your application, you may need to update them to use the new layout system.

How to Fix

Bounds -> Viewport

View.AutoSize has been removed. Use @Terminal.Gui.Dim.Auto for width or height instead.

In v1, View.AutoSize was used to size a view to its Text. In v2, View.AutoSize has been removed. Use @Terminal.Gui.Dim.Auto for width or height instead.

How to Fix

Adornments

In v2, the Border, Margin, and Padding properties have been added to all views. This simplifies view development and enables a sophisticated look and feel. If you are using custom borders, margins, or padding in your application, you may need to update them to use the new properties.

How to Fix

In v1, scrolling was enabled by using ScrollView or ScrollBarView. In v2, the base View class supports scrolling inherently. The area of a view visible to the user at a given moment was previously a rectangle called Bounds. Bounds.Location was always Point.Empty. In v2 the visible area is a rectangle called Viewport which is a protal into the Views content, which can be bigger (or smaller) than the area visible to the user. Causing a view to scroll is as simple as changing View.Viewport.Location. The View's content is described by GetContentSize(). See Layout for details.

ScrollBar replaces ScrollBarView with a much cleaner implementation of a scrollbar. In addition, VerticalScrollBar and HorizontalScrollBar provide a simple way to enable scroll bars in any View with almost no code. See See Scrolling Deep Dive for more.

How to Fix

Updated Keyboard API

The API for handling keyboard input is significantly improved. See Keyboard API.

How to Fix

- Application.RootKeyEvent(KeyEvent arg)
+ Application.KeyDown(object? sender, Key e)

**Command has been expanded and simplified

In v1, the Command enum had duplicate entries and inconsistent naming. In v2 it has been both expanded and simplified.

How To Fix

Updated Mouse API

The API for mouse input is now internally consistent and easier to use.

How to Fix

- Application.RootMouseEvent(KeyEvent arg)
+ Application.MouseEvent(object? sender, MouseEventArgs mouseEvent)

Navigation - Cursor, Focus, TabStop etc...

The cursor and focus system has been redesigned in v2 to be more consistent and easier to use. If you are using custom cursor or focus logic in your application, you may need to update it to use the new system.

Cursor

In v1, whether the cursor (the flashing caret) was visible or not was controlled by View.CursorVisibility which was an enum extracted from Ncruses/Terminfo. It only works in some cases on Linux, and only partially with WindowsDriver. The position of the cursor was the same as ConsoleDriver.Row/Col and determined by the last call to ConsoleDriver.Move. View.PositionCursor() could be overridden by views to cause Application to call ConsoleDriver.Move on behalf of the app and to manage setting CursorVisibility. This API was confusing and bug-prone.

In v2, the API is (NOT YET IMPLEMENTED) simplified. A view simply reports the style of cursor it wants and the Viewport-relative location:

How to Fix (Cursor API)

Focus

See navigation.md for more details. See also Keyboard where HotKey is covered more deeply...

How to Fix (Focus API)

Keyboard Navigation

In v2, HotKeys can be used to navigate across the entire application view-hierarchy. They work independently of Focus. This enables a user to navigate across a complex UI of nested subviews if needed (even in overlapped scenarios). An example use-case is the AllViewsTester scenario.

In v2, unlike v1, multiple Views in an application (even within the same SuperView) can have the same HotKey. Each press of the HotKey will invoke the next HotKey across the View hierarchy (NOT IMPLEMENTED YET)*

In v1, the keys used for navigation were both hard-coded and configurable, but in an inconsistent way. Tab and Shift+Tab worked consistently for navigating between SubViews, but were not configurable. Ctrl+Tab and Ctrl+Shift+Tab navigated across Overlapped views and had configurable "alternate" versions (Ctrl+PageDown and Ctrl+PageUp).

In v2, this is made consistent and configurable:

F6 was chosen to match Windows

These keys are all registered as KeyBindingScope.Application key bindings by Application. Because application-scoped key bindings have the lowest priority, Views can override the behaviors of these keys (e.g. TextView overrides Key.Tab by default, enabling the user to enter \t into text). The AllViews_AtLeastOneNavKey_Leaves unit test ensures all built-in Views have at least one of the above keys that can advance.

How to Fix (Keyboard Navigation)

...

Button.Clicked Event Renamed

The Button.Clicked event has been renamed Button.Accepting

How to Fix

Rename all instances of Button.Clicked to Button.Accepting. Note the signature change to mouse events below.

- btnLogin.Clicked 
+ btnLogin.Accepting

Alternatively, if you want to have key events as well as mouse events to fire an event, use Button.Accepting.

Events now use object sender, EventArgs args signature

Previously events in Terminal.Gui used a mixture of Action (no arguments), Action<string> (or other raw datatype) and Action<EventArgs>. Now all events use the EventHandler<EventArgs> standard .net design pattern.

For example, event Action TimeoutAddedhas becomeevent EventHandler TimeoutAdded`

This change was made for the following reasons:

For example:


public class TimeoutEventArgs : EventArgs {

    /// <summary>
    /// Gets the <see cref="DateTime.Ticks"/> in UTC time when the 
    /// <see cref="Timeout"/> will next execute after.
    /// </summary>
    public long Ticks { get; }

[...]
}

How To Fix

If you previously had a lambda expression, you can simply add the extra arguments:

- btnLogin.Clicked += () => { /*do something*/ };
+ btnLogin.Accepting += (s,e) => { /*do something*/ };

Note that the event name has also changed as noted above.

If you have used a named method instead of a lamda you will need to update the signature e.g.

- private void MyButton_Clicked ()
+ private void MyButton_Clicked (object sender, EventArgs e)

ReDraw is now Draw

How to Fix

No more nested classes

All public classes that were previously nested classes are now in the root namespace as their own classes.

How To Fix

Replace references to nested types with the new standalone version

- var myTab = new TabView.Tab();
+ var myTab = new Tab();

View and Text Alignment Changes

In v1, both TextAlignment and VerticalTextAlignment enums were used to align text in views. In v2, these enums have been replaced with the Alignment enum. The TextAlignment property controls horizontal text alignment and the VerticalTextAlignment property controls vertical text alignment.

v2 now supports @Terminal.Gui.Pos.Align which enables views to be easily aligned within their Superview.

The Aligner class makes it easy to align elements (text, Views, etc...) within a container.

How to Fix

StatusBar- StatusItem is replaced by Shortcut

StatusBar has been upgraded to utilize Shortcut.

How to Fix

-  var statusBar = new StatusBar (
-                                       new StatusItem []
-                                       {
-                                           new (
-                                                Application.QuitKey,
-                                                $"{Application.QuitKey} to Quit",
-                                                () => Quit ()
-                                               )
-                                       }
-                                      );
+ var statusBar = new StatusBar (new Shortcut [] { new (Application.QuitKey, "Quit", Quit) });

CheckBox - API renamed and simplified

In v1 CheckBox used bool? to represent the 3 states. To support consistent behavior for the Accept event, CheckBox was refactored to use the new CheckState enum instead of bool?.

Additionally, the Toggle event was renamed CheckStateChanging and made cancelable. The Toggle method was renamed to AdvanceCheckState.

How to Fix

-var cb = new CheckBox ("_Checkbox", true); {
-				X = Pos.Right (label) + 1,
-				Y = Pos.Top (label) + 2
-			};
-			cb.Toggled += (e) => {
-			};
-           cb.Toggle ();
+
+var cb = new CheckBox ()
+{ 
+	Title = "_Checkbox",
+	CheckState = CheckState.Checked
+}
+cb.CheckStateChanging += (s, e) =>
+{	
+	e.Cancel = preventChange;
+}
+preventChange = false;
+cb.AdvanceCheckState ();

MainLoop is no longer accessible from Application

In v1, you could add timeouts via Application.MainLoop.AddTimeout among other things. In v2, the MainLoop object is internal to Application and methods previously accessed via MainLoop can now be accessed directly via Application

How to Fix

- Application.MainLoop.AddTimeout (TimeSpan time, Func<MainLoop, bool> callback)
+ Application.AddTimeout (TimeSpan time, Func<bool> callback)

SendSubViewXXX renamed and corrected

In v1, the View methods to move SubViews within the SubViews list were poorly named and actually operated in reverse of what their names suggested.

In v2, these methods have been named correctly.

Mdi Replaced by ViewArrangement.Overlapped

In v1, it apps with multiple overlapping views could be created using a set of APIs spread across Application (e.g. Application.MdiTop) and Toplevel (e.g. IsMdiContainer). This functionality has been replaced in v2 with Arrangement. Specifically, overlapped views with Arrangement having the Overlapped flag set will be arranged in an overlapped fashion using the order in their SuperView's subview list as the Z-order.

Setting the Movable flag will enable the overlapped views to be movable with the mouse or keyboard (Ctrl+F5 to activate).

Setting the @Terminal.Gui.ViewArrangement.Sizable flag will enable the overlapped views to be resized with the mouse or keyboard (Ctrl+F5 to activate).

In v1, only Views derived from Toplevel could be overlapped. In v2, any view can be.

v1 conflated the concepts of

PopoverMenu replaces ContrextMenu.

new (
      Strings.charMapCopyGlyph,
      "",
      CopyGlyph,
-      null,
-      null,
      (KeyCode)Key.G.WithCtrl
     ),

Others...