Skip to content

Commit 0478162

Browse files
[material_ui] Document RefreshIndicator mouse behavior on desktop and web (flutter#13286)
Adds a "Refresh indicator does not respond to a mouse" section to the `RefreshIndicator` troubleshooting docs. It explains that: - Clicking and dragging with a mouse doesn't trigger the refresh indicator by default, because `ScrollBehavior.dragDevices` doesn't include `PointerDeviceKind.mouse`. - Mouse wheel scrolling never triggers it, because it isn't a drag gesture. - Touch screens trigger it on all platforms, and trackpads do in desktop apps. On the web, trackpad scrolling is handled like mouse wheel scrolling, so it doesn't. - To support mouse users, apps can add a refresh button or shortcut that calls `RefreshIndicatorState.show`, or add `PointerDeviceKind.mouse` to `ScrollBehavior.dragDevices` (with a code example and a note about the text-selection trade-off). This is a documentation-only change (test-exempt) with no behavior changes. It adds a pending changelog entry (`version: patch`). Fixes flutter#135510 %23%23 Pre-Review Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] page, which explains my responsibilities. - [x] I read and followed the [relevant style guides] and ran [the auto-formatter]. - [x] I signed the [CLA]. - [x] The title of the PR starts with the name of the package surrounded by square brackets, e.g. `[shared_preferences]` - [x] I [linked to at least one issue that this PR fixes] in the description above. - [x] I followed [the version and CHANGELOG instructions], using [semantic versioning] and the [repository CHANGELOG style], or I have commented below to indicate which documented exception this PR falls under[^1]. - [x] I updated/added any relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or I have commented below to indicate which [test exemption] this PR falls under[^1]. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the %23hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot 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. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. <!-- Links --> [Contributor Guide]: https://github.com/flutter/packages/blob/main/CONTRIBUTING.md [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md%23ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md [relevant style guides]: https://github.com/flutter/packages/blob/main/CONTRIBUTING.md%23style [the auto-formatter]: https://github.com/flutter/packages/blob/main/script/tool/README.md%23format-code [CLA]: https://cla.developers.google.com/ [Discord]: https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md [linked to at least one issue that this PR fixes]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md%23overview [the version and CHANGELOG instructions]: https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md%23version-and-changelog-updates [semantic versioning]: https://dart.dev/tools/pub/versioning%23semantic-versions [repository CHANGELOG style]: https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md%23changelog-style [test exemption]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md%23tests
1 parent 3dbab32 commit 0478162

2 files changed

Lines changed: 41 additions & 0 deletions

File tree

‎packages/material_ui/lib/src/refresh_indicator.dart‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
// Use of this source code is governed by a BSD-style license that can be
33
// found in the LICENSE file.
44

5+
/// @docImport 'package:flutter/gestures.dart';
6+
///
57
/// @docImport 'color_scheme.dart';
68
library;
79

@@ -143,6 +145,42 @@ enum _IndicatorType { material, adaptive, noSpinner }
143145
///
144146
/// A [RefreshIndicator] can only be used with a vertical scroll view.
145147
///
148+
/// ### Refresh indicator does not respond to a mouse
149+
///
150+
/// The refresh indicator is triggered by a drag gesture that overscrolls its
151+
/// scrollable descendant, and a scrollable only accepts drag gestures from
152+
/// the pointer devices in [ScrollBehavior.dragDevices]. By default,
153+
/// [ScrollBehavior.dragDevices] does not include [PointerDeviceKind.mouse], so
154+
/// on desktop and web, clicking and dragging with a mouse does not show the
155+
/// refresh indicator. Scrolling with a mouse wheel does not show it either,
156+
/// because mouse wheel scrolling is not a drag gesture.
157+
///
158+
/// Touch screens can trigger the refresh indicator on all platforms, and so
159+
/// can trackpads in desktop apps. On the web, trackpad scrolling is handled
160+
/// like mouse wheel scrolling, so it does not trigger the refresh indicator.
161+
///
162+
/// To let users refresh with a mouse, consider providing another way to
163+
/// refresh, such as a button or keyboard shortcut that calls
164+
/// [RefreshIndicatorState.show]. Alternatively, allow scrollables to be
165+
/// dragged with a mouse by adding [PointerDeviceKind.mouse] to
166+
/// [ScrollBehavior.dragDevices], for example, for the whole app:
167+
///
168+
/// ```dart
169+
/// MaterialApp(
170+
/// scrollBehavior: const MaterialScrollBehavior().copyWith(
171+
/// dragDevices: <PointerDeviceKind>{
172+
/// ...const MaterialScrollBehavior().dragDevices,
173+
/// PointerDeviceKind.mouse,
174+
/// },
175+
/// ),
176+
/// // ...
177+
/// )
178+
/// ```
179+
///
180+
/// Allowing a mouse to drag scrollables can make it difficult to select text
181+
/// inside them. To limit this to part of the app, wrap that part in a
182+
/// [ScrollConfiguration] instead.
183+
///
146184
/// See also:
147185
///
148186
/// * <https://material.io/design/platform-guidance/android-swipe-to-refresh.html>
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Documents why `RefreshIndicator` does not respond to a mouse on desktop and web, and how to support mouse input.
3+
version: patch

0 commit comments

Comments
 (0)