gum-visual-events

Explains cursor event dispatch and routing internals in the Gum UI runtime.

614|78|Updated Mar 11, 2015
One-click install
npx skills add https://github.com/vchelaru/Gum --skill gum-visual-events
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gum-visual-events
Source: https://github.com/vchelaru/Gum/tree/main/.claude/skills/gum-visual-events
Command: npx skills add https://github.com/vchelaru/Gum --skill gum-visual-events

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Developers working on the Gum UI runtime struggle to understand how cursor events like Click, Push, and RollOver are raised and routed through the visual tree, leading to bugs when adding new events or diagnosing why clicks fail to fire.

Core Features & Use Cases

  • Dispatch Internals Reference: Documents DoUiActivityRecursively in InteractiveGue.cs, the single recursive walk that drives all cursor events.
  • Routing Model Clarification: Explains the three coexisting dispatch disciplines (tunneling, bubbling, single-target) and how HandledActions plus RoutedEventArgs.Handled implement routing.
  • Gotcha Catalog: Covers edge cases like edge-triggered Cursor.Activity collapsing on double Update calls, reverse-order root traversal, and the FlatRedBall InteractiveGue divergence.
  • Use Case: When adding a new bubbling event to Gum, follow the documented precedent of creating a parallel *Bubbling event with its own HandledActions flag so existing single-target behavior is not broken.

Quick Start

Explain how Gum routes Click and RollOver events through the visual tree and how to add a new bubbling event without breaking existing behavior.

Frequently Asked Questions about gum-visual-events

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do cursor events work in the Gum UI runtime?

Gum cursor events are dispatched by DoUiActivityRecursively in InteractiveGue.cs, a single recursive walk over the visual tree. It descends to the deepest child under the cursor first, then unwinds, raising tunneling, bubbling, and single-target events along the way.

How do I add a bubbling event to Gum without breaking existing behavior?

Add a parallel *Bubbling event alongside the single-target one, following the RollOverBubbling and ClickBubbling precedent. Give it its own HandledActions flag so its Handled state only suppresses ancestors for that event and never touches single-target Click or Push.

Why do Gum Click events not fire even though hover works?

Cursor.Activity is edge-triggered, so calling Update twice in the same frame collapses the press/release edge and Push and Click silently never fire. Hover still works because it is position-only, so suspect a double Update call when GetEventFailureReason reports no problem.

What is the difference between Click and ClickBubbling in Gum?

Click is single-target and fires only where the cursor was both pushed and released on the same element. ClickBubbling uses a HandledActions.DidClickOccur flag set when a real click resolves, then fires on that element and the ancestors it unwinds through.

Does adding an event to InteractiveGue affect FlatRedBall?

No, FlatRedBall does not share InteractiveGue because it is absent from GumCoreShared.projitems and FRB keeps its own copy. If a shared Forms control subscribes to a new visual event, FRB's InteractiveGue must gain the same member or FRB breaks with CS1061.