Commit c7469e00 authored by Ian Hickson's avatar Ian Hickson Committed by GitHub

Fix many dartdoc typos (#9822)

parent 07b1f7f7
...@@ -350,7 +350,7 @@ class AnimationController extends Animation<double> ...@@ -350,7 +350,7 @@ class AnimationController extends Animation<double>
/// ///
/// Defaults to repeating between the lower and upper bounds. /// Defaults to repeating between the lower and upper bounds.
/// ///
/// Returns a [TickerFuture] that never completes. The [TickerFuture.onCancel] future /// Returns a [TickerFuture] that never completes. The [TickerFuture.orCancel] future
/// completes with an error when the animation is stopped (e.g. with [stop]). /// completes with an error when the animation is stopped (e.g. with [stop]).
/// ///
/// The most recently returned [TickerFuture], if any, is marked as having been /// The most recently returned [TickerFuture], if any, is marked as having been
......
...@@ -280,7 +280,7 @@ abstract class BindingBase { ...@@ -280,7 +280,7 @@ abstract class BindingBase {
/// extension method is called. The callback must return a [Future] /// extension method is called. The callback must return a [Future]
/// that either eventually completes to a return value in the form /// that either eventually completes to a return value in the form
/// of a name/value map where the values can all be converted to /// of a name/value map where the values can all be converted to
/// JSON using [JSON.encode], or fails. In case of failure, the /// JSON using `JSON.encode()` (see [JsonCodec.encode]), or fails. In case of failure, the
/// failure is reported to the remote caller and is dumped to the /// failure is reported to the remote caller and is dumped to the
/// logs. /// logs.
/// ///
......
...@@ -125,7 +125,7 @@ class _PointAtTime { ...@@ -125,7 +125,7 @@ class _PointAtTime {
String toString() => '_PointAtTime($point at $time)'; String toString() => '_PointAtTime($point at $time)';
} }
/// Computes a pointer's velocity based on data from [PointerMove] events. /// Computes a pointer's velocity based on data from [PointerMoveEvent]s.
/// ///
/// The input data is provided by calling [addPosition]. Adding data is cheap. /// The input data is provided by calling [addPosition]. Adding data is cheap.
/// ///
......
...@@ -59,7 +59,7 @@ class BottomNavigationBarItem { ...@@ -59,7 +59,7 @@ class BottomNavigationBarItem {
/// The icon of the item. /// The icon of the item.
/// ///
/// Typically the icon is an [Icon] or an [IconImage] widget. If another type /// Typically the icon is an [Icon] or an [ImageIcon] widget. If another type
/// of widget is provided then it should configure itself to match the current /// of widget is provided then it should configure itself to match the current
/// [IconTheme] size and color. /// [IconTheme] size and color.
final Widget icon; final Widget icon;
......
...@@ -25,7 +25,7 @@ const Color _kBarrierColor = Colors.black54; ...@@ -25,7 +25,7 @@ const Color _kBarrierColor = Colors.black54;
/// supplements the primary content of the app. A persistent bottom sheet /// supplements the primary content of the app. A persistent bottom sheet
/// remains visible even when the user interacts with other parts of the app. /// remains visible even when the user interacts with other parts of the app.
/// Persistent bottom sheets can be created and displayed with the /// Persistent bottom sheets can be created and displayed with the
/// [Scaffold.showBottomSheet] function. /// [ScaffoldState.showBottomSheet] function.
/// ///
/// * _Modal_. A modal bottom sheet is an alternative to a menu or a dialog and /// * _Modal_. A modal bottom sheet is an alternative to a menu or a dialog and
/// prevents the user from interacting with the rest of the app. Modal bottom /// prevents the user from interacting with the rest of the app. Modal bottom
...@@ -45,7 +45,7 @@ class BottomSheet extends StatefulWidget { ...@@ -45,7 +45,7 @@ class BottomSheet extends StatefulWidget {
/// Creates a bottom sheet. /// Creates a bottom sheet.
/// ///
/// Typically, bottom sheets are created implicitly by /// Typically, bottom sheets are created implicitly by
/// [Scaffold.showBottomSheet], for persistent bottom sheets, or by /// [ScaffoldState.showBottomSheet], for persistent bottom sheets, or by
/// [showModalBottomSheet], for modal bottom sheets. /// [showModalBottomSheet], for modal bottom sheets.
const BottomSheet({ const BottomSheet({
Key key, Key key,
...@@ -253,10 +253,14 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> { ...@@ -253,10 +253,14 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
/// ///
/// See also: /// See also:
/// ///
/// * [BottomSheet] /// * [BottomSheet], which is the widget normally returned by the function
/// * [Scaffold.showBottomSheet] /// passed as the `builder` argument to [showModalBottomSheet].
/// * [ScaffoldState.showBottomSheet], for showing non-modal bottom sheets.
/// * <https://material.google.com/components/bottom-sheets.html#bottom-sheets-modal-bottom-sheets> /// * <https://material.google.com/components/bottom-sheets.html#bottom-sheets-modal-bottom-sheets>
Future<T> showModalBottomSheet<T>({ @required BuildContext context, @required WidgetBuilder builder }) { Future<T> showModalBottomSheet<T>({
@required BuildContext context,
@required WidgetBuilder builder,
}) {
assert(context != null); assert(context != null);
assert(builder != null); assert(builder != null);
return Navigator.push(context, new _ModalBottomSheetRoute<T>( return Navigator.push(context, new _ModalBottomSheetRoute<T>(
......
...@@ -17,7 +17,7 @@ class ColorSwatch extends Color { ...@@ -17,7 +17,7 @@ class ColorSwatch extends Color {
final Map<int, Color> _swatch; final Map<int, Color> _swatch;
/// Returns an element of the [swatch] table. /// Returns an element of the swatch table.
Color operator [](int index) => _swatch[index]; Color operator [](int index) => _swatch[index];
@override @override
...@@ -927,7 +927,7 @@ class Colors { ...@@ -927,7 +927,7 @@ class Colors {
/// ///
/// See also: /// See also:
/// ///
/// * [yellowAccentAccent], the corresponding accent colors. /// * [yellowAccent], the corresponding accent colors.
/// * [Theme.of], which allows you to select colors from the current theme /// * [Theme.of], which allows you to select colors from the current theme
/// rather than hard-coding colors in your build methods. /// rather than hard-coding colors in your build methods.
static const MaterialColor yellow = const MaterialColor( static const MaterialColor yellow = const MaterialColor(
......
...@@ -157,7 +157,7 @@ class DataCell { ...@@ -157,7 +157,7 @@ class DataCell {
/// Creates an object to hold the data for a cell in a [DataTable]. /// Creates an object to hold the data for a cell in a [DataTable].
/// ///
/// The first argument is the widget to show for the cell, typically /// The first argument is the widget to show for the cell, typically
/// a [Text] or [DropdownButton] widget; this becomes the [widget] /// a [Text] or [DropdownButton] widget; this becomes the [child]
/// property and must not be null. /// property and must not be null.
/// ///
/// If the cell has no data, then a [Text] widget with placeholder /// If the cell has no data, then a [Text] widget with placeholder
...@@ -166,7 +166,7 @@ class DataCell { ...@@ -166,7 +166,7 @@ class DataCell {
const DataCell(this.child, { const DataCell(this.child, {
this.placeholder: false, this.placeholder: false,
this.showEditIcon: false, this.showEditIcon: false,
this.onTap this.onTap,
}); });
/// A cell that has no content and has zero width and height. /// A cell that has no content and has zero width and height.
...@@ -201,7 +201,7 @@ class DataCell { ...@@ -201,7 +201,7 @@ class DataCell {
/// ///
/// If non-null, tapping the cell will call this callback. If /// If non-null, tapping the cell will call this callback. If
/// null, tapping the cell will attempt to select the row (if /// null, tapping the cell will attempt to select the row (if
/// [TableRow.onSelectChanged] is provided). /// [DataRow.onSelectChanged] is provided).
final VoidCallback onTap; final VoidCallback onTap;
bool get _debugInteractive => onTap != null; bool get _debugInteractive => onTap != null;
......
...@@ -12,7 +12,7 @@ import 'material.dart'; ...@@ -12,7 +12,7 @@ import 'material.dart';
/// only used in contexts where they can print ink onto some material. /// only used in contexts where they can print ink onto some material.
/// ///
/// To call this function, use the following pattern, typically in the /// To call this function, use the following pattern, typically in the
/// relevant Widget's [build] method: /// relevant Widget's build method:
/// ///
/// ```dart /// ```dart
/// assert(debugCheckHasMaterial(context)); /// assert(debugCheckHasMaterial(context));
......
...@@ -71,7 +71,7 @@ class Dialog extends StatelessWidget { ...@@ -71,7 +71,7 @@ class Dialog extends StatelessWidget {
/// ///
/// If the content is too large to fit on the screen vertically, the dialog will /// If the content is too large to fit on the screen vertically, the dialog will
/// display the title and the actions and let the content overflow. Consider /// display the title and the actions and let the content overflow. Consider
/// using a scrolling widget, such as [ScrollList], for [content] to avoid /// using a scrolling widget, such as [ListView], for [content] to avoid
/// overflow. /// overflow.
/// ///
/// For dialogs that offer the user a choice between several options, consider /// For dialogs that offer the user a choice between several options, consider
...@@ -114,8 +114,8 @@ class AlertDialog extends StatelessWidget { ...@@ -114,8 +114,8 @@ class AlertDialog extends StatelessWidget {
/// The (optional) content of the dialog is displayed in the center of the /// The (optional) content of the dialog is displayed in the center of the
/// dialog in a lighter font. /// dialog in a lighter font.
/// ///
/// Typically, this is a [ScrollList] containing the contents of the dialog. /// Typically, this is a [ListView] containing the contents of the dialog.
/// Using a [ScrollList] ensures that the contents can scroll if they are too /// Using a [ListView] ensures that the contents can scroll if they are too
/// big to fit on the display. /// big to fit on the display.
final Widget content; final Widget content;
...@@ -358,12 +358,13 @@ class _DialogRoute<T> extends PopupRoute<T> { ...@@ -358,12 +358,13 @@ class _DialogRoute<T> extends PopupRoute<T> {
/// This function typically receives a [Dialog] widget as its child argument. /// This function typically receives a [Dialog] widget as its child argument.
/// Content below the dialog is dimmed with a [ModalBarrier]. /// Content below the dialog is dimmed with a [ModalBarrier].
/// ///
/// Returns a `Future` that resolves to the value (if any) that was passed to /// Returns a [Future] that resolves to the value (if any) that was passed to
/// [Navigator.pop] when the dialog was closed. /// [Navigator.pop] when the dialog was closed.
/// ///
/// See also: /// See also:
/// * [SimpleDialog], which handles the scrolling of the contents but has no [actions]. /// * [AlertDialog], for dialogs that have a row of buttons below a body.
/// * [AlertDialog], for dialogs that have a row of buttons below the body. /// * [SimpleDialog], which handles the scrolling of the contents and does
/// not show buttons below its body.
/// * [Dialog], on which [SimpleDialog] and [AlertDialog] are based. /// * [Dialog], on which [SimpleDialog] and [AlertDialog] are based.
/// * <https://material.google.com/components/dialogs.html> /// * <https://material.google.com/components/dialogs.html>
Future<T> showDialog<T>({ Future<T> showDialog<T>({
......
...@@ -21,7 +21,7 @@ import 'theme.dart'; ...@@ -21,7 +21,7 @@ import 'theme.dart';
/// See also: /// See also:
/// ///
/// * [PopupMenuDivider], which is the equivalent but for popup menus. /// * [PopupMenuDivider], which is the equivalent but for popup menus.
/// * [ListTile.divideItems], another approach to dividing widgets in a list. /// * [ListTile.divideTiles], another approach to dividing widgets in a list.
/// * <https://material.google.com/components/dividers.html> /// * <https://material.google.com/components/dividers.html>
class Divider extends StatelessWidget { class Divider extends StatelessWidget {
/// Creates a material design divider. /// Creates a material design divider.
......
...@@ -233,7 +233,7 @@ class DrawerControllerState extends State<DrawerController> with SingleTickerPro ...@@ -233,7 +233,7 @@ class DrawerControllerState extends State<DrawerController> with SingleTickerPro
/// Starts an animation to open the drawer. /// Starts an animation to open the drawer.
/// ///
/// Typically called by [Scaffold.openDrawer]. /// Typically called by [ScaffoldState.openDrawer].
void open() { void open() {
_controller.fling(velocity: 1.0); _controller.fling(velocity: 1.0);
} }
......
...@@ -59,11 +59,11 @@ class FlutterLogo extends StatelessWidget { ...@@ -59,11 +59,11 @@ class FlutterLogo extends StatelessWidget {
/// itself is drawn. /// itself is drawn.
final FlutterLogoStyle style; final FlutterLogoStyle style;
/// The length of time for the animation if the [style], [swatch], or /// The length of time for the animation if the [style], [colors], or
/// [textColor] properties are changed. /// [textColor] properties are changed.
final Duration duration; final Duration duration;
/// The curve for the logo animation if the [style], [swatch], or [textColor] /// The curve for the logo animation if the [style], [colors], or [textColor]
/// change. /// change.
final Curve curve; final Curve curve;
......
...@@ -62,7 +62,7 @@ class Icon extends StatelessWidget { ...@@ -62,7 +62,7 @@ class Icon extends StatelessWidget {
/// 24.0. /// 24.0.
/// ///
/// If this [Icon] is being placed inside an [IconButton], then use /// If this [Icon] is being placed inside an [IconButton], then use
/// [IconButton.size] instead, so that the [IconButton] can make the splash /// [IconButton.iconSize] instead, so that the [IconButton] can make the splash
/// area the appropriate size as well. The [IconButton] uses an [IconTheme] to /// area the appropriate size as well. The [IconButton] uses an [IconTheme] to
/// pass down the size to the [Icon]. /// pass down the size to the [Icon].
final double size; final double size;
......
...@@ -96,9 +96,10 @@ class IconButton extends StatelessWidget { ...@@ -96,9 +96,10 @@ class IconButton extends StatelessWidget {
/// The icon to display inside the button. /// The icon to display inside the button.
/// ///
/// The [size] and [color] of the icon is configured automatically based on /// The [Icon.size] and [Icon.color] of the icon is configured automatically
/// the properties of _this_ widget using an [IconTheme] and therefore should /// based on the [iconSize] nad [color] properties of _this_ widget using an
/// not be explicitly given in the icon widget. /// [IconTheme] and therefore should not be explicitly given in the icon
/// widget.
/// ///
/// This property must not be null. /// This property must not be null.
/// ///
......
...@@ -24,7 +24,7 @@ import 'theme.dart'; ...@@ -24,7 +24,7 @@ import 'theme.dart';
/// Must have an ancestor [Material] widget in which to cause ink reactions. /// 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 /// If a Widget uses this class directly, it should include the following line
/// at the top of its [build] function to call [debugCheckHasMaterial]: /// at the top of its build function to call [debugCheckHasMaterial]:
/// ///
/// ```dart /// ```dart
/// assert(debugCheckHasMaterial(context)); /// assert(debugCheckHasMaterial(context));
...@@ -254,7 +254,7 @@ class _InkResponseState<T extends InkResponse> extends State<T> { ...@@ -254,7 +254,7 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
/// Must have an ancestor [Material] widget in which to cause ink reactions. /// 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 /// If a Widget uses this class directly, it should include the following line
/// at the top of its [build] function to call [debugCheckHasMaterial]: /// at the top of its build function to call [debugCheckHasMaterial]:
/// ///
/// ```dart /// ```dart
/// assert(debugCheckHasMaterial(context)); /// assert(debugCheckHasMaterial(context));
......
...@@ -136,7 +136,7 @@ class ListTileTheme extends InheritedWidget { ...@@ -136,7 +136,7 @@ class ListTileTheme extends InheritedWidget {
/// height based on their contents. If you are looking for a widget that allows /// height based on their contents. If you are looking for a widget that allows
/// for arbitrary layout in a row, consider [Row]. /// for arbitrary layout in a row, consider [Row].
/// ///
/// List tiles are typically used in [MaterialList]s or in [Card]s. /// List tiles are typically used in [ListView]s, [Drawer]s, and [Card]s.
/// ///
/// Requires one of its ancestors to be a [Material] widget. /// Requires one of its ancestors to be a [Material] widget.
/// ///
......
...@@ -60,7 +60,7 @@ class MaterialGap extends MergeableMaterialItem { ...@@ -60,7 +60,7 @@ class MaterialGap extends MergeableMaterialItem {
}) : assert(key != null), }) : assert(key != null),
super(key); super(key);
/// The main axis extent of this gap. For example, if the [MergableMaterial] /// The main axis extent of this gap. For example, if the [MergeableMaterial]
/// is vertical, then this is the height of the gap. /// is vertical, then this is the height of the gap.
final double size; final double size;
......
...@@ -333,8 +333,8 @@ class RefreshIndicatorState extends State<RefreshIndicator> with TickerProviderS ...@@ -333,8 +333,8 @@ class RefreshIndicatorState extends State<RefreshIndicator> with TickerProviderS
/// Creating the [RefreshIndicator] with a [GlobalKey<RefreshIndicatorState>] /// Creating the [RefreshIndicator] with a [GlobalKey<RefreshIndicatorState>]
/// makes it possible to refer to the [RefreshIndicatorState]. /// makes it possible to refer to the [RefreshIndicatorState].
/// ///
/// The future returned from this method completes when the [onRefresh] /// The future returned from this method completes when the
/// callback's future completes. /// [RefreshIndicator.onRefresh] callback's future completes.
/// ///
/// If you await the future returned by this function from a [State], you /// If you await the future returned by this function from a [State], you
/// should check that the state is still [mounted] before calling [setState]. /// should check that the state is still [mounted] before calling [setState].
......
...@@ -314,7 +314,7 @@ class Scaffold extends StatefulWidget { ...@@ -314,7 +314,7 @@ class Scaffold extends StatefulWidget {
/// ///
/// If you have a column of widgets that should normally fit on the screen, /// If you have a column of widgets that should normally fit on the screen,
/// but may overflow and would in such cases need to scroll, consider using a /// but may overflow and would in such cases need to scroll, consider using a
/// [ScrollList] as the body of the scaffold. This is also a good choice for /// [ListView] as the body of the scaffold. This is also a good choice for
/// the case where your body is a scrollable list. /// the case where your body is a scrollable list.
final Widget body; final Widget body;
...@@ -922,7 +922,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin { ...@@ -922,7 +922,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
/// An interface for controlling a feature of a [Scaffold]. /// An interface for controlling a feature of a [Scaffold].
/// ///
/// Commonly obtained from [Scaffold.showSnackBar] or [Scaffold.showBottomSheet]. /// Commonly obtained from [ScaffoldState.showSnackBar] or [ScaffoldState.showBottomSheet].
class ScaffoldFeatureController<T extends Widget, U> { class ScaffoldFeatureController<T extends Widget, U> {
const ScaffoldFeatureController._(this._widget, this._completer, this.close, this.setState); const ScaffoldFeatureController._(this._widget, this._completer, this.close, this.setState);
final T _widget; final T _widget;
...@@ -1005,7 +1005,7 @@ class _PersistentBottomSheetState extends State<_PersistentBottomSheet> { ...@@ -1005,7 +1005,7 @@ class _PersistentBottomSheetState extends State<_PersistentBottomSheet> {
/// A [ScaffoldFeatureController] for persistent bottom sheets. /// A [ScaffoldFeatureController] for persistent bottom sheets.
/// ///
/// This is the type of objects returned by [Scaffold.showBottomSheet]. /// This is the type of objects returned by [ScaffoldState.showBottomSheet].
class PersistentBottomSheetController<T> extends ScaffoldFeatureController<_PersistentBottomSheet, T> { class PersistentBottomSheetController<T> extends ScaffoldFeatureController<_PersistentBottomSheet, T> {
const PersistentBottomSheetController._( const PersistentBottomSheetController._(
_PersistentBottomSheet widget, _PersistentBottomSheet widget,
......
...@@ -32,10 +32,10 @@ const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOut ...@@ -32,10 +32,10 @@ const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOut
/// Specify how a [SnackBar] was closed. /// Specify how a [SnackBar] was closed.
/// ///
/// The [showSnackBar] function returns a [ScaffoldFeatureController]. The value /// The [ScaffoldState.showSnackBar] function returns a
/// of the controller's closed property is a Future that resolves to a /// [ScaffoldFeatureController]. The value of the controller's closed property
/// SnackBarClosedReason. Applications that need to know how a snackbar /// is a Future that resolves to a SnackBarClosedReason. Applications that need
/// was closed can use this value. /// to know how a snackbar was closed can use this value.
/// ///
/// Example: /// Example:
/// ///
...@@ -54,10 +54,10 @@ enum SnackBarClosedReason { ...@@ -54,10 +54,10 @@ enum SnackBarClosedReason {
swipe, swipe,
/// The snack bar was closed by the [ScaffoldFeatureController] close callback /// The snack bar was closed by the [ScaffoldFeatureController] close callback
/// or by calling [hideCurrentSnackBar] directly. /// or by calling [ScaffoldState.hideCurrentSnackBar] directly.
hide, hide,
/// The snack bar was closed by an call to [removeCurrentSnackBar]. /// The snack bar was closed by an call to [ScaffoldState.removeCurrentSnackBar].
remove, remove,
/// The snack bar was closed because its timer expired. /// The snack bar was closed because its timer expired.
......
...@@ -327,7 +327,7 @@ class ThemeData { ...@@ -327,7 +327,7 @@ class ThemeData {
// ...this should be the "50-value of secondary app color". // ...this should be the "50-value of secondary app color".
final Color secondaryHeaderColor; final Color secondaryHeaderColor;
/// The color of text selections in text fields, such as [Input]. /// The color of text selections in text fields, such as [TextField].
final Color textSelectionColor; final Color textSelectionColor;
/// The color of the handles used to adjust what part of the text is currently selected. /// The color of the handles used to adjust what part of the text is currently selected.
...@@ -344,10 +344,10 @@ class ThemeData { ...@@ -344,10 +344,10 @@ class ThemeData {
final Color indicatorColor; final Color indicatorColor;
/// The color to use for hint text or placeholder text, e.g. in /// The color to use for hint text or placeholder text, e.g. in
/// [Input] fields. /// [TextField] fields.
final Color hintColor; final Color hintColor;
/// The color to use for input validation errors, e.g. in [Input] fields. /// The color to use for input validation errors, e.g. in [TextField] fields.
final Color errorColor; final Color errorColor;
/// Text with a color that contrasts with the card and canvas colors. /// Text with a color that contrasts with the card and canvas colors.
......
...@@ -79,7 +79,7 @@ abstract class RenderToggleable extends RenderConstrainedBox implements Semantic ...@@ -79,7 +79,7 @@ abstract class RenderToggleable extends RenderConstrainedBox implements Semantic
/// The visual value of the control. /// The visual value of the control.
/// ///
/// When the control is inactive, the [value] is false and this animation has /// When the control is inactive, the [value] is false and this animation has
/// the value 0.0. When the control is active, the value is [true] and this /// the value 0.0. When the control is active, the value is true and this
/// animation has the value 1.0. When the control is changing from inactive /// animation has the value 1.0. When the control is changing from inactive
/// to active (or vice versa), [value] is the target value and this animation /// to active (or vice versa), [value] is the target value and this animation
/// gradually updates from 0.0 to 1.0 (or vice versa). /// gradually updates from 0.0 to 1.0 (or vice versa).
......
...@@ -3,6 +3,7 @@ ...@@ -3,6 +3,7 @@
// found in the LICENSE file. // found in the LICENSE file.
import 'dart:math' as math; import 'dart:math' as math;
import 'dart:ui' show Image; // to disambiguate mentions of Image in the dartdocs
import 'package:flutter/foundation.dart'; import 'package:flutter/foundation.dart';
......
...@@ -95,9 +95,15 @@ class TextPainter { ...@@ -95,9 +95,15 @@ class TextPainter {
_needsLayout = true; _needsLayout = true;
} }
/// The string used to ellipsize overflowing text. Setting this to a nonempty /// The string used to ellipsize overflowing text. Setting this to a non-empty
/// string will cause this string to be substituted for the remaining text /// string will cause this string to be substituted for the remaining text
/// if the text can not fit within the specificed maximum width. /// if the text can not fit within the specified maximum width.
///
/// Specifically, the ellipsis is applied to the last line before the line
/// truncated by [maxLines], if [maxLines] is non-null and that line overflows
/// the width constraint, or to the first line that is wider than the width
/// constraint, if [maxLines] is null. The width constraint is the `maxWidth`
/// passed to [layout].
/// ///
/// After this is set, you must call [layout] before the next call to [paint]. /// After this is set, you must call [layout] before the next call to [paint].
String get ellipsis => _ellipsis; String get ellipsis => _ellipsis;
...@@ -111,10 +117,11 @@ class TextPainter { ...@@ -111,10 +117,11 @@ class TextPainter {
_needsLayout = true; _needsLayout = true;
} }
/// An optional maximum number of lines for the text to span, wrapping if necessary. /// An optional maximum number of lines for the text to span, wrapping if
/// necessary.
/// ///
/// If the text exceeds the given number of lines, it will be truncated according /// If the text exceeds the given number of lines, it is truncated such that
/// to [overflow]. /// subsequent lines are dropped.
/// ///
/// After this is set, you must call [layout] before the next call to [paint]. /// After this is set, you must call [layout] before the next call to [paint].
int get maxLines => _maxLines; int get maxLines => _maxLines;
...@@ -129,10 +136,10 @@ class TextPainter { ...@@ -129,10 +136,10 @@ class TextPainter {
ui.Paragraph _layoutTemplate; ui.Paragraph _layoutTemplate;
/// The height of a zero-width space in [style] in logical pixels. /// The height of a zero-width space in [text] in logical pixels.
/// ///
/// Not every line of text in [style] will have this height, but this height /// Not every line of text in [text] will have this height, but this height
/// is "typical" for text in [style] and useful for sizing other objects /// is "typical" for text in [text] and useful for sizing other objects
/// relative a typical line of text. /// relative a typical line of text.
double get preferredLineHeight { double get preferredLineHeight {
assert(text != null); assert(text != null);
...@@ -198,7 +205,8 @@ class TextPainter { ...@@ -198,7 +205,8 @@ class TextPainter {
return new Size(width, height); return new Size(width, height);
} }
/// Returns the distance from the top of the text to the first baseline of the given type. /// Returns the distance from the top of the text to the first baseline of the
/// given type.
/// ///
/// Valid only after [layout] has been called. /// Valid only after [layout] has been called.
double computeDistanceToActualBaseline(TextBaseline baseline) { double computeDistanceToActualBaseline(TextBaseline baseline) {
...@@ -213,10 +221,17 @@ class TextPainter { ...@@ -213,10 +221,17 @@ class TextPainter {
return null; return null;
} }
/// Whether the previous call to [layout] attempted to produce more than /// Whether any text was truncated or ellipsized.
/// [maxLines] lines. ///
/// If [maxLines] is not null, this is true if there were more lines to be
/// drawn than the given [maxLines], and thus at least one line was omitted in
/// the output; otherwise it is false.
/// ///
/// If [didExceedMaxLines] is true, then any overflow effect is operative. /// If [maxLines] is null, this is true if [ellipsis] is not the empty string
/// and there was a line that overflowed the `maxWidth` argument passed to
/// [layout]; otherwise it is false.
///
/// Valid only after [layout] has been called.
bool get didExceedMaxLines { bool get didExceedMaxLines {
assert(!_needsLayout); assert(!_needsLayout);
return _paragraph.didExceedMaxLines; return _paragraph.didExceedMaxLines;
......
...@@ -113,7 +113,7 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding, ...@@ -113,7 +113,7 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
/// Called when the system metrics change. /// Called when the system metrics change.
/// ///
/// See [ui.window.onMetricsChanged]. /// See [Window.onMetricsChanged].
void handleMetricsChanged() { void handleMetricsChanged() {
assert(renderView != null); assert(renderView != null);
renderView.configuration = createViewConfiguration(); renderView.configuration = createViewConfiguration();
...@@ -179,11 +179,11 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding, ...@@ -179,11 +179,11 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
/// Each frame consists of the following phases: /// Each frame consists of the following phases:
/// ///
/// 1. The animation phase: The [handleBeginFrame] method, which is registered /// 1. The animation phase: The [handleBeginFrame] method, which is registered
/// with [ui.window.onBeginFrame], invokes all the transient frame callbacks /// with [Window.onBeginFrame], invokes all the transient frame callbacks
/// registered with [scheduleFrameCallback] and [addFrameCallback], in /// registered with [scheduleFrameCallback], in registration order. This
/// registration order. This includes all the [Ticker] instances that are /// includes all the [Ticker] instances that are driving [AnimationController]
/// driving [AnimationController] objects, which means all of the active /// objects, which means all of the active [Animation] objects tick at this
/// [Animation] objects tick at this point. /// point.
/// ///
/// 2. Microtasks: After [handleBeginFrame] returns, any microtasks that got /// 2. Microtasks: After [handleBeginFrame] returns, any microtasks that got
/// scheduled by transient frame callbacks get to run. This typically includes /// scheduled by transient frame callbacks get to run. This typically includes
...@@ -191,7 +191,7 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding, ...@@ -191,7 +191,7 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
/// completed this frame. /// completed this frame.
/// ///
/// After [handleBeginFrame], [handleDrawFrame], which is registered with /// After [handleBeginFrame], [handleDrawFrame], which is registered with
/// [ui.window.onDrawFrame], is called, which invokes all the persistent frame /// [Window.onDrawFrame], is called, which invokes all the persistent frame
/// callbacks, of which the most notable is this method, [drawFrame], which /// callbacks, of which the most notable is this method, [drawFrame], which
/// proceeds as follows: /// proceeds as follows:
/// ///
...@@ -208,11 +208,11 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding, ...@@ -208,11 +208,11 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
/// [RenderObject.markNeedsPaint] for further details on marking an object /// [RenderObject.markNeedsPaint] for further details on marking an object
/// dirty for paint. /// dirty for paint.
/// ///
/// 6. The compositing phase: The layer tree is turned into a [ui.Scene] and /// 6. The compositing phase: The layer tree is turned into a [Scene] and
/// sent to the GPU. /// sent to the GPU.
/// ///
/// 7. The semantics phase: All the dirty [RenderObject]s in the system have /// 7. The semantics phase: All the dirty [RenderObject]s in the system have
/// their semantics updated (see [RenderObject.SemanticsAnnotator]). This /// their semantics updated (see [RenderObject.semanticsAnnotator]). This
/// generates the [SemanticsNode] tree. See /// generates the [SemanticsNode] tree. See
/// [RenderObject.markNeedsSemanticsUpdate] for further details on marking an /// [RenderObject.markNeedsSemanticsUpdate] for further details on marking an
/// object dirty for semantics. /// object dirty for semantics.
......
...@@ -935,7 +935,7 @@ class _IntrinsicDimensionsCacheEntry { ...@@ -935,7 +935,7 @@ class _IntrinsicDimensionsCacheEntry {
/// ///
/// For a render box to be accessible, implement the /// For a render box to be accessible, implement the
/// [describeApproximatePaintClip] and [visitChildrenForSemantics] methods, and /// [describeApproximatePaintClip] and [visitChildrenForSemantics] methods, and
/// the [semanticAnnotator] getter. The default implementations are sufficient /// the [semanticsAnnotator] getter. The default implementations are sufficient
/// for objects that only affect layout, but nodes that represent interactive /// for objects that only affect layout, but nodes that represent interactive
/// components or information (diagrams, text, images, etc) should provide more /// components or information (diagrams, text, images, etc) should provide more
/// complete implementations. For more information, see the documentation for /// complete implementations. For more information, see the documentation for
...@@ -1089,11 +1089,23 @@ abstract class RenderBox extends RenderObject { ...@@ -1089,11 +1089,23 @@ abstract class RenderBox extends RenderObject {
/// children. It is the size that is needed to paint the box's contents (in /// children. It is the size that is needed to paint the box's contents (in
/// this case, the children) _without clipping_ that matters. /// this case, the children) _without clipping_ that matters.
/// ///
/// In many cases, viewports do not have efficient access to all the children, /// ### When the intrinsic dimensions cannot be known
/// and therefore cannot actually return a valid answer. In this case, when ///
/// [RenderObject.debugCheckingIntrinsics] is false and asserts are enabled, /// There are cases where render objects do not have an efficient way to
/// the intrinsic functions should throw; in other cases, they should return /// compute their intrinsic dimensions. For example, it may be prohibitively
/// 0.0. See [RenderVirtualViewport.debugThrowIfNotCheckingIntrinsics]. /// expensive to reify and measure every child of a lazy viewport (viewports
/// generally only instantiate the actually visible children), or the
/// dimensions may be computed by a callback about which the render object
/// cannot reason.
///
/// In such cases, it may be impossible (or at least impractical) to actually
/// return a valid answer. In such cases, the intrinsic functions should throw
/// when [RenderObject.debugCheckingIntrinsics] is false and asserts are
/// enabled, and return 0.0 otherwise.
///
/// See the implementations of [LayoutBuilder] or [RenderViewportBase] for
/// examples (in particular,
/// [RenderViewportBase.debugThrowIfNotCheckingIntrinsics]).
/// ///
/// ### Aspect-ratio-driven boxes /// ### Aspect-ratio-driven boxes
/// ///
......
...@@ -38,7 +38,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox> ...@@ -38,7 +38,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox>
/// Override [shouldRelayout] to determine when the layout of the children needs /// Override [shouldRelayout] to determine when the layout of the children needs
/// to be recomputed when the delegate changes. /// to be recomputed when the delegate changes.
/// ///
/// Used with [MultiChildCustomLayout], the widget for the /// Used with [CustomMultiChildLayout], the widget for the
/// [RenderCustomMultiChildLayoutBox] render object. /// [RenderCustomMultiChildLayoutBox] render object.
/// ///
/// ## Example /// ## Example
......
...@@ -111,7 +111,7 @@ bool debugCheckIntrinsicSizes = false; ...@@ -111,7 +111,7 @@ bool debugCheckIntrinsicSizes = false;
/// Adds [Timeline] events for every RenderObject painted. /// Adds [Timeline] events for every RenderObject painted.
/// ///
/// For details on how to use [Timeline] events in the Dart Observatory to /// For details on how to use [Timeline] events in the Dart Observatory to
/// optimize your app, see https://fuchsia.googlesource.com/sysui/+/master/docs/performance.md /// optimize your app, see: https://fuchsia.googlesource.com/sysui/+/master/docs/performance.md
bool debugProfilePaintsEnabled = false; bool debugProfilePaintsEnabled = false;
......
...@@ -177,7 +177,7 @@ class RenderFlow extends RenderBox ...@@ -177,7 +177,7 @@ class RenderFlow extends RenderBox
/// Creates a render object for a flow layout. /// Creates a render object for a flow layout.
/// ///
/// For optimal performance, consider using children that return true from /// For optimal performance, consider using children that return true from
/// [isRepaintBounday]. /// [isRepaintBoundary].
RenderFlow({ RenderFlow({
List<RenderBox> children, List<RenderBox> children,
@required FlowDelegate delegate @required FlowDelegate delegate
......
...@@ -22,10 +22,10 @@ import 'node.dart'; ...@@ -22,10 +22,10 @@ import 'node.dart';
/// different parents. The scene must be explicitly recomposited after such /// different parents. The scene must be explicitly recomposited after such
/// changes are made; the layer tree does not maintain its own dirty state. /// changes are made; the layer tree does not maintain its own dirty state.
/// ///
/// To composite the tree, create a [ui.SceneBuilder] object, pass it to the /// To composite the tree, create a [SceneBuilder] object, pass it to the
/// root [Layer] object's [addToScene] method, and then call /// root [Layer] object's [addToScene] method, and then call
/// [ui.SceneBuilder.build] to obtain a [Scene]. A [Scene] can then be painted /// [SceneBuilder.build] to obtain a [Scene]. A [Scene] can then be painted
/// using [ui.window.render]. /// using [Window.render].
/// ///
/// See also: /// See also:
/// ///
...@@ -334,7 +334,7 @@ class ContainerLayer extends Layer { ...@@ -334,7 +334,7 @@ class ContainerLayer extends Layer {
/// ///
/// This method is typically used by [addToScene] to insert the children into /// This method is typically used by [addToScene] to insert the children into
/// the scene. Subclasses of [ContainerLayer] typically override [addToScene] /// the scene. Subclasses of [ContainerLayer] typically override [addToScene]
/// to apply effects to the scene using the [ui.SceneBuilder] API, then insert /// to apply effects to the scene using the [SceneBuilder] API, then insert
/// their children using [addChildrenToScene], then reverse the aforementioned /// their children using [addChildrenToScene], then reverse the aforementioned
/// effects before returning from [addToScene]. /// effects before returning from [addToScene].
void addChildrenToScene(ui.SceneBuilder builder, Offset childOffset) { void addChildrenToScene(ui.SceneBuilder builder, Offset childOffset) {
......
...@@ -556,23 +556,21 @@ abstract class Constraints { ...@@ -556,23 +556,21 @@ abstract class Constraints {
/// ///
/// This might involve checks more detailed than [isNormalized]. /// This might involve checks more detailed than [isNormalized].
/// ///
/// For example, the [BoxConstraints] subclass verifies that the /// For example, the [BoxConstraints] subclass verifies that the constraints
/// constraints are not [NaN]. /// are not [double.NAN].
/// ///
/// If the `isAppliedConstraint` argument is true, then even /// If the `isAppliedConstraint` argument is true, then even stricter rules
/// stricter rules are enforced. This argument is set to true when /// are enforced. This argument is set to true when checking constraints that
/// checking constraints that are about to be applied to a /// are about to be applied to a [RenderObject] during layout, as opposed to
/// [RenderObject] during layout, as opposed to constraints that may /// constraints that may be further affected by other constraints. For
/// be further affected by other constraints. For example, the /// example, the asserts for verifying the validity of
/// asserts for verifying the validity of /// [RenderConstrainedBox.additionalConstraints] do not set this argument, but
/// [RenderConstrainedBox.additionalConstraints] do not set this /// the asserts for verifying the argument passed to the [RenderObject.layout]
/// argument, but the asserts for verifying the argument passed to /// method do.
/// the [layout] method do. ///
/// /// The `informationCollector` argument takes an optional callback which is
/// The `informationCollector` argument takes an optional callback /// called when an exception is to be thrown. The collected information is
/// which is called when an exception is to be thrown. The collected /// then included in the message after the error line.
/// information is then included in the message after the error
/// line.
/// ///
/// Returns the same as [isNormalized] if asserts are disabled. /// Returns the same as [isNormalized] if asserts are disabled.
bool debugAssertIsValid({ bool debugAssertIsValid({
...@@ -1076,7 +1074,7 @@ class PipelineOwner { ...@@ -1076,7 +1074,7 @@ class PipelineOwner {
} }
final List<RenderObject> _nodesNeedingCompositingBitsUpdate = <RenderObject>[]; final List<RenderObject> _nodesNeedingCompositingBitsUpdate = <RenderObject>[];
/// Updates the [needsCompositing] bits. /// Updates the [RenderObject.needsCompositing] bits.
/// ///
/// Called as part of the rendering pipeline after [flushLayout] and before /// Called as part of the rendering pipeline after [flushLayout] and before
/// [flushPaint]. /// [flushPaint].
...@@ -2102,8 +2100,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget { ...@@ -2102,8 +2100,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
bool _needsCompositing; // initialised in the constructor bool _needsCompositing; // initialised in the constructor
/// Whether we or one of our descendants has a compositing layer. /// Whether we or one of our descendants has a compositing layer.
/// ///
/// Only legal to call after [flushLayout] and [flushCompositingBits] have /// Only legal to call after [PipelineOwner.flushLayout] and
/// been called. /// [PipelineOwner.flushCompositingBits] have been called.
bool get needsCompositing { bool get needsCompositing {
assert(!_needsCompositingBitsUpdate); // make sure we don't use this bit when it is dirty assert(!_needsCompositingBitsUpdate); // make sure we don't use this bit when it is dirty
return _needsCompositing; return _needsCompositing;
...@@ -2325,8 +2323,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget { ...@@ -2325,8 +2323,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// ///
/// Do not call this function directly. If you wish to paint yourself, call /// Do not call this function directly. If you wish to paint yourself, call
/// [markNeedsPaint] instead to schedule a call to this function. If you wish /// [markNeedsPaint] instead to schedule a call to this function. If you wish
/// to paint one of your children, call one of the paint child functions on /// to paint one of your children, call [PaintingContext.paintChild] on the
/// the given context, such as [paintChild] or [paintChildWithClipRect]. /// given `context`.
/// ///
/// When painting one of your children (via a paint child function on the /// When painting one of your children (via a paint child function on the
/// given context), the current canvas held by the context might change /// given context), the current canvas held by the context might change
...@@ -2374,7 +2372,12 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget { ...@@ -2374,7 +2372,12 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
owner.requestVisualUpdate(); owner.requestVisualUpdate();
} }
/// Whether this RenderObject introduces a new box for accessibility purposes. /// Whether this [RenderObject] introduces a new box for accessibility purposes.
///
/// See also:
///
/// * [semanticsAnnotator], which fills in the [SemanticsNode] implied by
/// setting [isSemanticBoundary] to true.
bool get isSemanticBoundary => false; bool get isSemanticBoundary => false;
/// The bounding box, in the local coordinate system, of this /// The bounding box, in the local coordinate system, of this
...@@ -2388,8 +2391,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget { ...@@ -2388,8 +2391,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// The semantics of this render object. /// The semantics of this render object.
/// ///
/// Exposed only for testing and debugging. To learn about the semantics of /// Exposed only for testing and debugging. To learn about the semantics of
/// render objects in production, register as a listener using /// render objects in production, obtain a [SemanticsHandle] from
/// [SemanticsNode.addListener]. /// [PipelineOwner.ensureSemantics].
/// ///
/// Only valid when asserts are enabled. In release builds, always returns /// Only valid when asserts are enabled. In release builds, always returns
/// null. /// null.
...@@ -2551,25 +2554,24 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget { ...@@ -2551,25 +2554,24 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// Returns a function that will annotate a [SemanticsNode] with the semantics /// Returns a function that will annotate a [SemanticsNode] with the semantics
/// of this [RenderObject]. /// of this [RenderObject].
/// ///
/// To annotate a SemanticsNode for this node, return an annotator that /// To annotate a [SemanticsNode] for this node, return an annotator that adds
/// adds the annotations. When the behavior of the annotator would /// the annotations. When the behavior of the annotator would change (e.g. the
/// change (e.g. the box is now checked rather than unchecked), call /// box is now checked rather than unchecked), call [markNeedsSemanticsUpdate]
/// [markNeedsSemanticsUpdate] to indicate to the rendering system /// to indicate to the rendering system that the semantics tree needs to be
/// that the semantics tree needs to be rebuilt. /// rebuilt.
/// ///
/// To introduce a new SemanticsNode, set hasSemantics to true for /// To introduce a new [SemanticsNode], set [isSemanticBoundary] to true for
/// this object. The function returned by this function will be used /// this object. The function returned by this function will be used to
/// to annotate the SemanticsNode for this object. /// annotate the [SemanticsNode] for this object.
/// ///
/// Semantic annotations are persistent. Values set in one pass will /// Semantic annotations are persistent. Values set in one pass will still be
/// still be set in the next pass. Therefore it is important to /// set in the next pass. Therefore it is important to explicitly set fields
/// explicitly set fields to false once they are no longer true; /// to false once they are no longer true; setting them to true when they are
/// setting them to true when they are to be enabled, and not /// to be enabled, and not setting them at all when they are not, will mean
/// setting them at all when they are not, will mean they remain set /// they remain set once enabled once and will never get unset.
/// once enabled once and will never get unset. ///
/// /// If the return value will change from null to non-null (or vice versa), and
/// If the value return will change from null to non-null (or vice versa), and /// [isSemanticBoundary] isn't true, then the associated call to
/// [hasSemantics] isn't true, then the associated call to
/// [markNeedsSemanticsUpdate] must not have `onlyChanges` set, as it is /// [markNeedsSemanticsUpdate] must not have `onlyChanges` set, as it is
/// possible that the node should be entirely removed. /// possible that the node should be entirely removed.
SemanticsAnnotator get semanticsAnnotator => null; SemanticsAnnotator get semanticsAnnotator => null;
......
...@@ -769,7 +769,7 @@ typedef Shader ShaderCallback(Rect bounds); ...@@ -769,7 +769,7 @@ typedef Shader ShaderCallback(Rect bounds);
/// Applies a mask generated by a [Shader] to its child. /// Applies a mask generated by a [Shader] to its child.
/// ///
/// For example, [RenderShaderMask] can be used to gradually fade out the edge /// For example, [RenderShaderMask] can be used to gradually fade out the edge
/// of a child by using a [ui.Gradient.linear] mask. /// of a child by using a [new ui.Gradient.linear] mask.
class RenderShaderMask extends RenderProxyBox { class RenderShaderMask extends RenderProxyBox {
/// Creates a render object that applies a mask generated by a [Shader] to its child. /// Creates a render object that applies a mask generated by a [Shader] to its child.
/// ///
...@@ -1885,8 +1885,8 @@ abstract class CustomPainter extends Listenable { ...@@ -1885,8 +1885,8 @@ abstract class CustomPainter extends Listenable {
/// ///
/// If a custom delegate has a particularly expensive paint function such that /// If a custom delegate has a particularly expensive paint function such that
/// repaints should be avoided as much as possible, a [RepaintBoundary] or /// repaints should be avoided as much as possible, a [RepaintBoundary] or
/// [RenderRepaintBoundary] (or other render object with [isRepaintBoundary] /// [RenderRepaintBoundary] (or other render object with
/// set to true) might be helpful. /// [RenderObject.isRepaintBoundary] set to true) might be helpful.
bool shouldRepaint(covariant CustomPainter oldDelegate); bool shouldRepaint(covariant CustomPainter oldDelegate);
/// Called whenever a hit test is being performed on an object that is using /// Called whenever a hit test is being performed on an object that is using
......
...@@ -17,10 +17,9 @@ export 'dart:ui' show SemanticsAction; ...@@ -17,10 +17,9 @@ export 'dart:ui' show SemanticsAction;
/// Interface for [RenderObject]s to implement when they want to support /// Interface for [RenderObject]s to implement when they want to support
/// being tapped, etc. /// being tapped, etc.
/// ///
/// These handlers will only be called if the relevant flag is set /// The handler will only be called for a particular flag if that flag is set
/// (e.g. [handleSemanticTap] will only be called if /// (e.g. [performAction] will only be called with [SemanticsAction.tap] if
/// [SemanticsNode.canBeTapped] is true, [handleSemanticScrollDown] will only /// [SemanticsNode.addAction] was called for [SemanticsAction.tap].)
/// be called if [SemanticsNode.canBeScrolledVertically] is true, etc).
abstract class SemanticsActionHandler { // ignore: one_member_abstracts abstract class SemanticsActionHandler { // ignore: one_member_abstracts
/// Called when the object implementing this interface receives a /// Called when the object implementing this interface receives a
/// [SemanticsAction]. For example, if the user of an accessibility tool /// [SemanticsAction]. For example, if the user of an accessibility tool
...@@ -36,7 +35,7 @@ abstract class SemanticsActionHandler { // ignore: one_member_abstracts ...@@ -36,7 +35,7 @@ abstract class SemanticsActionHandler { // ignore: one_member_abstracts
/// corresponds to the [RenderObject]. (One [SemanticsNode] can /// corresponds to the [RenderObject]. (One [SemanticsNode] can
/// correspond to multiple [RenderObject] objects.) /// correspond to multiple [RenderObject] objects.)
/// ///
/// See [RenderObject.getSemanticsAnnotators()] for details on the /// See [RenderObject.semanticsAnnotator] for details on the
/// contract that semantic annotators must follow. /// contract that semantic annotators must follow.
typedef void SemanticsAnnotator(SemanticsNode semantics); typedef void SemanticsAnnotator(SemanticsNode semantics);
...@@ -74,7 +73,7 @@ class SemanticsData { ...@@ -74,7 +73,7 @@ class SemanticsData {
/// A bit field of [SemanticsFlags] that apply to this node. /// A bit field of [SemanticsFlags] that apply to this node.
final int flags; final int flags;
/// A bit field of [SemanticsActions] that apply to this node. /// A bit field of [SemanticsAction]s that apply to this node.
final int actions; final int actions;
/// A textual description of this node. /// A textual description of this node.
...@@ -606,8 +605,9 @@ class SemanticsNode extends AbstractNode { ...@@ -606,8 +605,9 @@ class SemanticsNode extends AbstractNode {
/// Owns [SemanticsNode] objects and notifies listeners of changes to the /// Owns [SemanticsNode] objects and notifies listeners of changes to the
/// render tree semantics. /// render tree semantics.
/// ///
/// To listen for semantic updates, call [PipelineOwner.addSemanticsListener], /// To listen for semantic updates, call [PipelineOwner.ensureSemantics] to
/// which will create a [SemanticsOwner] if necessary. /// obtain a [SemanticsHandle]. This will create a [SemanticsOwner] if
/// necessary.
class SemanticsOwner extends ChangeNotifier { class SemanticsOwner extends ChangeNotifier {
final Set<SemanticsNode> _dirtyNodes = new Set<SemanticsNode>(); final Set<SemanticsNode> _dirtyNodes = new Set<SemanticsNode>();
final Map<int, SemanticsNode> _nodes = <int, SemanticsNode>{}; final Map<int, SemanticsNode> _nodes = <int, SemanticsNode>{};
...@@ -626,7 +626,7 @@ class SemanticsOwner extends ChangeNotifier { ...@@ -626,7 +626,7 @@ class SemanticsOwner extends ChangeNotifier {
super.dispose(); super.dispose();
} }
/// Update the semantics using [ui.window.updateSemantics]. /// Update the semantics using [Window.updateSemantics].
void sendSemanticsUpdate() { void sendSemanticsUpdate() {
if (_dirtyNodes.isEmpty) if (_dirtyNodes.isEmpty)
return; return;
...@@ -745,7 +745,7 @@ class SemanticsOwner extends ChangeNotifier { ...@@ -745,7 +745,7 @@ class SemanticsOwner extends ChangeNotifier {
return node._canPerformAction(action) ? node._actionHandler : null; return node._canPerformAction(action) ? node._actionHandler : null;
} }
/// Asks the [SemanticsNode] with at the given position to perform the given action. /// Asks the [SemanticsNode] at the given position to perform the given action.
/// ///
/// If the [SemanticsNode] has not indicated that it can perform the action, /// If the [SemanticsNode] has not indicated that it can perform the action,
/// this function does nothing. /// this function does nothing.
......
...@@ -254,8 +254,17 @@ class SliverConstraints extends Constraints { ...@@ -254,8 +254,17 @@ class SliverConstraints extends Constraints {
/// ///
/// For example, if [growthDirection] is [GrowthDirection.reverse] and /// For example, if [growthDirection] is [GrowthDirection.reverse] and
/// [axisDirection] is [AxisDirection.down], then a /// [axisDirection] is [AxisDirection.down], then a
/// [userScrollDirection.forward] means that the user is scrolling up, in the /// [ScrollDirection.forward] means that the user is scrolling up, in the
/// positive [scrollOffset] direction. /// positive [scrollOffset] direction.
///
/// If the _user_ is not scrolling, this will return [ScrollDirection.idle]
/// even if there is (for example) a [ScrollActivity] currently animating the
/// position.
///
/// This is used by some slivers to determine how to react to a change in
/// scroll offset. For example, [RenderSliverFloatingPersistentHeader] will
/// only expand a floating app bar when the [userScrollDirection] is in the
/// positive scroll offset direction.
final ScrollDirection userScrollDirection; final ScrollDirection userScrollDirection;
/// The scroll offset, in this sliver's coordinate system, that corresponds to /// The scroll offset, in this sliver's coordinate system, that corresponds to
......
...@@ -52,7 +52,8 @@ abstract class RenderSliverBoxChildManager { ...@@ -52,7 +52,8 @@ abstract class RenderSliverBoxChildManager {
/// ///
/// The index of the given child can be obtained using the /// The index of the given child can be obtained using the
/// [RenderSliverMultiBoxAdaptor.indexOf] method, which reads it from the /// [RenderSliverMultiBoxAdaptor.indexOf] method, which reads it from the
/// [SliverMultiBoxAdaptorParentData.index] field of the child's [parentData]. /// [SliverMultiBoxAdaptorParentData.index] field of the child's
/// [RenderObject.parentData].
void removeChild(RenderBox child); void removeChild(RenderBox child);
/// Called to estimate the total scrollable extents of this object. /// Called to estimate the total scrollable extents of this object.
...@@ -70,8 +71,8 @@ abstract class RenderSliverBoxChildManager { ...@@ -70,8 +71,8 @@ abstract class RenderSliverBoxChildManager {
/// Called during [RenderSliverMultiBoxAdaptor.adoptChild]. /// Called during [RenderSliverMultiBoxAdaptor.adoptChild].
/// ///
/// Subclasses must ensure that the [SliverMultiBoxAdaptorParentData.index] /// Subclasses must ensure that the [SliverMultiBoxAdaptorParentData.index]
/// field of the child's [parentData] accurately reflects the child's index in /// field of the child's [RenderObject.parentData] accurately reflects the
/// the child list after this function returns. /// child's index in the child list after this function returns.
void didAdoptChild(RenderBox child); void didAdoptChild(RenderBox child);
/// Called during layout to indicate whether this object provided insufficient /// Called during layout to indicate whether this object provided insufficient
......
...@@ -91,9 +91,9 @@ class RenderSliverPadding extends RenderSliver with RenderObjectWithChildMixin<R ...@@ -91,9 +91,9 @@ class RenderSliverPadding extends RenderSliver with RenderObjectWithChildMixin<R
return null; return null;
} }
/// The total padding in the [constraints.axisDirection]. (In other words, for /// The total padding in the [SliverConstraints.axisDirection]. (In other
/// a vertical downwards-growing list, the sum of the padding on the top and /// words, for a vertical downwards-growing list, the sum of the padding on
/// bottom.) /// the top and bottom.)
/// ///
/// Only valid after layout has started, since before layout the render object /// Only valid after layout has started, since before layout the render object
/// doesn't know what direction it will be laid out in. /// doesn't know what direction it will be laid out in.
......
...@@ -351,7 +351,7 @@ class RenderStack extends RenderBox ...@@ -351,7 +351,7 @@ class RenderStack extends RenderBox
/// Whether overflowing children should be clipped. See [Overflow]. /// Whether overflowing children should be clipped. See [Overflow].
/// ///
/// Some children in a stack might overflow its box. When this flag is set to /// Some children in a stack might overflow its box. When this flag is set to
/// [Overflow.clipped], children cannot paint outside of the stack's box. /// [Overflow.clip], children cannot paint outside of the stack's box.
Overflow get overflow => _overflow; Overflow get overflow => _overflow;
Overflow _overflow; Overflow _overflow;
set overflow(Overflow value) { set overflow(Overflow value) {
......
...@@ -452,7 +452,7 @@ enum TableCellVerticalAlignment { ...@@ -452,7 +452,7 @@ enum TableCellVerticalAlignment {
/// Cells with this alignment are aligned such that they all share the same /// Cells with this alignment are aligned such that they all share the same
/// baseline. Cells with no baseline are top-aligned instead. The baseline /// baseline. Cells with no baseline are top-aligned instead. The baseline
/// used is specified by [RenderTable.baseline]. It is not valid to use the /// used is specified by [RenderTable.baseline]. It is not valid to use the
/// baseline value if [RenderTable.baseline] is not specified. /// baseline value if [RenderTable.textBaseline] is not specified.
/// ///
/// This vertial alignment is relatively expensive because it causes the table /// This vertial alignment is relatively expensive because it causes the table
/// to compute the baseline for each cell in the row. /// to compute the baseline for each cell in the row.
......
...@@ -82,7 +82,7 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix ...@@ -82,7 +82,7 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
assert(offset != null); assert(offset != null);
} }
/// The direction in which the [scrollOffset] increases. /// The direction in which the [SliverConstraints.scrollOffset] increases.
/// ///
/// For example, if the [axisDirection] is [AxisDirection.down], a scroll /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
/// offset of zero is at the top of the viewport and increases towards the /// offset of zero is at the top of the viewport and increases towards the
...@@ -138,6 +138,56 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix ...@@ -138,6 +138,56 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
super.detach(); super.detach();
} }
/// Throws an exception saying that the object does not support returning
/// intrinsic dimensions if, in checked mode, we are not in the
/// [RenderObject.debugCheckingIntrinsics] mode.
///
/// This is used by [computeMinIntrinsicWidth] et al because viewports do not
/// generally support returning intrinsic dimensions. See the discussion at
/// [computeMinIntrinsicWidth].
@protected
bool debugThrowIfNotCheckingIntrinsics() {
assert(() {
if (!RenderObject.debugCheckingIntrinsics) {
assert(this is! RenderShrinkWrappingViewport); // it has its own message
throw new FlutterError(
'$runtimeType does not support returning intrinsic dimensions.\n'
'Calculating the intrinsic dimensions would require instantiating every child of '
'the viewport, which defeats the point of viewports being lazy.\n'
'If you are merely trying to shrink-wrap the viewport in the main axis direction, '
'consider a RenderShrinkWrappingViewport render object (ShrinkWrappingViewport widget), '
'which achieves that effect without implementing the intrinsic dimension API.'
);
}
return true;
});
return true;
}
@override
double computeMinIntrinsicWidth(double height) {
assert(debugThrowIfNotCheckingIntrinsics());
return 0.0;
}
@override
double computeMaxIntrinsicWidth(double height) {
assert(debugThrowIfNotCheckingIntrinsics());
return 0.0;
}
@override
double computeMinIntrinsicHeight(double width) {
assert(debugThrowIfNotCheckingIntrinsics());
return 0.0;
}
@override
double computeMaxIntrinsicHeight(double width) {
assert(debugThrowIfNotCheckingIntrinsics());
return 0.0;
}
@override @override
bool get isRepaintBoundary => true; bool get isRepaintBoundary => true;
...@@ -161,8 +211,8 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix ...@@ -161,8 +211,8 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
/// * `remainingPaintExtent` is [SliverConstraints.remainingPaintExtent] to /// * `remainingPaintExtent` is [SliverConstraints.remainingPaintExtent] to
/// pass the first child. The remaining paint extent is updated by the /// pass the first child. The remaining paint extent is updated by the
/// [SliverGeometry.layoutExtent] for subsequent children. /// [SliverGeometry.layoutExtent] for subsequent children.
/// * `mainAxisExtent` is the [SliverConstraints.mainAxisExtent] to pass to /// * `mainAxisExtent` is the [SliverConstraints.viewportMainAxisExtent] to
/// each child. /// pass to each child.
/// * `crossAxisExtent` is the [SliverConstraints.crossAxisExtent] to pass to /// * `crossAxisExtent` is the [SliverConstraints.crossAxisExtent] to pass to
/// each child. /// each child.
/// * `growthDirection` is the [SliverConstraints.growthDirection] to pass to /// * `growthDirection` is the [SliverConstraints.growthDirection] to pass to
...@@ -1024,6 +1074,24 @@ class RenderShrinkWrappingViewport extends RenderViewportBase<SliverLogicalConta ...@@ -1024,6 +1074,24 @@ class RenderShrinkWrappingViewport extends RenderViewportBase<SliverLogicalConta
child.parentData = new SliverLogicalContainerParentData(); child.parentData = new SliverLogicalContainerParentData();
} }
@override
bool debugThrowIfNotCheckingIntrinsics() {
assert(() {
if (!RenderObject.debugCheckingIntrinsics) {
throw new FlutterError(
'$runtimeType does not support returning intrinsic dimensions.\n'
'Calculating the intrinsic dimensions would require instantiating every child of '
'the viewport, which defeats the point of viewports being lazy.\n'
'If you are merely trying to shrink-wrap the viewport in the main axis direction, '
'you should be able to achieve that effect by just giving the viewport loose '
'constraints, without needing to measure its intrinsic dimensions.'
);
}
return true;
});
return true;
}
// Out-of-band data computed during layout. // Out-of-band data computed during layout.
double _maxScrollExtent; double _maxScrollExtent;
double _shrinkWrapExtent; double _shrinkWrapExtent;
......
...@@ -55,7 +55,7 @@ ScrollDirection flipScrollDirection(ScrollDirection direction) { ...@@ -55,7 +55,7 @@ ScrollDirection flipScrollDirection(ScrollDirection direction) {
/// select which part of its content to display. As the user scrolls the /// select which part of its content to display. As the user scrolls the
/// viewport, this value changes, which changes the content that is displayed. /// viewport, this value changes, which changes the content that is displayed.
/// ///
/// This object is a [Listable] that notifies its listeners when [pixels] /// This object is a [Listenable] that notifies its listeners when [pixels]
/// changes. /// changes.
/// ///
/// See also: /// See also:
...@@ -155,13 +155,15 @@ abstract class ViewportOffset extends ChangeNotifier { ...@@ -155,13 +155,15 @@ abstract class ViewportOffset extends ChangeNotifier {
/// The direction in which the user is trying to change [pixels], relative to /// The direction in which the user is trying to change [pixels], relative to
/// the viewport's [RenderViewport.axisDirection]. /// the viewport's [RenderViewport.axisDirection].
/// ///
/// If the user is not scrolling, this will return [ScrollDirection.idle] even /// If the _user_ is not scrolling, this will return [ScrollDirection.idle]
/// if there is an [activity] currently animating the position. /// even if there is (for example) a [ScrollActivity] currently animating the
/// position.
/// ///
/// This is used by some slivers to determine how to react to a change in /// This is exposed in [SliverConstraints.userScrollDirection], which is used
/// scroll offset. For example, [RenderSliverFloatingPersistentHeader] will /// by some slivers to determine how to react to a change in scroll offset.
/// only expand a floating app bar when the [userScrollDirection] is in the /// For example, [RenderSliverFloatingPersistentHeader] will only expand a
/// positive scroll offset direction. /// floating app bar when the [userScrollDirection] is in the positive scroll
/// offset direction.
ScrollDirection get userScrollDirection; ScrollDirection get userScrollDirection;
@override @override
......
...@@ -214,7 +214,7 @@ class RenderWrap extends RenderBox with ContainerRenderObjectMixin<RenderBox, Wr ...@@ -214,7 +214,7 @@ class RenderWrap extends RenderBox with ContainerRenderObjectMixin<RenderBox, Wr
/// the cross axis. /// the cross axis.
/// ///
/// For example, if this is set to [WrapCrossAlignment.end], and the /// For example, if this is set to [WrapCrossAlignment.end], and the
/// [direction] is [WrapDirection.horizontal], then the children within each /// [direction] is [Axis.horizontal], then the children within each
/// run will have their bottom edges aligned to the bottom edge of the run. /// run will have their bottom edges aligned to the bottom edge of the run.
/// ///
/// Defaults to [WrapCrossAlignment.start]. /// Defaults to [WrapCrossAlignment.start].
......
...@@ -98,7 +98,7 @@ class _FrameCallbackEntry { ...@@ -98,7 +98,7 @@ class _FrameCallbackEntry {
/// The values of this enum are ordered in the same order as the phases occur, /// The values of this enum are ordered in the same order as the phases occur,
/// so their relative index values can be compared to each other. /// so their relative index values can be compared to each other.
/// ///
/// See also [WidgetsBinding.beginFrame]. /// See also the discussion at [WidgetsBinding.drawFrame].
enum SchedulerPhase { enum SchedulerPhase {
/// No frame is being processed. Tasks (scheduled by /// No frame is being processed. Tasks (scheduled by
/// [WidgetsBinding.scheduleTask]), microtasks (scheduled by /// [WidgetsBinding.scheduleTask]), microtasks (scheduled by
...@@ -113,7 +113,7 @@ enum SchedulerPhase { ...@@ -113,7 +113,7 @@ enum SchedulerPhase {
/// Typically, these callbacks handle updating objects to new animation /// Typically, these callbacks handle updating objects to new animation
/// states. /// states.
/// ///
/// See [handleBeginFrame]. /// See [SchedulerBinding.handleBeginFrame].
transientCallbacks, transientCallbacks,
/// Microtasks scheduled during the processing of transient callbacks are /// Microtasks scheduled during the processing of transient callbacks are
...@@ -127,7 +127,7 @@ enum SchedulerPhase { ...@@ -127,7 +127,7 @@ enum SchedulerPhase {
/// [WidgetsBinding.addPersistentFrameCallback]) are currently executing. /// [WidgetsBinding.addPersistentFrameCallback]) are currently executing.
/// ///
/// Typically, this is the build/layout/paint pipeline. See /// Typically, this is the build/layout/paint pipeline. See
/// [WidgetsBinding.drawFrame] and [handleDrawFrame]. /// [WidgetsBinding.drawFrame] and [SchedulerBinding.handleDrawFrame].
persistentCallbacks, persistentCallbacks,
/// The post-frame callbacks (scheduled by /// The post-frame callbacks (scheduled by
...@@ -136,24 +136,24 @@ enum SchedulerPhase { ...@@ -136,24 +136,24 @@ enum SchedulerPhase {
/// Typically, these callbacks handle cleanup and scheduling of work for the /// Typically, these callbacks handle cleanup and scheduling of work for the
/// next frame. /// next frame.
/// ///
/// See [handleDrawFrame]. /// See [SchedulerBinding.handleDrawFrame].
postFrameCallbacks, postFrameCallbacks,
} }
/// Scheduler for running the following: /// Scheduler for running the following:
/// ///
/// * _Transient callbacks_, triggered by the system's [ui.window.onBeginFrame] /// * _Transient callbacks_, triggered by the system's [Window.onBeginFrame]
/// callback, for synchronizing the application's behavior to the system's /// callback, for synchronizing the application's behavior to the system's
/// display. For example, [Ticker]s and [AnimationController]s trigger from /// display. For example, [Ticker]s and [AnimationController]s trigger from
/// these. /// these.
/// ///
/// * _Persistent callbacks_, triggered by the system's [ui.window.onDrawFrame] /// * _Persistent callbacks_, triggered by the system's [Window.onDrawFrame]
/// callback, for updating the system's display after transient callbacks have /// callback, for updating the system's display after transient callbacks have
/// executed. For example, the rendering layer uses this to drive its /// executed. For example, the rendering layer uses this to drive its
/// rendering pipeline. /// rendering pipeline.
/// ///
/// * _Post-frame callbacks_, which are run after persistent callbacks, just /// * _Post-frame callbacks_, which are run after persistent callbacks, just
/// before returning from the [ui.window.onDrawFrame] callback. /// before returning from the [Window.onDrawFrame] callback.
/// ///
/// * Non-rendering tasks, to be run between frames. These are given a /// * Non-rendering tasks, to be run between frames. These are given a
/// priority and are executed in priority order according to a /// priority and are executed in priority order according to a
...@@ -475,7 +475,7 @@ abstract class SchedulerBinding extends BindingBase { ...@@ -475,7 +475,7 @@ abstract class SchedulerBinding extends BindingBase {
} }
/// If necessary, schedules a new frame by calling /// If necessary, schedules a new frame by calling
/// [ui.window.scheduleFrame]. /// [Window.scheduleFrame].
/// ///
/// After this is called, the engine will (eventually) call /// After this is called, the engine will (eventually) call
/// [handleBeginFrame]. (This call might be delayed, e.g. if the device's /// [handleBeginFrame]. (This call might be delayed, e.g. if the device's
......
...@@ -21,7 +21,7 @@ import 'package:flutter/foundation.dart'; ...@@ -21,7 +21,7 @@ import 'package:flutter/foundation.dart';
/// intra-frame output from inter-frame output, set [debugPrintEndFrameBanner] /// intra-frame output from inter-frame output, set [debugPrintEndFrameBanner]
/// to true as well. /// to true as well.
/// ///
/// See [SchedulerBinding.beginFrame]. /// See [SchedulerBinding.handleBeginFrame].
bool debugPrintBeginFrameBanner = false; bool debugPrintBeginFrameBanner = false;
/// Print a banner at the end of each frame. /// Print a banner at the end of each frame.
...@@ -32,7 +32,7 @@ bool debugPrintEndFrameBanner = false; ...@@ -32,7 +32,7 @@ bool debugPrintEndFrameBanner = false;
/// Log the call stacks that cause a frame to be scheduled. /// Log the call stacks that cause a frame to be scheduled.
/// ///
/// This is called whenever [Scheduler.scheduleFrame] schedules a frame. This /// This is called whenever [SchedulerBinding.scheduleFrame] schedules a frame. This
/// can happen for various reasons, e.g. when a [Ticker] or /// can happen for various reasons, e.g. when a [Ticker] or
/// [AnimationController] is started, or when [RenderObject.markNeedsLayout] is /// [AnimationController] is started, or when [RenderObject.markNeedsLayout] is
/// called, or when [State.setState] is called. /// called, or when [State.setState] is called.
......
...@@ -8,7 +8,7 @@ import 'package:flutter/foundation.dart'; ...@@ -8,7 +8,7 @@ import 'package:flutter/foundation.dart';
import 'binding.dart'; import 'binding.dart';
/// Signature for the [onTick] constructor argument of the [Ticker] class. /// Signature for the callback passed to the [Ticker] class's constructor.
/// ///
/// The argument is the time that the object had spent enabled so far /// The argument is the time that the object had spent enabled so far
/// at the time of the callback being called. /// at the time of the callback being called.
...@@ -54,7 +54,8 @@ abstract class TickerProvider { ...@@ -54,7 +54,8 @@ abstract class TickerProvider {
/// Tickers are driven by the [SchedulerBinding]. See /// Tickers are driven by the [SchedulerBinding]. See
/// [SchedulerBinding.scheduleFrameCallback]. /// [SchedulerBinding.scheduleFrameCallback].
class Ticker { class Ticker {
/// Creates a ticker that will call [onTick] once per frame while running. /// Creates a ticker that will call the provided callback once per frame while
/// running.
/// ///
/// An optional label can be provided for debugging purposes. That label /// An optional label can be provided for debugging purposes. That label
/// will appear in the [toString] output in debug builds. /// will appear in the [toString] output in debug builds.
......
...@@ -12,7 +12,7 @@ const int _kDefaultSize = 1000; ...@@ -12,7 +12,7 @@ const int _kDefaultSize = 1000;
/// size can be adjusted using [maximumSize]. Images that are actively in use /// size can be adjusted using [maximumSize]. Images that are actively in use
/// (i.e. to which the application is holding references, either via /// (i.e. to which the application is holding references, either via
/// [ImageStream] objects, [ImageStreamCompleter] objects, [ImageInfo] objects, /// [ImageStream] objects, [ImageStreamCompleter] objects, [ImageInfo] objects,
/// or raw [ui.Image] objects) may get evicted from the cache (and thus need to /// or raw [Image] objects) may get evicted from the cache (and thus need to
/// be refetched from the network if they are referenced in the [putIfAbsent] /// be refetched from the network if they are referenced in the [putIfAbsent]
/// method), but the raw bits are kept in memory for as long as the application /// method), but the raw bits are kept in memory for as long as the application
/// is using them. /// is using them.
......
...@@ -10,7 +10,7 @@ import 'dart:ui' as ui show Image, decodeImageFromList; ...@@ -10,7 +10,7 @@ import 'dart:ui' as ui show Image, decodeImageFromList;
/// ///
/// This function attempts to interpret the given bytes an image. If successful, /// This function attempts to interpret the given bytes an image. If successful,
/// the returned [Future] resolves to the decoded image. Otherwise, the [Future] /// the returned [Future] resolves to the decoded image. Otherwise, the [Future]
/// resolves to [null]. /// resolves to null.
Future<ui.Image> decodeImageFromList(Uint8List list) { Future<ui.Image> decodeImageFromList(Uint8List list) {
final Completer<ui.Image> completer = new Completer<ui.Image>(); final Completer<ui.Image> completer = new Completer<ui.Image>();
ui.decodeImageFromList(list, completer.complete); ui.decodeImageFromList(list, completer.complete);
......
...@@ -34,7 +34,7 @@ class ImageInfo { ...@@ -34,7 +34,7 @@ class ImageInfo {
/// ///
/// For example, if this is 2.0 it means that there are four image pixels for /// For example, if this is 2.0 it means that there are four image pixels for
/// every one logical pixel, and the image's actual width and height (as given /// every one logical pixel, and the image's actual width and height (as given
/// by the [ui.Image.width] and [ui.Image.height] properties) are double the /// by the [Image.width] and [Image.height] properties) are double the
/// height and width that should be used when painting the image (e.g. in the /// height and width that should be used when painting the image (e.g. in the
/// arguments given to [Canvas.drawImage]). /// arguments given to [Canvas.drawImage]).
final double scale; final double scale;
......
...@@ -16,7 +16,7 @@ import 'platform_channel.dart'; ...@@ -16,7 +16,7 @@ import 'platform_channel.dart';
/// ///
/// See also: /// See also:
/// ///
/// * [PlatformMessageChannel], which use [MessageCodec]s for communication /// * [MessageChannel], which use [MessageCodec]s for communication
/// between Flutter and platform plugins. /// between Flutter and platform plugins.
abstract class MessageCodec<T> { abstract class MessageCodec<T> {
/// Encodes the specified [message] in binary. /// Encodes the specified [message] in binary.
...@@ -99,9 +99,9 @@ class MethodCall { ...@@ -99,9 +99,9 @@ class MethodCall {
/// ///
/// See also: /// See also:
/// ///
/// * [PlatformMethodChannel], which use [MethodCodec]s for communication /// * [MethodChannel], which use [MethodCodec]s for communication
/// between Flutter and platform plugins. /// between Flutter and platform plugins.
/// * [PlatformEventChannel], which use [MethodCodec]s for communication /// * [EventChannel], which use [MethodCodec]s for communication
/// between Flutter and platform plugins. /// between Flutter and platform plugins.
abstract class MethodCodec { abstract class MethodCodec {
/// Encodes the specified [methodCall] into binary. /// Encodes the specified [methodCall] into binary.
......
...@@ -55,7 +55,7 @@ class BinaryMessages { ...@@ -55,7 +55,7 @@ class BinaryMessages {
/// Calls the handler registered for the given channel. /// Calls the handler registered for the given channel.
/// ///
/// Typically called by [ServicesBinding] to handle platform messages received /// Typically called by [ServicesBinding] to handle platform messages received
/// from [ui.window.onPlatformMessage]. /// from [Window.onPlatformMessage].
/// ///
/// To register a handler for a given message channel, see [setMessageHandler]. /// To register a handler for a given message channel, see [setMessageHandler].
static Future<Null> handlePlatformMessage( static Future<Null> handlePlatformMessage(
......
...@@ -133,7 +133,7 @@ class BlacklistingTextInputFormatter extends TextInputFormatter { ...@@ -133,7 +133,7 @@ class BlacklistingTextInputFormatter extends TextInputFormatter {
class WhitelistingTextInputFormatter extends TextInputFormatter { class WhitelistingTextInputFormatter extends TextInputFormatter {
/// Creates a formatter that allows only the insertion of whitelisted characters patterns. /// Creates a formatter that allows only the insertion of whitelisted characters patterns.
/// ///
/// The [blacklistedPattern] must not be null. /// The [whitelistedPattern] must not be null.
WhitelistingTextInputFormatter(this.whitelistedPattern) : WhitelistingTextInputFormatter(this.whitelistedPattern) :
assert(whitelistedPattern != null); assert(whitelistedPattern != null);
......
...@@ -59,11 +59,13 @@ class AnimatedCrossFade extends StatefulWidget { ...@@ -59,11 +59,13 @@ class AnimatedCrossFade extends StatefulWidget {
super(key: key); super(key: key);
/// The child that is visible when [crossFadeState] is [showFirst]. It fades /// The child that is visible when [crossFadeState] is [showFirst]. It fades
/// out when transitioning from [showFirst] to [showSecond] and vice versa. /// out when transitioning [crossFadeState] from [CrossFadeState.showFirst] to
/// [CrossFadeState.showSecond] and vice versa.
final Widget firstChild; final Widget firstChild;
/// The child that is visible when [crossFadeState] is [showSecond]. It fades /// The child that is visible when [crossFadeState] is [showSecond]. It fades
/// in when transitioning from [showFirst] to [showSecond] and vice versa. /// in when transitioning [crossFadeState] from [CrossFadeState.showFirst] to
/// [CrossFadeState.showSecond] and vice versa.
final Widget secondChild; final Widget secondChild;
/// The child that will be shown when the animation has completed. /// The child that will be shown when the animation has completed.
......
...@@ -178,8 +178,8 @@ class AnimatedList extends StatefulWidget { ...@@ -178,8 +178,8 @@ class AnimatedList extends StatefulWidget {
/// The state for a scrolling container that animates items when they are /// The state for a scrolling container that animates items when they are
/// inserted or removed. /// inserted or removed.
/// ///
/// When an item is inserted with [insertItem] an animation begins running. /// When an item is inserted with [insertItem] an animation begins running. The
/// The animation is passed to [itemBuilder] whenever the item's widget /// animation is passed to [AnimatedList.itemBuilder] whenever the item's widget
/// is needed. /// is needed.
/// ///
/// When an item is removed with [removeItem] its animation is reversed. /// When an item is removed with [removeItem] its animation is reversed.
...@@ -197,8 +197,8 @@ class AnimatedList extends StatefulWidget { ...@@ -197,8 +197,8 @@ class AnimatedList extends StatefulWidget {
/// listKey.currentState.insert(123); /// listKey.currentState.insert(123);
/// ``` /// ```
/// ///
/// AnimatedList item input handlers can also refer to their [AnimatedListState] /// [AnimatedList] item input handlers can also refer to their [AnimatedListState]
/// with the static [of] method. /// with the static [AnimatedList.of] method.
class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixin { class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixin {
final List<_ActiveItem> _incomingItems = <_ActiveItem>[]; final List<_ActiveItem> _incomingItems = <_ActiveItem>[];
final List<_ActiveItem> _outgoingItems = <_ActiveItem>[]; final List<_ActiveItem> _outgoingItems = <_ActiveItem>[];
...@@ -259,7 +259,7 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi ...@@ -259,7 +259,7 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi
} }
/// Insert an item at [index] and start an animation that will be passed /// Insert an item at [index] and start an animation that will be passed
/// to [itemBuilder] when the item is visible. /// to [AnimatedList.itemBuilder] when the item is visible.
/// ///
/// This method's semantics are the same as Dart's [List.insert] method: /// This method's semantics are the same as Dart's [List.insert] method:
/// it increases the length of the list by one and shifts all items at or /// it increases the length of the list by one and shifts all items at or
...@@ -300,9 +300,9 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi ...@@ -300,9 +300,9 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi
/// to [builder] when the item is visible. /// to [builder] when the item is visible.
/// ///
/// Items are removed immediately. After an item has been removed, its index /// Items are removed immediately. After an item has been removed, its index
/// will no longer be passed to the [itemBuilder]. However the item will still /// will no longer be passed to the [AnimatedList.itemBuilder]. However the
/// appear in the list for [duration] and during that time [builder] must /// item will still appear in the list for [duration] and during that time
/// construct its widget as needed. /// [builder] must construct its widget as needed.
/// ///
/// This method's semantics are the same as Dart's [List.remove] method: /// This method's semantics are the same as Dart's [List.remove] method:
/// it decreases the length of the list by one and shifts all items at or /// it decreases the length of the list by one and shifts all items at or
......
...@@ -47,8 +47,8 @@ abstract class StreamBuilderBase<T, S> extends StatefulWidget { ...@@ -47,8 +47,8 @@ abstract class StreamBuilderBase<T, S> extends StatefulWidget {
/// The asynchronous computation to which this builder is currently connected, /// The asynchronous computation to which this builder is currently connected,
/// possibly null. When changed, the current summary is updated using /// possibly null. When changed, the current summary is updated using
/// [afterDisconnecting], if the previous stream was not null, followed by /// [afterDisconnected], if the previous stream was not null, followed by
/// [afterConnecting], if the new stream is not null. /// [afterConnected], if the new stream is not null.
final Stream<T> stream; final Stream<T> stream;
/// Returns the initial summary of stream interaction, typically representing /// Returns the initial summary of stream interaction, typically representing
...@@ -349,17 +349,17 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> { ...@@ -349,17 +349,17 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// ///
/// Widget rebuilding is scheduled by the completion of the future, using /// Widget rebuilding is scheduled by the completion of the future, using
/// [State.setState], but is otherwise decoupled from the timing of the future. /// [State.setState], but is otherwise decoupled from the timing of the future.
/// The [build] method is called at the discretion of the Flutter pipeline, and /// The [builder] callback is called at the discretion of the Flutter pipeline, and
/// will thus receive a timing-dependent sub-sequence of the snapshots that /// will thus receive a timing-dependent sub-sequence of the snapshots that
/// represent the interaction with the future. /// represent the interaction with the future.
/// ///
/// For a future that completes successfully with data, the [build] method may /// For a future that completes successfully with data, the [builder] may
/// be called with either both or only the latter of the following snapshots: /// be called with either both or only the latter of the following snapshots:
/// ///
/// * `new AsyncSnapshot<String>(ConnectionState.waiting, null, null)` /// * `new AsyncSnapshot<String>(ConnectionState.waiting, null, null)`
/// * `new AsyncSnapshot<String>(ConnectionState.done, 'some data', null)` /// * `new AsyncSnapshot<String>(ConnectionState.done, 'some data', null)`
/// ///
/// For a future completing with an error, the [build] method may be called with /// For a future completing with an error, the [builder] may be called with
/// either both or only the latter of: /// either both or only the latter of:
/// ///
/// * `new AsyncSnapshot<String>(ConnectionState.waiting, null, null)` /// * `new AsyncSnapshot<String>(ConnectionState.waiting, null, null)`
......
...@@ -103,7 +103,7 @@ class Opacity extends SingleChildRenderObjectWidget { ...@@ -103,7 +103,7 @@ class Opacity extends SingleChildRenderObjectWidget {
/// A widget that applies a mask generated by a [Shader] to its child. /// A widget that applies a mask generated by a [Shader] to its child.
/// ///
/// For example, [ShaderMask] can be used to gradually fade out the edge /// For example, [ShaderMask] can be used to gradually fade out the edge
/// of a child by using a [ui.Gradient.linear] mask. /// of a child by using a [new ui.Gradient.linear] mask.
class ShaderMask extends SingleChildRenderObjectWidget { class ShaderMask extends SingleChildRenderObjectWidget {
/// Creates a widget that applies a mask generated by a [Shader] to its child. /// Creates a widget that applies a mask generated by a [Shader] to its child.
/// ///
...@@ -162,7 +162,7 @@ class BackdropFilter extends SingleChildRenderObjectWidget { ...@@ -162,7 +162,7 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
/// The image filter to apply to the existing painted content before painting the child. /// The image filter to apply to the existing painted content before painting the child.
/// ///
/// For example, consider using [ui.ImageFilter.blur] to create a backdrop /// For example, consider using [ImageFilter.blur] to create a backdrop
/// blur effect /// blur effect
final ui.ImageFilter filter; final ui.ImageFilter filter;
...@@ -1152,7 +1152,7 @@ class LimitedBox extends SingleChildRenderObjectWidget { ...@@ -1152,7 +1152,7 @@ class LimitedBox extends SingleChildRenderObjectWidget {
/// A widget that imposes different constraints on its child than it gets /// A widget that imposes different constraints on its child than it gets
/// from its parent, possibly allowing the child to overflow the parent. /// from its parent, possibly allowing the child to overflow the parent.
/// ///
/// See [RenderOverflowBox] for details. /// See [RenderConstrainedOverflowBox] for details.
class OverflowBox extends SingleChildRenderObjectWidget { class OverflowBox extends SingleChildRenderObjectWidget {
/// Creates a widget that lets its child overflow itself. /// Creates a widget that lets its child overflow itself.
const OverflowBox({ const OverflowBox({
...@@ -1520,10 +1520,10 @@ class SliverToBoxAdapter extends SingleChildRenderObjectWidget { ...@@ -1520,10 +1520,10 @@ class SliverToBoxAdapter extends SingleChildRenderObjectWidget {
/// side. /// side.
/// ///
/// Applying padding to anything but the most mundane sliver is likely to have /// Applying padding to anything but the most mundane sliver is likely to have
/// undesired effects. For example, wrapping a /// undesired effects. For example, wrapping a [SliverPersistentHeader] with
/// [SliverPinnedPersistentHeader] will cause the app bar to overlap /// `pinned:true` will cause the app bar to overlap earlier slivers (contrary to
/// earlier slivers (contrary to the normal behavior of pinned app bars), and /// the normal behavior of pinned app bars), and while the app bar is pinned,
/// while the app bar is pinned, the padding will scroll away. /// the padding will scroll away.
/// ///
/// See also: /// See also:
/// ///
...@@ -1671,7 +1671,7 @@ class Stack extends MultiChildRenderObjectWidget { ...@@ -1671,7 +1671,7 @@ class Stack extends MultiChildRenderObjectWidget {
/// Whether overflowing children should be clipped. See [Overflow]. /// Whether overflowing children should be clipped. See [Overflow].
/// ///
/// Some children in a stack might overflow its box. When this flag is set to /// Some children in a stack might overflow its box. When this flag is set to
/// [Overflow.clipped], children cannot paint outside of the stack's box. /// [Overflow.clip], children cannot paint outside of the stack's box.
final Overflow overflow; final Overflow overflow;
@override @override
...@@ -1921,7 +1921,7 @@ class Positioned extends ParentDataWidget<Stack> { ...@@ -1921,7 +1921,7 @@ class Positioned extends ParentDataWidget<Stack> {
/// The [Flex] widget does not scroll (and in general it is considered an error /// The [Flex] widget does not scroll (and in general it is considered an error
/// to have more children in a [Flex] than will fit in the available room). If /// to have more children in a [Flex] than will fit in the available room). If
/// you have some widgets and want them to be able to scroll if there is /// you have some widgets and want them to be able to scroll if there is
/// insufficient room, consider using a [ScrollList]. /// insufficient room, consider using a [ListView].
/// ///
/// If you only have one child, then rather than using [Flex], [Row], or /// If you only have one child, then rather than using [Flex], [Row], or
/// [Column], consider using [Align] or [Center] to position the child. /// [Column], consider using [Align] or [Center] to position the child.
...@@ -2050,7 +2050,7 @@ class Flex extends MultiChildRenderObjectWidget { ...@@ -2050,7 +2050,7 @@ class Flex extends MultiChildRenderObjectWidget {
/// The [Row] widget does not scroll (and in general it is considered an error /// 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 /// 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 /// you have a line of widgets and want them to be able to scroll if there is
/// insufficient room, consider using a [ScrollList]. /// insufficient room, consider using a [ListView].
/// ///
/// For a vertical variant, see [Column]. /// For a vertical variant, see [Column].
/// ///
...@@ -2121,7 +2121,7 @@ class Row extends Flex { ...@@ -2121,7 +2121,7 @@ class Row extends Flex {
/// The [Column] widget does not scroll (and in general it is considered an error /// The [Column] widget does not scroll (and in general it is considered an error
/// to have more children in a [Column] than will fit in the available room). If /// to have more children in a [Column] 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 /// you have a line of widgets and want them to be able to scroll if there is
/// insufficient room, consider using a [ScrollList]. /// insufficient room, consider using a [ListView].
/// ///
/// For a horizontal variant, see [Row]. /// For a horizontal variant, see [Row].
/// ///
...@@ -2380,7 +2380,7 @@ class Wrap extends MultiChildRenderObjectWidget { ...@@ -2380,7 +2380,7 @@ class Wrap extends MultiChildRenderObjectWidget {
/// the cross axis. /// the cross axis.
/// ///
/// For example, if this is set to [WrapCrossAlignment.end], and the /// For example, if this is set to [WrapCrossAlignment.end], and the
/// [direction] is [WrapDirection.horizontal], then the children within each /// [direction] is [Axis.horizontal], then the children within each
/// run will have their bottom edges aligned to the bottom edge of the run. /// run will have their bottom edges aligned to the bottom edge of the run.
/// ///
/// Defaults to [WrapCrossAlignment.start]. /// Defaults to [WrapCrossAlignment.start].
...@@ -2590,7 +2590,7 @@ class RichText extends LeafRenderObjectWidget { ...@@ -2590,7 +2590,7 @@ class RichText extends LeafRenderObjectWidget {
} }
} }
/// A widget that displays a [ui.Image] directly. /// A widget that displays a [dart:ui.Image] directly.
/// ///
/// The image is painted using [paintImage], which describes the meanings of the /// The image is painted using [paintImage], which describes the meanings of the
/// various fields on this class in more detail. /// various fields on this class in more detail.
...@@ -2937,7 +2937,7 @@ class RepaintBoundary extends SingleChildRenderObjectWidget { ...@@ -2937,7 +2937,7 @@ class RepaintBoundary extends SingleChildRenderObjectWidget {
/// When [ignoring] is true, this widget (and its subtree) is invisible /// When [ignoring] is true, this widget (and its subtree) is invisible
/// to hit testing. It still consumes space during layout and paints its child /// to hit testing. It still consumes space during layout and paints its child
/// as usual. It just cannot be the target of located events, because it returns /// as usual. It just cannot be the target of located events, because it returns
/// false from [hitTest]. /// false from [RenderBox.hitTest].
/// ///
/// When [ignoringSemantics] is true, the subtree will be invisible to /// When [ignoringSemantics] is true, the subtree will be invisible to
/// the semantics layer (and thus e.g. accessibility tools). If /// the semantics layer (and thus e.g. accessibility tools). If
...@@ -3001,7 +3001,7 @@ class IgnorePointer extends SingleChildRenderObjectWidget { ...@@ -3001,7 +3001,7 @@ class IgnorePointer extends SingleChildRenderObjectWidget {
/// pointer events by terminating hit testing at itself. It still consumes space /// pointer events by terminating hit testing at itself. It still consumes space
/// during layout and paints its child as usual. It just prevents its children /// during layout and paints its child as usual. It just prevents its children
/// from being the target of located events, because it returns true from /// from being the target of located events, because it returns true from
/// [hitTest]. /// [RenderBox.hitTest].
/// ///
/// See also: /// See also:
/// ///
......
...@@ -154,7 +154,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren ...@@ -154,7 +154,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
/// Notifies all the observers using /// Notifies all the observers using
/// [WidgetsBindingObserver.didChangeMetrics]. /// [WidgetsBindingObserver.didChangeMetrics].
/// ///
/// See [ui.window.onMetricsChanged]. /// See [window.onMetricsChanged].
@override @override
void handleMetricsChanged() { void handleMetricsChanged() {
super.handleMetricsChanged(); super.handleMetricsChanged();
...@@ -166,7 +166,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren ...@@ -166,7 +166,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
/// ///
/// Calls [dispatchLocaleChanged] to notify the binding observers. /// Calls [dispatchLocaleChanged] to notify the binding observers.
/// ///
/// See [ui.window.onLocaleChanged]. /// See [Window.onLocaleChanged].
void handleLocaleChanged() { void handleLocaleChanged() {
dispatchLocaleChanged(ui.window.locale); dispatchLocaleChanged(ui.window.locale);
} }
...@@ -293,7 +293,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren ...@@ -293,7 +293,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
/// Each frame consists of the following phases: /// Each frame consists of the following phases:
/// ///
/// 1. The animation phase: The [handleBeginFrame] method, which is registered /// 1. The animation phase: The [handleBeginFrame] method, which is registered
/// with [ui.window.onBeginFrame], invokes all the transient frame callbacks /// with [window.onBeginFrame], invokes all the transient frame callbacks
/// registered with [scheduleFrameCallback], in /// registered with [scheduleFrameCallback], in
/// registration order. This includes all the [Ticker] instances that are /// registration order. This includes all the [Ticker] instances that are
/// driving [AnimationController] objects, which means all of the active /// driving [AnimationController] objects, which means all of the active
...@@ -305,7 +305,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren ...@@ -305,7 +305,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
/// completed this frame. /// completed this frame.
/// ///
/// After [handleBeginFrame], [handleDrawFrame], which is registered with /// After [handleBeginFrame], [handleDrawFrame], which is registered with
/// [ui.window.onDrawFrame], is called, which invokes all the persistent frame /// [window.onDrawFrame], is called, which invokes all the persistent frame
/// callbacks, of which the most notable is this method, [drawFrame], which /// callbacks, of which the most notable is this method, [drawFrame], which
/// proceeds as follows: /// proceeds as follows:
/// ///
...@@ -327,7 +327,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren ...@@ -327,7 +327,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
/// [RenderObject.markNeedsPaint] for further details on marking an object /// [RenderObject.markNeedsPaint] for further details on marking an object
/// dirty for paint. /// dirty for paint.
/// ///
/// 7. The compositing phase: The layer tree is turned into a [ui.Scene] and /// 7. The compositing phase: The layer tree is turned into a [Scene] and
/// sent to the GPU. /// sent to the GPU.
/// ///
/// 8. The semantics phase: All the dirty [RenderObject]s in the system have /// 8. The semantics phase: All the dirty [RenderObject]s in the system have
......
...@@ -85,7 +85,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget { ...@@ -85,7 +85,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
/// ///
/// A container first surrounds the child with [padding] (inflated by any /// A container first surrounds the child with [padding] (inflated by any
/// borders present in the [decoration]) and then applies additional /// borders present in the [decoration]) and then applies additional
/// [constraints] to the padded extent (incorporating the [width] and [height] /// [constraints] to the padded extent (incorporating the `width` and `height`
/// as constraints, if either is non-null). The container is then surrounded by /// as constraints, if either is non-null). The container is then surrounded by
/// additional empty space described from the [margin]. /// additional empty space described from the [margin].
/// ///
......
...@@ -3,6 +3,7 @@ ...@@ -3,6 +3,7 @@
// found in the LICENSE file. // found in the LICENSE file.
import 'dart:collection'; import 'dart:collection';
import 'dart:developer' show Timeline; // to disambiguate reference in dartdocs below
import 'package:flutter/foundation.dart'; import 'package:flutter/foundation.dart';
...@@ -18,10 +19,12 @@ import 'table.dart'; ...@@ -18,10 +19,12 @@ import 'table.dart';
/// Combined with [debugPrintBuildScope] or [debugPrintBeginFrameBanner], this /// Combined with [debugPrintBuildScope] or [debugPrintBeginFrameBanner], this
/// allows you to distinguish builds triggered by the initial mounting of a /// allows you to distinguish builds triggered by the initial mounting of a
/// widget tree (e.g. in a call to [runApp]) from the regular builds triggered /// widget tree (e.g. in a call to [runApp]) from the regular builds triggered
/// by the pipeline (see [WidgetsBinding.beginFrame]. /// by the pipeline.
/// ///
/// Combined with [debugPrintScheduleBuildForStacks], this lets you watch a /// Combined with [debugPrintScheduleBuildForStacks], this lets you watch a
/// widget's dirty/clean lifecycle. /// widget's dirty/clean lifecycle.
///
/// See also the discussion at [WidgetsBinding.drawFrame].
bool debugPrintRebuildDirtyWidgets = false; bool debugPrintRebuildDirtyWidgets = false;
/// Log all calls to [BuildOwner.buildScope]. /// Log all calls to [BuildOwner.buildScope].
...@@ -32,8 +35,9 @@ bool debugPrintRebuildDirtyWidgets = false; ...@@ -32,8 +35,9 @@ bool debugPrintRebuildDirtyWidgets = false;
/// Combined with [debugPrintRebuildDirtyWidgets] or /// Combined with [debugPrintRebuildDirtyWidgets] or
/// [debugPrintBeginFrameBanner], this allows you to distinguish builds /// [debugPrintBeginFrameBanner], this allows you to distinguish builds
/// triggered by the initial mounting of a widget tree (e.g. in a call to /// triggered by the initial mounting of a widget tree (e.g. in a call to
/// [runApp]) from the regular builds triggered by the pipeline (see /// [runApp]) from the regular builds triggered by the pipeline.
/// [WidgetsBinding.beginFrame]. ///
/// See also the discussion at [WidgetsBinding.drawFrame].
bool debugPrintBuildScope = false; bool debugPrintBuildScope = false;
/// Log the call stacks that mark widgets as needing to be rebuilt. /// Log the call stacks that mark widgets as needing to be rebuilt.
...@@ -44,7 +48,7 @@ bool debugPrintBuildScope = false; ...@@ -44,7 +48,7 @@ bool debugPrintBuildScope = false;
/// ///
/// To see when a widget is rebuilt, see [debugPrintRebuildDirtyWidgets]. /// To see when a widget is rebuilt, see [debugPrintRebuildDirtyWidgets].
/// ///
/// To see when the dirty list is flushed, see [debugPrintBuildDirtyElements]. /// To see when the dirty list is flushed, see [debugPrintBuildScope].
/// ///
/// To see when a frame is scheduled, see [debugPrintScheduleFrameStacks]. /// To see when a frame is scheduled, see [debugPrintScheduleFrameStacks].
bool debugPrintScheduleBuildForStacks = false; bool debugPrintScheduleBuildForStacks = false;
...@@ -132,7 +136,7 @@ bool debugItemsHaveDuplicateKeys(Iterable<Widget> items) { ...@@ -132,7 +136,7 @@ bool debugItemsHaveDuplicateKeys(Iterable<Widget> items) {
/// Used by [TableRowInkWell] to make sure that it is only used in an appropriate context. /// Used by [TableRowInkWell] to make sure that it is only used in an appropriate context.
/// ///
/// To invoke this function, use the following pattern, typically in the /// To invoke this function, use the following pattern, typically in the
/// relevant Widget's [build] method: /// relevant Widget's build method:
/// ///
/// ```dart /// ```dart
/// assert(debugCheckHasTable(context)); /// assert(debugCheckHasTable(context));
...@@ -163,7 +167,7 @@ bool debugCheckHasTable(BuildContext context) { ...@@ -163,7 +167,7 @@ bool debugCheckHasTable(BuildContext context) {
/// appropriate context. /// appropriate context.
/// ///
/// To invoke this function, use the following pattern, typically in the /// To invoke this function, use the following pattern, typically in the
/// relevant Widget's [build] method: /// relevant Widget's build method:
/// ///
/// ```dart /// ```dart
/// assert(debugCheckHasMediaQuery(context)); /// assert(debugCheckHasMediaQuery(context));
......
...@@ -57,7 +57,7 @@ enum DismissDirection { ...@@ -57,7 +57,7 @@ enum DismissDirection {
/// is specified it is stacked behind the Dismissible's child and is exposed when /// is specified it is stacked behind the Dismissible's child and is exposed when
/// the child moves. /// the child moves.
/// ///
/// The widget calls the [onDimissed] callback either after its size has /// The widget calls the [onDismissed] callback either after its size has
/// collapsed to zero (if [resizeDuration] is non-null) or immediately after /// collapsed to zero (if [resizeDuration] is non-null) or immediately after
/// the slide animation (if [resizeDuration] is null). If the Dismissible is a /// the slide animation (if [resizeDuration] is null). If the Dismissible is a
/// list item, it must have a key that distinguishes it from the other items and /// list item, it must have a key that distinguishes it from the other items and
......
...@@ -171,7 +171,8 @@ class EditableText extends StatefulWidget { ...@@ -171,7 +171,8 @@ class EditableText extends StatefulWidget {
/// For example, if the text scale factor is 1.5, text will be 50% larger than /// For example, if the text scale factor is 1.5, text will be 50% larger than
/// the specified font size. /// the specified font size.
/// ///
/// Defaults to [MediaQuery.textScaleFactor]. /// Defaults to the [MediaQueryData.textScaleFactor] obtained from the ambient
/// [MediaQuery], or 1.0 if there is no [MediaQuery] in scope.
final double textScaleFactor; final double textScaleFactor;
/// The color to use when painting the cursor. /// The color to use when painting the cursor.
......
...@@ -379,8 +379,8 @@ class FocusScopeNode extends Object with TreeDiagnosticsMixin { ...@@ -379,8 +379,8 @@ class FocusScopeNode extends Object with TreeDiagnosticsMixin {
/// the root of the focus tree and tracking which [FocusNode] has the overall /// the root of the focus tree and tracking which [FocusNode] has the overall
/// focus. /// focus.
/// ///
/// The [FocusManager] is held by the [WidgetBinding] as /// The [FocusManager] is held by the [WidgetsBinding] as
/// [WidgetBinding.focusManager]. The [FocusManager] is rarely accessed /// [WidgetsBinding.focusManager]. The [FocusManager] is rarely accessed
/// directly. Instead, to find the [FocusScopeNode] for a given [BuildContext], /// directly. Instead, to find the [FocusScopeNode] for a given [BuildContext],
/// use [FocusScope.of]. /// use [FocusScope.of].
/// ///
...@@ -395,7 +395,7 @@ class FocusManager { ...@@ -395,7 +395,7 @@ class FocusManager {
/// Creates an object that manages the focus tree. /// Creates an object that manages the focus tree.
/// ///
/// This constructor is rarely called directly. To access the [FocusManager], /// This constructor is rarely called directly. To access the [FocusManager],
/// consider using [WidgetBinding.focusManager] instead. /// consider using [WidgetsBinding.focusManager] instead.
FocusManager() { FocusManager() {
rootScope._manager = this; rootScope._manager = this;
assert(rootScope._firstChild == null); assert(rootScope._firstChild == null);
......
...@@ -9,7 +9,7 @@ import 'routes.dart'; ...@@ -9,7 +9,7 @@ import 'routes.dart';
import 'will_pop_scope.dart'; import 'will_pop_scope.dart';
/// An optional container for grouping together multiple form field widgets /// An optional container for grouping together multiple form field widgets
/// (e.g. [Input] widgets). /// (e.g. [TextField] widgets).
/// ///
/// Each individual form field should be wrapped in a [FormField] widget, with /// Each individual form field should be wrapped in a [FormField] widget, with
/// the [Form] widget as a common ancestor of all of those. Call methods on /// the [Form] widget as a common ancestor of all of those. Call methods on
......
...@@ -734,9 +734,10 @@ abstract class State<T extends StatefulWidget> { ...@@ -734,9 +734,10 @@ abstract class State<T extends StatefulWidget> {
/// A [State] object's configuration is the corresponding [StatefulWidget] /// A [State] object's configuration is the corresponding [StatefulWidget]
/// instance. This property is initialized by the framework before calling /// instance. This property is initialized by the framework before calling
/// [initState]. If the parent updates this location in the tree to a new /// [initState]. If the parent updates this location in the tree to a new
/// widget with the same [runtimeType] and [key] as the current configuration, /// widget with the same [runtimeType] and [Widget.key] as the current
/// the framework will update this property to refer to the new widget and /// configuration, the framework will update this property to refer to the new
/// then call [didUpdateWidget], passing the old configuration as an argument. /// widget and then call [didUpdateWidget], passing the old configuration as
/// an argument.
T get widget => _widget; T get widget => _widget;
T _widget; T _widget;
...@@ -806,10 +807,10 @@ abstract class State<T extends StatefulWidget> { ...@@ -806,10 +807,10 @@ abstract class State<T extends StatefulWidget> {
/// Called whenever the widget configuration changes. /// Called whenever the widget configuration changes.
/// ///
/// If the parent widget rebuilds and request that this location in the tree /// If the parent widget rebuilds and request that this location in the tree
/// update to display a new widget with the same [runtimeType] and [key], the /// update to display a new widget with the same [runtimeType] and
/// framework will update the [widget] property of this [State] object to /// [Widget.key], the framework will update the [widget] property of this
/// refer to the new widget and then call the this method with the previous /// [State] object to refer to the new widget and then call the this method
/// widget as an argument. /// with the previous widget as an argument.
/// ///
/// Override this method to respond to changes in the [widget] widget (e.g., /// Override this method to respond to changes in the [widget] widget (e.g.,
/// to start implicit animations). /// to start implicit animations).
...@@ -1517,8 +1518,8 @@ abstract class BuildContext { ...@@ -1517,8 +1518,8 @@ abstract class BuildContext {
/// [RenderObjectWidget]. /// [RenderObjectWidget].
/// ///
/// This method will only return a valid result after the build phase is /// This method will only return a valid result after the build phase is
/// complete. It is therefore not valid to call this from the [build] function /// complete. It is therefore not valid to call this from a build method.
/// itself. It should only be called from interaction event handlers (e.g. /// It should only be called from interaction event handlers (e.g.
/// gesture callbacks) or layout or paint callbacks. /// gesture callbacks) or layout or paint callbacks.
/// ///
/// If the render object is a [RenderBox], which is the common case, then the /// If the render object is a [RenderBox], which is the common case, then the
...@@ -1527,8 +1528,8 @@ abstract class BuildContext { ...@@ -1527,8 +1528,8 @@ abstract class BuildContext {
/// from paint callbacks or interaction event handlers (e.g. gesture /// from paint callbacks or interaction event handlers (e.g. gesture
/// callbacks). /// callbacks).
/// ///
/// For details on the different phases of a frame, see /// For details on the different phases of a frame, see the discussion at
/// [WidgetsBinding.beginFrame]. /// [WidgetsBinding.drawFrame].
/// ///
/// Calling this method is theoretically relatively expensive (O(N) in the /// Calling this method is theoretically relatively expensive (O(N) in the
/// depth of the tree), but in practice is usually cheap because the tree /// depth of the tree), but in practice is usually cheap because the tree
...@@ -1539,12 +1540,12 @@ abstract class BuildContext { ...@@ -1539,12 +1540,12 @@ abstract class BuildContext {
/// The size of the [RenderBox] returned by [findRenderObject]. /// The size of the [RenderBox] returned by [findRenderObject].
/// ///
/// This getter will only return a valid result after the layout phase is /// This getter will only return a valid result after the layout phase is
/// complete. It is therefore not valid to call this from the [build] function /// complete. It is therefore not valid to call this from a build method.
/// itself. It should only be called from paint callbacks or interaction event /// It should only be called from paint callbacks or interaction event
/// handlers (e.g. gesture callbacks). /// handlers (e.g. gesture callbacks).
/// ///
/// For details on the different phases of a frame, see /// For details on the different phases of a frame, see the discussion at
/// [WidgetsBinding.beginFrame]. /// [WidgetsBinding.drawFrame].
/// ///
/// This getter will only return a valid result if [findRenderObject] actually /// This getter will only return a valid result if [findRenderObject] actually
/// returns a [RenderBox]. If [findRenderObject] returns a render object that /// returns a [RenderBox]. If [findRenderObject] returns a render object that
...@@ -1750,7 +1751,7 @@ class BuildOwner { ...@@ -1750,7 +1751,7 @@ class BuildOwner {
bool _dirtyElementsNeedsResorting; // null means we're not in a buildScope bool _dirtyElementsNeedsResorting; // null means we're not in a buildScope
/// Adds an element to the dirty elements list so that it will be rebuilt /// Adds an element to the dirty elements list so that it will be rebuilt
/// when [WidgetsBinding.beginFrame] calls [buildScope]. /// when [WidgetsBinding.drawFrame] calls [buildScope].
void scheduleBuildFor(Element element) { void scheduleBuildFor(Element element) {
assert(element != null); assert(element != null);
assert(element.owner == this); assert(element.owner == this);
...@@ -1832,8 +1833,8 @@ class BuildOwner { ...@@ -1832,8 +1833,8 @@ class BuildOwner {
/// `callback`, if any. Then, builds all the elements that were marked as /// `callback`, if any. Then, builds all the elements that were marked as
/// dirty using [scheduleBuildFor], in depth order. /// dirty using [scheduleBuildFor], in depth order.
/// ///
/// This mechanism prevents build functions from transitively requiring other /// This mechanism prevents build methods from transitively requiring other
/// build functions to run, potentially causing infinite loops. /// build methods to run, potentially causing infinite loops.
/// ///
/// The dirty list is processed after `callback` returns, building all the /// The dirty list is processed after `callback` returns, building all the
/// elements that were marked as dirty using [scheduleBuildFor], in depth /// elements that were marked as dirty using [scheduleBuildFor], in depth
...@@ -1843,11 +1844,16 @@ class BuildOwner { ...@@ -1843,11 +1844,16 @@ class BuildOwner {
/// ///
/// To flush the current dirty list without performing any other work, this /// To flush the current dirty list without performing any other work, this
/// function can be called with no callback. This is what the framework does /// function can be called with no callback. This is what the framework does
/// each frame, in [WidgetsBinding.beginFrame]. /// each frame, in [WidgetsBinding.drawFrame].
/// ///
/// Only one [buildScope] can be active at a time. /// Only one [buildScope] can be active at a time.
/// ///
/// A [buildScope] implies a [lockState] scope as well. /// A [buildScope] implies a [lockState] scope as well.
///
/// To print a console message every time this method is called, set
/// [debugPrintBuildScope] to true. This is useful when debugging problems
/// involving widgets not getting marked dirty, or getting marked dirty too
/// often.
void buildScope(Element context, [VoidCallback callback]) { void buildScope(Element context, [VoidCallback callback]) {
if (callback == null && _dirtyElements.isEmpty) if (callback == null && _dirtyElements.isEmpty)
return; return;
...@@ -1970,7 +1976,7 @@ class BuildOwner { ...@@ -1970,7 +1976,7 @@ class BuildOwner {
/// Complete the element build pass by unmounting any elements that are no /// Complete the element build pass by unmounting any elements that are no
/// longer active. /// longer active.
/// ///
/// This is called by [WidgetsBinding.beginFrame]. /// This is called by [WidgetsBinding.drawFrame].
/// ///
/// In debug mode, this also runs some sanity checks, for example checking for /// In debug mode, this also runs some sanity checks, for example checking for
/// duplicate global keys. /// duplicate global keys.
...@@ -3058,7 +3064,7 @@ abstract class Element implements BuildContext { ...@@ -3058,7 +3064,7 @@ abstract class Element implements BuildContext {
/// A widget that renders an exception's message. /// A widget that renders an exception's message.
/// ///
/// This widget is used when a build function fails, to help with determining /// This widget is used when a build method fails, to help with determining
/// where the problem lies. Exceptions are also logged to the console, which you /// where the problem lies. Exceptions are also logged to the console, which you
/// can read using `flutter logs`. The console will also include additional /// can read using `flutter logs`. The console will also include additional
/// information such as the stack trace for the exception. /// information such as the stack trace for the exception.
...@@ -3096,7 +3102,7 @@ typedef Widget WidgetBuilder(BuildContext context); ...@@ -3096,7 +3102,7 @@ typedef Widget WidgetBuilder(BuildContext context);
/// Signature for a function that creates a widget for a given index, e.g., in a /// Signature for a function that creates a widget for a given index, e.g., in a
/// list. /// list.
/// ///
/// Used by [LazyBlockBuilder.builder]. /// Used by [ListView.builder] and other APIs that use lazily-generated widgets.
typedef Widget IndexedWidgetBuilder(BuildContext context, int index); typedef Widget IndexedWidgetBuilder(BuildContext context, int index);
/// An [Element] that composes other [Element]s. /// An [Element] that composes other [Element]s.
...@@ -3285,7 +3291,7 @@ class StatefulElement extends ComponentElement { ...@@ -3285,7 +3291,7 @@ class StatefulElement extends ComponentElement {
void activate() { void activate() {
super.activate(); super.activate();
// Since the State could have observed the deactivate() and thus disposed of // Since the State could have observed the deactivate() and thus disposed of
// resources allocated in the build function, we have to rebuild the widget // resources allocated in the build method, we have to rebuild the widget
// so that its State can reallocate its resources. // so that its State can reallocate its resources.
assert(_active); // otherwise markNeedsBuild is a no-op assert(_active); // otherwise markNeedsBuild is a no-op
markNeedsBuild(); markNeedsBuild();
...@@ -3588,7 +3594,7 @@ class InheritedElement extends ProxyElement { ...@@ -3588,7 +3594,7 @@ class InheritedElement extends ProxyElement {
/// ### Updating children /// ### Updating children
/// ///
/// Early in the lifecycle of an element, the framework calls the [mount] /// Early in the lifecycle of an element, the framework calls the [mount]
/// method. This method should call [inflateChild] for each child, passing in /// method. This method should call [updateChild] for each child, passing in
/// the widget for that child, and the slot for that child, thus obtaining a /// the widget for that child, and the slot for that child, thus obtaining a
/// list of child [Element]s. /// list of child [Element]s.
/// ///
...@@ -3607,9 +3613,9 @@ class InheritedElement extends ProxyElement { ...@@ -3607,9 +3613,9 @@ class InheritedElement extends ProxyElement {
/// method may be useful in this regard. /// method may be useful in this regard.
/// ///
/// [updateChild] should be called for children in their logical order. The /// [updateChild] should be called for children in their logical order. The
/// order can matter; for example, if two of the children use [Focus.at]'s /// order can matter; for example, if two of the children use [PageStorage]'s
/// `autofocus` feature in their build method, then the first one to be updated /// `writeState` feature in their build method (and neither has a [key]), then
/// will gain the focus. /// the state written by the first will be overwritten by the second.
/// ///
/// #### Dynamically determining the children during the build phase /// #### Dynamically determining the children during the build phase
/// ///
...@@ -3623,8 +3629,9 @@ class InheritedElement extends ProxyElement { ...@@ -3623,8 +3629,9 @@ class InheritedElement extends ProxyElement {
/// the [update] method won't work: layout of this element's render object /// the [update] method won't work: layout of this element's render object
/// hasn't started yet at that point. Instead, the [update] method can mark the /// hasn't started yet at that point. Instead, the [update] method can mark the
/// render object as needing layout (see [RenderObject.markNeedsLayout]), and /// render object as needing layout (see [RenderObject.markNeedsLayout]), and
/// then the render object's [performLayout] method can call back to the element /// then the render object's [RenderOBject.performLayout] method can call back
/// to have it generate the widgets and call [updateChild] accordingly. /// to the element to have it generate the widgets and call [updateChild]
/// accordingly.
/// ///
/// For a render object to call an element during layout, it must use /// For a render object to call an element during layout, it must use
/// [RenderObject.invokeLayoutCallback]. For an element to call [updateChild] /// [RenderObject.invokeLayoutCallback]. For an element to call [updateChild]
...@@ -4011,7 +4018,7 @@ abstract class RootRenderObjectElement extends RenderObjectElement { ...@@ -4011,7 +4018,7 @@ abstract class RootRenderObjectElement extends RenderObjectElement {
/// [WidgetsBinding.buildOwner], and assigns it to the widget tree in the call /// [WidgetsBinding.buildOwner], and assigns it to the widget tree in the call
/// to [runApp]. The binding is responsible for driving the build pipeline by /// to [runApp]. The binding is responsible for driving the build pipeline by
/// calling the build owner's [BuildOwner.buildScope] method. See /// calling the build owner's [BuildOwner.buildScope] method. See
/// [WidgetsBinding.beginFrame]. /// [WidgetsBinding.drawFrame].
void assignOwner(BuildOwner owner) { void assignOwner(BuildOwner owner) {
_owner = owner; _owner = owner;
} }
......
...@@ -91,7 +91,7 @@ class Hero extends StatefulWidget { ...@@ -91,7 +91,7 @@ class Hero extends StatefulWidget {
final Object tag; final Object tag;
/// The widget subtree that will "fly" from one route to another during a /// The widget subtree that will "fly" from one route to another during a
/// [Naviator] push or pop transition. /// [Navigator] push or pop transition.
/// ///
/// The appearance of this subtree should be similar to the appearance of /// The appearance of this subtree should be similar to the appearance of
/// the subtrees of any other heroes in the application with the same [tag]. /// the subtrees of any other heroes in the application with the same [tag].
...@@ -398,7 +398,7 @@ class _HeroFlight { ...@@ -398,7 +398,7 @@ class _HeroFlight {
/// A [Navigator] observer that manages [Hero] transitions. /// A [Navigator] observer that manages [Hero] transitions.
/// ///
/// An instance of [HeroController] should be used as the [Navigator.observer]. /// An instance of [HeroController] should be used in [Navigator.observers].
/// This is done automatically by [MaterialApp]. /// This is done automatically by [MaterialApp].
class HeroController extends NavigatorObserver { class HeroController extends NavigatorObserver {
/// Creates a hero controller with the given [RectTween] constructor if any. /// Creates a hero controller with the given [RectTween] constructor if any.
......
...@@ -243,10 +243,10 @@ abstract class AnimatedWidgetBaseState<T extends ImplicitlyAnimatedWidget> exten ...@@ -243,10 +243,10 @@ abstract class AnimatedWidgetBaseState<T extends ImplicitlyAnimatedWidget> exten
/// duration. Properties that are null are not animated. /// duration. Properties that are null are not animated.
/// ///
/// This class is useful for generating simple implicit transitions between /// This class is useful for generating simple implicit transitions between
/// different parameters to [Container] with its internal /// different parameters to [Container] with its internal [AnimationController].
/// [AnimationController]. For more complex animations, you'll likely want to /// For more complex animations, you'll likely want to use a subclass of
/// use a subclass of [Transition] such as the [DecoratedBoxTransition] or use /// [AnimatedWidget] such as the [DecoratedBoxTransition] or use your own
/// your own [AnimationController]. /// [AnimationController].
class AnimatedContainer extends ImplicitlyAnimatedWidget { class AnimatedContainer extends ImplicitlyAnimatedWidget {
/// Creates a container that animates its parameters implicitly. /// Creates a container that animates its parameters implicitly.
/// ///
......
...@@ -16,12 +16,12 @@ typedef Widget LayoutWidgetBuilder(BuildContext context, BoxConstraints constrai ...@@ -16,12 +16,12 @@ typedef Widget LayoutWidgetBuilder(BuildContext context, BoxConstraints constrai
/// Similar to the [Builder] widget except that the framework calls the [builder] /// Similar to the [Builder] widget except that the framework calls the [builder]
/// function at layout time and provides the parent widget's constraints. This /// function at layout time and provides the parent widget's constraints. This
/// is useful when the parent constrains the child's size and doesn't depend on /// is useful when the parent constrains the child's size and doesn't depend on
/// the child's intrinsic size. The LayoutBuilder's final size will match its /// the child's intrinsic size. The [LayoutBuilder]'s final size will match its
/// child's size. /// child's size.
/// ///
/// If the child should be smaller than the parent, consider wrapping the child /// If the child should be smaller than the parent, consider wrapping the child
/// in an [Align] widget. If the child might want to be bigger, consider /// in an [Align] widget. If the child might want to be bigger, consider
/// wrapping it in a [ScrollableViewport]. /// wrapping it in a [SingleChildScrollView].
/// ///
/// See also: /// See also:
/// ///
...@@ -168,8 +168,8 @@ class _RenderLayoutBuilder extends RenderBox with RenderObjectWithChildMixin<Ren ...@@ -168,8 +168,8 @@ class _RenderLayoutBuilder extends RenderBox with RenderObjectWithChildMixin<Ren
if (!RenderObject.debugCheckingIntrinsics) { if (!RenderObject.debugCheckingIntrinsics) {
throw new FlutterError( throw new FlutterError(
'LayoutBuilder does not support returning intrinsic dimensions.\n' 'LayoutBuilder does not support returning intrinsic dimensions.\n'
'Calculating the intrinsic dimensions would require running the layout callback speculatively, ' 'Calculating the intrinsic dimensions would require running the layout '
'which might mutate the live render object tree.' 'callback speculatively, which might mutate the live render object tree.'
); );
} }
return true; return true;
......
...@@ -35,7 +35,7 @@ class MediaQueryData { ...@@ -35,7 +35,7 @@ class MediaQueryData {
/// Creates data for a media query with explicit values. /// Creates data for a media query with explicit values.
/// ///
/// Consider using [MediaQueryData.fromWindow] to create data based on a /// Consider using [MediaQueryData.fromWindow] to create data based on a
/// [ui.Window]. /// [Window].
const MediaQueryData({ const MediaQueryData({
this.size: Size.zero, this.size: Size.zero,
this.devicePixelRatio: 1.0, this.devicePixelRatio: 1.0,
...@@ -48,7 +48,7 @@ class MediaQueryData { ...@@ -48,7 +48,7 @@ class MediaQueryData {
/// If you use this, you should ensure that you also register for /// If you use this, you should ensure that you also register for
/// notifications so that you can update your [MediaQueryData] when the /// notifications so that you can update your [MediaQueryData] when the
/// window's metrics change. For example, see /// window's metrics change. For example, see
/// [WidgetsBindingObserver.didChangeMetrics] or [ui.window.onMetricsChanged]. /// [WidgetsBindingObserver.didChangeMetrics] or [Window.onMetricsChanged].
MediaQueryData.fromWindow(ui.Window window) MediaQueryData.fromWindow(ui.Window window)
: size = window.physicalSize / window.devicePixelRatio, : size = window.physicalSize / window.devicePixelRatio,
devicePixelRatio = window.devicePixelRatio, devicePixelRatio = window.devicePixelRatio,
......
...@@ -64,7 +64,7 @@ abstract class Route<T> { ...@@ -64,7 +64,7 @@ abstract class Route<T> {
void didReplace(Route<dynamic> oldRoute) { } void didReplace(Route<dynamic> oldRoute) { }
/// Returns false if this route wants to veto a [Navigator.pop]. This method is /// Returns false if this route wants to veto a [Navigator.pop]. This method is
/// called by [Naviagtor.willPop]. /// called by [Navigator.willPop].
/// ///
/// By default, routes veto a pop if they're the first route in the history /// By default, routes veto a pop if they're the first route in the history
/// (i.e., if [isFirst]). This behavior prevents the user from popping the /// (i.e., if [isFirst]). This behavior prevents the user from popping the
...@@ -72,7 +72,7 @@ abstract class Route<T> { ...@@ -72,7 +72,7 @@ abstract class Route<T> {
/// ///
/// See also: /// See also:
/// ///
/// * [Form], which provides an `onWillPop` callback that uses this mechanism. /// * [Form], which provides a [Form.onWillPop] callback that uses this mechanism.
Future<RoutePopDisposition> willPop() async { Future<RoutePopDisposition> willPop() async {
return isFirst ? RoutePopDisposition.bubble : RoutePopDisposition.pop; return isFirst ? RoutePopDisposition.bubble : RoutePopDisposition.pop;
} }
...@@ -156,7 +156,7 @@ abstract class Route<T> { ...@@ -156,7 +156,7 @@ abstract class Route<T> {
/// If attempts to dismiss this route might be vetoed, for example because /// If attempts to dismiss this route might be vetoed, for example because
/// a [WillPopCallback] was defined for the route, then it may make sense /// a [WillPopCallback] was defined for the route, then it may make sense
/// to disable the pop gesture. For example, the iOS back gesture is disabled /// to disable the pop gesture. For example, the iOS back gesture is disabled
/// when [ModalRoute.hasScopedWillCallback] is true. /// when [ModalRoute.hasScopedWillPopCallback] is true.
NavigationGestureController startPopGesture() => null; NavigationGestureController startPopGesture() => null;
/// Whether this route is the top-most route on the navigator. /// Whether this route is the top-most route on the navigator.
...@@ -426,7 +426,7 @@ typedef bool RoutePredicate(Route<dynamic> route); ...@@ -426,7 +426,7 @@ typedef bool RoutePredicate(Route<dynamic> route);
/// because they block input to the widgets below. /// because they block input to the widgets below.
/// ///
/// There are functions which create and show popup routes. For /// There are functions which create and show popup routes. For
/// example: [showDialog], [showMenu], and [showBottomSheet]. These /// example: [showDialog], [showMenu], and [showModalBottomSheet]. These
/// functions return their pushed route's Future as described above. /// functions return their pushed route's Future as described above.
/// Callers can await the returned value to take an action when the /// Callers can await the returned value to take an action when the
/// route is popped, or to discover the route's value. /// route is popped, or to discover the route's value.
...@@ -527,8 +527,8 @@ class Navigator extends StatefulWidget { ...@@ -527,8 +527,8 @@ class Navigator extends StatefulWidget {
/// encloses the given context, and transitions to it. /// encloses the given context, and transitions to it.
/// ///
/// The new route and the previous route (if any) are notified (see /// The new route and the previous route (if any) are notified (see
/// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has an /// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has any
/// [Navigator.observer], it will be notified as well (see /// [Navigator.observers], they will be notified as well (see
/// [NavigatorObserver.didPush]). /// [NavigatorObserver.didPush]).
/// ///
/// Ongoing gestures within the current route are canceled when a new route is /// Ongoing gestures within the current route are canceled when a new route is
...@@ -540,9 +540,9 @@ class Navigator extends StatefulWidget { ...@@ -540,9 +540,9 @@ class Navigator extends StatefulWidget {
return Navigator.of(context).push(route); return Navigator.of(context).push(route);
} }
/// Returns the value of the current route's `willPop` method. This method is /// Returns the value of the current route's [Route.willPop] method. This
/// typically called before a user-initiated [pop]. For example on Android it's /// method is typically called before a user-initiated [pop]. For example on
/// called by the binding for the system's back button. /// Android it's called by the binding for the system's back button.
/// ///
/// See also: /// See also:
/// ///
...@@ -791,8 +791,8 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin { ...@@ -791,8 +791,8 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin {
/// Adds the given route to the navigator's history, and transitions to it. /// Adds the given route to the navigator's history, and transitions to it.
/// ///
/// The new route and the previous route (if any) are notified (see /// The new route and the previous route (if any) are notified (see
/// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has an /// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has any
/// [Navigator.observer], it will be notified as well (see /// [Navigator.observers], they will be notified as well (see
/// [NavigatorObserver.didPush]). /// [NavigatorObserver.didPush]).
/// ///
/// Ongoing gestures within the current route are canceled when a new route is /// Ongoing gestures within the current route are canceled when a new route is
...@@ -991,7 +991,7 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin { ...@@ -991,7 +991,7 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin {
/// ///
/// If there are any routes left on the history, the top remaining route is /// If there are any routes left on the history, the top remaining route is
/// notified (see [Route.didPopNext]), and the method returns true. In that /// notified (see [Route.didPopNext]), and the method returns true. In that
/// case, if the [Navigator] has an [Navigator.observer], it will be notified /// case, if the [Navigator] has any [Navigator.observers], they will be notified
/// as well (see [NavigatorObserver.didPop]). Otherwise, if the popped route /// as well (see [NavigatorObserver.didPop]). Otherwise, if the popped route
/// was the last route, the method returns false. /// was the last route, the method returns false.
/// ///
......
...@@ -44,7 +44,7 @@ import 'ticker_provider.dart'; ...@@ -44,7 +44,7 @@ import 'ticker_provider.dart';
/// overlay entry is still built even if it is not visible, set [maintainState] /// overlay entry is still built even if it is not visible, set [maintainState]
/// to true. This is more expensive, so should be done with care. In particular, /// to true. This is more expensive, so should be done with care. In particular,
/// if widgets in an overlay entry with [maintainState] set to true repeatedly /// if widgets in an overlay entry with [maintainState] set to true repeatedly
/// call [setState], the user's battery will be drained unnecessarily. /// call [State.setState], the user's battery will be drained unnecessarily.
/// ///
/// See also: /// See also:
/// ///
...@@ -99,7 +99,7 @@ class OverlayEntry { ...@@ -99,7 +99,7 @@ class OverlayEntry {
/// overlay entry is still built even if it is not visible, set [maintainState] /// overlay entry is still built even if it is not visible, set [maintainState]
/// to true. This is more expensive, so should be done with care. In particular, /// to true. This is more expensive, so should be done with care. In particular,
/// if widgets in an overlay entry with [maintainState] set to true repeatedly /// if widgets in an overlay entry with [maintainState] set to true repeatedly
/// call [setState], the user's battery will be drained unnecessarily. /// call [State.setState], the user's battery will be drained unnecessarily.
/// ///
/// This is used by the [Navigator] and [Route] objects to ensure that routes /// This is used by the [Navigator] and [Route] objects to ensure that routes
/// are kept around even when in the background, so that [Future]s promised /// are kept around even when in the background, so that [Future]s promised
...@@ -123,8 +123,8 @@ class OverlayEntry { ...@@ -123,8 +123,8 @@ class OverlayEntry {
/// This should only be called once. /// This should only be called once.
/// ///
/// If this method is called while the [SchedulerBinding.schedulerPhase] is /// If this method is called while the [SchedulerBinding.schedulerPhase] is
/// [SchedulerBinding.persistentCallbacks], i.e. during the build, layout, or /// [SchedulerPhase.persistentCallbacks], i.e. during the build, layout, or
/// paint phases (see [WidgetsBinding.beginFrame]), then the removal is /// paint phases (see [WidgetsBinding.drawFrame]), then the removal is
/// delayed until the post-frame callbacks phase. Otherwise the removal is /// delayed until the post-frame callbacks phase. Otherwise the removal is
/// done synchronously. This means that it is safe to call during builds, but /// done synchronously. This means that it is safe to call during builds, but
/// also that if you do call this during a build, the UI will not update until /// also that if you do call this during a build, the UI will not update until
......
...@@ -15,7 +15,7 @@ import 'package:flutter/widgets.dart'; ...@@ -15,7 +15,7 @@ import 'package:flutter/widgets.dart';
/// ///
/// A [GlowingOverscrollIndicator] listens for [ScrollNotification]s in order /// A [GlowingOverscrollIndicator] listens for [ScrollNotification]s in order
/// to control the overscroll indication. These notifications are typically /// to control the overscroll indication. These notifications are typically
/// generated by a [ScrolView], such as a [ListView] or a [GridView]. /// generated by a [ScrollView], such as a [ListView] or a [GridView].
/// ///
/// [GlowingOverscrollIndicator] generates [OverscrollIndicatorNotification] /// [GlowingOverscrollIndicator] generates [OverscrollIndicatorNotification]
/// before showing an overscroll indication. To prevent the indicator from /// before showing an overscroll indication. To prevent the indicator from
......
...@@ -26,7 +26,7 @@ class PerformanceOverlay extends LeafRenderObjectWidget { ...@@ -26,7 +26,7 @@ class PerformanceOverlay extends LeafRenderObjectWidget {
/// Create a performance overlay that only displays specific statistics. The /// Create a performance overlay that only displays specific statistics. The
/// mask is created by shifting 1 by the index of the specific /// mask is created by shifting 1 by the index of the specific
/// [StatisticOption] to enable. /// [PerformanceOverlayOption] to enable.
const PerformanceOverlay({ const PerformanceOverlay({
Key key, Key key,
this.optionsMask: 0, this.optionsMask: 0,
......
...@@ -280,7 +280,7 @@ class LocalHistoryEntry { ...@@ -280,7 +280,7 @@ class LocalHistoryEntry {
/// opportunity to handle the pop internally. A LocalHistoryRoute handles the /// opportunity to handle the pop internally. A LocalHistoryRoute handles the
/// pop internally if its list of local history entries is non-empty. Rather /// pop internally if its list of local history entries is non-empty. Rather
/// than being removed as the current route, the most recent [LocalHistoryEntry] /// than being removed as the current route, the most recent [LocalHistoryEntry]
/// is removed from the list and its [onRemove] is called. /// is removed from the list and its [LocalHistoryEntry.onRemove] is called.
abstract class LocalHistoryRoute<T> extends Route<T> { abstract class LocalHistoryRoute<T> extends Route<T> {
List<LocalHistoryEntry> _localHistory; List<LocalHistoryEntry> _localHistory;
...@@ -304,7 +304,8 @@ abstract class LocalHistoryRoute<T> extends Route<T> { ...@@ -304,7 +304,8 @@ abstract class LocalHistoryRoute<T> extends Route<T> {
/// Remove a local history entry from this route. /// Remove a local history entry from this route.
/// ///
/// The entry's [onRemove] callback, if any, will be called synchronously. /// The entry's [LocalHistoryEntry.onRemove] callback, if any, will be called
/// synchronously.
void removeLocalHistoryEntry(LocalHistoryEntry entry) { void removeLocalHistoryEntry(LocalHistoryEntry entry) {
assert(entry != null); assert(entry != null);
assert(entry._owner == this); assert(entry._owner == this);
...@@ -806,7 +807,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T ...@@ -806,7 +807,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
/// ``` /// ```
/// ///
/// This callback runs asynchronously and it's possible that it will be called /// This callback runs asynchronously and it's possible that it will be called
/// after its route has been disposed. The callback should check [mounted] /// after its route has been disposed. The callback should check [State.mounted]
/// before doing anything. /// before doing anything.
/// ///
/// A typical application of this callback would be to warn the user about /// A typical application of this callback would be to warn the user about
......
...@@ -25,6 +25,7 @@ import 'ticker_provider.dart'; ...@@ -25,6 +25,7 @@ import 'ticker_provider.dart';
/// See also: /// See also:
/// ///
/// * [ScrollActivity], which uses this class as its delegate. /// * [ScrollActivity], which uses this class as its delegate.
/// * [ScrollPositionWithSingleContext], the main implementation of this interface.
abstract class ScrollActivityDelegate { abstract class ScrollActivityDelegate {
/// The direction in which the scroll view scrolls. /// The direction in which the scroll view scrolls.
AxisDirection get axisDirection; AxisDirection get axisDirection;
...@@ -353,7 +354,7 @@ class DragScrollActivity extends ScrollActivity { ...@@ -353,7 +354,7 @@ class DragScrollActivity extends ScrollActivity {
} }
} }
/// An activity that animates a scroll view based on a physics [simulation]. /// An activity that animates a scroll view based on a physics [Simulation].
/// ///
/// A [BallisticScrollActivity] is typically used when the user lifts their /// A [BallisticScrollActivity] is typically used when the user lifts their
/// finger off the screen to continue the scrolling gesture with the current velocity. /// finger off the screen to continue the scrolling gesture with the current velocity.
......
...@@ -47,10 +47,10 @@ class ScrollBehavior { ...@@ -47,10 +47,10 @@ class ScrollBehavior {
return null; return null;
} }
/// The scroll physics to use for the given platform. /// The scroll physics to use for the platform given by [getPlatform].
/// ///
/// Used by [createScrollPosition] to get the scroll physics for newly created /// Defaults to [BouncingScrollPhysics] on iOS and [ClampingScrollPhysics] on
/// scroll positions. /// Android.
ScrollPhysics getScrollPhysics(BuildContext context) { ScrollPhysics getScrollPhysics(BuildContext context) {
switch (getPlatform(context)) { switch (getPlatform(context)) {
case TargetPlatform.iOS: case TargetPlatform.iOS:
...@@ -93,6 +93,9 @@ class ScrollConfiguration extends InheritedWidget { ...@@ -93,6 +93,9 @@ class ScrollConfiguration extends InheritedWidget {
final ScrollBehavior behavior; final ScrollBehavior behavior;
/// The [ScrollBehavior] for [Scrollable] widgets in the given [BuildContext]. /// The [ScrollBehavior] for [Scrollable] widgets in the given [BuildContext].
///
/// If no [ScrollConfiguration] widget is in scope of the given `context`,
/// a default [ScrollBehavior] instance is returned.
static ScrollBehavior of(BuildContext context) { static ScrollBehavior of(BuildContext context) {
final ScrollConfiguration configuration = context.inheritFromWidgetOfExactType(ScrollConfiguration); final ScrollConfiguration configuration = context.inheritFromWidgetOfExactType(ScrollConfiguration);
return configuration?.behavior ?? const ScrollBehavior(); return configuration?.behavior ?? const ScrollBehavior();
......
...@@ -53,11 +53,11 @@ abstract class ViewportNotificationMixin extends Notification { ...@@ -53,11 +53,11 @@ abstract class ViewportNotificationMixin extends Notification {
/// position to go outside its scroll bounds. /// position to go outside its scroll bounds.
/// * Interspersed with the [ScrollUpdateNotification]s and /// * Interspersed with the [ScrollUpdateNotification]s and
/// [OverscrollNotification]s are zero or more [UserScrollNotification]s, /// [OverscrollNotification]s are zero or more [UserScrollNotification]s,
/// which indicate that the user has changed the direciton in which they are /// which indicate that the user has changed the direction in which they are
/// scrolling. /// scrolling.
/// * A [ScrollEndNotification], which indicates that the widget has stopped /// * A [ScrollEndNotification], which indicates that the widget has stopped
/// scrolling. /// scrolling.
/// * A [UserScrollNotification], with a [UserScrollNotification.direciton] of /// * A [UserScrollNotification], with a [UserScrollNotification.direction] of
/// [ScrollDirection.idle]. /// [ScrollDirection.idle].
/// ///
/// Notifications bubble up through the tree, which means a given /// Notifications bubble up through the tree, which means a given
......
...@@ -47,7 +47,7 @@ class ScrollPhysics { ...@@ -47,7 +47,7 @@ class ScrollPhysics {
/// Used by [DragScrollActivity] and other user-driven activities to /// Used by [DragScrollActivity] and other user-driven activities to
/// convert an offset in logical pixels as provided by the [DragUpdateDetails] /// convert an offset in logical pixels as provided by the [DragUpdateDetails]
/// into a delta to apply using [setPixels]. /// into a delta to apply using [ScrollActivityDelegate.setPixels].
/// ///
/// This is used by some [ScrollPosition] subclasses to apply friction during /// This is used by some [ScrollPosition] subclasses to apply friction during
/// overscroll situations. /// overscroll situations.
...@@ -86,8 +86,8 @@ class ScrollPhysics { ...@@ -86,8 +86,8 @@ class ScrollPhysics {
/// is updated, to determine how much of the offset is to be clamped off and /// is updated, to determine how much of the offset is to be clamped off and
/// sent to [ScrollPosition.didOverscrollBy]. /// sent to [ScrollPosition.didOverscrollBy].
/// ///
/// The `value` argument is guaranteed to not equal [pixels] when this is /// The `value` argument is guaranteed to not equal the [ScrollMetrics.pixels]
/// called. /// of the `position` argument when this is called.
/// ///
/// It is possible for this method to be called when the `position` describes /// It is possible for this method to be called when the `position` describes
/// an already-out-of-bounds position. In that case, the boundary conditions /// an already-out-of-bounds position. In that case, the boundary conditions
...@@ -189,8 +189,8 @@ class ScrollPhysics { ...@@ -189,8 +189,8 @@ class ScrollPhysics {
/// ///
/// See also: /// See also:
/// ///
/// * [ViewportScrollBehavior], which uses this to provide the iOS component of /// * [ScrollConfiguration], which uses this to provide the the default
/// its scroll behavior. /// scroll behavior on iOS.
/// * [ClampingScrollPhysics], which is the analogous physics for Android's /// * [ClampingScrollPhysics], which is the analogous physics for Android's
/// clamping behavior. /// clamping behavior.
class BouncingScrollPhysics extends ScrollPhysics { class BouncingScrollPhysics extends ScrollPhysics {
...@@ -264,11 +264,11 @@ class BouncingScrollPhysics extends ScrollPhysics { ...@@ -264,11 +264,11 @@ class BouncingScrollPhysics extends ScrollPhysics {
/// ///
/// See also: /// See also:
/// ///
/// * [ViewportScrollBehavior], which uses this to provide the Android component /// * [ScrollConfiguration], which uses this to provide the the default
/// of its scroll behavior. /// scroll behavior on Android.
/// * [BouncingScrollPhysics], which is the analogous physics for iOS' bouncing /// * [BouncingScrollPhysics], which is the analogous physics for iOS' bouncing
/// behavior. /// behavior.
/// * [GlowingOverscrollIndicator], which is used by [ViewportScrollBehavior] to /// * [GlowingOverscrollIndicator], which is used by [ScrollConfiguration] to
/// provide the glowing effect that is usually found with this clamping effect /// provide the glowing effect that is usually found with this clamping effect
/// on Android. /// on Android.
class ClampingScrollPhysics extends ScrollPhysics { class ClampingScrollPhysics extends ScrollPhysics {
......
...@@ -36,7 +36,7 @@ export 'scroll_activity.dart' show ScrollHoldController; ...@@ -36,7 +36,7 @@ export 'scroll_activity.dart' show ScrollHoldController;
/// typically start activities in response to user input or instructions from a /// typically start activities in response to user input or instructions from a
/// [ScrollController]. /// [ScrollController].
/// ///
/// This object is a [Listable] that notifies its listeners when [pixels] /// This object is a [Listenable] that notifies its listeners when [pixels]
/// changes. /// changes.
/// ///
/// ## Subclassing ScrollPosition /// ## Subclassing ScrollPosition
...@@ -375,7 +375,7 @@ abstract class ScrollPosition extends ViewportOffset with ScrollMetrics { ...@@ -375,7 +375,7 @@ abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
/// before. /// before.
/// ///
/// The default implementation informs the [activity] of the new dimensions by /// The default implementation informs the [activity] of the new dimensions by
/// calling [ScrollActivityDelegate.applyNewDimensions]. /// calling its [ScrollActivity.applyNewDimensions] method.
/// ///
/// See also: /// See also:
/// ///
......
...@@ -127,6 +127,15 @@ abstract class ScrollView extends StatelessWidget { ...@@ -127,6 +127,15 @@ abstract class ScrollView extends StatelessWidget {
/// ```dart /// ```dart
/// physics: const ScrollPhysics(), /// physics: const ScrollPhysics(),
/// ``` /// ```
///
/// The physics can be changed dynamically (by providing a new object in a
/// subsequent build), but new physics will only take effect if the _class_ of
/// the provided object changes. Merely constructing a new instance with a
/// different configuration is insufficient to cause the physics to be
/// reapplied. (This is because the final object used is generated
/// dynamically, which can be relatively expensive, and it would be
/// inefficient to speculatively create this object each frame to see if the
/// physics should be updated.)
final ScrollPhysics physics; final ScrollPhysics physics;
/// Whether the extent of the scroll view in the [scrollDirection] should be /// Whether the extent of the scroll view in the [scrollDirection] should be
......
...@@ -107,7 +107,22 @@ class Scrollable extends StatefulWidget { ...@@ -107,7 +107,22 @@ class Scrollable extends StatefulWidget {
/// For example, determines how the widget continues to animate after the /// For example, determines how the widget continues to animate after the
/// user stops dragging the scroll view. /// user stops dragging the scroll view.
/// ///
/// Defaults to matching platform conventions. /// Defaults to matching platform conventions via the physics provided from
/// the ambient [ScrollConfiguration].
///
/// The physics can be changed dynamically, but new physics will only take
/// effect if the _class_ of the provided object changes. Merely constructing
/// a new instance with a different configuration is insufficient to cause the
/// physics to be reapplied. (This is because the final object used is
/// generated dynamically, which can be relatively expensive, and it would be
/// inefficient to speculatively create this object each frame to see if the
/// physics should be updated.)
///
/// See also:
///
/// * [AlwaysScrollableScrollPhysics], which can be used to indicate that the
/// scrollable should react to scroll requests (and possible overscroll)
/// even if the scrollable's contents fit without scrolling being necessary.
final ScrollPhysics physics; final ScrollPhysics physics;
/// Builds the viewport through which the scrollable content is displayed. /// Builds the viewport through which the scrollable content is displayed.
......
...@@ -421,7 +421,8 @@ class SliverGrid extends SliverMultiBoxAdaptorWidget { ...@@ -421,7 +421,8 @@ class SliverGrid extends SliverMultiBoxAdaptorWidget {
/// ///
/// See also: /// See also:
/// ///
/// * [SliverFixedExtentList], which has a configurable [itemExtent]. /// * [SliverFixedExtentList], which has a configurable
/// [SliverFixedExtentList.itemExtent].
/// * [SliverList], which does not require its children to have the same /// * [SliverList], which does not require its children to have the same
/// extent in the main axis. /// extent in the main axis.
class SliverFillViewport extends SliverMultiBoxAdaptorWidget { class SliverFillViewport extends SliverMultiBoxAdaptorWidget {
......
...@@ -185,7 +185,8 @@ class Text extends StatelessWidget { ...@@ -185,7 +185,8 @@ class Text extends StatelessWidget {
/// For example, if the text scale factor is 1.5, text will be 50% larger than /// For example, if the text scale factor is 1.5, text will be 50% larger than
/// the specified font size. /// the specified font size.
/// ///
/// Defaults to [MediaQuery.textScaleFactor]. /// Defaults to the [MediaQueryData.textScaleFactor] obtained from the ambient
/// [MediaQuery], or 1.0 if there is no [MediaQuery] in scope.
final double textScaleFactor; final double textScaleFactor;
/// An optional maximum number of lines the text is allowed to take up. /// An optional maximum number of lines the text is allowed to take up.
......
...@@ -164,11 +164,11 @@ class TextSelectionOverlay implements TextSelectionDelegate { ...@@ -164,11 +164,11 @@ class TextSelectionOverlay implements TextSelectionDelegate {
_toolbarController.forward(from: 0.0); _toolbarController.forward(from: 0.0);
} }
/// Updates the overlay after the [selection] has changed. /// Updates the overlay after the selection has changed.
/// ///
/// If this method is called while the [SchedulerBinding.schedulerPhase] is /// If this method is called while the [SchedulerBinding.schedulerPhase] is
/// [SchedulerBinding.persistentCallbacks], i.e. during the build, layout, or /// [SchedulerPhase.persistentCallbacks], i.e. during the build, layout, or
/// paint phases (see [WidgetsBinding.beginFrame]), then the update is delayed /// paint phases (see [WidgetsBinding.drawFrame]), then the update is delayed
/// until the post-frame callbacks phase. Otherwise the update is done /// until the post-frame callbacks phase. Otherwise the update is done
/// synchronously. This means that it is safe to call during builds, but also /// synchronously. This means that it is safe to call during builds, but also
/// that if you do call this during a build, the UI will not update until the /// that if you do call this during a build, the UI will not update until the
......
...@@ -61,7 +61,7 @@ class Viewport extends MultiChildRenderObjectWidget { ...@@ -61,7 +61,7 @@ class Viewport extends MultiChildRenderObjectWidget {
assert(center == null || children.where((Widget child) => child.key == center).length == 1); assert(center == null || children.where((Widget child) => child.key == center).length == 1);
} }
/// The direction in which the [scrollOffset] increases. /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
/// ///
/// For example, if the [axisDirection] is [AxisDirection.down], a scroll /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
/// offset of zero is at the top of the viewport and increases towards the /// offset of zero is at the top of the viewport and increases towards the
...@@ -207,7 +207,7 @@ class ShrinkWrappingViewport extends MultiChildRenderObjectWidget { ...@@ -207,7 +207,7 @@ class ShrinkWrappingViewport extends MultiChildRenderObjectWidget {
assert(offset != null); assert(offset != null);
} }
/// The direction in which the [scrollOffset] increases. /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
/// ///
/// For example, if the [axisDirection] is [AxisDirection.down], a scroll /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
/// offset of zero is at the top of the viewport and increases towards the /// offset of zero is at the top of the viewport and increases towards the
......
...@@ -12,7 +12,7 @@ import 'routes.dart'; ...@@ -12,7 +12,7 @@ import 'routes.dart';
/// ///
/// See also: /// See also:
/// ///
/// * [ModalRoute.addScopedWillPopCallback] and [ModalScope.removeScopedWillPopCallback], /// * [ModalRoute.addScopedWillPopCallback] and [ModalRoute.removeScopedWillPopCallback],
/// which this widget uses to register and unregister [onWillPop]. /// which this widget uses to register and unregister [onWillPop].
class WillPopScope extends StatefulWidget { class WillPopScope extends StatefulWidget {
/// Creates a widget that registers a callback to veto attempts by the user to /// Creates a widget that registers a callback to veto attempts by the user to
......
...@@ -32,7 +32,8 @@ class TestRenderingFlutterBinding extends BindingBase with SchedulerBinding, Ser ...@@ -32,7 +32,8 @@ class TestRenderingFlutterBinding extends BindingBase with SchedulerBinding, Ser
pipelineOwner.flushSemantics(); pipelineOwner.flushSemantics();
if (phase == EnginePhase.flushSemantics) if (phase == EnginePhase.flushSemantics)
return; return;
assert(phase == EnginePhase.flushSemantics || phase == EnginePhase.sendSemanticsTree); assert(phase == EnginePhase.flushSemantics ||
phase == EnginePhase.sendSemanticsUpdate);
} }
} }
......
...@@ -80,7 +80,7 @@ class MarkdownStyleSheet { ...@@ -80,7 +80,7 @@ class MarkdownStyleSheet {
/// Creates a [MarkdownStyle] from the [TextStyle]s in the provided [ThemeData]. /// Creates a [MarkdownStyle] from the [TextStyle]s in the provided [ThemeData].
/// ///
/// This constructor uses larger fonts for the headings than in /// This constructor uses larger fonts for the headings than in
/// [MarkdownStyle.fromTheme]. /// [new MarkdownStyle.fromTheme].
factory MarkdownStyleSheet.largeFromTheme(ThemeData theme) { factory MarkdownStyleSheet.largeFromTheme(ThemeData theme) {
return new MarkdownStyleSheet( return new MarkdownStyleSheet(
a: const TextStyle(color: Colors.blue), a: const TextStyle(color: Colors.blue),
......
...@@ -54,8 +54,8 @@ enum EnginePhase { ...@@ -54,8 +54,8 @@ enum EnginePhase {
flushSemantics, flushSemantics,
/// The final phase in the rendering library, wherein semantics information is /// The final phase in the rendering library, wherein semantics information is
/// sent to the embedder. See [SemanticsNode.sendSemanticsTree]. /// sent to the embedder. See [SemanticsNode.sendSemanticsUpdate].
sendSemanticsTree, sendSemanticsUpdate,
} }
/// Parts of the system that can generate pointer events that reach the test /// Parts of the system that can generate pointer events that reach the test
...@@ -162,7 +162,7 @@ abstract class TestWidgetsFlutterBinding extends BindingBase ...@@ -162,7 +162,7 @@ abstract class TestWidgetsFlutterBinding extends BindingBase
/// ///
/// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
/// this method works when the test is run with `flutter run`. /// this method works when the test is run with `flutter run`.
Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsTree ]); Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsUpdate ]);
/// Artificially calls dispatchLocaleChanged on the Widget binding, /// Artificially calls dispatchLocaleChanged on the Widget binding,
/// then flushes microtasks. /// then flushes microtasks.
...@@ -512,7 +512,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding { ...@@ -512,7 +512,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
int get microtaskCount => _fakeAsync.microtaskCount; int get microtaskCount => _fakeAsync.microtaskCount;
@override @override
Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsTree ]) { Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsUpdate ]) {
return TestAsyncUtils.guard(() { return TestAsyncUtils.guard(() {
assert(inTest); assert(inTest);
assert(_clock != null); assert(_clock != null);
...@@ -548,7 +548,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding { ...@@ -548,7 +548,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
return result; return result;
} }
EnginePhase _phase = EnginePhase.sendSemanticsTree; EnginePhase _phase = EnginePhase.sendSemanticsUpdate;
// Cloned from RendererBinding.drawFrame() but with early-exit semantics. // Cloned from RendererBinding.drawFrame() but with early-exit semantics.
@override @override
...@@ -568,7 +568,8 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding { ...@@ -568,7 +568,8 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
renderView.compositeFrame(); // this sends the bits to the GPU renderView.compositeFrame(); // this sends the bits to the GPU
if (_phase != EnginePhase.composite) { if (_phase != EnginePhase.composite) {
pipelineOwner.flushSemantics(); pipelineOwner.flushSemantics();
assert(_phase == EnginePhase.flushSemantics || _phase == EnginePhase.sendSemanticsTree); assert(_phase == EnginePhase.flushSemantics ||
_phase == EnginePhase.sendSemanticsUpdate);
} }
} }
} }
...@@ -837,8 +838,8 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding { ...@@ -837,8 +838,8 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
} }
@override @override
Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsTree ]) { Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsUpdate ]) {
assert(newPhase == EnginePhase.sendSemanticsTree); assert(newPhase == EnginePhase.sendSemanticsUpdate);
assert(inTest); assert(inTest);
assert(!_expectingFrame); assert(!_expectingFrame);
assert(_pendingFrame == null); assert(_pendingFrame == null);
......
...@@ -18,7 +18,7 @@ import 'finders.dart'; ...@@ -18,7 +18,7 @@ import 'finders.dart';
/// See also: /// See also:
/// ///
/// * [findsWidgets], when you want the finder to find one or more widgets. /// * [findsWidgets], when you want the finder to find one or more widgets.
/// * [findsOneWidgets], when you want the finder to find exactly one widget. /// * [findsOneWidget], when you want the finder to find exactly one widget.
/// * [findsNWidgets], when you want the finder to find a specific number of widgets. /// * [findsNWidgets], when you want the finder to find a specific number of widgets.
const Matcher findsNothing = const _FindsWidgetMatcher(null, 0); const Matcher findsNothing = const _FindsWidgetMatcher(null, 0);
...@@ -33,7 +33,7 @@ const Matcher findsNothing = const _FindsWidgetMatcher(null, 0); ...@@ -33,7 +33,7 @@ const Matcher findsNothing = const _FindsWidgetMatcher(null, 0);
/// See also: /// See also:
/// ///
/// * [findsNothing], when you want the finder to not find anything. /// * [findsNothing], when you want the finder to not find anything.
/// * [findsOneWidgets], when you want the finder to find exactly one widget. /// * [findsOneWidget], when you want the finder to find exactly one widget.
/// * [findsNWidgets], when you want the finder to find a specific number of widgets. /// * [findsNWidgets], when you want the finder to find a specific number of widgets.
const Matcher findsWidgets = const _FindsWidgetMatcher(1, null); const Matcher findsWidgets = const _FindsWidgetMatcher(1, null);
...@@ -64,7 +64,7 @@ const Matcher findsOneWidget = const _FindsWidgetMatcher(1, 1); ...@@ -64,7 +64,7 @@ const Matcher findsOneWidget = const _FindsWidgetMatcher(1, 1);
/// ///
/// * [findsNothing], when you want the finder to not find anything. /// * [findsNothing], when you want the finder to not find anything.
/// * [findsWidgets], when you want the finder to find one or more widgets. /// * [findsWidgets], when you want the finder to find one or more widgets.
/// * [findsOneWidgets], when you want the finder to find exactly one widget. /// * [findsOneWidget], when you want the finder to find exactly one widget.
Matcher findsNWidgets(int n) => new _FindsWidgetMatcher(n, n); Matcher findsNWidgets(int n) => new _FindsWidgetMatcher(n, n);
/// Asserts that the [Finder] locates the a single widget that has at /// Asserts that the [Finder] locates the a single widget that has at
...@@ -81,7 +81,7 @@ Matcher findsNWidgets(int n) => new _FindsWidgetMatcher(n, n); ...@@ -81,7 +81,7 @@ Matcher findsNWidgets(int n) => new _FindsWidgetMatcher(n, n);
/// ///
/// See also: /// See also:
/// ///
/// * [isOnStage], the opposite. /// * [isOnstage], the opposite.
const Matcher isOffstage = const _IsOffstage(); const Matcher isOffstage = const _IsOffstage();
/// Asserts that the [Finder] locates the a single widget that has no /// Asserts that the [Finder] locates the a single widget that has no
...@@ -89,7 +89,7 @@ const Matcher isOffstage = const _IsOffstage(); ...@@ -89,7 +89,7 @@ const Matcher isOffstage = const _IsOffstage();
/// ///
/// See also: /// See also:
/// ///
/// * [isOffStage], the opposite. /// * [isOffstage], the opposite.
const Matcher isOnstage = const _IsOnstage(); const Matcher isOnstage = const _IsOnstage();
/// Asserts that the [Finder] locates the a single widget that has at /// Asserts that the [Finder] locates the a single widget that has at
...@@ -173,7 +173,7 @@ const Matcher isAssertionError = const isInstanceOf<AssertionError>(); ...@@ -173,7 +173,7 @@ const Matcher isAssertionError = const isInstanceOf<AssertionError>();
/// ///
/// * [closeTo], which is identical except that the epsilon argument is /// * [closeTo], which is identical except that the epsilon argument is
/// required and not named. /// required and not named.
/// * [isInclusiveRange], which matches if the argument is in a specified /// * [inInclusiveRange], which matches if the argument is in a specified
/// range. /// range.
Matcher moreOrLessEquals(double value, { double epsilon: 1e-10 }) { Matcher moreOrLessEquals(double value, { double epsilon: 1e-10 }) {
return new _MoreOrLessEquals(value, epsilon); return new _MoreOrLessEquals(value, epsilon);
......
...@@ -181,7 +181,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker ...@@ -181,7 +181,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
/// this method works when the test is run with `flutter run`. /// this method works when the test is run with `flutter run`.
Future<Null> pumpWidget(Widget widget, [ Future<Null> pumpWidget(Widget widget, [
Duration duration, Duration duration,
EnginePhase phase = EnginePhase.sendSemanticsTree EnginePhase phase = EnginePhase.sendSemanticsUpdate,
]) { ]) {
return TestAsyncUtils.guard(() { return TestAsyncUtils.guard(() {
binding.attachRootWidget(widget); binding.attachRootWidget(widget);
...@@ -204,7 +204,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker ...@@ -204,7 +204,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
@override @override
Future<Null> pump([ Future<Null> pump([
Duration duration, Duration duration,
EnginePhase phase = EnginePhase.sendSemanticsTree EnginePhase phase = EnginePhase.sendSemanticsUpdate,
]) { ]) {
return TestAsyncUtils.guard(() => binding.pump(duration, phase)); return TestAsyncUtils.guard(() => binding.pump(duration, phase));
} }
...@@ -235,7 +235,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker ...@@ -235,7 +235,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
/// matches the expected number of pumps. /// matches the expected number of pumps.
Future<int> pumpAndSettle([ Future<int> pumpAndSettle([
Duration duration = const Duration(milliseconds: 100), Duration duration = const Duration(milliseconds: 100),
EnginePhase phase = EnginePhase.sendSemanticsTree, EnginePhase phase = EnginePhase.sendSemanticsUpdate,
Duration timeout = const Duration(minutes: 10), Duration timeout = const Duration(minutes: 10),
]) { ]) {
assert(duration != null); assert(duration != null);
...@@ -448,7 +448,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker ...@@ -448,7 +448,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
/// Returns the TestTextInput singleton. /// Returns the TestTextInput singleton.
/// ///
/// Typical app tests will not need to use this value. To add text to widgets /// Typical app tests will not need to use this value. To add text to widgets
/// like [TextField] or [FormTextField], call [enterText]. /// like [TextField] or [TextFormField], call [enterText].
TestTextInput get testTextInput => binding.testTextInput; TestTextInput get testTextInput => binding.testTextInput;
/// Give the text input widget specified by [finder] the focus, as if the /// Give the text input widget specified by [finder] the focus, as if the
...@@ -456,10 +456,10 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker ...@@ -456,10 +456,10 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
/// ///
/// The widget specified by [finder] must be an [EditableText] or have /// The widget specified by [finder] must be an [EditableText] or have
/// an [EditableText] descendant. For example `find.byType(TextField)` /// an [EditableText] descendant. For example `find.byType(TextField)`
/// or `find.byType(FormTextField)`, or `find.byType(EditableText)`. /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
/// ///
/// Tests that just need to add text to widgets like [TextField] /// Tests that just need to add text to widgets like [TextField]
/// or [FormTextField] only need to call [enterText]. /// or [TextFormField] only need to call [enterText].
Future<Null> showKeyboard(Finder finder) async { Future<Null> showKeyboard(Finder finder) async {
return TestAsyncUtils.guard(() async { return TestAsyncUtils.guard(() async {
final EditableTextState editable = state(find.descendant( final EditableTextState editable = state(find.descendant(
...@@ -479,7 +479,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker ...@@ -479,7 +479,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
/// ///
/// The widget specified by [finder] must be an [EditableText] or have /// The widget specified by [finder] must be an [EditableText] or have
/// an [EditableText] descendant. For example `find.byType(TextField)` /// an [EditableText] descendant. For example `find.byType(TextField)`
/// or `find.byType(FormTextField)`, or `find.byType(EditableText)`. /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
/// ///
/// To just give [finder] the focus without entering any text, /// To just give [finder] the focus without entering any text,
/// see [showKeyboard]. /// see [showKeyboard].
......
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