v2.x Breaking Change Thread

[tig]

Per this discussion I'm creating this thread to be the place where we document breaking changes in v2 and guidance for developers to migrate v1 code.

Let's make each breaking change a separate post within this discussion.

[tig]

#2358 - PosCombine is incorrect for scenarios involving PosAbsolute

Summary:

In v1, many use cases involving PosCombine with at least one PosAbsolute (e.g. Y = Pos.Center () - 3) behaved incorrectly. In v1 this has been fixed and as a result, code written for v1 will not function correctly.

How to fix:

If you notice layout issues after porting v1 code to v2, look for instances where a view's location (X or Y) was set using Pos.Center(), Pos.Left/Top/Bottom/Right(), Pos.AnchorEnd(), etc... with an absolute value added or subtracted. Tweak the code to work correctly.

The ComputedLayout Scenario includes a set of buttons placed using PosCombine to show how views should be placed:

[tig]

#2431 - v1 incorrectly allowed views to reference subviews in X, Y, Height, and Width

Summary

In v1, code like this was allowed and worked if the view in quesiton was FrameView or Window.

[Fact]
public void LayoutSubviews_ViewThatRefsSuperView_Throws ()
{
	var root = new View ();
	var super = new View ();
	root.Add (super);
	var sub = new View ();
	super.Add (sub);
	super.Width = Dim.Width (sub);
	Assert.Throws<InvalidOperationException> (() => root.LayoutSubviews ());
}

This only worked because FrameView and Window didn't actually add subviews to themselves, but to an embedded ContentView. In v2 this embedded view is no longer needed (and has been removed from FrameView and Window).

In v2, the ComputedLayout will now throw an InvalidOperationException if a view being laid out references a subview.

How to Fix

This comes up often when a developer is trying to have a view resize automatically to fit subviews. To fix, find another way to resize the superview based on subview sizing. The MessageBoxes scenario does this by handling the Loaded eventj and using the size values from subview's Frames:

			void Top_Loaded ()
			{
				frame.Height =
					widthEdit.Frame.Height +
					heightEdit.Frame.Height +
					titleEdit.Frame.Height +
					messageEdit.Frame.Height +
					numButtonsEdit.Frame.Height +
					defaultButtonEdit.Frame.Height +
					styleRadioGroup.Frame.Height +
					2 +
					ckbEffect3D.Frame.Height +
					ckbWrapMessage.Frame.Height;
				Application.Top.Loaded -= Top_Loaded;
			}
			Application.Top.Loaded += Top_Loaded;

See Also

• Finish Dim.Auto - DimAutoStyle.Content is half-baked #2432

[tig]

#92 - Removed Dependency on NStack.ustring

Summary

v2.0 removed the dependency on ustring and uses System.Rune instead. While ustring is neat, the fact that artifacts of it are exposed via the public Terminal.Gui API is problematic (F# support just being one). Another example is just simple usage of the API requires users to import NStack (see the C# Example in the main README).

How To Fix

Developers will need to replace all explicit uses of ustring with string etc...

(NEED MORE HERE)

[migueldeicaza]

The issue is whether you want to keep support for .NET framework and .NET standard 2.0 - because Rune doesn’t exist in that world.

[tig]

My view is 1.x is nicely featured, rich, and stable. It will continue to exist in parallel with 2.x.

Thus, for the diminishing use cases where strict net 2.0 compat is needed, 1.x will remain a reasonable solution and 2.x can plow ahead without nstack.

[ThomasNieto]

It looks like someone backported the Rune type: https://www.nuget.org/packages/Shim.System.Text.Rune

[tznind]

#2406 Events now use object sender, EventArgs args signature.

Summary

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<long> TimeoutAdded has become event EventHandler<TimeoutEventArgs> TimeoutAdded

This change was made for the following reasons:

• Event parameters are now individually named and documented (with xmldoc)
• Future additions to event parameters can be made without being breaking changes (i.e. adding new properties to the EventArgs class)

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 lamda expression, you can simply add the extra arguments:

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

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)

