Skip to content

Document event ordering for HitTestBehavior.translucent - #190163

Merged
auto-submit[bot] merged 7 commits into
flutter:masterfrom
binSaed:fix-hit-test-behavior-translucent-docs-28170
Aug 11, 2026
Merged

Document event ordering for HitTestBehavior.translucent#190163
auto-submit[bot] merged 7 commits into
flutter:masterfrom
binSaed:fix-hit-test-behavior-translucent-docs-28170

Conversation

@binSaed

@binSaed binSaed commented Jul 28, 2026 •
edited by Piinks
Loading

Copy link
Copy Markdown
Contributor

Description

Fixes #28170

This PR adds documentation to HitTestBehavior.translucent explaining which listener receives events first when both a translucent target and its descendant are listening to the same pointer event.

Currently, the documentation for translucent only says that both targets receive events, but does not explain the ordering or how gesture arena competitions are resolved. This has been a source of confusion since issue #28170 was filed.

Changes

  • Added a paragraph to HitTestBehavior.translucent explaining that:
    • Both the translucent target and its descendant receive pointer events
    • Events are dispatched to the most specific target first (the descendant), then to the translucent target
    • In gesture arena competitions, the descendant typically wins because it enters the arena first (first come, first served)
  • Added "See also" cross-references to HitTestResult.path and GestureDetector.behavior for further reading

Pre-launch Checklist

  • I read the Contributor Guide and followed the process outlined there for submitting PRs.
  • I read the Tree Hygiene wiki page, which explains my responsibilities.
  • I read and followed the Flutter Style Guide, including [Features: every day submit a PR].
  • I listed at least one issue that is owned by the Flutter team or is a valid community contribution in the description above.
  • I updated/added relevant documentation (doc comments with ///).
  • All existing and new tests are passing.
  • I signed the CLA.

Fixes #28170

@binSaed
Document event ordering for HitTestBehavior.translucent
f5810a4 
Add documentation to HitTestBehavior.translucent explaining which
listener receives events first when both a translucent target and
its descendant listen to the same pointer event. The descendant
(most specific target) receives events first and typically wins
gesture arena competitions.

Fixes flutter#28170
@github-actions github-actions Bot added the framework flutter/packages/flutter repository. See also f: labels. label Jul 28, 2026
@google-cla

google-cla Bot commented Jul 28, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

gemini-code-assist[bot]
gemini-code-assist Bot reviewed Jul 28, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds documentation to HitTestBehavior.translucent explaining event dispatching and gesture arena competition behavior between translucent targets and their descendants. The review feedback suggests clarifying that a translucent target's gesture can still be invoked if the descendant's gesture is rejected or if they listen to different gestures, and provides a code suggestion to refine the explanation.

Comment thread packages/flutter/lib/src/rendering/proxy_box.dart Outdated
@binSaed binSaed mentioned this pull request Jul 28, 2026
Closed
@binSaed
Clarify translucent gesture rejection behavior in docs
af22870 
Address review feedback: the translucent target's gesture can still be
invoked if the descendant's gesture is rejected, and scope the arena
explanation to competitions for the same gesture.
@binSaed
binSaed force-pushed the fix-hit-test-behavior-translucent-docs-28170 branch from 5cbe284 to af22870 Compare July 28, 2026 20:57
@Piinks Piinks added the d: api docs Issues with https://api.flutter.dev/ label Aug 4, 2026
@Piinks
Piinks self-requested a review August 4, 2026 22:18
Piinks
Piinks reviewed Aug 7, 2026
View reviewed changes

@Piinks Piinks left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @binSaed welcome! Thanks for contributing. 😄

Comment thread packages/flutter/lib/src/rendering/proxy_box.dart Outdated
@github-actions github-actions Bot removed the d: api docs Issues with https://api.flutter.dev/ label Aug 9, 2026
@binSaed

binSaed commented Aug 9, 2026

Copy link
Copy Markdown
Contributor Author

Thank you, @Piinks. Your suggestion has been applied.

Piinks
Piinks approved these changes Aug 10, 2026
View reviewed changes

@Piinks Piinks left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM thank you!

Piinks
Piinks approved these changes Aug 10, 2026
View reviewed changes

@Piinks Piinks left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM thank you!

@Piinks Piinks added the CICD Run CI/CD label Aug 10, 2026
@Hari-07 Hari-07 added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 11, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Aug 11, 2026
Merged via the queue into flutter:master with commit 061974f Aug 11, 2026
27 of 28 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Aug 11, 2026
This was referenced Aug 11, 2026
Closed
Closed
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Piinks Piinks Piinks approved these changes
@Hari-07 Hari-07 Hari-07 approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

CICD Run CI/CD framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document which listener will win with HitTestBehavior.translucent

3 participants

@binSaed @Piinks @Hari-07