Skip to content

Improve discoverability of CommandNotBound bubbling pattern for mouse events #5301

@tig

Description

@tig

Problem

When implementing mouse-wheel scrolling on a child view that should forward to a parent (e.g., a gutter subview inside an Editor's Padding that needs to scroll the Editor), the correct pattern is:

  1. Child adds only MouseBindings (e.g., MouseBindings.Add(MouseFlags.WheeledUp, Command.ScrollUp)) — no AddCommand handler.
  2. Parent sets CommandsToBubbleUp = [Command.ScrollUp, Command.ScrollDown, ...]
  3. When the child receives the wheel event, the mouse binding fires the command, DefaultCommandNotBoundHandler runs → TryBubbleUp finds the ancestor with the command in CommandsToBubbleUp → invokes it.

This is elegant and idiomatic, but extremely hard to discover:

  • command-diagrams.md focuses on Accept/Activate flows and doesn't mention scroll or mouse-wheel forwarding.
  • The CommandNotBound event XML docs describe the mechanism but don't explain when to use it (i.e., "add a MouseBinding without a handler to let it bubble").
  • CommandsToBubbleUp docs don't mention the AdornmentView special case (adornment.Adornment?.Parent) which is critical for views hosted in Padding/Border.
  • There's no example showing the "child forwards wheel to parent" pattern which is a very common need.

Suggested Improvements

  1. Add a "Mouse Event Forwarding" section to command-diagrams.md (or a new mouse-commands.md) showing:

    • The pattern: MouseBinding without AddCommand → CommandNotBound → TryBubbleUp → parent handles
    • A concrete example (e.g., ScrollBar/Gutter wheel forwarding)
    • The AdornmentView special case in CommandWillBubbleToAncestor
  2. Improve CommandsToBubbleUp API docs to:

    • Explicitly mention that views in Padding/Border/Margin bubble to the Adornment's Parent (not SuperView)
    • Show a code snippet of the wheel-forwarding pattern
  3. Improve CommandNotBound event docs to:

    • Clarify that adding a MouseBinding without an AddCommand handler is intentional and idiomatic
    • Link to the bubbling docs
  4. Add a scenario/example in UICatalog demonstrating mouse-wheel forwarding between views.

Context

Discovered while implementing gutter mousewheel scrolling for the Editor library (gui-cs/Editor#96). The pattern works perfectly once found, but required reading View.Command.cs source and CommandBridge.cs to piece together.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No fields configured for Task.

Projects

Status

✅ Done

Relationships

None yet

Development

No branches or pull requests

Issue actions