Fixes #4051 - Adds cancellable_work_pattern.md

Examples/UICatalog/Scenarios/Transparent.cs

@@ -24,7 +24,11 @@ public override void Main ()
         appWindow.VerticalTextAlignment = Alignment.Center;
         appWindow.ClearingViewport += (s, e) =>
                                     {
-                                        appWindow!.FillRect (appWindow!.Viewport, Glyphs.Stipple);
+                                        if (s is View sender)
+                                        {
+                                            sender.FillRect (sender.Viewport, Glyphs.Stipple);
+                                        }
+
                                         e.Cancel = true;
                                     };
         ViewportSettingsEditor viewportSettingsEditor = new ViewportSettingsEditor ()

Terminal.Gui/Input/Command.cs

@@ -10,7 +10,12 @@ namespace Terminal.Gui;
 /// <seealso cref="View.MouseBindings"/>
 /// <seealso cref="Application.KeyBindings"/>
 /// <remarks>
-///     <see cref="Application"/> supports a subset of these commands by default, which can be overriden via <see cref="Application.KeyBindings"/>.
+///     <para>
+///         <see cref="Application"/> supports a subset of these commands by default, which can be overriden via <see cref="Application.KeyBindings"/>.
+///     </para>
+///     <para>
+///         See the Commands Deep Dive for more information: <see href="https://gui-cs.github.io/Terminal.GuiV2Docs/docs/command.html"/>.
+///     </para>
 /// </remarks>
 public enum Command
 {

Terminal.Gui/View/View.Command.cs

@@ -68,6 +68,8 @@ private void SetupCommands ()
 
         // Best practice is to invoke the virtual method first.
         // This allows derived classes to handle the event and potentially cancel it.
+        // For robustness' sake, even if the virtual method returns true, if the args 
+        // indicate the event should be cancelled, we honor that.
         if (OnCommandNotBound (args) || args.Cancel)
         {
             return true;
@@ -299,6 +301,9 @@ private void SetupCommands ()
     ///     <para>
     ///         This version of AddCommand is for commands that require <see cref="ICommandContext"/>.
     ///     </para>
+    ///     <para>
+    ///         See the Commands Deep Dive for more information: <see href="https://gui-cs.github.io/Terminal.GuiV2Docs/docs/command.html"/>.
+    ///     </para>
     /// </remarks>
     /// <param name="command">The command.</param>
     /// <param name="impl">The delegate.</param>
@@ -320,6 +325,9 @@ private void SetupCommands ()
     ///         If the command requires context, use
     ///         <see cref="AddCommand(Command,CommandImplementation)"/>
     ///     </para>
+    ///     <para>
+    ///         See the Commands Deep Dive for more information: <see href="https://gui-cs.github.io/Terminal.GuiV2Docs/docs/command.html"/>.
+    ///     </para>
     /// </remarks>
     /// <param name="command">The command.</param>
     /// <param name="impl">The delegate.</param>

docfx/docs/View.md

@@ -14,6 +14,10 @@
 
   * *Parent View* - A view that holds a reference to another view in a parent/child relationship, but is NOT a SuperView of the child. Terminal.Gui uses the terms "Child" and "Parent" sparingly. Generally SubView/SuperView is preferred.
 
+### Commands
+
+See the [Command Deep Dive](command.md).
+
 ### Input
 
 See the [Keyboard Deep Dive](keyboard.md) and [Mouse Deep Dive](mouse.md).

docfx/docs/drawing.md

@@ -44,7 +44,7 @@ The @Terminal.Gui.Application MainLoop will iterate over all Views in the view h
 12) DrawComplete is raised.
 13) The current View's Frame NOT INCLUDING the Margin is excluded from the current Clip region.
 
-Most of the steps above can be overridden by developers using the standard [Terminal.Gui cancellable event pattern](events.md). For example, the base @Terminal.Gui.View always clears the viewport. To override this, a subclass can override @Terminal.Gui.View.OnClearingViewport to simply return `true`. Or, a user of `View` can subscribe to the @Terminal.Gui.View.ClearingViewport event and set the `Cancel` argument to `true`.
+Most of the steps above can be overridden by developers using the standard [Terminal.Gui Cancellable Work Pattern](cancellable_work_pattern.md). For example, the base @Terminal.Gui.View always clears the viewport. To override this, a subclass can override @Terminal.Gui.View.OnClearingViewport to simply return `true`. Or, a user of `View` can subscribe to the @Terminal.Gui.View.ClearingViewport event and set the `Cancel` argument to `true`.
 
 Then, after the above steps have completed, the Mainloop will iterate through all views in the view hierarchy again, this time calling Draw on any @Terminal.Gui.View.Margin objects, using the cached Clip region mentioned above. This enables Margin to be transparent.
 

docfx/docs/events.md

@@ -2,6 +2,11 @@
 
 Terminal.Gui exposes and uses events in many places. This deep dive covers the patterns used, where they are used, and notes any exceptions.
 
+## See Also
+
+* [Cancellable Work Pattern](cancellable_work_pattern.md)
+* [Command Deep Dive](command.md)
+
 ## Tenets for Terminal.Gui Events (Unless you know better ones...)
 
 Tenets higher in the list have precedence over tenets lower in the list.
