Unverified Commit e65c37ee authored by Ian Hickson's avatar Ian Hickson Committed by GitHub

More PageStorage clarity in the documentation (#131954)

Fixes https://github.com/flutter/flutter/issues/10867
parent b29069ec
...@@ -184,9 +184,9 @@ class ExpansionTileController { ...@@ -184,9 +184,9 @@ class ExpansionTileController {
/// A single-line [ListTile] with an expansion arrow icon that expands or collapses /// A single-line [ListTile] with an expansion arrow icon that expands or collapses
/// the tile to reveal or hide the [children]. /// the tile to reveal or hide the [children].
/// ///
/// This widget is typically used with [ListView] to create an /// This widget is typically used with [ListView] to create an "expand /
/// "expand / collapse" list entry. When used with scrolling widgets like /// collapse" list entry. When used with scrolling widgets like [ListView], a
/// [ListView], a unique [PageStorageKey] must be specified to enable the /// unique [PageStorageKey] must be specified as the [key], to enable the
/// [ExpansionTile] to save and restore its expanded state when it is scrolled /// [ExpansionTile] to save and restore its expanded state when it is scrolled
/// in and out of view. /// in and out of view.
/// ///
......
...@@ -28,6 +28,9 @@ import 'theme.dart'; ...@@ -28,6 +28,9 @@ import 'theme.dart';
/// Data is read lazily from a [DataTableSource]. The widget is presented /// Data is read lazily from a [DataTableSource]. The widget is presented
/// as a [Card]. /// as a [Card].
/// ///
/// If the [key] is a [PageStorageKey], the [initialFirstRowIndex] is persisted
/// to [PageStorage].
///
/// See also: /// See also:
/// ///
/// * [DataTable], which is not paginated. /// * [DataTable], which is not paginated.
......
...@@ -9,17 +9,19 @@ import 'framework.dart'; ...@@ -9,17 +9,19 @@ import 'framework.dart';
// Examples can assume: // Examples can assume:
// late BuildContext context; // late BuildContext context;
/// A key can be used to persist the widget state in storage after /// A [Key] that can be used to persist the widget state in storage after the
/// the destruction and will be restored when recreated. /// destruction and will be restored when recreated.
/// ///
/// Each key with its value plus the ancestor chain of other PageStorageKeys need to /// Each key with its value plus the ancestor chain of other [PageStorageKey]s
/// be unique within the widget's closest ancestor [PageStorage]. To make it possible for a /// need to be unique within the widget's closest ancestor [PageStorage]. To
/// saved value to be found when a widget is recreated, the key's value must /// make it possible for a saved value to be found when a widget is recreated,
/// not be objects whose identity will change each time the widget is created. /// the key's value must not be objects whose identity will change each time the
/// widget is created.
/// ///
/// See also: /// See also:
/// ///
/// * [PageStorage], which is the closet ancestor for [PageStorageKey]. /// * [PageStorage], which manages the data storage for widgets using
/// [PageStorageKey]s.
class PageStorageKey<T> extends ValueKey<T> { class PageStorageKey<T> extends ValueKey<T> {
/// Creates a [ValueKey] that defines where [PageStorage] values will be saved. /// Creates a [ValueKey] that defines where [PageStorage] values will be saved.
const PageStorageKey(super.value); const PageStorageKey(super.value);
...@@ -136,12 +138,12 @@ class PageStorageBucket { ...@@ -136,12 +138,12 @@ class PageStorageBucket {
/// included in routes. /// included in routes.
/// ///
/// [PageStorageKey] is used by [Scrollable] if [ScrollController.keepScrollOffset] /// [PageStorageKey] is used by [Scrollable] if [ScrollController.keepScrollOffset]
/// is enabled to save their [ScrollPosition]s. When more than one /// is enabled to save their [ScrollPosition]s. When more than one scrollable
/// scrollable ([ListView], [SingleChildScrollView], [TextField], etc.) appears /// ([ListView], [SingleChildScrollView], [TextField], etc.) appears within the
/// within the widget's closest ancestor [PageStorage] (such as within the same route), /// widget's closest ancestor [PageStorage] (such as within the same route), to
/// if you want to save all of their positions independently, /// save all of their positions independently, one must give each of them unique
/// you should give each of them unique [PageStorageKey]s, or set some of their /// [PageStorageKey]s, or set the `keepScrollOffset` property of some such
/// `keepScrollOffset` false to prevent saving. /// widgets to false to prevent saving.
/// ///
/// {@tool dartpad} /// {@tool dartpad}
/// This sample shows how to explicitly use a [PageStorage] to /// This sample shows how to explicitly use a [PageStorage] to
......
...@@ -612,6 +612,14 @@ const PageScrollPhysics _kPagePhysics = PageScrollPhysics(); ...@@ -612,6 +612,14 @@ const PageScrollPhysics _kPagePhysics = PageScrollPhysics();
/// ** See code in examples/api/lib/widgets/page_view/page_view.0.dart ** /// ** See code in examples/api/lib/widgets/page_view/page_view.0.dart **
/// {@end-tool} /// {@end-tool}
/// ///
/// ## Persisting the scroll position during a session
///
/// Scroll views attempt to persist their scroll position using [PageStorage].
/// For a [PageView], this can be disabled by setting [PageController.keepPage]
/// to false on the [controller]. If it is enabled, using a [PageStorageKey] for
/// the [key] of this widget is recommended to help disambiguate different
/// scroll views from each other.
///
/// See also: /// See also:
/// ///
/// * [PageController], which controls which page is visible in the view. /// * [PageController], which controls which page is visible in the view.
......
...@@ -178,8 +178,6 @@ enum ScrollPositionAlignmentPolicy { ...@@ -178,8 +178,6 @@ enum ScrollPositionAlignmentPolicy {
abstract class ScrollPosition extends ViewportOffset with ScrollMetrics { abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
/// Creates an object that determines which portion of the content is visible /// Creates an object that determines which portion of the content is visible
/// in a scroll view. /// in a scroll view.
///
/// The [physics], [context], and [keepScrollOffset] parameters must not be null.
ScrollPosition({ ScrollPosition({
required this.physics, required this.physics,
required this.context, required this.context,
......
...@@ -61,6 +61,16 @@ enum ScrollViewKeyboardDismissBehavior { ...@@ -61,6 +61,16 @@ enum ScrollViewKeyboardDismissBehavior {
/// To control the initial scroll offset of the scroll view, provide a /// To control the initial scroll offset of the scroll view, provide a
/// [controller] with its [ScrollController.initialScrollOffset] property set. /// [controller] with its [ScrollController.initialScrollOffset] property set.
/// ///
/// {@template flutter.widgets.ScrollView.PageStorage}
/// ## Persisting the scroll position during a session
///
/// Scroll views attempt to persist their scroll position using [PageStorage].
/// This can be disabled by setting [ScrollController.keepScrollOffset] to false
/// on the [controller]. If it is enabled, using a [PageStorageKey] for the
/// [key] of this widget is recommended to help disambiguate different scroll
/// views from each other.
/// {@endtemplate}
///
/// See also: /// See also:
/// ///
/// * [ListView], which is a commonly used [ScrollView] that displays a /// * [ListView], which is a commonly used [ScrollView] that displays a
...@@ -619,6 +629,8 @@ abstract class ScrollView extends StatelessWidget { ...@@ -619,6 +629,8 @@ abstract class ScrollView extends StatelessWidget {
/// parameter `semanticChildCount`. This should always be the same as the /// parameter `semanticChildCount`. This should always be the same as the
/// number of widgets wrapped in [IndexedSemantics]. /// number of widgets wrapped in [IndexedSemantics].
/// ///
/// {@macro flutter.widgets.ScrollView.PageStorage}
///
/// See also: /// See also:
/// ///
/// * [SliverList], which is a sliver that displays linear list of children. /// * [SliverList], which is a sliver that displays linear list of children.
...@@ -1165,6 +1177,8 @@ abstract class BoxScrollView extends ScrollView { ...@@ -1165,6 +1177,8 @@ abstract class BoxScrollView extends ScrollView {
/// ///
/// {@macro flutter.widgets.BoxScroll.scrollBehaviour} /// {@macro flutter.widgets.BoxScroll.scrollBehaviour}
/// ///
/// {@macro flutter.widgets.ScrollView.PageStorage}
///
/// See also: /// See also:
/// ///
/// * [SingleChildScrollView], which is a scrollable widget that has a single /// * [SingleChildScrollView], which is a scrollable widget that has a single
...@@ -1810,6 +1824,8 @@ class ListView extends BoxScrollView { ...@@ -1810,6 +1824,8 @@ class ListView extends BoxScrollView {
/// ** See code in examples/api/lib/widgets/scroll_view/list_view.0.dart ** /// ** See code in examples/api/lib/widgets/scroll_view/list_view.0.dart **
/// {@end-tool} /// {@end-tool}
/// ///
/// {@macro flutter.widgets.ScrollView.PageStorage}
///
/// See also: /// See also:
/// ///
/// * [SingleChildScrollView], which is a scrollable widget that has a single /// * [SingleChildScrollView], which is a scrollable widget that has a single
......
...@@ -72,6 +72,14 @@ typedef TwoDimensionalViewportBuilder = Widget Function(BuildContext context, Vi ...@@ -72,6 +72,14 @@ typedef TwoDimensionalViewportBuilder = Widget Function(BuildContext context, Vi
/// [PageController], which creates a page-oriented scroll position subclass /// [PageController], which creates a page-oriented scroll position subclass
/// that keeps the same page visible when the [Scrollable] resizes. /// that keeps the same page visible when the [Scrollable] resizes.
/// ///
/// ## Persisting the scroll position during a session
///
/// Scrollables attempt to persist their scroll position using [PageStorage].
/// This can be disabled by setting [ScrollController.keepScrollOffset] to false
/// on the [controller]. If it is enabled, using a [PageStorageKey] for the
/// [key] of this widget (or one of its ancestors, e.g. a [ScrollView]) is
/// recommended to help disambiguate different [Scrollable]s from each other.
///
/// See also: /// See also:
/// ///
/// * [ListView], which is a commonly used [ScrollView] that displays a /// * [ListView], which is a commonly used [ScrollView] that displays a
......
...@@ -130,6 +130,8 @@ import 'scrollable.dart'; ...@@ -130,6 +130,8 @@ import 'scrollable.dart';
/// ** See code in examples/api/lib/widgets/single_child_scroll_view/single_child_scroll_view.1.dart ** /// ** See code in examples/api/lib/widgets/single_child_scroll_view/single_child_scroll_view.1.dart **
/// {@end-tool} /// {@end-tool}
/// ///
/// {@macro flutter.widgets.ScrollView.PageStorage}
///
/// See also: /// See also:
/// ///
/// * [ListView], which handles multiple children in a scrolling list. /// * [ListView], which handles multiple children in a scrolling list.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment