From a82636a2baee8b90b2ae33e6b600e08abf468a12 Mon Sep 17 00:00:00 2001 From: Brian Gentry Date: Mon, 19 Aug 2024 10:39:12 -0400 Subject: [PATCH] Updated migration doc to include additional findings. (#3660) * Updated migration doc to include additional findings. * Updated per PR recommendations. --------- Co-authored-by: Tig --- docfx/docs/migratingfromv1.md | 46 +++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docfx/docs/migratingfromv1.md b/docfx/docs/migratingfromv1.md index 742521e02..7bd2f7e04 100644 --- a/docfx/docs/migratingfromv1.md +++ b/docfx/docs/migratingfromv1.md @@ -167,6 +167,7 @@ The API for handling keyboard input is significantly improved. See [Keyboard API * The preferred way to enable Application-wide or View-heirarchy-dependent keystrokes is to use the [Shortcut](~/api/Terminal.Gui.Shortcut.yml) View or the built-in View's that utilize it, such as the [Bar](~/api/Terminal.Gui.Bar.yml)-based views. * The preferred way to handle single keystrokes is to use **Key Bindings**. Key Bindings map a key press to a [Command](~/api/Terminal.Gui.Command.yml). A view can declare which commands it supports, and provide a lambda that implements the functionality of the command, using `View.AddCommand()`. Use the [View.Keybindings](~/api/Terminal.Gui.View.Keybindings.yml) to configure the key bindings. * For better consistency and user experience, the default key for closing an app or `Toplevel` is now `Esc` (it was previously `Ctrl+Q`). +* The `Application.RootKeyEvent` method has been replaced with `Application.KeyDown` ### How to Fix @@ -175,6 +176,12 @@ The API for handling keyboard input is significantly improved. See [Keyboard API * Use [View.Keybindings](~/api/Terminal.Gui.View.Keybindings.yml) to configure key bindings to `Command`s. * It should be very uncommon for v2 code to override `OnKeyPressed` etc... * Anywhere `Ctrl+Q` was hard-coded as the "quit key", replace with `Application.QuitKey`. +* Replace `Application.RootKeyEvent` with `Application.KeyDown`. If the reason for subscribing to RootKeyEvent was to enable an application-wide action based on a key-press, consider using Application.KeyBindings instead. + +```diff +- Application.RootKeyEvent(KeyEvent arg) ++ Application.KeyDown(object? sender, Key e) +``` ## Updated Mouse API @@ -185,6 +192,7 @@ The API for mouse input is now internally consistent and easier to use. * Views can use the [View.Highlight](~/api/Terminal.Gui.View.Highlight.yml) event to have the view be visibly highlighted on various mouse events. * Views can set `View.WantContinousButtonPresses = true` to have their [Command.Accept](~/api/Terminal.Gui.Command.Accept.yml) command be invoked repeatedly as the user holds a mouse button down on the view. * Mouse and draw events now provide coordinates relative to the `Viewport` not the `Screen`. +* The `Application.RootMouseEvent` method has been replaced with `Application.MouseEvent` ### How to Fix @@ -192,6 +200,12 @@ The API for mouse input is now internally consistent and easier to use. * Use the [View.Highlight](~/api/Terminal.Gui.View.Highlight.yml) event to have the view be visibly highlighted on various mouse events. * Set `View.WantContinousButtonPresses = true` to have the [Command.Accept](~/api/Terminal.Gui.Command.Accept.yml) command be invoked repeatedly as the user holds a mouse button down on the view. * Update any code that assumed mouse events provided coordinates relative to the `Screen`. +* Replace `Application.RootMouseEvent` with `Application.MouseEvent`. + +```diff +- Application.RootMouseEvent(KeyEvent arg) ++ Application.MouseEvent(object? sender, MouseEvent mouseEvent) +``` ## Cursor and Focus @@ -204,6 +218,21 @@ The cursor and focus system has been redesigned in v2 to be more consistent and * Set [View.CursorVisibility](~/api/Terminal.Gui.View.CursorVisibility.yml) to the cursor style you want to use. * Remove any overrides of `OnEnter` and `OnLeave` that explicitly change the cursor. +## Button.Clicked Event Renamed + +The `Button.Clicked` event has been renamed `Button.Accept` + +## How to Fix + +Rename all instances of `Button.Clicked` to `Button.Accept`. Note the signature change to mouse events below. + +```diff +- btnLogin.Clicked ++ btnLogin.Accept +``` + +Alternatively, if you want to have key events as well as mouse events to fire an event, use `Button.Accept`. + ## Events now use `object sender, EventArgs args` signature Previously events in Terminal.Gui used a mixture of `Action` (no arguments), `Action` (or other raw datatype) and `Action`. Now all events use the `EventHandler` [standard .net design pattern](https://learn.microsoft.com/en-us/dotnet/csharp/event-pattern#event-delegate-signatures). @@ -236,8 +265,9 @@ If you previously had a lamda expression, you can simply add the extra arguments ```diff - btnLogin.Clicked += () => { /*do something*/ }; -+ btnLogin.Clicked += (s,e) => { /*do something*/ }; ++ btnLogin.Accept += (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. @@ -325,4 +355,16 @@ Additionally the `Toggle` event was renamed `CheckStateChanging` and made cancel +} +preventChange = false; +cb.AdvanceCheckState (); -``` \ No newline at end of file +``` + +## `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 + +```diff +- Application.MainLoop.AddTimeout (TimeSpan time, Func callback) ++ Application.AddTimeout (TimeSpan time, Func callback) +``` +