Makes Run<T> and Run() return the Toplevel that gets created

Terminal.Gui/Application.cs

@@ -531,7 +531,7 @@ public static partial class Application
 
         //}
 
-        // BUGBUG: This call is likley not needed.
+        // BUGBUG: This call is likely not needed.
         toplevel.LayoutSubviews ();
         toplevel.PositionToplevels ();
         toplevel.FocusFirst ();
@@ -555,26 +555,39 @@ public static partial class Application
     ///     Runs the application by calling <see cref="Run(Toplevel, Func{Exception, bool}, ConsoleDriver)"/> with the value of
     ///     <see cref="Top"/>.
     /// </summary>
-    /// <remarks>See <see cref="Run(Toplevel, Func{Exception, bool}, ConsoleDriver)"/> for more details.</remarks>
-    public static void Run (Func<Exception, bool> errorHandler = null, ConsoleDriver driver = null) { Run<Toplevel> (errorHandler, driver);}
+    /// <remarks>
+    ///     <para>
+    ///         <see cref="Shutdown"/> must be called when the application is closing (typically after Run> has returned) to
+    ///         ensure resources are cleaned up and terminal settings restored.
+    ///     </para>
+    /// <para>
+    /// The caller is responsible for disposing the object returned by this method.</para>
+    /// </para>
+    /// <returns>The created <see cref="Toplevel"/> object. The caller is responsible for disposing this object.</returns>
+    public static Toplevel Run (Func<Exception, bool> errorHandler = null, ConsoleDriver driver = null) { return Run<Toplevel> (errorHandler, driver); }
 
     /// <summary>
     ///     Runs the application by calling <see cref="Run(Toplevel, Func{Exception, bool}, ConsoleDriver)"/> with a new instance of the
     ///     specified <see cref="Toplevel"/>-derived class.
     ///     <para>Calling <see cref="Init"/> first is not needed as this function will initialize the application.</para>
+    /// </summary>
+    /// <remarks>
     ///     <para>
     ///         <see cref="Shutdown"/> must be called when the application is closing (typically after Run> has returned) to
     ///         ensure resources are cleaned up and terminal settings restored.
     ///     </para>
-    /// </summary>
-    /// <remarks>See <see cref="Run(Toplevel, Func{Exception, bool}, ConsoleDriver)"/> for more details.</remarks>
+    /// <para>
+    /// The caller is responsible for disposing the object returned by this method.</para>
+    /// </para>
+    /// </remarks>
     /// <param name="errorHandler"></param>
     /// <param name="driver">
     ///     The <see cref="ConsoleDriver"/> to use. If not specified the default driver for the platform will
     ///     be used ( <see cref="WindowsDriver"/>, <see cref="CursesDriver"/>, or <see cref="NetDriver"/>). Must be
     ///     <see langword="null"/> if <see cref="Init"/> has already been called.
     /// </param>
-    public static void Run<T> (Func<Exception, bool> errorHandler = null, ConsoleDriver driver = null)
+    /// <returns>The created T object. The caller is responsible for disposing this object.</returns>
+    public static Toplevel Run<T> (Func<Exception, bool> errorHandler = null, ConsoleDriver driver = null)
         where T : Toplevel, new()
     {
         var top = new T () as Toplevel;
@@ -582,6 +595,8 @@ public static partial class Application
         EnsureValidInitialization (top, driver);
 
         RunApp (top, errorHandler);
+
+        return top;
     }
 
     /// <summary>Runs the main loop on the given <see cref="Toplevel"/> container.</summary>

UICatalog/Scenarios/BackgroundWorkerCollection.cs

@@ -174,12 +174,7 @@ public class BackgroundWorkerCollection : Scenario
 
         private void OverlappedMain_Activate (object sender, ToplevelEventArgs top)
         {
-            if (top.Toplevel is null)
-            {
-                return;
-            }
-
-            _workerApp?.WriteLog ($"{top.Toplevel.Data} activate.");
+            _workerApp?.WriteLog ($"{(top.Toplevel is null ? ((Toplevel)sender).Data : top.Toplevel.Data)} activate.");
         }
 
         private void OverlappedMain_Deactivate (object sender, ToplevelEventArgs top)