Update transformHitTests documentation for clarity #174286
Conversation
Fixes flutter#78120 - Clarified that only hits within parent bounds can be registered - Explained coordinate transformation behavior for both true/false cases - Added guidance for handling out-of-bounds interactive elements - Referenced Overlay as alternative solution
|
It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging. If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix? Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group. |
There was a problem hiding this comment.
Code Review
This pull request significantly improves the documentation for the transformHitTests property on the Transform widget. The new documentation is much clearer and addresses a common point of confusion for developers by explicitly stating the limitations of hit testing with transforms. The other changes in this PR are minor formatting adjustments. My review includes a suggestion to further enhance the documentation by adding a code example, as recommended by the style guide.
- Removed outdated explanation of hit test behavior. - Added detailed description of coordinate transformation rules. - Included runnable code snippet demonstrating scaling and tap region limits. Fixes flutter#78120
24ab5e8 to
45554dc
Compare
Description 📝
This PR updates the documentation for the transformHitTests parameter in the Transform widget to resolve ambiguity in the API documentation that has caused hit testing issues for developers.
The current documentation simply states "Whether to apply the transformation when performing hit tests" which is ambiguous. As seen in issues like #27587, developers expect transformed widgets to receive touch events across their entire visual area, but hits only register within the parent's original bounds.
The core issue: The documentation lacks clarity on:
⚠️ The distinction between visual rendering bounds and interactive bounds
❌ Hit test coordinate system transformation vs. hit test bounds expansion
🔄 Parent widget bounds as the constraint for hit test registration
Before (Current Documentation)
Current documentation is vague: "Whether to apply the transformation when performing hit tests"
After (Improved Documentation)
New documentation clearly explains behavior, limitations, and solutions
Changes made: ✅
transformHitTeststransforms registered hits into the child's resulting coordinate systemtrueandfalsesettings with concrete examples of transformation typesIssues Fixed 🐛
Fixes #78120
Related issues that motivated this change: 🔗
Note: This PR is test-exempt as it only updates documentation comments without changing any functionality.
Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.
Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the
gemini-code-assistbot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.