From 995fd27edd89299fe6e1a790fabc0fd5405213df Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Mon, 24 Oct 2016 11:06:26 -0700 Subject: [PATCH] More Block doc improvements (#6481) Mostly around pointing people towards Block more aggressively. --- packages/flutter/lib/src/material/list.dart | 10 +++++++--- .../flutter/lib/src/material/two_level_list.dart | 1 + packages/flutter/lib/src/widgets/basic.dart | 11 ++++++++++- packages/flutter/lib/src/widgets/lazy_block.dart | 6 +++++- packages/flutter/lib/src/widgets/scrollable.dart | 12 ++++++------ .../flutter/lib/src/widgets/scrollable_list.dart | 8 +++++--- 6 files changed, 34 insertions(+), 14 deletions(-) diff --git a/packages/flutter/lib/src/material/list.dart b/packages/flutter/lib/src/material/list.dart index 60cbd59636..d91d12616c 100644 --- a/packages/flutter/lib/src/material/list.dart +++ b/packages/flutter/lib/src/material/list.dart @@ -48,9 +48,13 @@ Map kListItemExtent = const /// /// See also: /// -/// * [ListItem] -/// * [ScrollableList] -/// * [TwoLevelList] +/// * [Block], which shows heterogeneous widgets in a list and makes the list +/// scrollable if necessary. +/// * [ListItem], to show content in a [MaterialList] using material design +/// conventions. +/// * [ScrollableList], on which this widget is based. +/// * [TwoLevelList], for lists that have subsections that can collapse and +/// expand. /// * [ScrollableGrid] /// * class MaterialList extends StatelessWidget { diff --git a/packages/flutter/lib/src/material/two_level_list.dart b/packages/flutter/lib/src/material/two_level_list.dart index 6318bee96f..c57dae6eb4 100644 --- a/packages/flutter/lib/src/material/two_level_list.dart +++ b/packages/flutter/lib/src/material/two_level_list.dart @@ -255,6 +255,7 @@ class _TwoLevelSublistState extends State with SingleTickerProv /// /// * [TwoLevelSublist] /// * [TwoLevelListItem] +/// * [MaterialList], for lists that only have one level. class TwoLevelList extends StatelessWidget { /// Creates a scrollable list of items that can expand and collapse. /// diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 617a5f1d90..9fb32f4322 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -1406,7 +1406,7 @@ class Viewport extends SingleChildRenderObjectWidget { /// /// See also: /// -/// * [Block] (which combines block layout with scrolling) +/// * [Block], which combines block layout with scrolling. class BlockBody extends MultiChildRenderObjectWidget { /// Creates a block layout widget. /// @@ -1951,6 +1951,13 @@ class Flex extends MultiChildRenderObjectWidget { /// /// For details about the flex layout algorithm, see [RenderFlex]. To control /// the flex of child widgets, see the [Flexible] widget. +/// +/// The Row widget does not scroll (and in general it is considered an error to +/// have more children in a Row than will fit in the available room). If you +/// have a line of widgets and want them to be able to scroll if there is +/// insufficient room, consider using a [Block]. +/// +/// For a vertical variant, see [Column]. class Row extends Flex { /// Creates a horizontal array of children. /// @@ -1984,6 +1991,8 @@ class Row extends Flex { /// to have more children in a Column than will fit in the available room). If /// you have a list of widgets and want them to be able to scroll if there is /// insufficient room, consider using a [Block]. +/// +/// For a horizontal variant, see [Row]. class Column extends Flex { /// Creates a vertical array of children. /// diff --git a/packages/flutter/lib/src/widgets/lazy_block.dart b/packages/flutter/lib/src/widgets/lazy_block.dart index b2bd3e9f17..36308b9887 100644 --- a/packages/flutter/lib/src/widgets/lazy_block.dart +++ b/packages/flutter/lib/src/widgets/lazy_block.dart @@ -191,9 +191,13 @@ class LazyBlockChildren extends LazyBlockDelegate { /// [scrollOffset] is expensive because [LazyBlock] computes the size of every /// child between the old scroll offset and the new scroll offset. /// -/// Prefer [ScrollableList] when all the children have the same size because +/// Prefer [ScrollableLazyList] when all the children have the same size because /// it can use that property to be more efficient. Prefer [ScrollableViewport] /// when there is only one child. +/// +/// Consider [Block] if you have a small number of children that will only +/// scroll in unusual circumstances (e.g. when the user's device is smaller than +/// expected). class LazyBlock extends StatelessWidget { /// Creates an infinite scrolling list of variable height children. /// diff --git a/packages/flutter/lib/src/widgets/scrollable.dart b/packages/flutter/lib/src/widgets/scrollable.dart index 97f0ea47aa..2fdbe713f7 100644 --- a/packages/flutter/lib/src/widgets/scrollable.dart +++ b/packages/flutter/lib/src/widgets/scrollable.dart @@ -61,14 +61,14 @@ typedef double SnapOffsetCallback(double scrollOffset, Size containerSize); /// A base class for scrollable widgets. /// +/// If you have a list of widgets and want them to be able to scroll if there is +/// insufficient room, consider using [Block]. +/// /// Commonly used classes that are based on Scrollable include [ScrollableList], /// [ScrollableGrid], and [ScrollableViewport]. /// /// Widgets that subclass [Scrollable] typically use state objects that subclass /// [ScrollableState]. -/// -/// If you have a list of widgets and want them to be able to scroll if there is -/// insufficient room, consider using [Block]. class Scrollable extends StatefulWidget { /// Initializes fields for subclasses. /// @@ -916,11 +916,11 @@ class ScrollNotification extends Notification { /// /// See also: /// +/// * [Block], if your single child is a [Column]. /// * [ScrollableList], if you have many identically-sized children. /// * [PageableList], if you have children that each take the entire screen. /// * [ScrollableGrid], if your children are in a grid pattern. /// * [LazyBlock], if you have many children of varying sizes. -/// * [Block], if your single child is a [BlockBody] or a [Column]. class ScrollableViewport extends StatelessWidget { /// Creates a simple scrolling widget that has a single child. /// @@ -1050,9 +1050,9 @@ class ScrollableViewport extends StatelessWidget { /// /// See also: /// -/// * [ScrollableViewport], if you only have one child. +/// * [LazyBlock], if you have many children with varying heights. /// * [ScrollableList], if all your children are the same height. -/// * [LazyBlock], if you have children with varying heights. +/// * [ScrollableViewport], if you only have one child. class Block extends StatelessWidget { /// Creates a scrollable array of children. Block({ diff --git a/packages/flutter/lib/src/widgets/scrollable_list.dart b/packages/flutter/lib/src/widgets/scrollable_list.dart index 5357cb8a1d..076a32e048 100644 --- a/packages/flutter/lib/src/widgets/scrollable_list.dart +++ b/packages/flutter/lib/src/widgets/scrollable_list.dart @@ -18,14 +18,16 @@ import 'virtual_viewport.dart'; /// uses an [Iterable] list of children. That makes [ScrollableList] suitable /// for a large (but not extremely large or infinite) list of children. /// -/// [ScrollableList] differs from [LazyBlock] in that [ScrollableList] requires -/// each of its children to be the same size. That makes [ScrollableList] more -/// efficient but less flexible than [LazyBlock]. +/// [ScrollableList] differs from [Block] and [LazyBlock] in that +/// [ScrollableList] requires each of its children to be the same size. That +/// makes [ScrollableList] more efficient but less flexible than [Block] and +/// [LazyBlock]. /// /// Prefer [ScrollableViewport] when there is only one child. /// /// See also: /// +/// * [Block]. /// * [ScrollableLazyList]. /// * [LazyBlock]. /// * [ScrollableViewport].