Commit 1b9c6a68 authored by Ian Hickson's avatar Ian Hickson Committed by GitHub

More documentation (#10426)

parent 498cfc67
......@@ -27,6 +27,13 @@ abstract class Curve {
/// Returns a new curve that is the reversed inversion of this one.
/// This is often useful as the reverseCurve of an [Animation].
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in.png)
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_flipped.png)
///
/// See also:
///
/// * [FlippedCurve], the class that is used to implement this getter.
Curve get flipped => new FlippedCurve(this);
@override
......@@ -49,6 +56,8 @@ class _Linear extends Curve {
///
/// The curve rises linearly from 0.0 to 1.0 and then falls discontinuously back
/// to 0.0 each iteration.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_sawtooth.png)
class SawTooth extends Curve {
/// Creates a sawtooth curve.
///
......@@ -80,6 +89,8 @@ class SawTooth extends Curve {
/// animation that uses an [Interval] with its [begin] set to 0.5 and its [end]
/// set to 1.0 will essentially become a three-second animation that starts
/// three seconds later.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_interval.png)
class Interval extends Curve {
/// Creates an interval curve.
///
......@@ -127,6 +138,8 @@ class Interval extends Curve {
}
/// A curve that is 0.0 until it hits the threshold, then it jumps to 1.0.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_threshold.png)
class Threshold extends Curve {
/// Creates a threshold curve.
///
......@@ -151,14 +164,17 @@ class Threshold extends Curve {
/// A cubic polynomial mapping of the unit interval.
///
/// See [Curves] for a number of commonly used cubic curves.
///
/// See also:
/// The [Curves] class contains some commonly used cubic curves:
///
/// * [Curves.ease]
/// * [Curves.easeIn]
/// * [Curves.easeOut]
/// * [Curves.easeInOut]
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease.png)
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in.png)
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_out.png)
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in_out.png)
class Cubic extends Curve {
/// Creates a cubic curve.
///
......@@ -232,6 +248,11 @@ class Cubic extends Curve {
/// This curve evalutes the given curve in reverse (i.e., from 1.0 to 0.0 as t
/// increases from 0.0 to 1.0) and returns the inverse of the given curve's value
/// (i.e., 1.0 minus the given curve's value).
///
/// This is the class used to implement the [flipped] getter on curves.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in.png)
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_flipped_curve.png)
class FlippedCurve extends Curve {
/// Creates a flipped curve.
///
......@@ -334,6 +355,11 @@ class _BounceInOutCurve extends Curve {
// ELASTIC CURVES
/// An oscillating curve that grows in magnitude while overshooting its bounds.
///
/// An instance of this class using the default period of 0.4 is available as
/// [Curves.elasticIn].
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in.png)
class ElasticInCurve extends Curve {
/// Creates an elastic-in curve.
///
......@@ -358,6 +384,11 @@ class ElasticInCurve extends Curve {
}
/// An oscillating curve that shrinks in magnitude while overshooting its bounds.
///
/// An instance of this class using the default period of 0.4 is available as
/// [Curves.elasticOut].
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_out.png)
class ElasticOutCurve extends Curve {
/// Creates an elastic-out curve.
///
......@@ -380,7 +411,13 @@ class ElasticOutCurve extends Curve {
}
}
/// An oscillating curve that grows and then shrinks in magnitude while overshooting its bounds.
/// An oscillating curve that grows and then shrinks in magnitude while
/// overshooting its bounds.
///
/// An instance of this class using the default period of 0.4 is available as
/// [Curves.elasticInOut].
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in_out.png)
class ElasticInOutCurve extends Curve {
/// Creates an elastic-in-out curve.
///
......@@ -419,6 +456,8 @@ class Curves {
/// This is the identity map over the unit interval: its [Curve.transform]
/// method returns its input unmodified. This is useful as a default curve for
/// cases where a [Curve] is required but no actual curve is desired.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_linear.png)
static const Curve linear = const _Linear._();
/// A curve where the rate of change starts out quickly and then decelerates; an
......@@ -426,18 +465,28 @@ class Curves {
///
/// This is equivalent to the Android `DecelerateInterpolator` class with a unit
/// factor (the default factor).
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_decelerate.png)
static const Curve decelerate = const _DecelerateCurve._();
/// A cubic animation curve that speeds up quickly and ends slowly.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease.png)
static const Cubic ease = const Cubic(0.25, 0.1, 0.25, 1.0);
/// A cubic animation curve that starts slowly and ends quickly.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in.png)
static const Cubic easeIn = const Cubic(0.42, 0.0, 1.0, 1.0);
/// A cubic animation curve that starts quickly and ends slowly.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_out.png)
static const Cubic easeOut = const Cubic(0.0, 0.0, 0.58, 1.0);
/// A cubic animation curve that starts slowly, speeds up, and then and ends slowly.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in_out.png)
static const Cubic easeInOut = const Cubic(0.42, 0.0, 0.58, 1.0);
/// A curve that starts quickly and eases into its final position.
......@@ -445,23 +494,37 @@ class Curves {
/// Over the course of the animation, the object spends more time near its
/// final destination. As a result, the user isn’t left waiting for the
/// animation to finish, and the negative effects of motion are minimized.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_fast_out_slow_in.png)
static const Cubic fastOutSlowIn = const Cubic(0.4, 0.0, 0.2, 1.0);
/// An oscillating curve that grows in magnitude.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in.png)
static const Curve bounceIn = const _BounceInCurve._();
/// An oscillating curve that first grows and then shrink in magnitude.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_out.png)
static const Curve bounceOut = const _BounceOutCurve._();
/// An oscillating curve that first grows and then shrink in magnitude.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in_out.png)
static const Curve bounceInOut = const _BounceInOutCurve._();
/// An oscillating curve that grows in magnitude while overshootings its bounds.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in.png)
static const ElasticInCurve elasticIn = const ElasticInCurve();
/// An oscillating curve that shrinks in magnitude while overshootings its bounds.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_out.png)
static const ElasticOutCurve elasticOut = const ElasticOutCurve();
/// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in_out.png)
static const ElasticInOutCurve elasticInOut = const ElasticInOutCurve();
}
......@@ -9,7 +9,7 @@ import 'colors.dart';
// TODO(eseidel): Font weights are supposed to be language relative.
// TODO(jackson): Baseline should be language relative.
// These values are for English-like text.
// TODO(ianh): These values are for English-like text.
/// Material design text theme.
///
......@@ -20,11 +20,21 @@ import 'colors.dart';
/// To obtain the current text theme, call [Theme.of] with the current
/// [BuildContext] and read the [ThemeData.textTheme] property.
///
/// The following image [from the material design
/// specification](https://material.io/guidelines/style/typography.html#typography-styles)
/// shows the recommended styles for each of the properties of a [TextTheme].
/// This image uses the `Roboto` font, which is the font used on Android. On
/// iOS, the [San Francisco
/// font](https://developer.apple.com/ios/human-interface-guidelines/visual-design/typography/)
/// is automatically used instead.
///
/// ![To see the image, visit the typography site referenced below.](https://storage.googleapis.com/material-design/publish/material_v_11/assets/0Bzhp5Z4wHba3alhXZ2pPWGk3Zjg/style_typography_styles_scale.png)
///
/// See also:
///
/// * [Typography]
/// * [Theme]
/// * [ThemeData]
/// * [Typography], the class that generates [TextTheme]s appropriate for a platform.
/// * [Theme], for other aspects of a material design application that can be
/// globally adjusted, such as the color scheme.
/// * <http://material.google.com/style/typography.html>
@immutable
class TextTheme {
......@@ -49,7 +59,7 @@ class TextTheme {
this.body2,
this.body1,
this.caption,
this.button
this.button,
});
const TextTheme._blackMountainView()
......@@ -173,7 +183,7 @@ class TextTheme {
body2: body2 ?? this.body2,
body1: body1 ?? this.body1,
caption: caption ?? this.caption,
button: button ?? this.button
button: button ?? this.button,
);
}
......@@ -199,67 +209,67 @@ class TextTheme {
color: displayColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
display3: display3.apply(
color: displayColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
display2: display2.apply(
color: displayColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
display1: display1.apply(
color: displayColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
headline: headline.apply(
color: bodyColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
title: title.apply(
color: bodyColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
subhead: subhead.apply(
color: bodyColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
body2: body2.apply(
color: bodyColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
body1: body1.apply(
color: bodyColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
caption: caption.apply(
color: displayColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
button: button.apply(
color: bodyColor,
fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta
fontSizeDelta: fontSizeDelta,
),
);
}
......@@ -277,7 +287,7 @@ class TextTheme {
body2: TextStyle.lerp(begin.body2, end.body2, t),
body1: TextStyle.lerp(begin.body1, end.body1, t),
caption: TextStyle.lerp(begin.caption, end.caption, t),
button: TextStyle.lerp(begin.button, end.button, t)
button: TextStyle.lerp(begin.button, end.button, t),
);
}
......@@ -285,7 +295,7 @@ class TextTheme {
bool operator ==(dynamic other) {
if (identical(this, other))
return true;
if (other is! TextTheme)
if (other.runtimeType != runtimeType)
return false;
final TextTheme typedOther = other;
return display4 == typedOther.display4 &&
......@@ -331,8 +341,9 @@ class TextTheme {
///
/// See also:
///
/// * [Theme]
/// * [ThemeData]
/// * [TextTheme], which shows what the text styles in a theme look like.
/// * [Theme], for other aspects of a material design application that can be
/// globally adjusted, such as the color scheme.
/// * <http://material.google.com/style/typography.html>
class Typography {
/// Creates the default typography for the specified platform.
......
......@@ -13,22 +13,6 @@ import 'basic_types.dart';
///
/// See also [applyBoxFit], which applies the sizing semantics of these values
/// (though not the alignment semantics).
///
/// The following diagrams show the effects of each value:
///
/// ![`fill`: Fill the target box by distorting the source's aspect ratio.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fill.png)
///
/// ![`contain`: As large as possible while still containing the source entirely within the target box.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_contain.png)
///
/// ![`cover`: As small as possible while still covering the entire target box.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_cover.png)
///
/// ![`fitWidth`: Make sure the full width of the source is shown.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitWidth.png)
///
/// ![`fitHeight`: Make sure the full height of the source is shown.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitHeight.png)
///
/// ![`none`: Do not resize the source.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_none.png)
///
/// ![`scaleDown`: Same as `contain` if that would shrink the image, otherwise same as `none`.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_scaleDown.png)
enum BoxFit {
/// Fill the target box by distorting the source's aspect ratio.
///
......
......@@ -773,7 +773,7 @@ class RenderOpacity extends RenderProxyBox {
/// Signature for a function that creates a [Shader] for a given [Rect].
///
/// Used by [RenderShaderMask].
/// Used by [RenderShaderMask] and the [ShaderMask] widget.
typedef Shader ShaderCallback(Rect bounds);
/// Applies a mask generated by a [Shader] to its child.
......@@ -1868,7 +1868,14 @@ class RenderFractionalTranslation extends RenderProxyBox {
/// }
///
/// @override
/// bool shouldRepaint(CustomPainter oldDelegate) => false;
/// bool shouldRepaint(Sky oldDelegate) {
/// // Since this Sky painter has no fields, it always paints
/// // the same thing, and therefore we return false here. If
/// // we had fields (set from the constructor) then we would
/// // return true if any of them differed from the same
/// // fields on the oldDelegate.
/// return false;
/// }
/// }
/// ```
///
......
......@@ -61,6 +61,25 @@ export 'package:flutter/rendering.dart' show
/// expensive because it requires painting the child into an intermediate
/// buffer. For the value 0.0, the child is simply not painted at all. For the
/// value 1.0, the child is painted immediately without an intermediate buffer.
///
/// ## Sample code
///
/// This example shows some [Text] when the `_visible` member field is true, and
/// hides it when it is false:
///
/// ```dart
/// new Opacity(
/// opacity: _visible ? 1.0 : 0.0,
/// child: const Text('Now you see me, now you don\'t!'),
/// )
/// ```
///
/// This is more efficient than adding and removing the child widget from the
/// tree on demand.
///
/// See also:
///
/// * [ShaderMask], which can apply more elaborate effects to its child.
class Opacity extends SingleChildRenderObjectWidget {
/// Creates a widget that makes its child partially transparent.
///
......@@ -69,7 +88,7 @@ class Opacity extends SingleChildRenderObjectWidget {
const Opacity({
Key key,
@required this.opacity,
Widget child
Widget child,
}) : assert(opacity != null && opacity >= 0.0 && opacity <= 1.0),
super(key: key, child: child);
......@@ -104,6 +123,30 @@ class Opacity extends SingleChildRenderObjectWidget {
///
/// For example, [ShaderMask] can be used to gradually fade out the edge
/// of a child by using a [new ui.Gradient.linear] mask.
///
/// ## Sample code
///
/// This example makes the text look like it is on fire:
///
/// ```dart
/// new ShaderMask(
/// shaderCallback: (Rect bounds) {
/// return new RadialGradient(
/// center: FractionalOffset.topLeft,
/// radius: 1.0,
/// colors: <Color>[Colors.yellow, Colors.deepOrange.shade900],
/// tileMode: TileMode.mirror,
/// ).createShader(bounds);
/// },
/// child: const Text('I’m burning the memories'),
/// )
/// ```
///
/// See also:
///
/// * [Opacity], which can apply a uniform alpha effect to its child.
/// * [CustomPaint], which lets you draw directly on the canvas.
/// * [DecoratedBox], for another approach at decorating child widgets.
class ShaderMask extends SingleChildRenderObjectWidget {
/// Creates a widget that applies a mask generated by a [Shader] to its child.
///
......@@ -117,10 +160,14 @@ class ShaderMask extends SingleChildRenderObjectWidget {
assert(blendMode != null),
super(key: key, child: child);
/// Called to creates the [Shader] that generates the mask.
/// Called to create the [dart:ui.Shader] that generates the mask.
///
/// The shader callback is called with the current size of the child so that
/// it can customize the shader to the size and location of the child.
///
/// Typically this will use a [LinearGradient] or [RadialGradient] to create
/// the [dart:ui.Shader], though the [dart:ui.ImageShader] class could also be
/// used.
final ShaderCallback shaderCallback;
/// The [BlendMode] to use when applying the shader to the child.
......@@ -133,7 +180,7 @@ class ShaderMask extends SingleChildRenderObjectWidget {
RenderShaderMask createRenderObject(BuildContext context) {
return new RenderShaderMask(
shaderCallback: shaderCallback,
blendMode: blendMode
blendMode: blendMode,
);
}
......@@ -682,6 +729,23 @@ class FractionalTranslation extends SingleChildRenderObjectWidget {
/// Unlike [Transform], which applies a transform just prior to painting,
/// this object applies its rotation prior to layout, which means the entire
/// rotated box consumes only as much space as required by the rotated child.
///
/// ## Sample code
///
/// This snippet rotates the child (some [Text]) so that it renders from bottom
/// to top, like an axis label on a graph:
///
/// ```dart
/// new RotatedBox(
/// quarterTurns: 3,
/// child: const Text('Hello World!'),
/// )
/// ```
///
/// See also:
///
/// * [Transform], which is a paint effect that allows you to apply an
/// arbitrary transform to a child.
class RotatedBox extends SingleChildRenderObjectWidget {
/// A widget that rotates its child.
///
......@@ -689,7 +753,7 @@ class RotatedBox extends SingleChildRenderObjectWidget {
const RotatedBox({
Key key,
@required this.quarterTurns,
Widget child
Widget child,
}) : assert(quarterTurns != null),
super(key: key, child: child);
......@@ -712,6 +776,17 @@ class RotatedBox extends SingleChildRenderObjectWidget {
/// size. Padding then sizes itself to its child's size, inflated by the
/// padding, effectively creating empty space around the child.
///
/// ## Sample code
///
/// This snippet indents the child (a [Card] with some [Text]) by eight pixels in each direction:
///
/// ```dart
/// new Padding(
/// padding: new EdgeInsets.all(8.0),
/// child: const Card(child: const Text('Hello World!')),
/// )
/// ```
///
/// ## Design discussion
///
/// ### Why use a [Padding] widget rather than a [Container] with a [Container.padding] property?
......@@ -731,6 +806,12 @@ class RotatedBox extends SingleChildRenderObjectWidget {
/// In fact, the majority of widgets in Flutter are simply combinations of other
/// simpler widgets. Composition, rather than inheritance, is the primary
/// mechansim for building up widgets.
///
/// See also:
///
/// * [EdgeInsets], the class that is used to describe the padding dimensions.
/// * [Center], which positions the child at its natural dimensions, centered
/// in the parent.
class Padding extends SingleChildRenderObjectWidget {
/// Creates a widget that insets its child.
///
......@@ -738,7 +819,7 @@ class Padding extends SingleChildRenderObjectWidget {
const Padding({
Key key,
@required this.padding,
Widget child
Widget child,
}) : assert(padding != null),
super(key: key, child: child);
......@@ -1001,6 +1082,30 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
/// The [new SizedBox.expand] constructor can be used to make a [SizedBox] that
/// sizes itself to fit the parent. It is equivalent to setting [width] and
/// [height] to [double.INFINITY].
///
/// ## Sample code
///
/// This snippet makes the child widget (a [Card] with some [Text]) have the
/// exact size 200x300, parental constraints permitting:
///
/// ```dart
/// new SizedBox(
/// width: 200.0,
/// height: 300.0,
/// child: const Card(child: const Text('Hello World!')),
/// )
/// ```
///
/// See also:
///
/// * [ConstrainedBox], a more generic version of this class that takes
/// arbitrary [BoxConstraints] instead of an explicit width and height.
/// * [FractionallySizedBox], a widget that sizes its child to a fraction of
/// the total available space.
/// * [AspectRatio], a widget that attempts to fit within the parent's
/// constraints while also sizing its child to match a given sapect ratio.
/// * [FittedBox], which sizes and positions its child widget to fit the parent
/// according to a given [BoxFit] discipline.
class SizedBox extends SingleChildRenderObjectWidget {
/// Creates a fixed size box. The [width] and [height] parameters can be null
/// to indicate that the size of the box should not be constrained in
......@@ -1028,7 +1133,7 @@ class SizedBox extends SingleChildRenderObjectWidget {
@override
RenderConstrainedBox createRenderObject(BuildContext context) => new RenderConstrainedBox(
additionalConstraints: _additionalConstraints
additionalConstraints: _additionalConstraints,
);
BoxConstraints get _additionalConstraints {
......@@ -1062,8 +1167,32 @@ class SizedBox extends SingleChildRenderObjectWidget {
/// A widget that imposes additional constraints on its child.
///
/// For example, if you wanted [child] to have a minimum height of 50.0 logical
/// pixels, you could use `const BoxConstraints(minHeight: 50.0)`` as the
/// pixels, you could use `const BoxConstraints(minHeight: 50.0)` as the
/// [constraints].
///
/// ## Sample code
///
/// This snippet makes the child widget (a [Card] with some [Text]) fill the
/// parent, by applying [BoxConstraints.expand] constraints:
///
/// ```dart
/// new ConstrainedBox(
/// constraints: const BoxConstraints.expand(),
/// child: const Card(child: const Text('Hello World!')),
/// )
/// ```
///
/// The same behaviour can be obtained using the [new SizedBox.expand] widget.
///
/// See also:
///
/// * [BoxConstraints], the class that describes constraints.
/// * [SizedBox], which lets you specify tight constraints by explicitly
/// specifying the height or width.
/// * [FractionallySizedBox], a widget that sizes its child to a fraction of
/// the total available space.
/// * [AspectRatio], a widget that attempts to fit within the parent's
/// constraints while also sizing its child to match a given sapect ratio.
class ConstrainedBox extends SingleChildRenderObjectWidget {
/// Creates a widget that imposes additional constraints on its child.
///
......@@ -1190,6 +1319,13 @@ class FractionallySizedBox extends SingleChildRenderObjectWidget {
/// This is useful when composing widgets that normally try to match their
/// parents' size, so that they behave reasonably in lists (which are
/// unbounded).
///
/// See also:
///
/// * [ConstrainedBox], which applies its constraints in all cases, not just
/// when the incoming constraints are unbounded.
/// * [SizedBox], which lets you specify tight constraints by explicitly
/// specifying the height or width.
class LimitedBox extends SingleChildRenderObjectWidget {
/// Creates a box that limits its size only when it's unconstrained.
///
......@@ -1199,7 +1335,7 @@ class LimitedBox extends SingleChildRenderObjectWidget {
Key key,
this.maxWidth: double.INFINITY,
this.maxHeight: double.INFINITY,
Widget child
Widget child,
}) : assert(maxWidth != null && maxWidth >= 0.0),
assert(maxHeight != null && maxHeight >= 0.0),
super(key: key, child: child);
......@@ -2188,6 +2324,64 @@ class Flex extends MultiChildRenderObjectWidget {
/// )
/// ```
///
/// ## Troubleshooting
///
/// ### Why is my row turning red?
///
/// If the contents of the row overflow, meaning that together they are wider
/// than the row, then the row runs out of space to give its [Expanded] and
/// [Flexible] children, and reports this by drawing a red warning box on the
/// edge that is overflowing.
///
/// #### Story time
///
/// Suppose, for instance, that you had this code:
///
/// ```dart
/// new Row(
/// children: <Widget>[
/// const FlutterLogo(),
/// const Text('Flutter\'s hot reload helps you quickly and easily experiment, build UIs, add features, and fix bug faster. Experience sub-second reload times, without losing state, on emulators, simulators, and hardware for iOS and Android.'),
/// const Icon(Icons.sentiment_very_satisfied),
/// ],
/// )
/// ```
///
/// The row first asks its first child, the [FlutterLogo], to lay out, at
/// whatever size the logo would like. The logo is friendly and happily decides
/// to be 24 pixels to a side. This leaves lots of room for the next child. The
/// row then asks that next child, the text, to lay out, at whatever size it
/// thinks is best.
///
/// At this point, the text, not knowing how wide is too wide, says "Ok, I will
/// be thiiiiiiiiiiiiiiiiiiiis wide.", and goes well beyond the space that the
/// row has available, not wrapping. The row responds, "That's not fair, now I
/// have no more room available for my other children!", and gets angry and
/// turns red.
///
/// The fix is to wrap the second child in an [Expanded] widget, which tells the
/// row that the child should be given the remaining room:
///
/// ```dart
/// new Row(
/// children: <Widget>[
/// const FlutterLogo(),
/// const Expanded(
/// child: const Text('Flutter\'s hot reload helps you quickly and easily experiment, build UIs, add features, and fix bug faster. Experience sub-second reload times, without losing state, on emulators, simulators, and hardware for iOS and Android.'),
/// ),
/// const Icon(Icons.sentiment_very_satisfied),
/// ],
/// )
/// ```
///
/// Now, the row first asks the logo to lay out, and then asks the _icon_ to lay
/// out. The [Icon], like the logo, is happy to take on a reasonable size (also
/// 24 pixels, not coincidentally, since both [FlutterLogo] and [Icon] honor the
/// ambient [IconTheme]). This leaves some room left over, and now the row tells
/// the text exactly how wide to be: the exact width of the remaining space. The
/// text, now happy to comply to a reasonable request, wraps the text within
/// that width, and you end up with a paragraph split over several lines.
///
/// ## Layout algorithm
///
/// _This section describes how a [Row] is rendered by the framework._
......
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