[migueldeicaza]

My reason for not using the idiom is that it always looked like noise from a bygone era

[tznind]

My reason for not using the idiom is that it always looked like noise from a bygone era

I can see that point of view. Especially sender feels a bit redundant nowadays.

I have updated this discussion so that it explains some more of the rationale why we made the change.

[tznind]

#2259 FileDialog (and Open/Save) rewrite.

Summary

The following new features have been added (see below). These changes have made it necessary to change the method signatures for FileDialog, OpenDialog and SaveDialog. Care has been taken to minimise the API change as much as possible.

• Autocomplete (tab completion on file/directory names)
• Display Size/Type/Modified information for files/directories
• Recursive search feature
• Expandable folder tree view
• Back/Forward buttons
• Context menu for file operations
  • Delete file
  • Rename file/directory
  • New directory
• Allowed types (*.csv, *.tsv etc) are now first class citizens
  • Can be grouped into categories
  • Can be customized through inheritence

Old FileDialog

New FileDialog

How To Fix

The breaking changes are:

• There is no longer a message parameter (e.g. "Save your file my friend")
• Allowed extensions are now a class IAllowedType (no longer just a string)
• The AllowsOtherFileTypes property has been removed.
  • Pass new AllowedTypeAny() to the dialog's constructor instead
  • You only need to do this if you are using other IAllowedType in addition to the "Any Files".

Consider the following example usage:

using Terminal.Gui;

Application.Init();

  var dlg = new SaveDialog("Save my file", 
-     "Save your file my friend",
-      new List<string> { ".csv" });
+     new List<IAllowedType> {
+         new AllowedType("Comma Separated File",".csv")
+ });

Application.Run(dlg);

if(!dlg.Canceled)
{
-   MessageBox.Query("File Chosen", $"You chose {dlg.FilePath} or possibly {dlg.DirectoryPath}","Ok");
+  MessageBox.Query ("File Chosen", $"You chose {dlg.Path}", "Ok"); 
}
Application.Shutdown();

[tznind]

#2581 / #2576 TableView data model now uses an interface ITableSource.

Summary

Previously TableView worked exclusively with data held in System.Data.DataTable. The data model has been abstracted out to a new interface ITableSource. For backwards compatibility a wrapper class has been created DataTableSource.

Additionally, column styles are now configured by ordinal (index) rather than DataColumn class.

These changes are to streamline use cases where the data you want to present is already stored in a collection other than System.Data.DataTable (e.g. a list). If this is the case then you should instead investigate using EnumerableTableSource.

How To Fix

Update your code where you set Table property to use the new wrapper:

- myTableView.Table = myDataTable;
+ myTableView.Table = new DataTableSource(myDataTable);

When configuring a ColumnStyle use the index or DataColumn.Ordinal of the column instead of the instance:

- var style = tableView.Style.GetOrCreateColumnStyle (col);
+ var style = tableView.Style.GetOrCreateColumnStyle (col.Ordinal);

If you currently have code to convert a collection into a System.Data.DataTable you can instead use EnumerableTableSource<T>.

- myTableView.Table = ConvertToDataTable(Process.GetProcesses ());
+ myTableView.Table = new EnumerableTableSource<Process> (
+		Process.GetProcesses (),
+		new Dictionary<string, Func<Process, object>>() {
+			{ "ID",(p)=>p.Id},
+			{ "Name",(p)=>p.ProcessName},
+			{ "Threads",(p)=>p.Threads.Count},
+			{ "Virtual Memory",(p)=>p.VirtualMemorySize64},
+			{ "Working Memory",(p)=>p.WorkingSet64},
+		});

[Nutzzz]

@tznind : This comment was supposed to be the description of the breaking change as a result of #2576 .

[tznind]

Good spot thanks🤦‍♂️! I have fixed it and will post the template seperately

[tznind]

#2577 ReDraw is now Draw

Summary

