github/flutter
7
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2025-06-03 00:51:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Much work on the documentation (#10331)

Browse Source 
Minor fixes throughout, e.g. removing trailing commas from the end of sample code expressions, changing headings to "sample code" more consistently, removing stale todos, fix typos in a private method name, minor grammar fixes, added some clarifications to CircularProgressIndicator, LinearProgressIndicator, CrossAxisAlignment, added some cross-references to various members, made it slightly clearer that layout algorithms are implementation details.

Clarified "elevation" throughout.

Added docs to InkResponse and InkWell.

Added sample code for: SliverAppBar, Card, ListTile, EdgeInsets, Row, Column, CustomScrollView, ListView, SliverFixedExtentList, and SliverGrid.

Fixes #10317.
Fixes #10316.
Fixes #10267. (sort of, see comment therein)
Fixes #9331. (sort of, see comment therein)
Fixes #9407. (sort of, see comment therein)
This commit is contained in:
Ian Hickson 2017-05-26 17:15:09 -07:00 committed by GitHub
parent 4743a806cb
commit f50caddfbd
31 changed files with 510 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
examples/flutter_gallery/lib/demo/material/cards_demo.dart
View File

@ -110,7 +110,6 @@ class TravelDestinationItem extends StatelessWidget {
),
),
// share, explore buttons
// TODO(abarth): The theme and the bar should be part of card.
new ButtonTheme.bar(
child: new ButtonBar(
alignment: MainAxisAlignment.start,

2
packages/flutter/lib/src/animation/tween.dart
View File

@ -90,7 +90,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
/// which results in two [Animation] separate objects, each configured with a
/// single [Tween].
///
/// ## Sample usage
/// ## Sample code
///
/// Suppose `_controller` is an [AnimationController], and we want to create an
/// [Animation<Offset>] that is controlled by that controller, and save it in

2
packages/flutter/lib/src/cupertino/slider.dart
View File

@ -85,7 +85,7 @@ class CupertinoSlider extends StatefulWidget {
/// _duelCommandment = newValue.round();
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<double> onChanged;

2
packages/flutter/lib/src/cupertino/switch.dart
View File

@ -57,7 +57,7 @@ class CupertinoSwitch extends StatefulWidget {
/// _giveVerse = newValue;
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<bool> onChanged;

26
packages/flutter/lib/src/material/app_bar.dart
View File

@ -269,7 +269,8 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
/// * [PreferredSize], which can be used to give an arbitrary widget a preferred size.
final PreferredSizeWidget bottom;
/// The z-coordinate at which to place this app bar.
/// The z-coordinate at which to place this app bar. This controls the size of
/// the shadow below the app bar.
///
/// Defaults to 4, the appropriate elevation for app bars.
final double elevation;
@ -694,6 +695,27 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
/// [actions], above the [bottom] (if any). If a [flexibleSpace] widget is
/// specified then it is stacked behind the toolbar and the bottom widget.
///
/// ## Sample code
///
/// This is an example that could be included in a [CustomScrollView]'s
/// [CustomScrollView.slivers] list:
///
/// ```dart
/// new SliverAppBar(
/// expandedHeight: 150.0,
/// flexibleSpace: const FlexibleSpaceBar(
/// title: const Text('Available seats'),
/// ),
/// actions: <Widget>[
/// new IconButton(
/// icon: const Icon(Icons.add_circle),
/// tooltip: 'Add new entry',
/// onPressed: () { /* ... */ },
/// ),
/// ]
/// )
/// ```
///
/// See also:
///
/// * [CustomScrollView], which integrates the [SliverAppBar] into its
@ -800,7 +822,7 @@ class SliverAppBar extends StatefulWidget {
final PreferredSizeWidget bottom;
/// The z-coordinate at which to place this app bar when it is above other
/// content.
/// content. This controls the size of the shadow below the app bar.
///
/// Defaults to 4, the appropriate elevation for app bars.
///

17
packages/flutter/lib/src/material/button.dart
View File

@ -195,14 +195,27 @@ class MaterialButton extends StatefulWidget {
/// Defaults to the highlight color from the [Theme].
final Color highlightColor;
/// The z-coordinate at which to place this button.
/// The z-coordinate at which to place this button. This controls the size of
/// the shadow below the button.
///
/// Defaults to 0.
///
/// See also:
///
/// * [FlatButton], a material button specialized for the case where the
/// elevation is zero.
/// * [RaisedButton], a material button specialized for the case where the
/// elevation is non-zero.
final double elevation;
/// The z-coordinate at which to place this button when highlighted.
/// The z-coordinate at which to place this button when highlighted. This
/// controls the size of the shadow below the button.
///
/// Defaults to 0.
///
/// See also:
///
/// * [elevation], the default elevation.
final double highlightElevation;
/// The smallest horizontal extent that the button will occupy.

47
packages/flutter/lib/src/material/card.dart
View File

@ -11,11 +11,51 @@ import 'material.dart';
/// A card is a sheet of [Material] used to represent some related information,
/// for example an album, a geographical location, a meal, contact details, etc.
///
/// ## Sample code
///
/// Here is an example of using a [Card] widget.
///
/// ```dart
/// new Card(
/// child: new Column(
/// mainAxisSize: MainAxisSize.min,
/// children: <Widget>[
/// const ListTile(
/// leading: const Icon(Icons.album),
/// title: const Text('The Enchanted Nightingale'),
/// subtitle: const Text('Music by Julie Gable. Lyrics by Sidney Stein.'),
/// ),
/// new ButtonTheme.bar( // make buttons use the appropriate styles for cards
/// child: new ButtonBar(
/// children: <Widget>[
/// new FlatButton(
/// child: const Text('BUY TICKETS'),
/// onPressed: () { /* ... */ },
/// ),
/// new FlatButton(
/// child: const Text('LISTEN'),
/// onPressed: () { /* ... */ },
/// ),
/// ],
/// ),
/// ),
/// ],
/// ),
/// )
/// ```
///
/// This is what it would look like:
///
/// ![A card with a slight shadow, consisting of two rows, one with an icon and
/// some text describing a musical, and the other with buttons for buying
/// tickets or listening to the show.]
/// (https://flutter.github.io/assets-for-api-docs/material/card.png)
///
/// See also:
///
/// * [ListTile], to display icons and text in a card.
/// * [ButtonBar], to display buttons at the bottom of a card. Typically these
/// would be styled using a ButtonTheme created with [new ButtonTheme.bar].
/// would be styled using a [ButtonTheme] created with [new ButtonTheme.bar].
/// * [showDialog], to display a modal card.
/// * <https://material.google.com/components/cards.html>
class Card extends StatelessWidget {
@ -24,7 +64,7 @@ class Card extends StatelessWidget {
Key key,
this.color,
this.elevation: 2.0,
this.child
this.child,
}) : super(key: key);
/// The widget below this widget in the tree.
@ -33,7 +73,8 @@ class Card extends StatelessWidget {
/// The color of material used for this card.
final Color color;
/// The z-coordinate at which to place this card.
/// The z-coordinate at which to place this card. This controls the size of
/// the shadow below the card.
///
/// Defaults to 2, the appropriate elevation for cards.
final double elevation;

2
packages/flutter/lib/src/material/checkbox.dart
View File

@ -80,7 +80,7 @@ class Checkbox extends StatefulWidget {
/// _throwShotAway = newValue;
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<bool> onChanged;

2
packages/flutter/lib/src/material/checkbox_list_tile.dart
View File

@ -118,7 +118,7 @@ class CheckboxListTile extends StatelessWidget {
/// });
/// },
/// title: new Text('Throw away your shot'),
/// ),
/// )
/// ```
final ValueChanged<bool> onChanged;

3
packages/flutter/lib/src/material/drawer.dart
View File

@ -72,7 +72,8 @@ class Drawer extends StatelessWidget {
this.child
}) : super(key: key);
/// The z-coordinate at which to place this drawer.
/// The z-coordinate at which to place this drawer. This controls the size of
/// the shadow below the drawer.
///
/// Defaults to 16, the appropriate elevation for drawers.
final double elevation;

11
packages/flutter/lib/src/material/floating_action_button.dart
View File

@ -76,15 +76,22 @@ class FloatingActionButton extends StatefulWidget {
/// If this is set to null, the button will be disabled.
final VoidCallback onPressed;
/// The z-coordinate at which to place this button.
/// The z-coordinate at which to place this button. This controls the size of
/// the shadow below the floating action button.
///
/// Defaults to 6, the appropriate elevation for floating action buttons.
final double elevation;
/// The z-coordinate at which to place this button when the user is touching the button.
/// The z-coordinate at which to place this button when the user is touching
/// the button. This controls the size of the shadow below the floating action
/// button.
///
/// Defaults to 12, the appropriate elevation for floating action buttons
/// while they are being touched.
///
/// See also:
///
/// * [elevation], the default elevation.
final double highlightElevation;
/// Controls the size of this button.

4
packages/flutter/lib/src/material/ink_splash.dart
View File

@ -29,12 +29,12 @@ RectCallback _getClipCallback(RenderBox referenceBox, bool containedInkWell, Rec
double _getTargetRadius(RenderBox referenceBox, bool containedInkWell, RectCallback rectCallback, Offset position) {
if (containedInkWell) {
final Size size = rectCallback != null ? rectCallback().size : referenceBox.size;
return _getSplashRadiusForPoistionInSize(size, position);
return _getSplashRadiusForPositionInSize(size, position);
}
return Material.defaultSplashRadius;
}
double _getSplashRadiusForPoistionInSize(Size bounds, Offset position) {
double _getSplashRadiusForPositionInSize(Size bounds, Offset position) {
final double d1 = (position - bounds.topLeft(Offset.zero)).distance;
final double d2 = (position - bounds.topRight(Offset.zero)).distance;
final double d3 = (position - bounds.bottomLeft(Offset.zero)).distance;

27
packages/flutter/lib/src/material/ink_well.dart
View File

@ -21,6 +21,25 @@ import 'theme.dart';
/// For a variant of this widget that is specialized for rectangular areas that
/// always clip splashes, see [InkWell].
///
/// The following two diagrams show how [InkResponse] looks when tapped if the
/// [highlightShape] is [BoxShape.circle] (the default) and [containedInkWell]
/// is false (also the default). The first diagram shows how it looks if the
/// [InkResponse] is relatively large, the second shows how it looks if it is
/// small. The main thing to notice is that the splashes happily exceed the
/// bounds of the widget (because [containedInkWell] is false).
///
/// ![The highlight is a disc centered in the box, smaller than the child widget.]
/// (https://flutter.github.io/assets-for-api-docs/material/ink_response_large.png)
/// ![The highlight is a disc overflowing the box, centered on the child.]
/// (https://flutter.github.io/assets-for-api-docs/material/ink_response_small.png)
///
/// The following diagram shows the effect when the [InkResponse] has a
/// [highlightShape] of [BoxShape.rectangle] with [containedInkWell] set to
/// true. These are the values used by [InkWell].
///
/// ![The highlight is a rectangle the size of the box.]
/// (https://flutter.github.io/assets-for-api-docs/material/ink_well.png)
///
/// Must have an ancestor [Material] widget in which to cause ink reactions.
///
/// If a Widget uses this class directly, it should include the following line
@ -267,8 +286,16 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
/// A rectangular area of a [Material] that responds to touch.
///
/// For a variant of this widget that does not clip splashes, see [InkResponse].
///
/// Must have an ancestor [Material] widget in which to cause ink reactions.
///
/// The following diagram shows how an [InkWell] looks when tapped, when using
/// default values.
///
/// ![The highlight is a rectangle the size of the box.]
/// (https://flutter.github.io/assets-for-api-docs/material/ink_well.png)
///
/// If a Widget uses this class directly, it should include the following line
/// at the top of its build function to call [debugCheckHasMaterial]:
///

30
packages/flutter/lib/src/material/list_tile.dart
View File

@ -151,10 +151,38 @@ enum ListTileControlAffinity {
/// height based on their contents. If you are looking for a widget that allows
/// for arbitrary layout in a row, consider [Row].
///
/// List tiles are typically used in [ListView]s, [Drawer]s, and [Card]s.
/// List tiles are typically used in [ListView]s, or arranged in [Column]s in
/// [Drawer]s and [Card]s.
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// ## Sample code
///
/// Here is a simple tile with an icon and some text.
///
/// ```dart
/// new ListTile(
/// leading: const Icon(Icons.event_seat),
/// title: const Text('The seat for the narrator'),
/// )
/// ```
///
/// Tiles can be much more elaborate. Here is a tile which can be tapped, but
/// which is disabled when the `_act` variable is not 2. When the tile is
/// tapped, the whole row has an ink splash effect (see [InkWell]).
///
/// ```dart
/// int _act = 1;
/// // ...
/// new ListTile(
/// leading: const Icon(Icons.flight_land),
/// title: const Text('Trix\'s airplane'),
/// subtitle: _act != 2 ? const Text('The airplane is only in Act II.') : null,
/// enabled: _act == 2,
/// onTap: () { /* react to the tile being tapped */ }
/// )
/// ```
///
/// See also:
///
/// * [ListTileTheme], which defines visual properties for [ListTile]s.

9
packages/flutter/lib/src/material/material.dart
View File

@ -130,9 +130,14 @@ class Material extends StatefulWidget {
/// the shape is rectangular, and the default color.
final MaterialType type;
/// The z-coordinate at which to place this material.
/// The z-coordinate at which to place this material. This controls the size
/// of the shadow below the material.
///
/// Defaults to 0.
/// If this is non-zero, the contents of the card are clipped, because the
/// widget conceptually defines an independent printed piece of material.
///
/// Defaults to 0. Changing this value will cause the shadow to animate over
/// [kThemeChangeDuration].
final double elevation;
/// The color to paint the material.

5
packages/flutter/lib/src/material/popup_menu.dart
View File

@ -498,7 +498,10 @@ class PopupMenuButton<T> extends StatefulWidget {
/// used for accessibility.
final String tooltip;
/// The z-coordinate at which to place the menu when open.
/// The z-coordinate at which to place the menu when open. This controls the
/// size of the shadow below the menu.
///
/// Defaults to 8, the appropriate elevation for popup menus.
final double elevation;
/// Matches IconButton's 8 dps padding by default. In some cases, notably where

7
packages/flutter/lib/src/material/progress_indicator.dart
View File

@ -14,7 +14,7 @@ const double _kMinCircularProgressIndicatorSize = 36.0;
// TODO(hansmuller): implement the support for buffer indicator
/// A base class for material design progress indicators
/// A base class for material design progress indicators.
///
/// This widget cannot be instantiated directly. For a linear progress
/// indicator, see [LinearProgressIndicator]. For a circular progress indicator,
@ -112,7 +112,7 @@ class _LinearProgressIndicatorPainter extends CustomPainter {
}
}
/// A material design linear progress indicator.
/// A material design linear progress indicator, also known as a progress bar.
///
/// A widget that shows progress along a line. There are two kinds of linear
/// progress indicators:
@ -253,7 +253,8 @@ class _CircularProgressIndicatorPainter extends CustomPainter {
}
}
/// A material design circular progress indicator.
/// A material design circular progress indicator, which spins to indicate that
/// the application is busy.
///
/// A widget that shows progress along a circle. There are two kinds of circular
/// progress indicators:

2
packages/flutter/lib/src/material/radio.dart
View File

@ -89,7 +89,7 @@ class Radio<T> extends StatefulWidget {
/// _character = newValue;
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<T> onChanged;

4
packages/flutter/lib/src/material/radio_list_tile.dart
View File

@ -62,7 +62,7 @@ import 'theme.dart';
/// onChanged: (SingingCharacter value) { setState(() { _character = value; }); },
/// ),
/// ],
/// ),
/// )
/// ```
///
/// See also:
@ -136,7 +136,7 @@ class RadioListTile<T> extends StatelessWidget {
/// _character = newValue;
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<T> onChanged;

21
packages/flutter/lib/src/material/raised_button.dart
View File

@ -100,20 +100,35 @@ class RaisedButton extends StatelessWidget {
/// value.
final Color disabledColor;
/// The z-coordinate at which to place this button.
/// The z-coordinate at which to place this button. This controls the size of
/// the shadow below the raised button.
///
/// Defaults to 2, the appropriate elevation for raised buttons.
///
/// See also:
///
/// * [FlatButton], a button with no elevation.
final double elevation;
/// The z-coordinate at which to place this button when highlighted.
/// The z-coordinate at which to place this button when highlighted. This
/// controls the size of the shadow below the raised button.
///
/// Defaults to 8, the appropriate elevation for raised buttons while they are
/// being touched.
///
/// See also:
///
/// * [elevation], the default elevation.
final double highlightElevation;
/// The z-coordinate at which to place this button when disabled.
/// The z-coordinate at which to place this button when disabled. This
/// controls the size of the shadow below the raised button.
///
/// Defaults to 0, the appropriate elevation for disabled raised buttons.
///
/// See also:
///
/// * [elevation], the default elevation.
final double disabledElevation;
/// The theme brightness to use for this button.

2
packages/flutter/lib/src/material/slider.dart
View File

@ -103,7 +103,7 @@ class Slider extends StatefulWidget {
/// _duelCommandment = newValue.round();
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<double> onChanged;

2
packages/flutter/lib/src/material/switch.dart
View File

@ -80,7 +80,7 @@ class Switch extends StatefulWidget {
/// _giveVerse = newValue;
/// });
/// },
/// ),
/// )
/// ```
final ValueChanged<bool> onChanged;

2
packages/flutter/lib/src/material/switch_list_tile.dart
View File

@ -111,7 +111,7 @@ class SwitchListTile extends StatelessWidget {
/// });
/// },
/// title: new Text('Lights'),
/// ),
/// )
/// ```
final ValueChanged<bool> onChanged;

6
packages/flutter/lib/src/painting/box_painter.dart
View File

@ -213,7 +213,7 @@ enum BorderStyle {
/// ),
/// ),
/// child: new Text('Flutter in the sky', textAlign: TextAlign.center),
/// ),
/// )
/// ```
///
/// See also:
@ -366,7 +366,7 @@ class BorderSide {
/// style: const TextStyle(color: const Color(0xFF000000))
/// ),
/// ),
/// ),
/// )
/// ```
///
/// See also:
@ -809,7 +809,7 @@ abstract class Gradient {
/// tileMode: TileMode.repeated, // repeats the gradient over the canvas
/// ),
/// ),
/// ),
/// )
/// ```
///
/// See also:

45
packages/flutter/lib/src/painting/edge_insets.dart
View File

@ -21,16 +21,49 @@ enum Axis {
///
/// Typically used for an offset from each of the four sides of a box. For
/// example, the padding inside a box can be represented using this class.
///
/// ## Sample code
///
/// Here are some examples of how to create [EdgeInsets] instances:
///
/// ```dart
/// // typical 8-pixel margin on all sides
/// const EdgeInsets.all(8.0)
///
/// // 8-pixel margin above and below, no horizontal margins
/// const EdgeInsets.symmetric(vertical: 8.0)
///
/// // left-margin indent of 40 pixels
/// const EdgeInsets.only(left: 40.0)
/// ```
///
/// See also:
///
/// * [Padding], a widget that describes margins using [EdgeInsets].
@immutable
class EdgeInsets {
/// Creates insets from offsets from the left, top, right, and bottom.
const EdgeInsets.fromLTRB(this.left, this.top, this.right, this.bottom);
/// Creates insets where all the offsets are value.
///
/// ## Sample code
///
/// ```dart
/// // typical 8-pixel margin on all sides
/// const EdgeInsets.all(8.0)
/// ```
const EdgeInsets.all(double value)
: left = value, top = value, right = value, bottom = value;
/// Creates insets with only the given values non-zero.
///
/// ## Sample code
///
/// ```dart
/// // left-margin indent of 40 pixels
/// const EdgeInsets.only(left: 40.0)
/// ```
const EdgeInsets.only({
this.left: 0.0,
this.top: 0.0,
@ -39,11 +72,23 @@ class EdgeInsets {
});
/// Creates insets with symmetrical vertical and horizontal offsets.
///
/// ## Sample code
///
/// ```dart
/// // 8-pixel margin above and below, no horizontal margins
/// const EdgeInsets.symmetric(vertical: 8.0)
/// ```
const EdgeInsets.symmetric({ double vertical: 0.0,
double horizontal: 0.0 })
: left = horizontal, top = vertical, right = horizontal, bottom = vertical;
/// Creates insets that match the given window padding.
///
/// If you need the current system padding in the context of a widget,
/// consider using [MediaQuery.of] to obtain the current padding rather than
/// using the value from [ui.window], so that you get notified when it
/// changes.
EdgeInsets.fromWindowPadding(ui.WindowPadding padding, double devicePixelRatio)
: left = padding.left / devicePixelRatio,
top = padding.top / devicePixelRatio,

49
packages/flutter/lib/src/rendering/flex.dart
View File

@ -8,12 +8,23 @@ import 'box.dart';
import 'object.dart';
/// How the child is inscribed into the available space.
///
/// See also:
///
/// * [RenderFlex], the flex render object.
/// * [Column], [Row], and [Flex], the flex widgets.
/// * [Expanded], the widget equivalent of [tight].
/// * [Flexible], the widget equivalent of [loose].
enum FlexFit {
/// The child is forced to fill the available space.
///
/// The [Expanded] widget assigns this kind of [FlexFit] to its child.
tight,
/// The child can be at most as large as the available space (but is
/// allowed to be smaller).
///
/// The [Flexible] widget assigns this kind of [FlexFit] to its child.
loose,
}
@ -47,7 +58,13 @@ class FlexParentData extends ContainerBoxParentDataMixin<RenderBox> {
/// This value controls whether to maximize or minimize the amount of free
/// space, subject to the incoming layout constraints.
///
/// See [Row], [Column], [MainAxisAlignment], [Flexible].
/// See also:
///
/// * [Column], [Row], and [Flex], the flex widgets.
/// * [Expanded] and [Flexible], the widgets that controls a flex widgets'
/// children's flex.
/// * [RenderFlex], the flex render object.
/// * [MainAxisAlignment], which controls how the free space is distributed.
enum MainAxisSize {
/// Minimize the amount of free space along the main axis, subject to the
/// incoming layout constraints.
@ -67,6 +84,11 @@ enum MainAxisSize {
}
/// How the children should be placed along the main axis in a flex layout.
///
/// See also:
///
/// * [Column], [Row], and [Flex], the flex widgets.
/// * [RenderFlex], the flex render object.
enum MainAxisAlignment {
/// Place the children as close to the start of the main axis as possible.
start,
@ -90,20 +112,41 @@ enum MainAxisAlignment {
}
/// How the children should be placed along the cross axis in a flex layout.
///
/// See also:
///
/// * [Column], [Row], and [Flex], the flex widgets.
/// * [RenderFlex], the flex render object.
enum CrossAxisAlignment {
/// Place the children as close to the start of the cross axis as possible.
/// Place the children with their start edge aligned with the start side of
/// the cross axis.
///
/// For example, in a column (a flex with a vertical axis), this aligns the
/// left edge of the children along the left edge of the column.
start,
/// Place the children as close to the end of the cross axis as possible.
///
/// For example, in a column (a flex with a vertical axis), this aligns the
/// right edge of the children along the right edge of the column.
end,
/// Place the children as close to the middle of the cross axis as possible.
/// Place the children so that their centers align with the middle of the
/// cross axis.
///
/// This is the default cross-axis alignment.
center,
/// Require the children to fill the cross axis.
///
/// This causes the constraints passed to the children to be tight in the
/// cross axis.
stretch,
/// Place the children along the cross axis such that their baselines match.
///
/// If the main axis is vertical, then this value is treated like [start]
/// (since baselines are always horizontal).
baseline,
}

4
packages/flutter/lib/src/widgets/async.dart
View File

@ -325,7 +325,7 @@ typedef Widget AsyncWidgetBuilder<T>(BuildContext context, AsyncSnapshot<T> snap
/// default: throw "Unknown: ${snapshot.connectionState}";
/// }
/// },
/// ),
/// )
/// ```
class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// Creates a new [StreamBuilder] that builds itself based on the latest
@ -424,7 +424,7 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// return new Text('Result: ${snapshot.data}');
/// }
/// },
/// ),
/// )
/// ```
class FutureBuilder<T> extends StatefulWidget {
/// Creates a widget that builds itself based on the latest snapshot of

110
packages/flutter/lib/src/widgets/basic.dart
View File

@ -217,7 +217,7 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
/// ),
/// ),
/// ),
/// ),
/// )
/// ```
///
/// See also:
@ -285,7 +285,7 @@ class CustomPaint extends SingleChildRenderObjectWidget {
/// * [OverflowBox]
/// * [SizedOverflowBox]
///
/// ## Example
/// ## Sample code
///
/// For example, use a clip to show the top half of an [Image], you can use a
/// [ClipRect] combined with an [Align]:
@ -297,7 +297,7 @@ class CustomPaint extends SingleChildRenderObjectWidget {
/// heightFactor: 0.5,
/// child: new Image(...),
/// ),
/// ),
/// )
/// ```
///
/// See also:
@ -1096,7 +1096,8 @@ class ConstrainedBox extends SingleChildRenderObjectWidget {
}
/// A widget that sizes its child to a fraction of the total available space.
/// For more details about the layout algorithm, see [RenderFractionallySizedOverflowBox].
/// For more details about the layout algorithm, see
/// [RenderFractionallySizedOverflowBox].
///
/// See also:
///
@ -2023,6 +2024,8 @@ class Positioned extends ParentDataWidget<Stack> {
///
/// ## Layout algorithm
///
/// _This section describes how a [Flex] is rendered by the framework._
///
/// Layout for a [Flex] proceeds in six steps:
///
/// 1. Layout each child a null or zero flex factor (e.g., those that are not
@ -2055,6 +2058,14 @@ class Positioned extends ParentDataWidget<Stack> {
/// [mainAxisAlignment] is [MainAxisAlignment.spaceBetween], any main axis
/// space that has not been allocated to children is divided evenly and
/// placed between the children.
///
/// See also:
///
/// * [Row], for a version of this widget that is always horizontal.
/// * [Column], for a version of this widget that is always vertical.
/// * [Expanded], to indicate children that should take all the remaining room.
/// * [Flexible], to indicate children that should share the remaining room but
/// that may be sized smaller (leaving some remaining room unused).
class Flex extends MultiChildRenderObjectWidget {
/// Creates a flex layout.
///
@ -2152,8 +2163,35 @@ class Flex extends MultiChildRenderObjectWidget {
/// If you only have one child, then consider using [Align] or [Center] to
/// position the child.
///
/// ## Sample code
///
/// This example divides the available space into three (horizontally), and
/// places text centered in the first two cells and the Flutter logo centered in
/// the third:
///
/// ```dart
/// new Row(
/// children: <Widget>[
/// new Expanded(
/// child: new Text('Deliver features faster', textAlign: TextAlign.center),
/// ),
/// new Expanded(
/// child: new Text('Craft beautiful UIs', textAlign: TextAlign.center),
/// ),
/// new Expanded(
/// child: new FittedBox(
/// fit: BoxFit.contain, // otherwise the logo will be tiny
/// child: const FlutterLogo(),
/// ),
/// ),
/// ],
/// )
/// ```
///
/// ## Layout algorithm
///
/// _This section describes how a [Row] is rendered by the framework._
///
/// Layout for a [Row] proceeds in six steps:
///
/// 1. Layout each child a null or zero flex factor (e.g., those that are not
@ -2184,6 +2222,15 @@ class Flex extends MultiChildRenderObjectWidget {
/// [mainAxisAlignment] is [MainAxisAlignment.spaceBetween], any horizontal
/// space that has not been allocated to children is divided evenly and
/// placed between the children.
///
/// See also:
///
/// * [Column], for a vertical equivalent.
/// * [Flex], if you don't know in advance if you want a horizontal or vertical
/// arrangement.
/// * [Expanded], to indicate children that should take all the remaining room.
/// * [Flexible], to indicate children that should share the remaining room but
/// that may by sized smaller (leaving some remaining room unused).
class Row extends Flex {
/// Creates a horizontal array of children.
///
@ -2223,8 +2270,52 @@ class Row extends Flex {
/// If you only have one child, then consider using [Align] or [Center] to
/// position the child.
///
/// ## Sample code
///
/// This example uses a [Column] to arrange three widgets vertically, the last
/// being made to fill all the remaining space.
///
/// ```dart
/// new Column(
/// children: <Widget>[
/// new Text('Deliver features faster'),
/// new Text('Craft beautiful UIs'),
/// new Expanded(
/// child: new FittedBox(
/// fit: BoxFit.contain,
/// child: const FlutterLogo(),
/// ),
/// ),
/// ],
/// )
/// ```
///
/// In the sample above, the text and the logo are centered on each line. In the
/// following example, the [crossAxisAlignment] is set to
/// [CrossAxisAlignment.start], so that the children are left-aligned. The
/// [mainAxisSize] is set to [MainAxisSize.min], so that the column shrinks to
/// fit the children.
///
/// ```dart
/// new Column(
/// crossAxisAlignment: CrossAxisAlignment.start,
/// mainAxisSize: MainAxisSize.min,
/// children: <Widget>[
/// new Text('We move under cover and we move as one'),
/// new Text('Through the night, we have one shot to live another day'),
/// new Text('We cannot let a stray gunshot give us away'),
/// new Text('We will fight up close, seize the moment and stay in it'),
/// new Text('It’s either that or meet the business end of a bayonet'),
/// new Text('The code word is ‘Rochambeau,’ dig me?'),
/// new Text('Rochambeau!', style: DefaultTextStyle.of(context).style.apply(fontSizeFactor: 2.0)),
/// ],
/// )
/// ```
///
/// ## Layout algorithm
///
/// _This section describes how a [Column] is rendered by the framework._
///
/// Layout for a [Column] proceeds in six steps:
///
/// 1. Layout each child a null or zero flex factor (e.g., those that are not
@ -2257,6 +2348,15 @@ class Row extends Flex {
/// [mainAxisAlignment] is [MainAxisAlignment.spaceBetween], any vertical
/// space that has not been allocated to children is divided evenly and
/// placed between the children.
///
/// See also:
///
/// * [Row], for a horizontal equivalent.
/// * [Flex], if you don't know in advance if you want a horizontal or vertical
/// arrangement.
/// * [Expanded], to indicate children that should take all the remaining room.
/// * [Flexible], to indicate children that should share the remaining room but
/// that may size smaller (leaving some remaining room unused).
class Column extends Flex {
/// Creates a vertical array of children.
///
@ -2651,7 +2751,7 @@ class Flow extends MultiChildRenderObjectWidget {
/// new TextSpan(text: ' world!'),
/// ],
/// ),
/// ),
/// )
/// ```
///
/// See also:

2
packages/flutter/lib/src/widgets/container.dart
View File

@ -34,7 +34,7 @@ import 'image.dart';
/// stops: <double>[0.9, 1.0],
/// ),
/// ),
/// ),
/// )
/// ```
///
/// See also:

67
packages/flutter/lib/src/widgets/scroll_view.dart
View File

@ -235,6 +235,55 @@ abstract class ScrollView extends StatelessWidget {
/// list and a grid, use a list of three slivers: [SliverAppBar], [SliverList],
/// and [SliverGrid].
///
/// ## Sample code
///
/// This sample code shows a scroll view that contains a flexible pinned app
/// bar, a grid, and an infinite list.
///
/// ```dart
/// new CustomScrollView(
/// slivers: <Widget>[
/// const SliverAppBar(
/// pinned: true,
/// expandedHeight: 250.0,
/// flexibleSpace: const FlexibleSpaceBar(
/// title: const Text('Demo'),
/// ),
/// ),
/// new SliverGrid(
/// gridDelegate: new SliverGridDelegateWithMaxCrossAxisExtent(
/// maxCrossAxisExtent: 200.0,
/// mainAxisSpacing: 10.0,
/// crossAxisSpacing: 10.0,
/// childAspectRatio: 4.0,
/// ),
/// delegate: new SliverChildBuilderDelegate(
/// (BuildContext context, int index) {
/// return new Container(
/// alignment: FractionalOffset.center,
/// color: Colors.teal[100 * (index % 9)],
/// child: new Text('grid item $index'),
/// );
/// },
/// childCount: 20,
/// ),
/// ),
/// new SliverFixedExtentList(
/// itemExtent: 50.0,
/// delegate: new SliverChildBuilderDelegate(
/// (BuildContext context, int index) {
/// return new Container(
/// alignment: FractionalOffset.center,
/// color: Colors.lightBlue[100 * (index % 9)],
/// child: new Text('list item $index'),
/// );
/// },
/// ),
/// ),
/// ],
/// )
/// ```
///
/// See also:
///
/// * [SliverList], which is a sliver that displays linear list of children.
@ -329,7 +378,7 @@ abstract class BoxScrollView extends ScrollView {
}
}
/// A scrollable, linear list of widgets.
/// A scrollable list of widgets arranged linearly.
///
/// [ListView] is the most commonly used scrolling widget. It displays its
/// children one after another in the scroll direction. In the cross axis, the
@ -359,6 +408,20 @@ abstract class BoxScrollView extends ScrollView {
/// a [SliverChildDelegate] can control the algorithm used to estimate the
/// size of children that are not actually visible.
///
/// ## Sample code
///
/// An infinite list of children:
///
/// ```dart
/// new ListView.builder(
/// padding: new EdgeInsets.all(8.0),
/// itemExtent: 20.0,
/// itemBuilder: (BuildContext context, int index) {
/// return new Text('entry $index');
/// },
/// )
/// ```
///
/// See also:
///
/// * [SingleChildScrollView], which is a scrollable widget that has a single
@ -368,6 +431,8 @@ abstract class BoxScrollView extends ScrollView {
/// * [GridView], which is scrollable, 2D array of widgets.
/// * [CustomScrollView], which is a scrollable widget that creates custom
/// scroll effects using slivers.
/// * [ListBody], which arranges its children in a similar manner, but without
/// scrolling.
class ListView extends BoxScrollView {
/// Creates a scrollable, linear array of widgets from an explicit [List].
///

46
packages/flutter/lib/src/widgets/sliver.dart
View File

@ -334,6 +334,26 @@ class SliverList extends SliverMultiBoxAdaptorWidget {
/// [SliverFixedExtentList] does not need to perform layout on its children to
/// obtain their extent in the main axis.
///
/// ## Sample code
///
/// This example, which would be inserted into a [CustomScrollView.slivers]
/// list, shows an infinite number of items in varying shades of blue:
///
/// ```dart
/// new SliverFixedExtentList(
/// itemExtent: 50.0,
/// delegate: new SliverChildBuilderDelegate(
/// (BuildContext context, int index) {
/// return new Container(
/// alignment: FractionalOffset.center,
/// color: Colors.lightBlue[100 * (index % 9)],
/// child: new Text('list item $index'),
/// );
/// },
/// ),
/// )
/// ```
///
/// See also:
///
/// * [SliverPrototypeExtentList], which is similar to [SliverFixedExtentList]
@ -373,6 +393,32 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
/// [gridDelegate]. Each child is forced to have the size specified by the
/// [gridDelegate].
///
/// ## Sample code
///
/// This example, which would be inserted into a [CustomScrollView.slivers]
/// list, shows twenty boxes in a pretty teal grid:
///
/// ```dart
/// new SliverGrid(
/// gridDelegate: new SliverGridDelegateWithMaxCrossAxisExtent(
/// maxCrossAxisExtent: 200.0,
/// mainAxisSpacing: 10.0,
/// crossAxisSpacing: 10.0,
/// childAspectRatio: 4.0,
/// ),
/// delegate: new SliverChildBuilderDelegate(
/// (BuildContext context, int index) {
/// return new Container(
/// alignment: FractionalOffset.center,
/// color: Colors.teal[100 * (index % 9)],
/// child: new Text('grid item $index'),
/// );
/// },
/// childCount: 20,
/// ),
/// )
/// ```
///
/// See also:
///
/// * [SliverList], which places its children in a linear array.