┌─────────────────────────────────────────────────────────────┐
│              Which Event Pattern Should I Use?              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Need to notify about something?                            │
│           │                                                 │
│           ▼                                                 │
│  ┌─────────────────┐                                        │
│  │ Can it be       │──► NO ──► Simple EventHandler          │
│  │ cancelled?      │          (no CWP needed)               │
│  └────────┬────────┘                                        │
│           │ YES                                             │
│           ▼                                                 │
│  ┌─────────────────┐                                        │
│  │ Property or     │──► PROPERTY ──► CWPPropertyHelper      │
│  │ Action/Workflow?│                 (Recipe 1)             │
│  └────────┬────────┘                                        │
│           │ ACTION                                          │
│           ▼                                                 │
│       Manual CWP or CWPWorkflowHelper                       │
│       (Recipe 2)                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

public class MyDataView : View
{
    private object? _dataSource;

    // Pre-change event (cancellable)
    public event EventHandler<ValueChangingEventArgs<object?>>? DataSourceChanging;

    // Post-change event (notification)
    public event EventHandler<ValueChangedEventArgs<object?>>? DataSourceChanged;

    // Virtual method for subclasses (pre-change) - returns true to cancel
    protected virtual bool OnDataSourceChanging (ValueChangingEventArgs<object?> args) => false;

    // Virtual method for subclasses (post-change) - void, cannot cancel
    protected virtual void OnDataSourceChanged (ValueChangedEventArgs<object?> args) { }
}

public object? DataSource
{
    get => _dataSource;
    set
    {
        if (CWPPropertyHelper.ChangeProperty (
                sender: this,
                currentValue: ref _dataSource,
                newValue: value,
                onChanging: OnDataSourceChanging,
                changingEvent: DataSourceChanging,
                doWork: newDataSource =>
                {
                    // Additional work AFTER value changes but BEFORE Changed events
                    // e.g., refresh display, update selection
                    SetNeedsDraw ();
                },
                onChanged: OnDataSourceChanged,
                changedEvent: DataSourceChanged,
                out _))
        {
            // Property was changed (not cancelled)
        }
    }
}

// External subscriber (event)
myDataView.DataSourceChanging += (sender, args) =>
{
    if (args.NewValue is null)
    {
        args.Handled = true; // Prevent null assignment
    }
};

myDataView.DataSourceChanged += (sender, args) =>
{
    Console.WriteLine($"DataSource changed from {args.OldValue} to {args.NewValue}");
};

// Subclass (virtual method override)
public class MyCustomDataView : MyDataView
{
    protected override bool OnDataSourceChanging (ValueChangingEventArgs<object?> args)
    {
        // Validate new data source
        if (args.NewValue is ICollection { Count: 0 })
        {
            return true; // Cancel - don't allow empty collections
        }

        return false;
    }
}

public class MyProcessor : View
{
    // Event for external subscribers
    public event EventHandler<CancelEventArgs>? Processing;

    // Virtual method for subclasses
    protected virtual bool OnProcessing (CancelEventArgs args)
    {
        return false; // Return true to cancel
    }

    // Internal method that implements CWP
    public bool Process ()
    {
        CancelEventArgs args = new ();

        // Step 1: Call virtual method (subclass gets first chance)
        if (OnProcessing (args) || args.Cancel)
        {
            return false; // Cancelled
        }

        // Step 2: Raise event (external subscribers get a chance)
        Processing?.Invoke (this, args);

        if (args.Cancel)
        {
            return false; // Cancelled
        }

        // Step 3: Execute default behavior
        DoProcessing ();

        return true;
    }

    private void DoProcessing ()
    {
        // Default processing logic
    }
}

public class MyProcessor : View
{
    public event EventHandler<ResultEventArgs<bool>>? Processing;

    protected virtual bool OnProcessing (ResultEventArgs<bool> args)
    {
        return false; // Return true to cancel
    }

    public bool? Process ()
    {
        ResultEventArgs<bool> args = new ();

        return CWPWorkflowHelper.Execute (
            onMethod: OnProcessing,
            eventHandler: Processing,
            args: args,
            defaultAction: () =>
            {
                // Default processing logic
                DoProcessing ();
                args.Result = true;
            });
    }

    private void DoProcessing ()
    {
        // Processing logic
    }
}

public class MyView : View
{
    // Simple event - no cancellation
    public event EventHandler? SelectionMade;

    // Virtual method for subclasses - NO-OP by default
    protected virtual void OnSelectionMade ()
    {
        // Does nothing by default.
        // Subclasses override this to react to the selection.
    }

    // Internal method that raises the notification
    private void RaiseSelectionMade ()
    {
        // 1. Call virtual method first (subclasses get priority)
        OnSelectionMade ();

        // 2. Raise event (external subscribers)
        SelectionMade?.Invoke (this, EventArgs.Empty);
    }

    private void HandleSelection ()
    {
        // ... selection logic ...
        RaiseSelectionMade ();
    }
}

// Subclass example
public class MyCustomView : MyView
{
    protected override void OnSelectionMade ()
    {
        // React to selection in subclass
        UpdateStatusBar ();
    }
}

public class ViewModel : INotifyPropertyChanged
{
    private string _name = string.Empty;

    public event PropertyChangedEventHandler? PropertyChanged;

    public string Name
    {
        get => _name;
        set
        {
            if (_name != value)
            {
                _name = value;
                PropertyChanged?.Invoke (this, new PropertyChangedEventArgs (nameof (Name)));
            }
        }
    }
}

