docs: Clarify Transform.rotate origin interaction with alignment #163934
Conversation
This commit improves the documentation for Transform.rotate's origin property to clarify its interaction with the alignment property. It emphasizes that the origin offset is applied after the alignment transformation, and provides examples to avoid common misinterpretations.
|
@SunkenInTime Heads up that there are failures. I'll try to take a look at this later, thanks for the PR! |
|
@justinmc |
There was a problem hiding this comment.
Hey @SunkenInTime welcome! Thanks for contributing!
It looks like the failures are caused by your change, from the output:
RUNNING: cd .; bin/cache/dart-sdk/bin/dart --enable-asserts /b/s/w/ir/x/w/flutter/dev/bots/analyze_snippet_code.dart --verbose
workingDirectory: /b/s/w/ir/x/w/flutter, executable: /b/s/w/ir/x/w/flutter/bin/cache/dart-sdk/bin/dart, arguments: [--enable-asserts, /b/s/w/ir/x/w/flutter/dev/bots/analyze_snippet_code.dart, --verbose]
packages/flutter/lib/src/widgets/basic.dart:1737:17: Use 'const' with the constructor to improve performance (expression) (prefer_const_constructors)
packages/flutter/lib/src/widgets/basic.dart:1738:16: Abstract classes can't be instantiated (expression) (instantiate_abstract_class)
packages/flutter/lib/src/widgets/basic.dart:1738:16: Use 'const' with the constructor to improve performance (expression) (prefer_const_constructors)
packages/flutter/lib/src/widgets/basic.dart:1747:17: Use 'const' with the constructor to improve performance (expression) (prefer_const_constructors)
packages/flutter/lib/src/widgets/basic.dart:1748:16: Abstract classes can't be instantiated (expression) (instantiate_abstract_class)
packages/flutter/lib/src/widgets/basic.dart:1748:16: Use 'const' with the constructor to improve performance (expression) (prefer_const_constructors)
Found 6 snippet code errors.
Can you update to resolve these?
|
Hi @Piinks , thanks for the heads up! I didn't realize that it lints the code snippets 😭. I've made the changes to the affected lines. I would also like to know if the text widgets used there are appropriate. Thanks again! |
|
@justinmc Apologies for taking so long, just made the proposed fixes to the commit! Thanks for the guidance 😊 |
|
Golden file changes have been found for this pull request. Click here to view and triage (e.g. because this is an intentional change). If you are still iterating on this change and are not ready to resolve the images on the Flutter Gold dashboard, consider marking this PR as a draft pull request above. You will still be able to view image results on the dashboard, commenting will be silenced, and the check will not try to resolve itself until marked ready for review. For more guidance, visit Writing a golden file test for Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. |
|
I believe I've fixed all errors @justinmc 😊 |
|
@SunkenInTime Are you still available to follow up on this PR? Sorry for the slow responses here. |
|
Yes, I’m still available to follow up on this PR. No worries about the delay!
The main issue is that the interaction between origin and alignment in Transform.rotate is inconsistent with how offsets typically work in Flutter. In Flutter’s coordinate system, the point (0, 0) is at the top-left of the widget. However, Transform.rotate defaults its alignment to Alignment.center, which shifts the coordinate origin to the center of the widget. What makes this even more confusing is that alignment does not have to be explicitly defined—if you don’t specify it, it silently defaults to the center. This can make it difficult to realize that alignment is affecting the transformation, especially when you’re trying to use origin to control the rotation point. As a result, the behavior may not match what you’d expect if you’re following typical Flutter coordinate conventions. To illustrate this, I’ve created a DartPad example that demonstrates the issue. Please take a look for more clarity. |
|
Hi @justinmc, just checking in on the status of this PR when you have a chance. Please let me know if there’s anything I can do to help move it forward. Thanks! |
There was a problem hiding this comment.
@SunkenInTime Sorry for losing track of this PR. Feel free to ping me on the Flutter Discord if it happens again.
Thank you for the dartpad and the clear explanation. I see how this is confusing and I agree that we should mention alignment in the origin docs.
Take a look at my rewrite below and let me know what you think. It doesn't explicitly use alignment in the examples, would you prefer that it did?
|
Hi @justinmc , no worries at all! I think your rewrite is great and it maintains brevity, which is awesome. The only issue I have is with this section: /// However in this example, the child is rotated about its bottom right
/// corner:I changed it to: /// However, in this example the `origin` offset is applied after the
/// `alignment`, so the child rotates about its bottom-right corner:I realize my version might be a bit redundant, but I don’t think there’s any harm in being explicit about the behavior, especially since this part can be confusing. What do you think? |
This commit improves the documentation for Transform.rotate's origin property to clarify its interaction with the alignment property.
Before: The documentation did not clearly explain how the origin offset interacts with the alignment property, potentially leading to confusion about the actual rotation point.
After: The documentation now emphasizes that the origin offset is applied after the alignment transformation, and provides examples to avoid common misinterpretations.
This change ensures developers can correctly position the rotation point.