Skip to content

Fixes #3849. Docs: clarify when to use -ing vs -ed events (Accepting vs Accepted, etc.)#5298

Merged
tig merged 2 commits into
developfrom
copilot/docs-clarify-ing-vs-ed-events
May 12, 2026
Merged

Fixes #3849. Docs: clarify when to use -ing vs -ed events (Accepting vs Accepted, etc.)#5298
tig merged 2 commits into
developfrom
copilot/docs-clarify-ing-vs-ed-events

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 12, 2026

AI agents and IntelliSense autocomplete consistently reach for -ing events (Accepting, Activating) for simple side-effect handlers that should use -ed events instead. The -ing variants run synchronously mid-dispatch and are cancellable — subscribing without cancelling is both wasteful and misleading.

Changes

  • docfx/docs/events.md — New "When to Use -ing vs -ed Events" section added near the top with the canonical rule, concrete ✅/❌ examples, and a quick-reference table covering all common pairs.

  • .claude/rules/event-patterns.md — Same rule added as the first section so Copilot/Claude sees it immediately when reading event guidance.

  • View.Command.cs XML docs<remarks> added to all four paired command events:

    • Accepting / Accepted
    • Activating / Activated

Rule (now in docs, xmldoc, and AI rules)

// ✅ side-effect — use the -ed event
button.Accepted += (_, _) => DoTheThing ();

// ✅ needs to cancel — -ing is correct
button.Accepting += (_, e) => { if (!CanProceed ()) e.Handled = true; };

// ❌ handler ignores EventArgs — should be Accepted
button.Accepting += (_, _) => DoTheThing ();

If your handler doesn't read or set anything on EventArgs (no e.Handled, no e.Cancel), use the -ed event.

Pull Request checklist:

  • I've named my PR in the form of "Fixes #issue. Terse description."
  • My code follows the style guidelines of Terminal.Gui - if you use Visual Studio, hit CTRL-K-D to automatically reformat your files before committing.
  • My code follows the Terminal.Gui library design guidelines
  • I ran dotnet test before commit
  • I have made corresponding changes to the API documentation (using /// style comments)
  • My changes generate no new warnings
  • I have checked my code and corrected any poor grammar or misspellings
  • I conducted basic QA to assure all features are working

Copilot AI changed the title [WIP] Docs: clarify when to use -ing vs -ed events Fixes #3849. Docs: clarify when to use -ing vs -ed events (Accepting vs Accepted, etc.) May 12, 2026
Copilot finished work on behalf of tig May 12, 2026 14:43
Copilot AI requested a review from tig May 12, 2026 14:43
@tig tig marked this pull request as ready for review May 12, 2026 14:52
@tig tig requested review from BDisp, YourRobotOverlord and harder May 12, 2026 14:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: clarify when to use -ing vs -ed events (Accepting vs Accepted, etc.)

3 participants