Terminal.Gui/docfx/docs/cancellable-work-pattern.md

Cancellable Work Pattern in Terminal.Gui

The Cancellable Work Pattern is a core design pattern in Terminal.Gui, used to structure workflows that can be executed in a default manner, modified by external code or subclasses, or cancelled entirely. This pattern is prevalent across various components of Terminal.Gui, including the View class for rendering, keyboard input, and command execution, as well as application-level input handling and property changes. Unlike traditional inheritance-based approaches that rely on overriding virtual methods (which often require subclasses to understand base class implementation details), the Cancellable Work Pattern prioritizes events for loose coupling, supplemented by optional virtual methods for flexibility.

This deep dive defines the Cancellable Work Pattern, outlines its components and goals, and illustrates its implementation through examples in View.Draw, View.Keyboard, View.Command, Application.Keyboard, and OrientationHelper.

Definition

The Cancellable Work Pattern is a design pattern for executing a structured workflow with one or more phases, where each phase can:

• Proceed in a default manner.
• Be modified by external code or subclasses.
• Be cancelled to halt further processing.

The pattern uses events as the primary mechanism for notification and customization, supplemented by virtual methods for subclassing when needed. It is a specialization of the Observer Pattern, extended with structured workflows, explicit cancellation mechanisms, and context-aware notifications. It also incorporates elements of the Template Method Pattern (via virtual methods) and Pipeline Pattern (via sequential phases).

Goals

The Cancellable Work Pattern is designed to achieve the following:

1. Default Execution: Provide a standard process that executes unless interrupted, ensuring predictable behavior out of the box.
2. Modification: Allow external code or subclasses to customize specific phases without requiring deep knowledge of the implementation.
3. Cancellation: Enable halting of a phase or the entire workflow, giving consumers control over the process.
4. Decoupling: Use events to reduce reliance on inheritance, minimizing the need for subclasses to understand base class details.

Components

The Cancellable Work Pattern consists of the following components:

• Workflow: A sequence of phases, which may be multi-phase (e.g., rendering in View.Draw), linear (e.g., key processing in View.Keyboard), per-unit (e.g., command execution in View.Command), or event-driven (e.g., key handling in Application.Keyboard, property changes in OrientationHelper).
• Notifications: Events (e.g., DrawingText, KeyDown, Activating, OrientationChanging) and virtual methods (e.g., OnDrawingText, OnKeyDown, OnActivating, OnOrientationChanging) raised at each phase to notify observers.
• Cancellation: Mechanisms to halt a phase or workflow, such as setting Cancel/Handled properties in event arguments or returning bool from virtual methods.
• Context: Data passed to observers for informed decision-making, such as DrawContext (drawing), Key (keyboard), ICommandContext (commands), or CancelEventArgs<Orientation> (orientation).
• Default Behavior: A standard implementation for each phase, such as DrawText (drawing), InvokeCommands (keyboard and application-level), RaiseActivating (commands), or updating a property (OrientationHelper).

Implementation in Terminal.Gui

The Cancellable Work Pattern is implemented consistently across several key areas of Terminal.Gui’s v2_develop branch. Below are five primary examples, each illustrating the pattern in a different domain: rendering, keyboard input at the view level, command execution, application-level keyboard input, and property changes.

1. View.Draw: Rendering Workflow

The View.Draw method orchestrates the rendering of a view, including its adornments (margin, border, padding), viewport, text, content, subviews, and line canvas. It is a multi-phase workflow where each phase can be customized or cancelled.

Example: DoDrawText

The DoDrawText method, responsible for drawing a view’s text, exemplifies the pattern:

private void DoDrawText(DrawContext? context = null)
{
    if (OnDrawingText(context)) // Virtual method for subclasses
    {
        return; // Cancel if true
    }
    if (OnDrawingText()) // Legacy virtual method
    {
        return; // Cancel if true
    }
    var dev = new DrawEventArgs(Viewport, Rectangle.Empty, context);
    DrawingText?.Invoke(this, dev); // Notify observers
    if (dev.Cancel) // Check for cancellation
    {
        return;
    }
    DrawText(context); // Default behavior
}

