Document moveStep direction on WidgetController.dragUntilVisible#186943
Merged
auto-submit[bot] merged 3 commits intoJun 11, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Code Review
This pull request adds documentation to the WidgetController class explaining the touch-input conventions for the moveStep parameter. Feedback suggests formatting the direction explanations as a bulleted list to improve readability and providing consistent context for all swipe directions.
Comment on lines
+2452
to
+2456
| /// The `moveStep` is the offset by which the virtual finger moves on the | ||
| /// virtual screen between drags. Following the standard touch-input | ||
| /// convention, a negative `dy` swipes up (which scrolls the content down to | ||
| /// reveal items below), a positive `dy` swipes down, a positive `dx` swipes | ||
| /// right, and a negative `dx` swipes left. |
Contributor
There was a problem hiding this comment.
The documentation for the directions of moveStep is a bit dense as a single paragraph. Using a bulleted list would significantly improve readability and make it easier for developers to quickly find the direction they need. Additionally, the current text only explains the resulting "reveal" behavior for one of the four directions; providing this context for all directions ensures the documentation is consistently useful and fully addresses the confusion mentioned in the linked issue.
/// The `moveStep` is the offset by which the virtual finger moves on the
/// virtual screen between drags. Following the standard touch-input
/// convention:
///
/// * A negative `dy` swipes up (scrolling down to reveal items below).
/// * A positive `dy` swipes down (scrolling up to reveal items above).
/// * A negative `dx` swipes left (scrolling right to reveal items to the right).
/// * A positive `dx` swipes right (scrolling left to reveal items to the left).
Contributor
There was a problem hiding this comment.
I agree with Gemini, although I think we don't need a list here. My suggestion:
/// The `moveStep` is the offset by which the virtual finger moves on the
/// virtual screen between drags. Following the standard touch-input
/// convention, a negative [Offset.dy] swipes up (revealing items below), a
/// positive [Offset.dy] swipes down (revealing items above), a positive
/// [Offset.dx] swipes right (revealing items to the left), and a negative
/// [Offset.dx] swipes left (revealing items to the right).
dkwingsmt
previously approved these changes
Jun 10, 2026
dkwingsmt
left a comment
Contributor
There was a problem hiding this comment.
LGTM with minor suggestion. Thank you!
Comment on lines
+2452
to
+2456
| /// The `moveStep` is the offset by which the virtual finger moves on the | ||
| /// virtual screen between drags. Following the standard touch-input | ||
| /// convention, a negative `dy` swipes up (which scrolls the content down to | ||
| /// reveal items below), a positive `dy` swipes down, a positive `dx` swipes | ||
| /// right, and a negative `dx` swipes left. |
Contributor
There was a problem hiding this comment.
I agree with Gemini, although I think we don't need a list here. My suggestion:
/// The `moveStep` is the offset by which the virtual finger moves on the
/// virtual screen between drags. Following the standard touch-input
/// convention, a negative [Offset.dy] swipes up (revealing items below), a
/// positive [Offset.dy] swipes down (revealing items above), a positive
/// [Offset.dx] swipes right (revealing items to the left), and a negative
/// [Offset.dx] swipes left (revealing items to the right).…xt for all four directions
Contributor
Author
|
Hello @dkwingsmt, Applied, thanks. Reads much cleaner with the Offset refs. |
dkwingsmt
approved these changes
Jun 10, 2026
AbdeMohlbi
approved these changes
Jun 10, 2026
Contributor
|
autosubmit label was removed for flutter/flutter/186943, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR. |
auto-submit Bot
pushed a commit
to flutter/packages
that referenced
this pull request
Jun 11, 2026
flutter/flutter@c0a1129...8bdce07 2026-06-11 bernaferrari2@gmail.com Make shape border lerp symmetric (flutter/flutter#187282) 2026-06-11 matt.kosarek@canonical.com Sized to content for regular and dialog windows on win32 (flutter/flutter#186829) 2026-06-11 jason-simmons@users.noreply.github.com Ensure that directory names are typed as strings in the CIPD package YAML file generated by merge_and_upload_debug_symbols.py (flutter/flutter#187813) 2026-06-11 stuartmorgan@google.com Add core-packages to ecosystem triage (flutter/flutter#187796) 2026-06-11 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from 8azSyvz57mKcPqTwk... to 2KosSR4ONUjIB7tP_... (flutter/flutter#187842) 2026-06-11 ishaquehassan@gmail.com Document moveStep direction on WidgetController.dragUntilVisible (flutter/flutter#186943) 2026-06-11 ahmedsameha1@gmail.com Add more 0x0 size tests part 11 (flutter/flutter#186822) 2026-06-10 kumarshivam72@gmail.com Fix ShapeDecoration.lerp crash when interpolating between gradient and color (flutter/flutter#187368) 2026-06-10 codedoctor@linwood.dev Reland "Add support for stylus buttons" (flutter/flutter#187629) 2026-06-10 tanyabouman@gmail.com Api docs: typo fix in Navigator (flutter/flutter#187572) 2026-06-10 engine-flutter-autoroll@skia.org Roll Packages from bd297cf to 1b56cde (4 revisions) (flutter/flutter#187784) 2026-06-10 116356835+AbdeMohlbi@users.noreply.github.com Improve docs on MediaQuery: highContrast, invertColors and disableAnimations (flutter/flutter#186614) 2026-06-10 matt.boetger@gmail.com [Android] Test to verify AnnounceSemanticsEvent deprecation warning on API 36 (flutter/flutter#187754) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC louisehsu@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
via-guy
pushed a commit
to via-guy/flutter
that referenced
this pull request
Jun 26, 2026
…tter#186943) Fixes flutter#89332. ## Description `WidgetController.dragUntilVisible` takes a `moveStep` offset but its dartdoc says nothing about which direction the offset moves the finger. People keep getting the sign wrong because the convention here is the opposite of `scrollUntilVisible`: to reveal content below the viewport you pass a negative `dy` to drag (the finger swipes up) but a positive `dy` to scroll. The linked issue collects a few reports of this. This PR adds a short paragraph to the dartdoc spelling out the touch-input sign convention: negative `dy` swipes up (revealing items below), positive `dy` swipes down, positive `dx` swipes right, negative `dx` swipes left. No behaviour changes, only doc text. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. This PR is test-exempt: it only edits a dartdoc comment, no code behaviour changes. - [x] All existing and new tests are passing. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md --------- Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #89332.
Description
WidgetController.dragUntilVisibletakes amoveStepoffset but its dartdoc says nothing about which direction the offset moves the finger. People keep getting the sign wrong because the convention here is the opposite ofscrollUntilVisible: to reveal content below the viewport you pass a negativedyto drag (the finger swipes up) but a positivedyto scroll. The linked issue collects a few reports of this.This PR adds a short paragraph to the dartdoc spelling out the touch-input sign convention: negative
dyswipes up (revealing items below), positivedyswipes down, positivedxswipes right, negativedxswipes left. No behaviour changes, only doc text.Pre-launch Checklist
///).