The draw events have been refactored.

How To Fix

Rename ReDraw to Draw and remove the Rect argument.

-	v.Redraw (v.Bounds);
+	v.Draw ();

[tznind]

#2595 Driver.HLine, Driver.VLine etc are now in ConfigurationManager.Glyphs

Summary

All character definitions are now in the GlyphDefinitions class. This should be accessed via the static class ConfigurationManager.

This was done to support end user configuration of glyphs (for accessibility, font variation support etc).

How To Fix

If you access runes via Driver change to using ConfigurationManger

- Driver.HLine
+ ConfigurationManager.Glyphs.HLine

If you accessed via Application then again change to ConfigurationManager

- Application.Driver.HLine
+ ConfigurationManager.Glyphs.HLine

In the UICatalog demo application, ConfigurationManager is aliased as CM. You can do this by adding the following line to your code (see below). This allows you to access glyphs with CM.Glyphs.HLine etc.

global using CM = Terminal.Gui.ConfigurationManager;

[tznind]

#2620 ustring removed (now uses System.Text.Rune)

Summary

Upstream library NStack has been removed in favour of native dependency System.Text. This means that ustring is gone and some method names have changed.

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();

When creating

[BDisp]

When measuring the screen space taken up by a string use EnumerateRunes

Or use the GetColumns() string extension

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

This is more advantage if really want to get the columns occupying by a string in the screen, because if some rune returns -1 (like Tab does '\t') it will subtract instead returning 0, which what the string extension really does.

[tznind]

Ah cool I didn't see this method and had in fact written my own in TerminalGuiDesigner lol. Cool I've updated the description in the main post.

[BDisp]

On other words, what I meaning about my above explanation is that Rune.GetColumns() isn't the same as String.GetColumns(). They may return different values for the same string if the condition referred above is true.

[tig]

We should update the Rune.GetColumns API docs to be clear this is the case.

[BDisp]

I let this for you guys :-)

[tznind]

#2664 No more nested classes

Summary

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

How To Fix

Replace references to to nested types with the new standalone version

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

[tznind]

#2452 ListView now defaults to 'no selection'

Summary

Previously ListView would always start with a SelectedItem of 0. Now ListView uses -1 to represent 'no selection'.

How To Fix

If you are using the SelectedItem to reference an array/collection you will need to check for -1.

int selected = this.listView.SelectedItem;
- if ( selected >= this.collection.Count)
+ if (selected < 0 || selected >= this.collection.Count)
{
    return null;
}

return this.collection[selected];

Additionally if you want the initial element to be selected upon focusing or opening the user interface you can manually set the SelectedItem to 0:

this.listView.SelectedItem = 0;

[tig]

Did I introduce the change that led to this? I don't remember.

I also don't remember my reasoning.

Could this just be a bug?

[BDisp]

Did I introduce the change that led to this? I don't remember.

No, it's was me.

I also don't remember my reasoning.

It's to allow no item is selected at start. If a item is indeed needed then set the SelectedItem at initialization. I think was a user requesting this on a issue.

Could this just be a bug?

No, it's a bug for sure.

[tig]

Iirc most platforms (eg windows) default to automatically selecting the first item.

[BDisp]

At the time was decided this, but it could default to the first item and if a user want it without no item selected, then set the SelectedItem = -1.

[tznind]

Here is the breaking change template:

# <issue> Description of change

## Summary
What changed and how

## How To Fix
Describe how to fix
Use code blocks with the language 'diff' (with +/- at start of line) to show how to change code

[tig]

'View' now supports 'Frames' with adornments; 'Bounds' no longer equals 'Frame'; 'Border' is completely changed.

Summary

The architecture of 'View' has been refactored. Apps will need to be updated to:

How to fix

• Not assume Frame == Border. This applies to drawing and mouse handling.
• Not assume they can draw outside of 'Bounds'. Use the 'Margin', 'Border', and 'Padding' Frames to do things outside of Bounds. View subclasses should not implement their own concept of padding or margins but leverage these Frames instead. Test with non-zero thickness Frames.
• Mouse and draw events now provide coordinates relative to Bounds.