• Workflow: Single phase for text drawing within the broader Draw workflow.
• Notifications: OnDrawingText (virtual), DrawingText (event).
• Cancellation: OnDrawingText returning true or dev.Cancel = true.
• Context: DrawContext and DrawEventArgs provide rendering details.
• Default Behavior: DrawText renders the view’s text.
• Use Case: Allows customization of text rendering (e.g., custom formatting) or cancellation (e.g., skipping text for performance).

2. View.Keyboard: View-Level Keyboard Input

The View.ProcessKeyDown method processes keyboard input for a view, mapping keys to commands or handling them directly. It is a linear workflow with a single phase per key event.

Example: ProcessKeyDown

public virtual bool ProcessKeyDown(Key key)
{
    if (OnKeyDown(key)) // Virtual method
    {
        return true; // Cancel if true
    }
    KeyDown?.Invoke(this, key); // Notify observers
    if (key.Handled) // Check for cancellation
    {
        return true;
    }
    bool handled = InvokeCommands(key, KeyBindingScope.HotKey | KeyBindingScope.Focused); // Default behavior
    return handled;
}

• Workflow: Linear, processing one key event.
• Notifications: OnKeyDown (virtual), KeyDown (event).
• Cancellation: OnKeyDown returning true or key.Handled = true.
• Context: Key provides key details and bindings.
• Default Behavior: InvokeCommands maps keys to commands (e.g., Command.Accept).
• Use Case: Allows views to customize key handling (e.g., TextField capturing input) or cancel default command execution.

3. View.Command: Command Execution

The View.Command APIs execute commands like Command.Activate and Command.Accept, used for state changes (e.g., CheckBox toggling) and action confirmation (e.g., dialog submission). It is a per-unit workflow, with one phase per command.

Example: RaiseActivating

The RaiseActivating method handles Command.Activate:

protected bool? RaiseActivating(ICommandContext? ctx)
{
    CommandEventArgs args = new() { Context = ctx };
    if (OnActivating(args) || args.Handled)
    {
        return true;
    }
    Activating?.Invoke(this, args);
    return Activating is null ? null : args.Handled;
}

• Workflow: Single phase for Command.Activate.
• Notifications: OnActivating (virtual), Activating (event).
• Cancellation: OnActivating returning true or args.Handled = true.
• Context: ICommandContext provides Command, Source, and Binding.
• Default Behavior: SetFocus for Command.Activate (in SetupCommands).
• Use Case: Allows customization of state changes (e.g., CheckBox toggling) or cancellation (e.g., preventing focus in MenuItemv2).

Propagation Challenge

• Command.Activate is local, limiting hierarchical coordination (e.g., MenuBarv2 popovers). A proposed PropagatedCommands property addresses this, as detailed in the appendix.

4. Application.Keyboard: Application-Level Keyboard Input

The Application.OnKeyDown method processes application-wide keyboard input, raising events for global key handling. It is an event-driven workflow, with a single phase per key event.

Example: OnKeyDown

public static bool OnKeyDown(Key key)
{
    if (KeyDown is null)
    {
        return false;
    }
    KeyDown?.Invoke(null, key); // Notify observers
    return key.Handled; // Check for cancellation
}

• Workflow: Event-driven, processing one key event.
• Notifications: KeyDown (event, no virtual method).
• Cancellation: key.Handled = true.
• Context: Key provides key details.
• Default Behavior: None; relies on subscribers (e.g., Top view processing).
• Use Case: Allows global key bindings (e.g., Ctrl+Q to quit) or cancellation of default view handling.

5. OrientationHelper: Property Changes

The OrientationHelper class manages orientation changes (e.g., in StackPanel), raising events for property updates. It is an event-driven workflow, with a single phase per change.

Example: Orientation Setter