public interface ICommandContext
{
    Command Command { get; }                    // The command being invoked
    WeakReference<View>? Source { get; }        // Weak ref to the originating view
    ICommandBinding? Binding { get; }           // The binding that triggered the command
    CommandRouting Routing { get; }             // Direct, BubblingUp, DispatchingDown, or Bridged
    IReadOnlyList<object?> Values { get; }     // Values accumulated as the command propagated
    object? Value { get; }                      // Most recently appended value (Values[^1])
}

protected override bool OnAccepting (CommandEventArgs args)
{
    // Determine what triggered the command
    switch (args.Context?.Binding)
    {
        case KeyBinding kb:
            // Keyboard-triggered
            Key? key = kb.Key;

            break;

        case MouseBinding mb:
            // Mouse-triggered
            Point position = mb.MouseEvent.Position;
            MouseFlags flags = mb.MouseEvent.Flags;

            break;

        case CommandBinding ib:
            // Programmatic invocation
            object? data = ib.Data;

            break;
    }

    return false;
}

// Or use property patterns for concise access:
if (args.Context?.Binding is MouseBinding { MouseEvent: { } mouse })
{
    Point position = mouse.Position;
}

protected override bool OnAccepting (CommandEventArgs args)
{
    // In the Accepting event handler, `this` is the view raising the event (changes as it bubbles).
    // args.Context?.Source is a WeakReference<View> to the original view that started the command (constant).

    View? originalView = null;
    args.Context?.Source?.TryGetTarget (out originalView);

    return false;
}

/// <summary>
/// Non-generic interface for accessing a View's value as a boxed object.
/// Used by command propagation to carry values without knowing the generic type.
/// </summary>
public interface IValue
{
    /// <summary>Gets the value as a boxed object.</summary>
    object? GetValue ();
}

/// <summary>
/// Interface for Views that provide a strongly-typed value.
/// </summary>
public interface IValue<TValue> : IValue
{
    /// <summary>Gets or sets the value.</summary>
    TValue? Value { get; set; }

    /// <summary>
    /// Raised when <see cref="Value"/> is about to change.
    /// Set <see cref="ValueChangingEventArgs{T}.Handled"/> to cancel.
    /// </summary>
    event EventHandler<ValueChangingEventArgs<TValue?>>? ValueChanging;

    /// <summary>
    /// Raised when <see cref="Value"/> has changed.
    /// </summary>
    event EventHandler<ValueChangedEventArgs<TValue?>>? ValueChanged;

    /// <inheritdoc/>
    object? IValue.GetValue () => Value;
}

menuBar.Accepting += (_, args) =>
{
    // Access the value from the originating view via WeakReference
    View? sourceView = null;
    args.Context?.Source?.TryGetTarget (out sourceView);

    if (sourceView is IValue valueView)
    {
        object? value = valueView.GetValue ();

        // Pattern match on value type
        if (value is CheckState checkState)
        {
            _autoSave = checkState == CheckState.Checked;
        }
        else if (value is int optionIndex)
        {
            _selectedOption = optionIndex;
        }
    }
};

void ProcessValueView<T> (IValue<T> valueView)
{
    T? currentValue = valueView.Value;

    valueView.ValueChanged += (sender, args) =>
    {
        T? newValue = args.NewValue;
        T? oldValue = args.OldValue;
        // Handle value change
    };
}

// CheckBox example
public class CheckBox : View, IValue<CheckState>
{
    public CheckState CheckedState { get; set; }  // Legacy property

    public CheckState? Value  // IValue<T> property
    {
        get => CheckedState;
        set => CheckedState = value ?? CheckState.None;
    }
}

// CORRECT order: Virtual -> Event -> Default behavior
protected void DoSomething ()
{
    SomeEventArgs args = new ();

    // 1. Virtual method first
    if (OnDoingSomething (args))
    {
        return; // Cancelled by subclass
    }

    // 2. Event second
    DoingSomething?.Invoke (this, args);

    if (args.Handled)
    {
        return; // Cancelled by subscriber
    }

    // 3. Default behavior
    ExecuteDefaultBehavior ();

    // 4. Post-change notification (if applicable)
    OnDidSomething (new DidSomethingEventArgs ());
    DidSomething?.Invoke (this, new DidSomethingEventArgs ());
}

// BAD: Potential memory leak
view.Accepting += OnAccepting;

// GOOD: Unsubscribe in Dispose
protected override void Dispose (bool disposing)
{
    if (disposing)
    {
        view.Accepting -= OnAccepting;
    }

    base.Dispose (disposing);
}

// ❌ WRONG: Using non-existent Cancel property
args.Cancel = true;  // ValueChangingEventArgs doesn't have Cancel!

// ✅ CORRECT: Use Handled for all CWP events
args.Handled = true;

// WRONG: Event raised before virtual method
DoingSomething?.Invoke (this, args);
if (OnDoingSomething (args)) { return; }  // Too late!

// CORRECT: Virtual method first, then event
if (OnDoingSomething (args)) { return; }
DoingSomething?.Invoke (this, args);

// WRONG: Only checking virtual method
if (OnDoingSomething (args)) { return; }
DoingSomething?.Invoke (this, args);
ExecuteDefault (); // Bug: Event subscribers can't cancel!

// CORRECT: Check both virtual method AND event args
if (OnDoingSomething (args) || args.Handled) { return; }
DoingSomething?.Invoke (this, args);
if (args.Handled) { return; }
ExecuteDefault ();