development/flutter
development/flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter synced 2024-10-13 03:32:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation for scrollUntilVisible and friends. (#81497)

Browse source
This commit is contained in:
Ian Hickson 2021-05-01 18:29:03 -07:00 committed by GitHub
parent 2b8556b6ac
commit ec91c6582b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
packages/flutter_test/lib/src/controller.dart
View file

@ -1096,36 +1096,42 @@ abstract class WidgetController {
/// Given a widget `W` specified by [finder] and a [Scrollable] widget `S` in /// Given a widget `W` specified by [finder] and a [Scrollable] widget `S` in
/// its ancestry tree, this scrolls `S` so as to make `W` visible. /// its ancestry tree, this scrolls `S` so as to make `W` visible.
/// ///
/// Usually the `finder` for this method should be labeled /// Usually the `finder` for this method should be labeled `skipOffstage:
/// `skipOffstage: false`, so that [Finder] deals with widgets that's out of /// false`, so that the [Finder] deals with widgets that are off the screen
/// the screen correctly. /// correctly.
/// ///
/// This does not work when the `S` is long and `W` far away from the /// This does not work when `S` is long enough, and `W` far away enough from
/// displayed part does not have a cached element yet. See /// the displayed part of `S`, that `S` has not yet cached `W`'s element.
/// https://github.com/flutter/flutter/issues/61458 /// Consider using [scrollUntilVisible] in such a situation.
/// ///
/// Shorthand for `Scrollable.ensureVisible(element(finder))` /// See also:
///
/// * [Scrollable.ensureVisible], which is the production API used to
/// implement this method.
Future<void> ensureVisible(Finder finder) => Scrollable.ensureVisible(element(finder)); Future<void> ensureVisible(Finder finder) => Scrollable.ensureVisible(element(finder));
/// Repeatedly scrolls a [Scrollable] by `delta` in the /// Repeatedly scrolls a [Scrollable] by `delta` in the
/// [Scrollable.axisDirection] until `finder` is visible. /// [Scrollable.axisDirection] direction until a widget matching `finder` is
/// visible.
/// ///
/// Between each scroll, wait for `duration` time for settling. /// Between each scroll, advances the clock by `duration` time.
/// ///
/// If `scrollable` is `null`, this will find a [Scrollable]. /// Scrolling is performed until the start of the `finder` is visible. This is
/// due to the default parameter values of the [Scrollable.ensureVisible] method.
/// ///
/// Throws a [StateError] if `finder` is not found for maximum `maxScrolls` /// If `scrollable` is `null`, a [Finder] that looks for a [Scrollable] is
/// times. /// used instead.
///
/// Throws a [StateError] if `finder` is not found after `maxScrolls` scrolls.
/// ///
/// This is different from [ensureVisible] in that this allows looking for /// This is different from [ensureVisible] in that this allows looking for
/// `finder` that is not built yet, but the caller must specify the scrollable /// `finder` that is not yet built. The caller must specify the scrollable
/// that will build child specified by `finder` when there are multiple /// that will build child specified by `finder` when there are multiple
///[Scrollable]s. /// [Scrollable]s.
/// ///
/// Scroll is performed until the start of the `finder` is visible. This is /// See also:
/// due to the default parameter values of [Scrollable.ensureVisible] method.
/// ///
/// See also [dragUntilVisible]. /// * [dragUntilVisible], which implements the body of this method.
Future<void> scrollUntilVisible( Future<void> scrollUntilVisible(
Finder finder, Finder finder,
double delta, { double delta, {
@ -1157,16 +1163,22 @@ abstract class WidgetController {
scrollable, scrollable,
moveStep, moveStep,
maxIteration: maxScrolls, maxIteration: maxScrolls,
duration: duration); duration: duration,
);
}); });
} }
/// Repeatedly drags the `view` by `moveStep` until `finder` is visible. /// Repeatedly drags `view` by `moveStep` until `finder` is visible.
/// ///
/// Between each operation, wait for `duration` time for settling. /// Between each drag, advances the clock by `duration`.
/// ///
/// Throws a [StateError] if `finder` is not found for maximum `maxIteration` /// Throws a [StateError] if `finder` is not found after `maxIteration`
/// times. /// drags.
///
/// See also:
///
/// * [scrollUntilVisible], which wraps this method with an API that is more
/// convenient when dealing with a [Scrollable].
Future<void> dragUntilVisible( Future<void> dragUntilVisible(
Finder finder, Finder finder,
Finder view, Finder view,
@ -1175,10 +1187,10 @@ abstract class WidgetController {
Duration duration = const Duration(milliseconds: 50), Duration duration = const Duration(milliseconds: 50),
}) { }) {
return TestAsyncUtils.guard<void>(() async { return TestAsyncUtils.guard<void>(() async {
while(maxIteration > 0 && finder.evaluate().isEmpty) { while (maxIteration > 0 && finder.evaluate().isEmpty) {
await drag(view, moveStep); await drag(view, moveStep);
await pump(duration); await pump(duration);
maxIteration-= 1; maxIteration -= 1;
} }
await Scrollable.ensureVisible(element(finder)); await Scrollable.ensureVisible(element(finder));
}); });