public Orientation Orientation
{
    get => _orientation;
    set
    {
        if (_orientation == value)
        {
            return;
        }
        var oldOrientation = _orientation;
        var args = new CancelEventArgs<Orientation>(_orientation, ref value);
        if (OnOrientationChanging(args))
        {
            return; // Cancel if true
        }
        OrientationChanging?.Invoke(this, args);
        if (args.Cancel)
        {
            return;
        }
        _orientation = value;
        var changedArgs = new EventArgs<Orientation>(oldOrientation, _orientation);
        OnOrientationChanged(changedArgs);
        OrientationChanged?.Invoke(this, changedArgs);
    }
}

• Workflow: Event-driven, processing one property change.
• Notifications: OnOrientationChanging (virtual), OrientationChanging (event), OnOrientationChanged, OrientationChanged (post-event).
• Cancellation: OnOrientationChanging returning true or args.Cancel = true.
• Context: CancelEventArgs<Orientation> provides old and new values.
• Default Behavior: Updates _orientation and notifies via OrientationChanged.
• Use Case: Allows customization of orientation changes (e.g., adjusting layout) or cancellation (e.g., rejecting invalid orientations).

Proposed Enhancement: Command Propagation

The Cancellable Work Pattern in View.Command currently supports local Command.Activate and propagating Command.Accept. To address hierarchical coordination needs (e.g., MenuBarv2 popovers, Dialog closing), a PropagatedCommands property is proposed (Issue #4050):

• Change: Add IReadOnlyList<Command> PropagatedCommands to View, defaulting to [Command.Accept]. Raise* methods propagate if the command is in SuperView?.PropagatedCommands and args.Handled is false.
• Example:

  public IReadOnlyList<Command> PropagatedCommands { get; set; } = new List<Command> { Command.Accept };
  protected bool? RaiseActivating(ICommandContext? ctx)
  {
      CommandEventArgs args = new() { Context = ctx };
      if (OnActivating(args) || args.Handled)
      {
          return true;
      }
      Activating?.Invoke(this, args);
      if (!args.Handled && SuperView?.PropagatedCommands.Contains(Command.Activate) == true)
      {
          return SuperView.InvokeCommand(Command.Activate, ctx);
      }
      return Activating is null ? null : args.Handled;
  }
  

• Impact: Enables Command.Activate propagation for MenuBarv2 while preserving Command.Accept propagation, maintaining decoupling and avoiding noise from irrelevant commands.

Challenges and Recommendations

1. Conflation in FlagSelector:

   • Issue: CheckBox.Activating triggers Accepting, conflating state change and confirmation.
   • Recommendation: Refactor to separate Activating and Accepting:

     checkbox.Activating += (sender, args) =>
     {
         if (RaiseActivating(args.Context) is true)
         {
             args.Handled = true;
         }
     };
     

2. Propagation Limitations:

   • Issue: Local Command.Activate restricts MenuBarv2 coordination; Command.Accept uses hacks (#3925).
   • Recommendation: Adopt PropagatedCommands to enable targeted propagation, as proposed.

3. Documentation Gaps:

   • Issue: The pattern’s phases and Handled semantics are not fully documented.
   • Recommendation: Document the pattern’s structure, phases, and examples across View.Draw, View.Keyboard, View.Command, Application.Keyboard, and OrientationHelper.

4. Complexity in Multi-Phase Workflows:

   • Issue: View.Draw’s multi-phase workflow can be complex for developers to customize.
   • Recommendation: Provide clearer phase-specific documentation and examples.

Conclusion

The Cancellable Work Pattern is a foundational design in Terminal.Gui, enabling extensible, cancellable, and decoupled workflows across rendering, input handling, command execution, and property changes. Its implementation in View.Draw, View.Keyboard, View.Command, Application.Keyboard, and OrientationHelper supports diverse use cases, from Menuv2’s hierarchical menus to CheckBox’s state toggling. The proposed PropagatedCommands property enhances the pattern’s applicability in View.Command, addressing propagation needs while maintaining its core principles. By refining implementation flaws (e.g., FlagSelector) and improving documentation, Terminal.Gui can further leverage this pattern for robust, flexible UI interactions.