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 { ...@@ -27,6 +27,13 @@ abstract class Curve {
/// Returns a new curve that is the reversed inversion of this one. /// Returns a new curve that is the reversed inversion of this one.
/// This is often useful as the reverseCurve of an [Animation]. /// 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); Curve get flipped => new FlippedCurve(this);
@override @override
...@@ -49,6 +56,8 @@ class _Linear extends Curve { ...@@ -49,6 +56,8 @@ class _Linear extends Curve {
/// ///
/// The curve rises linearly from 0.0 to 1.0 and then falls discontinuously back /// The curve rises linearly from 0.0 to 1.0 and then falls discontinuously back
/// to 0.0 each iteration. /// to 0.0 each iteration.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_sawtooth.png)
class SawTooth extends Curve { class SawTooth extends Curve {
/// Creates a sawtooth curve. /// Creates a sawtooth curve.
/// ///
...@@ -80,6 +89,8 @@ class SawTooth extends Curve { ...@@ -80,6 +89,8 @@ class SawTooth extends Curve {
/// animation that uses an [Interval] with its [begin] set to 0.5 and its [end] /// 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 /// set to 1.0 will essentially become a three-second animation that starts
/// three seconds later. /// three seconds later.
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_interval.png)
class Interval extends Curve { class Interval extends Curve {
/// Creates an interval curve. /// Creates an interval curve.
/// ///
...@@ -127,6 +138,8 @@ class Interval extends 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. /// 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 { class Threshold extends Curve {
/// Creates a threshold curve. /// Creates a threshold curve.
/// ///
...@@ -151,14 +164,17 @@ class Threshold extends Curve { ...@@ -151,14 +164,17 @@ class Threshold extends Curve {
/// A cubic polynomial mapping of the unit interval. /// A cubic polynomial mapping of the unit interval.
/// ///
/// See [Curves] for a number of commonly used cubic curves. /// The [Curves] class contains some commonly used cubic curves:
///
/// See also:
/// ///
/// * [Curves.ease] /// * [Curves.ease]
/// * [Curves.easeIn] /// * [Curves.easeIn]
/// * [Curves.easeOut] /// * [Curves.easeOut]
/// * [Curves.easeInOut] /// * [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 { class Cubic extends Curve {
/// Creates a cubic curve. /// Creates a cubic curve.
/// ///
...@@ -232,6 +248,11 @@ class Cubic extends 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 /// 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 /// 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). /// (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 { class FlippedCurve extends Curve {
/// Creates a flipped curve. /// Creates a flipped curve.
/// ///
...@@ -334,6 +355,11 @@ class _BounceInOutCurve extends Curve { ...@@ -334,6 +355,11 @@ class _BounceInOutCurve extends Curve {
// ELASTIC CURVES // ELASTIC CURVES
/// An oscillating curve that grows in magnitude while overshooting its bounds. /// 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 { class ElasticInCurve extends Curve {
/// Creates an elastic-in curve. /// Creates an elastic-in curve.
/// ///
...@@ -358,6 +384,11 @@ class ElasticInCurve extends Curve { ...@@ -358,6 +384,11 @@ class ElasticInCurve extends Curve {
} }
/// An oscillating curve that shrinks in magnitude while overshooting its bounds. /// 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 { class ElasticOutCurve extends Curve {
/// Creates an elastic-out curve. /// Creates an elastic-out curve.
/// ///
...@@ -380,7 +411,13 @@ class ElasticOutCurve extends 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 { class ElasticInOutCurve extends Curve {
/// Creates an elastic-in-out curve. /// Creates an elastic-in-out curve.
/// ///
...@@ -419,6 +456,8 @@ class Curves { ...@@ -419,6 +456,8 @@ class Curves {
/// This is the identity map over the unit interval: its [Curve.transform] /// 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 /// 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. /// 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._(); static const Curve linear = const _Linear._();
/// A curve where the rate of change starts out quickly and then decelerates; an /// A curve where the rate of change starts out quickly and then decelerates; an
...@@ -426,18 +465,28 @@ class Curves { ...@@ -426,18 +465,28 @@ class Curves {
/// ///
/// This is equivalent to the Android `DecelerateInterpolator` class with a unit /// This is equivalent to the Android `DecelerateInterpolator` class with a unit
/// factor (the default factor). /// factor (the default factor).
///
/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_decelerate.png)
static const Curve decelerate = const _DecelerateCurve._(); static const Curve decelerate = const _DecelerateCurve._();
/// A cubic animation curve that speeds up quickly and ends slowly. /// 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); static const Cubic ease = const Cubic(0.25, 0.1, 0.25, 1.0);
/// A cubic animation curve that starts slowly and ends quickly. /// 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); static const Cubic easeIn = const Cubic(0.42, 0.0, 1.0, 1.0);
/// A cubic animation curve that starts quickly and ends slowly. /// 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); 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. /// 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); 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. /// A curve that starts quickly and eases into its final position.
...@@ -445,23 +494,37 @@ class Curves { ...@@ -445,23 +494,37 @@ class Curves {
/// Over the course of the animation, the object spends more time near its /// 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 /// final destination. As a result, the user isn’t left waiting for the
/// animation to finish, and the negative effects of motion are minimized. /// 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); static const Cubic fastOutSlowIn = const Cubic(0.4, 0.0, 0.2, 1.0);
/// An oscillating curve that grows in magnitude. /// 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._(); static const Curve bounceIn = const _BounceInCurve._();
/// An oscillating curve that first grows and then shrink in magnitude. /// 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._(); static const Curve bounceOut = const _BounceOutCurve._();
/// An oscillating curve that first grows and then shrink in magnitude. /// 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._(); static const Curve bounceInOut = const _BounceInOutCurve._();
/// An oscillating curve that grows in magnitude while overshootings its bounds. /// 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(); static const ElasticInCurve elasticIn = const ElasticInCurve();
/// An oscillating curve that shrinks in magnitude while overshootings its bounds. /// 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(); static const ElasticOutCurve elasticOut = const ElasticOutCurve();
/// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds. /// 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(); static const ElasticInOutCurve elasticInOut = const ElasticInOutCurve();
} }
...@@ -9,7 +9,7 @@ import 'colors.dart'; ...@@ -9,7 +9,7 @@ import 'colors.dart';
// TODO(eseidel): Font weights are supposed to be language relative. // TODO(eseidel): Font weights are supposed to be language relative.
// TODO(jackson): Baseline should 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. /// Material design text theme.
/// ///
...@@ -20,11 +20,21 @@ import 'colors.dart'; ...@@ -20,11 +20,21 @@ import 'colors.dart';
/// To obtain the current text theme, call [Theme.of] with the current /// To obtain the current text theme, call [Theme.of] with the current
/// [BuildContext] and read the [ThemeData.textTheme] property. /// [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: /// See also:
/// ///
/// * [Typography] /// * [Typography], the class that generates [TextTheme]s appropriate for a platform.
/// * [Theme] /// * [Theme], for other aspects of a material design application that can be
/// * [ThemeData] /// globally adjusted, such as the color scheme.
/// * <http://material.google.com/style/typography.html> /// * <http://material.google.com/style/typography.html>
@immutable @immutable
class TextTheme { class TextTheme {
...@@ -49,7 +59,7 @@ class TextTheme { ...@@ -49,7 +59,7 @@ class TextTheme {
this.body2, this.body2,
this.body1, this.body1,
this.caption, this.caption,
this.button this.button,
}); });
const TextTheme._blackMountainView() const TextTheme._blackMountainView()
...@@ -173,7 +183,7 @@ class TextTheme { ...@@ -173,7 +183,7 @@ class TextTheme {
body2: body2 ?? this.body2, body2: body2 ?? this.body2,
body1: body1 ?? this.body1, body1: body1 ?? this.body1,
caption: caption ?? this.caption, caption: caption ?? this.caption,
button: button ?? this.button button: button ?? this.button,
); );
} }
...@@ -199,67 +209,67 @@ class TextTheme { ...@@ -199,67 +209,67 @@ class TextTheme {
color: displayColor, color: displayColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
display3: display3.apply( display3: display3.apply(
color: displayColor, color: displayColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
display2: display2.apply( display2: display2.apply(
color: displayColor, color: displayColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
display1: display1.apply( display1: display1.apply(
color: displayColor, color: displayColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
headline: headline.apply( headline: headline.apply(
color: bodyColor, color: bodyColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
title: title.apply( title: title.apply(
color: bodyColor, color: bodyColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
subhead: subhead.apply( subhead: subhead.apply(
color: bodyColor, color: bodyColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
body2: body2.apply( body2: body2.apply(
color: bodyColor, color: bodyColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
body1: body1.apply( body1: body1.apply(
color: bodyColor, color: bodyColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
caption: caption.apply( caption: caption.apply(
color: displayColor, color: displayColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
button: button.apply( button: button.apply(
color: bodyColor, color: bodyColor,
fontFamily: fontFamily, fontFamily: fontFamily,
fontSizeFactor: fontSizeFactor, fontSizeFactor: fontSizeFactor,
fontSizeDelta: fontSizeDelta fontSizeDelta: fontSizeDelta,
), ),
); );
} }
...@@ -277,7 +287,7 @@ class TextTheme { ...@@ -277,7 +287,7 @@ class TextTheme {
body2: TextStyle.lerp(begin.body2, end.body2, t), body2: TextStyle.lerp(begin.body2, end.body2, t),
body1: TextStyle.lerp(begin.body1, end.body1, t), body1: TextStyle.lerp(begin.body1, end.body1, t),
caption: TextStyle.lerp(begin.caption, end.caption, 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 { ...@@ -285,7 +295,7 @@ class TextTheme {
bool operator ==(dynamic other) { bool operator ==(dynamic other) {
if (identical(this, other)) if (identical(this, other))
return true; return true;
if (other is! TextTheme) if (other.runtimeType != runtimeType)
return false; return false;
final TextTheme typedOther = other; final TextTheme typedOther = other;
return display4 == typedOther.display4 && return display4 == typedOther.display4 &&
...@@ -331,8 +341,9 @@ class TextTheme { ...@@ -331,8 +341,9 @@ class TextTheme {
/// ///
/// See also: /// See also:
/// ///
/// * [Theme] /// * [TextTheme], which shows what the text styles in a theme look like.
/// * [ThemeData] /// * [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> /// * <http://material.google.com/style/typography.html>
class Typography { class Typography {
/// Creates the default typography for the specified platform. /// Creates the default typography for the specified platform.
......
...@@ -13,22 +13,6 @@ import 'basic_types.dart'; ...@@ -13,22 +13,6 @@ import 'basic_types.dart';
/// ///
/// See also [applyBoxFit], which applies the sizing semantics of these values /// See also [applyBoxFit], which applies the sizing semantics of these values
/// (though not the alignment semantics). /// (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 { enum BoxFit {
/// Fill the target box by distorting the source's aspect ratio. /// Fill the target box by distorting the source's aspect ratio.
/// ///
......
...@@ -773,7 +773,7 @@ class RenderOpacity extends RenderProxyBox { ...@@ -773,7 +773,7 @@ class RenderOpacity extends RenderProxyBox {
/// Signature for a function that creates a [Shader] for a given [Rect]. /// 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); 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.
...@@ -1868,7 +1868,14 @@ class RenderFractionalTranslation extends RenderProxyBox { ...@@ -1868,7 +1868,14 @@ class RenderFractionalTranslation extends RenderProxyBox {
/// } /// }
/// ///
/// @override /// @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 ...@@ -61,6 +61,25 @@ export 'package:flutter/rendering.dart' show
/// expensive because it requires painting the child into an intermediate /// 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 /// 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. /// 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 { class Opacity extends SingleChildRenderObjectWidget {
/// Creates a widget that makes its child partially transparent. /// Creates a widget that makes its child partially transparent.
/// ///
...@@ -69,7 +88,7 @@ class Opacity extends SingleChildRenderObjectWidget { ...@@ -69,7 +88,7 @@ class Opacity extends SingleChildRenderObjectWidget {
const Opacity({ const Opacity({
Key key, Key key,
@required this.opacity, @required this.opacity,
Widget child Widget child,
}) : assert(opacity != null && opacity >= 0.0 && opacity <= 1.0), }) : assert(opacity != null && opacity >= 0.0 && opacity <= 1.0),
super(key: key, child: child); super(key: key, child: child);
...@@ -104,6 +123,30 @@ class Opacity extends SingleChildRenderObjectWidget { ...@@ -104,6 +123,30 @@ class Opacity extends SingleChildRenderObjectWidget {
/// ///
/// 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 [new ui.Gradient.linear] mask. /// 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 { 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.
/// ///
...@@ -117,10 +160,14 @@ class ShaderMask extends SingleChildRenderObjectWidget { ...@@ -117,10 +160,14 @@ class ShaderMask extends SingleChildRenderObjectWidget {
assert(blendMode != null), assert(blendMode != null),
super(key: key, child: child); 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 /// 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. /// 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; final ShaderCallback shaderCallback;
/// The [BlendMode] to use when applying the shader to the child. /// The [BlendMode] to use when applying the shader to the child.
...@@ -133,7 +180,7 @@ class ShaderMask extends SingleChildRenderObjectWidget { ...@@ -133,7 +180,7 @@ class ShaderMask extends SingleChildRenderObjectWidget {
RenderShaderMask createRenderObject(BuildContext context) { RenderShaderMask createRenderObject(BuildContext context) {
return new RenderShaderMask( return new RenderShaderMask(
shaderCallback: shaderCallback, shaderCallback: shaderCallback,
blendMode: blendMode blendMode: blendMode,
); );
} }
...@@ -682,6 +729,23 @@ class FractionalTranslation extends SingleChildRenderObjectWidget { ...@@ -682,6 +729,23 @@ class FractionalTranslation extends SingleChildRenderObjectWidget {
/// Unlike [Transform], which applies a transform just prior to painting, /// Unlike [Transform], which applies a transform just prior to painting,
/// this object applies its rotation prior to layout, which means the entire /// 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. /// 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 { class RotatedBox extends SingleChildRenderObjectWidget {
/// A widget that rotates its child. /// A widget that rotates its child.
/// ///
...@@ -689,7 +753,7 @@ class RotatedBox extends SingleChildRenderObjectWidget { ...@@ -689,7 +753,7 @@ class RotatedBox extends SingleChildRenderObjectWidget {
const RotatedBox({ const RotatedBox({
Key key, Key key,
@required this.quarterTurns, @required this.quarterTurns,
Widget child Widget child,
}) : assert(quarterTurns != null), }) : assert(quarterTurns != null),
super(key: key, child: child); super(key: key, child: child);
...@@ -712,6 +776,17 @@ class RotatedBox extends SingleChildRenderObjectWidget { ...@@ -712,6 +776,17 @@ class RotatedBox extends SingleChildRenderObjectWidget {
/// size. Padding then sizes itself to its child's size, inflated by the /// size. Padding then sizes itself to its child's size, inflated by the
/// padding, effectively creating empty space around the child. /// 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 /// ## Design discussion
/// ///
/// ### Why use a [Padding] widget rather than a [Container] with a [Container.padding] property? /// ### Why use a [Padding] widget rather than a [Container] with a [Container.padding] property?
...@@ -731,6 +806,12 @@ class RotatedBox extends SingleChildRenderObjectWidget { ...@@ -731,6 +806,12 @@ class RotatedBox extends SingleChildRenderObjectWidget {
/// In fact, the majority of widgets in Flutter are simply combinations of other /// In fact, the majority of widgets in Flutter are simply combinations of other
/// simpler widgets. Composition, rather than inheritance, is the primary /// simpler widgets. Composition, rather than inheritance, is the primary
/// mechansim for building up widgets. /// 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 { class Padding extends SingleChildRenderObjectWidget {
/// Creates a widget that insets its child. /// Creates a widget that insets its child.
/// ///
...@@ -738,7 +819,7 @@ class Padding extends SingleChildRenderObjectWidget { ...@@ -738,7 +819,7 @@ class Padding extends SingleChildRenderObjectWidget {
const Padding({ const Padding({
Key key, Key key,
@required this.padding, @required this.padding,
Widget child Widget child,
}) : assert(padding != null), }) : assert(padding != null),
super(key: key, child: child); super(key: key, child: child);
...@@ -1001,6 +1082,30 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget { ...@@ -1001,6 +1082,30 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
/// The [new SizedBox.expand] constructor can be used to make a [SizedBox] that /// 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 /// sizes itself to fit the parent. It is equivalent to setting [width] and
/// [height] to [double.INFINITY]. /// [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 { class SizedBox extends SingleChildRenderObjectWidget {
/// Creates a fixed size box. The [width] and [height] parameters can be null /// 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 /// to indicate that the size of the box should not be constrained in
...@@ -1028,7 +1133,7 @@ class SizedBox extends SingleChildRenderObjectWidget { ...@@ -1028,7 +1133,7 @@ class SizedBox extends SingleChildRenderObjectWidget {
@override @override
RenderConstrainedBox createRenderObject(BuildContext context) => new RenderConstrainedBox( RenderConstrainedBox createRenderObject(BuildContext context) => new RenderConstrainedBox(
additionalConstraints: _additionalConstraints additionalConstraints: _additionalConstraints,
); );
BoxConstraints get _additionalConstraints { BoxConstraints get _additionalConstraints {
...@@ -1062,8 +1167,32 @@ class SizedBox extends SingleChildRenderObjectWidget { ...@@ -1062,8 +1167,32 @@ class SizedBox extends SingleChildRenderObjectWidget {
/// A widget that imposes additional constraints on its child. /// A widget that imposes additional constraints on its child.
/// ///
/// For example, if you wanted [child] to have a minimum height of 50.0 logical /// 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]. /// [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 { class ConstrainedBox extends SingleChildRenderObjectWidget {
/// Creates a widget that imposes additional constraints on its child. /// Creates a widget that imposes additional constraints on its child.
/// ///
...@@ -1190,6 +1319,13 @@ class FractionallySizedBox extends SingleChildRenderObjectWidget { ...@@ -1190,6 +1319,13 @@ class FractionallySizedBox extends SingleChildRenderObjectWidget {
/// This is useful when composing widgets that normally try to match their /// This is useful when composing widgets that normally try to match their
/// parents' size, so that they behave reasonably in lists (which are /// parents' size, so that they behave reasonably in lists (which are
/// unbounded). /// 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 { class LimitedBox extends SingleChildRenderObjectWidget {
/// Creates a box that limits its size only when it's unconstrained. /// Creates a box that limits its size only when it's unconstrained.
/// ///
...@@ -1199,7 +1335,7 @@ class LimitedBox extends SingleChildRenderObjectWidget { ...@@ -1199,7 +1335,7 @@ class LimitedBox extends SingleChildRenderObjectWidget {
Key key, Key key,
this.maxWidth: double.INFINITY, this.maxWidth: double.INFINITY,
this.maxHeight: double.INFINITY, this.maxHeight: double.INFINITY,
Widget child Widget child,
}) : assert(maxWidth != null && maxWidth >= 0.0), }) : assert(maxWidth != null && maxWidth >= 0.0),
assert(maxHeight != null && maxHeight >= 0.0), assert(maxHeight != null && maxHeight >= 0.0),
super(key: key, child: child); super(key: key, child: child);
...@@ -2188,6 +2324,64 @@ class Flex extends MultiChildRenderObjectWidget { ...@@ -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 /// ## Layout algorithm
/// ///
/// _This section describes how a [Row] is rendered by the framework._ /// _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