[tznind]

Color (Attribute) changes

Summary

Some methods to do with Attribute class have been simplified. Color names now match the ANSII 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;

[tznind]

MainLoop is now internal

Summary

The MainLoop class has been made internal. Functionally it was tightly coupled to the driver implementations. To assist with driver code changes this class functionality is now exposed directly through Application.

How To Fix

Invoke methods on Application instead

- Application.MainLoop.AddTimeout(TimeSpan.FromMilliseconds(100), this.MyTimerCallback);
+ Application.AddTimeout(TimeSpan.FromMilliseconds(100), this.MyTimerCallback);

Update your Timer callbacks to not take MainLoop

- private bool MyTimerCallback(MainLoop caller)
+ private bool MyTimerCallback()

- Application.MainLoop.Invoke(() => this.SomeMethod());
+ Application.Invoke(() => this.SomeMethod());

[tznind]

Root Event Changes

Summary

Global event handlers for key/mouse no longer use the Root prefix and follow now 'sender eventargs' pattern

How To Fix

- Application.RootKeyEvent += (k) =>
+ Application.KeyPressed += (s,k) =>
{
    if (this.SomeCondition)
    {
        // Suppress
-        return true;
+        k.Handled = true;
+        return;
    }
...

[tig]

A whole bunch more related changes are coming soon in #2927...

[tznind]

ScreenToView and ViewToScreen now refer to 'Bounds'

Summary

Bounds is the new term for 'client area' of a View and does not include any space allocated for margins, padding or frame. To be consistent with this design, ScreenToView and similar methods now refer to Bounds

How To Fix

- var clientPoint = myView.ScreenToView(screenX, screenY);
+ var clientPoint = myView.ScreenToBounds(screenX, screenY);

- v.ViewToScreen(clientX, clientY, out screenX, out screenY);
+ v.BoundsToScreen(clientX, clientY, out screenX, out screenY);

[dodexahedron]

Just in case this thread is still being used:

#3209 is going to result in many dozens of breaking changes, due to removal of many previously public methods and an overhaul of almost everything to do with events.

[tig]

We should start putting these in

https://gui-cs.github.io/Terminal.GuiV2Docs/docs/newinv2.html

Found here: ./docfx/docs/neweinv2.md

We should be doing this within PRs.

[dodexahedron]

Good idea.

Also, another strong case for and very useful application of projects. Or, if nothing else, a tag.

[tig]

Any new breaking changes should be documented here as part of a PR:

https://gui-cs.github.io/Terminal.GuiV2Docs/docs/migratingfromv1.html

[dasien]

Hello all - i am in the process of migrating my app from v1 to v2 and i wanted to add some things that could go in the Migration document.

• Button.Clicked is now Button.MouseClick. There is an example in the doc today that shows the migration of the event signature, but not the name of the event itself.
• Looks like MainLoop is no longer accessible from Application. In my v1 app i was adding a timeout via Application.MainLoop.AddTimout and that looks to be done directly from Application now.
• ComboBox.SetSource now takes an ObservableCollection<T>. Before i was able to pass a List<T>.
• SetChildNeedsDisplay() seems to have been removed from View
• Application.RootKeyEvent() and Application.RootMouseEvent() have both been removed. I am not sure if there is a direct replacement.

If i come across any others i will update this post.

[dasien]

apologies - i just saw the comment below to make any new changes a part of a PR to the documentation. i can do that.

[tznind]

Button.Clicked is now Button.MouseClick. There is an example in the doc today that shows the migration of the event signature, but not the name of the event itself.

I think that Accept is a better event as it will work with the keyboard too that way.

Application.RootKeyEvent() and Application.RootMouseEvent() have both been removed. I am not sure if there is a direct replacement.

These have been renamed to Application.KeyDown and Application.MouseEvent