@@ -29,98 +34,24 @@ Tenets higher in the list have precedence over tenets lower in the list.
 
 TG follows the *naming* advice provided in [.NET Naming Guidelines - Names of Events](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-type-members?redirectedfrom=MSDN#names-of-events).
 
-## `EventHandler` style event best-practices
+## Common Event Patterns
+
+### OnEvent/Event
+
+The primary pattern for events is the `OnEvent/Event` idiom. 
 
 * Implement a helper method for raising the event: `RaisexxxEvent`.
   * If the event is cancelable, the return type should be either `bool` or `bool?`.
   * Can be `private`, `internal`, or `public` depending on the situation. `internal` should only be used to enable unit tests.
-* Raising an event involves FIRST calling the `protected virtual` method, THEN invoking the `EventHandler.
-
-## `Action<T>` style callback best-practices
-
-- tbd
-
-## `INotifyPropertyChanged` style notification best practices
-
-- tbd
-
-## Common Patterns
-
-The primary pattern for events is the `event/EventHandler` idiom. We use the `Action<T>` idiom sparingly. We support `INotifyPropertyChanged` in cases where data binding is relevant.
-
-
-
-## Cancellable Event Pattern
-
-A cancellable event is really two events and some activity that takes place between those events. The "pre-event" happens before the activity. The activity then takes place (or not). If the activity takes place, then the "post-event" is typically raised. So, to be precise, no event is being cancelled even though we say we have a cancellable event. Rather, the activity that takes place between the two events is what is cancelled — and likely prevented from starting at all.
-
-### **Before** - If any pre-conditions are met raise the "pre-event", typically named in the form of "xxxChanging". e.g.
-
-  - A `protected virtual` method is called. This method is named `OnxxxChanging` and the base implementation simply does `return false`.
-  - If the `OnxxxChanging` method returns `true` it means a derived class canceled the event. Processing should stop.
-  - Otherwise, the `xxxChanging` event is invoked via `xxxChanging?.Invoke(args)`. If `args.Cancel/Handled == true` it means a subscriber has cancelled the event. Processing should stop.
-
-
-### **During** - Do work.
-
-### **After** - Raise the "post-event", typically named in the form of "xxxChanged"
-
-  - A `protected virtual` method is called. This method is named `OnxxxChanged` has a return type of `void`.
-  - The `xxxChanged` event is invoked via `xxxChanging?.Invoke(args)`. 
-
-The `OrientationHelper` class supporting `IOrientation` and a `View` having an `Orientation` property illustrates the preferred TG pattern for cancelable events.
-
-```cs
-   /// <summary>
-   ///     Gets or sets the orientation of the View.
-   /// </summary>
-   public Orientation Orientation
-   {
-       get => _orientation;
-       set
-       {
-           if (_orientation == value)
-           {
-               return;
-           }
-
-           // Best practice is to call the virtual method first.
-           // This allows derived classes to handle the event and potentially cancel it.
-           if (_owner?.OnOrientationChanging (value, _orientation) ?? false)
-           {
-               return;
-           }
-
-           // If the event is not canceled by the virtual method, raise the event to notify any external subscribers.
-           CancelEventArgs<Orientation> args = new (in _orientation, ref value);
-           OrientationChanging?.Invoke (_owner, args);
-
-           if (args.Cancel)
-           {
-               return;
-           }
-
-           // If the event is not canceled, update the value.
-           Orientation old = _orientation;
+* Raising an event involves FIRST calling the `protected virtual` method, THEN invoking 
+the `EventHandler`.
 
-           if (_orientation != value)
-           {
-               _orientation = value;
+### Action
 
-               if (_owner is { })
-               {
-                   _owner.Orientation = value;
-               }
-           }
+We use the `Action<T>` idiom sparingly. 
 
-           // Best practice is to call the virtual method first, then raise the event.
-           _owner?.OnOrientationChanged (_orientation);
-           OrientationChanged?.Invoke (_owner, new (in _orientation));
-       }
-   }
-```
+### INotifyPropertyChanged
 
- ## `bool` or `bool?` 
+We support `INotifyPropertyChanged` in cases where data binding is relevant.
 
-
 

docfx/docs/index.md

@@ -21,7 +21,9 @@ See [What's New in V2 For more](newinv2.md).
 ## Conceptual Documentation
 
 * [Arrangement API](arrangement.md)
+* [Cancellable Work Pattern](cancellable_work_pattern.md)
 * [Configuration and Theme Manager](config.md)
+* [Command Deep Dive](command.md)
 * [Cursor Deep Dive](cursor.md)
 * [Cross-platform Driver Model](drivers.md)
 * [Dim.Auto Deep Dive](dimauto.md)

docfx/docs/keyboard.md

@@ -1,5 +1,10 @@
 # Keyboard Deep Dive
 
+## See Also
+
+* [Cancellable Work Pattern](cancellable_work_pattern.md)
+* [Command Deep Dive](command.md)
+
 ## Tenets for Terminal.Gui Keyboard Handling (Unless you know better ones...)
 
 Tenets higher in the list have precedence over tenets lower in the list.

docfx/docs/mouse.md

@@ -1,5 +1,12 @@
 # Mouse API
 
+## See Also
+
+* [Cancellable Work Pattern](cancellable_work_pattern.md)
+* [Command Deep Dive](command.md)
+
+
+
 ## Tenets for Terminal.Gui Mouse Handling (Unless you know better ones...)
 
 Tenets higher in the list have precedence over tenets lower in the list.

docfx/docs/toc.yml

@@ -8,8 +8,12 @@
   href: migratingfromv1.md  
 - name: Arrangement
   href: arrangement.md
+- name: Cancellable Work Pattern
+  href: cancellable_work_pattern.md
 - name: Configuration
   href: config.md
+- name: Command Deep Dive
+  href: command.md
 - name: Cursor
   href: cursor.md
 - name: Dim.Auto Deep Dive