diff --git a/docfx/docs/application.md b/docfx/docs/application.md index 298cf6ff5..6aa37272d 100644 --- a/docfx/docs/application.md +++ b/docfx/docs/application.md @@ -8,7 +8,7 @@ Terminal.Gui v2 uses an instance-based application architecture that decouples v graph TB subgraph ViewTree["View Hierarchy (SuperView/SubView)"] direction TB - Top[app.Current
Window] + Top[app.Running
Window] Menu[MenuBar] Status[StatusBar] Content[Content View] @@ -127,7 +127,7 @@ public class MyView : View public override void OnEnter(View view) { // Use View.App instead of static Application - App?.Current?.SetNeedsDraw(); + App?.Running?.SetNeedsDraw(); // Access SessionStack if (App?.SessionStack.Count > 0) @@ -153,7 +153,7 @@ public class MyView : View public void DoWork() { - _app.Current?.SetNeedsDraw(); + _app.Running?.SetNeedsDraw(); } } ``` @@ -192,22 +192,22 @@ public interface IApplication Terminal.Gui v2 modernized its terminology for clarity: -### Application.Current (formerly "Top") +### Application.Running (formerly "Current", which was formerly "Top") -The `Current` property represents the currently running Toplevel (the active session): +The `Running` property represents the currently running Toplevel (the active session): ```csharp -// Access the current session -Toplevel? current = app.Current; +// Access the running session +Toplevel? running = app.Running; // From within a view -Toplevel? current = App?.Current; +Toplevel? running = App?.Running; ``` -**Why "Current" instead of "Top"?** -- Follows .NET patterns (`Thread.CurrentThread`, `HttpContext.Current`) -- Self-documenting: immediately clear it's the "current" active view -- Less confusing than "Top" which could mean "topmost in Z-order" +**Why "Running" instead of "Current"?** +- More descriptive: immediately clear it's the "running" toplevel +- Avoids confusion with `Current` used in other contexts (e.g., `Thread.Current`, `HttpContext.Current`) +- Consistent with `Toplevel.IsRunning` property ### Application.SessionStack (formerly "TopLevels") @@ -256,13 +256,13 @@ public static partial class Application // OLD: void MyMethod() { - Application.Current?.SetNeedsDraw(); + Application.Running?.SetNeedsDraw(); } // NEW: void MyMethod(View view) { - view.App?.Current?.SetNeedsDraw(); + view.App?.Running?.SetNeedsDraw(); } ``` @@ -302,7 +302,7 @@ public class MyService public void DoWork() { - _app.Current?.Title = "Processing..."; + _app.Running?.Title = "Processing..."; } } ``` @@ -323,7 +323,7 @@ var toplevel = new Toplevel(); SessionToken? token = app.Begin(toplevel); // Current now points to this toplevel -Debug.Assert(app.Current == toplevel); +Debug.Assert(app.Running == toplevel); // End the session - pops from SessionStack if (token != null) @@ -345,20 +345,20 @@ app.Init(); // Session 1 var main = new Toplevel { Title = "Main" }; var token1 = app.Begin(main); -// app.Current == main, SessionStack.Count == 1 +// app.Running == main, SessionStack.Count == 1 // Session 2 (nested) var dialog = new Dialog { Title = "Dialog" }; var token2 = app.Begin(dialog); -// app.Current == dialog, SessionStack.Count == 2 +// app.Running == dialog, SessionStack.Count == 2 // End dialog app.End(token2); -// app.Current == main, SessionStack.Count == 1 +// app.Running == main, SessionStack.Count == 1 // End main app.End(token1); -// app.Current == null, SessionStack.Count == 0 +// app.Running == null, SessionStack.Count == 0 ``` ## View.Driver Property @@ -457,7 +457,7 @@ public void MyView_WorksWithRealApplication() ✅ GOOD: public void Refresh() { - App?.Current?.SetNeedsDraw(); + App?.Running?.SetNeedsDraw(); } ``` @@ -467,7 +467,7 @@ public void Refresh() ❌ AVOID: public void Refresh() { - Application.Current?.SetNeedsDraw(); // Obsolete! + Application.Running?.SetNeedsDraw(); // Obsolete! } ``` @@ -487,13 +487,13 @@ public class Service ❌ AVOID (obsolete pattern): public void Refresh() { - Application.Current?.SetNeedsDraw(); // Obsolete static access + Application.Running?.SetNeedsDraw(); // Obsolete static access } ✅ PREFERRED: public void Refresh() { - App?.Current?.SetNeedsDraw(); // Use View.App property + App?.Running?.SetNeedsDraw(); // Use View.App property } ``` diff --git a/docfx/docs/config.md b/docfx/docs/config.md index e260cad34..70a2f1cf7 100644 --- a/docfx/docs/config.md +++ b/docfx/docs/config.md @@ -459,8 +459,8 @@ ThemeManager.ThemeChanged += (sender, e) => { // Theme has changed // Refresh all views to use new theme - // From within a View, use: App?.Current?.SetNeedsDraw(); - // Or access via IApplication instance: app.Current?.SetNeedsDraw(); + // From within a View, use: App?.Running?.SetNeedsDraw(); + // Or access via IApplication instance: app.Running?.SetNeedsDraw(); }; ``` diff --git a/docfx/docs/migratingfromv1.md b/docfx/docs/migratingfromv1.md index d7fd2c0b0..049e1f07a 100644 --- a/docfx/docs/migratingfromv1.md +++ b/docfx/docs/migratingfromv1.md @@ -85,12 +85,12 @@ When measuring the screen space taken up by a `string` you can use the extension In v1, @Terminal.Gui.View was derived from `Responder` which supported `IDisposable`. In v2, `Responder` has been removed and @Terminal.Gui.View is the base-class supporting `IDisposable`. -In v1, @Terminal.Gui./Terminal.Gui.Application.Init) automatically created a toplevel view and set [Application.Current](~/api/Terminal.Gui.Application.Current. In v2, @Terminal.Gui.App.Application.Init no longer automatically creates a toplevel or sets @Terminal.Gui.App.Application.Current; app developers must explicitly create the toplevel view and pass it to @Terminal.Gui.App.Application.Run (or use `Application.Run`). Developers are responsible for calling `Dispose` on any toplevel they create before exiting. +In v1, @Terminal.Gui./Terminal.Gui.Application.Init) automatically created a toplevel view and set [Application.Running](~/api/Terminal.Gui.Application.Running. In v2, @Terminal.Gui.App.Application.Init no longer automatically creates a toplevel or sets @Terminal.Gui.App.Application.Running; app developers must explicitly create the toplevel view and pass it to @Terminal.Gui.App.Application.Run (or use `Application.Run`). Developers are responsible for calling `Dispose` on any toplevel they create before exiting. ### How to Fix * Replace `Responder` with @Terminal.Gui.View -* Update any code that assumes `Application.Init` automatically created a toplevel view and set `Application.Current`. +* Update any code that assumes `Application.Init` automatically created a toplevel view and set `Application.Running`. * Update any code that assumes `Application.Init` automatically disposed of the toplevel view when the application exited. ## Instance-Based Application Architecture @@ -144,13 +144,13 @@ When accessing application services from within views, use the `App` property in // OLD (v1 / obsolete static): public void Refresh() { - Application.Current?.SetNeedsDraw(); + Application.Running?.SetNeedsDraw(); } // NEW (v2 - use View.App): public void Refresh() { - App?.Current?.SetNeedsDraw(); + App?.Running?.SetNeedsDraw(); } ``` @@ -591,6 +591,6 @@ new ( * To simplify programming, any `View` added as a SubView another `View` will have it's lifecycle owned by the Superview; when a `View` is disposed, it will call `Dispose` on all the items in the `SubViews` property. Note this behavior is the same as it was in v1, just clarified. -* In v1, `Application.End` called `Dispose ()` on @Terminal.Gui.App.Application.Current (via `Runstate.Toplevel`). This was incorrect as it meant that after `Application.Run` returned, `Application.Current` had been disposed, and any code that wanted to interrogate the results of `Run` by accessing `Application.Current` only worked by accident. This is because GC had not actually happened; if it had the application would have crashed. In v2 `Application.End` does NOT call `Dispose`, and it is the caller to `Application.Run` who is responsible for disposing the `Toplevel` that was either passed to `Application.Run (View)` or created by `Application.Run ()`. +* In v1, `Application.End` called `Dispose ()` on @Terminal.Gui.App.Application.Running (via `Runstate.Toplevel`). This was incorrect as it meant that after `Application.Run` returned, `Application.Running` had been disposed, and any code that wanted to interrogate the results of `Run` by accessing `Application.Running` only worked by accident. This is because GC had not actually happened; if it had the application would have crashed. In v2 `Application.End` does NOT call `Dispose`, and it is the caller to `Application.Run` who is responsible for disposing the `Toplevel` that was either passed to `Application.Run (View)` or created by `Application.Run ()`. * Any code that creates a `Toplevel`, either by using `top = new()` or by calling either `top = Application.Run ()` or `top = ApplicationRun()` must call `top.Dispose` when complete. The exception to this is if `top` is passed to `myView.Add(top)` making it a subview of `myView`. This is because the semantics of `Add` are that the `myView` takes over responsibility for the subviews lifetimes. Of course, if someone calls `myView.Remove(top)` to remove said subview, they then re-take responsbility for `top`'s lifetime and they must call `top.Dispose`. diff --git a/docfx/docs/navigation.md b/docfx/docs/navigation.md index 2c5c2391a..54b0eed0e 100644 --- a/docfx/docs/navigation.md +++ b/docfx/docs/navigation.md @@ -176,12 +176,12 @@ The @Terminal.Gui.App.ApplicationNavigation.AdvanceFocus method causes the focus The implementation is simple: ```cs -return app.Current?.AdvanceFocus (direction, behavior); +return app.Running?.AdvanceFocus (direction, behavior); ``` This method is called from the `Command` handlers bound to the application-scoped keybindings created during `app.Init()`. It is `public` as a convenience. -**Note:** When accessing from within a View, use `App?.Current` instead of `Application.Current` (which is obsolete). +**Note:** When accessing from within a View, use `App?.Running` instead of `Application.Running` (which is obsolete). This method replaces about a dozen functions in v1 (scattered across `Application` and `Toplevel`). @@ -379,7 +379,7 @@ In v1 `View` had `MostFocused` property that traversed up the view-hierarchy ret var focused = Application.Navigation.GetFocused(); // This replaces the v1 pattern: -// var focused = Application.Current.MostFocused; +// var focused = Application.Running.MostFocused; ``` ## How Does `View.Add/Remove` Work? diff --git a/local_packages/Terminal.Gui.2.0.0.nupkg b/local_packages/Terminal.Gui.2.0.0.nupkg index f784c5fef..ccf33a53c 100644 Binary files a/local_packages/Terminal.Gui.2.0.0.nupkg and b/local_packages/Terminal.Gui.2.0.0.nupkg differ diff --git a/local_packages/Terminal.Gui.2.0.0.snupkg b/local_packages/Terminal.Gui.2.0.0.snupkg index 5b2fcc136..c85366209 100644 Binary files a/local_packages/Terminal.Gui.2.0.0.snupkg and b/local_packages/Terminal.Gui.2.0.0.snupkg differ