From 5d8bad74d22b45c57ad9073d1feda0e9a5d20ae0 Mon Sep 17 00:00:00 2001 From: Adam Barth Date: Mon, 3 Apr 2017 22:08:51 -0700 Subject: [PATCH] Add more dartdocs (#9174) --- .../cupertino/cupertino_buttons_demo.dart | 6 +- .../demo/cupertino/cupertino_dialog_demo.dart | 8 +- .../flutter/lib/src/cupertino/button.dart | 24 ++-- .../flutter/lib/src/cupertino/switch.dart | 1 + .../lib/src/cupertino/thumb_painter.dart | 14 +++ .../lib/src/gestures/velocity_tracker.dart | 3 + packages/flutter/lib/src/material/colors.dart | 110 +++++++++++------- .../flutter/lib/src/material/list_tile.dart | 4 +- packages/flutter/lib/src/material/page.dart | 5 + .../lib/src/material/text_selection.dart | 1 + .../lib/src/widgets/editable_text.dart | 43 +++++++ 11 files changed, 160 insertions(+), 59 deletions(-) diff --git a/examples/flutter_gallery/lib/demo/cupertino/cupertino_buttons_demo.dart b/examples/flutter_gallery/lib/demo/cupertino/cupertino_buttons_demo.dart index 99525f8486e..aeee81583fc 100644 --- a/examples/flutter_gallery/lib/demo/cupertino/cupertino_buttons_demo.dart +++ b/examples/flutter_gallery/lib/demo/cupertino/cupertino_buttons_demo.dart @@ -5,6 +5,8 @@ import 'package:flutter/cupertino.dart'; import 'package:flutter/material.dart'; +const Color _kBlue = const Color(0xFF007AFF); + class CupertinoButtonsDemo extends StatefulWidget { static const String routeName = '/cupertino/buttons'; @@ -55,7 +57,7 @@ class _CupertinoButtonDemoState extends State { new Padding(padding: const EdgeInsets.all(12.0)), new CupertinoButton( child: new Text('With Background'), - color: CupertinoButton.kBlue, + color: _kBlue, onPressed: () { setState(() {_pressedCount++;}); } @@ -63,7 +65,7 @@ class _CupertinoButtonDemoState extends State { new Padding(padding: const EdgeInsets.all(12.0)), new CupertinoButton( child: new Text('Disabled'), - color: CupertinoButton.kBlue, + color: _kBlue, onPressed: null, ), ], diff --git a/examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart b/examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart index b8f54978ace..e8085576a57 100644 --- a/examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart +++ b/examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart @@ -5,6 +5,8 @@ import 'package:flutter/cupertino.dart'; import 'package:flutter/material.dart'; +const Color _kBlue = const Color(0xFF007AFF); + class CupertinoDialogDemo extends StatefulWidget { static const String routeName = '/cupertino/dialog'; @@ -30,8 +32,6 @@ class _CupertinoDialogDemoState extends State { }); } - - @override Widget build(BuildContext context) { return new Scaffold( @@ -44,7 +44,7 @@ class _CupertinoDialogDemoState extends State { children: [ new CupertinoButton( child: new Text('Alert'), - color: CupertinoButton.kBlue, + color: _kBlue, onPressed: () { showDemoDialog( context: context, @@ -68,7 +68,7 @@ class _CupertinoDialogDemoState extends State { new Padding(padding: const EdgeInsets.all(8.0)), new CupertinoButton( child: new Text('Alert with Title'), - color: CupertinoButton.kBlue, + color: _kBlue, padding: const EdgeInsets.symmetric(vertical: 16.0, horizontal: 36.0), onPressed: () { showDemoDialog( diff --git a/packages/flutter/lib/src/cupertino/button.dart b/packages/flutter/lib/src/cupertino/button.dart index b48e9c044cb..7e6b99ea6f1 100644 --- a/packages/flutter/lib/src/cupertino/button.dart +++ b/packages/flutter/lib/src/cupertino/button.dart @@ -5,28 +5,34 @@ import 'package:flutter/foundation.dart'; import 'package:flutter/widgets.dart'; +// TODO(xster): move this to a common Cupertino color palette with the next yak. +const Color _kBlue = const Color(0xFF007AFF); +const Color _kWhite = const Color(0xFFFFFFFF); +const Color _kDisabledBackground = const Color(0xFFA9A9A9); +const Color _kDisabledForeground = const Color(0xFFC4C4C4); + const TextStyle _kButtonTextStyle = const TextStyle( fontFamily: '.SF UI Text', inherit: false, fontSize: 15.0, fontWeight: FontWeight.normal, - color: CupertinoButton.kBlue, + color: _kBlue, textBaseline: TextBaseline.alphabetic, ); final TextStyle _kDisabledButtonTextStyle = _kButtonTextStyle.copyWith( - color: CupertinoButton.kDisabledForeground, + color: _kDisabledForeground, ); final TextStyle _kBackgroundButtonTextStyle = _kButtonTextStyle.copyWith( - color: CupertinoButton.kWhite, + color: _kWhite, ); const EdgeInsets _kButtonPadding = const EdgeInsets.all(16.0); const EdgeInsets _kBackgroundButtonPadding = const EdgeInsets.symmetric(vertical: 16.0, horizontal: 64.0); -/// An iOS style button. +/// An iOS-style button. /// /// Takes in a text or an icon that fades out and in on touch. May optionally have a /// background. @@ -35,13 +41,7 @@ const EdgeInsets _kBackgroundButtonPadding = /// /// * class CupertinoButton extends StatefulWidget { - // TODO(xster): move this to a common Cupertino color palatte with the next yak. - static const Color kBlue = const Color(0xFF007AFF); - static const Color kWhite = const Color(0xFFFFFFFF); - static const Color kDisabledBackground = const Color(0xFFA9A9A9); - static const Color kDisabledForeground = const Color(0xFFC4C4C4); - - + /// Creates an iOS-style button. CupertinoButton({ @required this.child, this.padding, @@ -156,7 +156,7 @@ class _CupertinoButtonState extends State with SingleTickerProv decoration: new BoxDecoration( borderRadius: const BorderRadius.all(const Radius.circular(8.0)), backgroundColor: backgroundColor != null && !enabled - ? CupertinoButton.kDisabledBackground + ? _kDisabledBackground : backgroundColor, ), child: new Padding( diff --git a/packages/flutter/lib/src/cupertino/switch.dart b/packages/flutter/lib/src/cupertino/switch.dart index 32bbed662b8..b7d5a56958a 100644 --- a/packages/flutter/lib/src/cupertino/switch.dart +++ b/packages/flutter/lib/src/cupertino/switch.dart @@ -25,6 +25,7 @@ import 'thumb_painter.dart'; /// /// * class CupertinoSwitch extends StatefulWidget { + /// Creates an iOS-style switch. CupertinoSwitch({ Key key, @required this.value, diff --git a/packages/flutter/lib/src/cupertino/thumb_painter.dart b/packages/flutter/lib/src/cupertino/thumb_painter.dart index d8163a20c73..ad486696a77 100644 --- a/packages/flutter/lib/src/cupertino/thumb_painter.dart +++ b/packages/flutter/lib/src/cupertino/thumb_painter.dart @@ -6,18 +6,32 @@ import 'package:flutter/painting.dart'; final MaskFilter _kShadowMaskFilter = new MaskFilter.blur(BlurStyle.normal, BoxShadow.convertRadiusToSigma(1.0)); +/// Paints an iOS-style slider thumb. +/// +/// Used by [CupertinoSwitch] and [CupertinoSlider]. class CupertinoThumbPainter { + /// Creates an object that paints an iOS-style slider thumb. CupertinoThumbPainter({ this.color: const Color(0xFFFFFFFF), this.shadowColor: const Color(0x2C000000), }); + /// The color of the interior of the thumb. final Color color; + + /// The color of the shadow case by the thumb. final Color shadowColor; + /// Half the default diameter of the thumb. static const double radius = 14.0; + + /// The default amount the thumb should be extended horizontally when pressed. static const double extension = 7.0; + /// Paints the thumb onto the given canvas in the given rectangle. + /// + /// Consider using [radius] and [extension] when deciding how large a + /// rectangle to use for the thumb. void paint(Canvas canvas, Rect rect) { final RRect rrect = new RRect.fromRectAndRadius(rect, new Radius.circular(rect.shortestSide / 2.0)); diff --git a/packages/flutter/lib/src/gestures/velocity_tracker.dart b/packages/flutter/lib/src/gestures/velocity_tracker.dart index fd615cb0007..0af4e5be1cf 100644 --- a/packages/flutter/lib/src/gestures/velocity_tracker.dart +++ b/packages/flutter/lib/src/gestures/velocity_tracker.dart @@ -147,6 +147,7 @@ class VelocityTracker { final List<_PointAtTime> _samples = new List<_PointAtTime>(_kHistorySize); int _index = 0; + /// Adds a position as the given time to the tracker. void addPosition(Duration time, Point position) { _index += 1; if (_index == _kHistorySize) @@ -154,6 +155,8 @@ class VelocityTracker { _samples[_index] = new _PointAtTime(position, time); } + /// Returns an estimate of the velocity of the object being tracked by the + /// tracker given the current information available to the tracker. VelocityEstimate getVelocityEstimate() { final List x = []; final List y = []; diff --git a/packages/flutter/lib/src/material/colors.dart b/packages/flutter/lib/src/material/colors.dart index 96750323749..77c8db70888 100644 --- a/packages/flutter/lib/src/material/colors.dart +++ b/packages/flutter/lib/src/material/colors.dart @@ -12,7 +12,7 @@ import 'dart:ui' show Color, hashValues; /// primary and accent color swatches. /// * [Colors], which defines all of the standard material design colors. class ColorSwatch extends Color { - // Creates a color that has a small table of related colors called a "swatch". + /// Creates a color that has a small table of related colors called a "swatch". const ColorSwatch(int primary, this._swatch) : super(primary); final Map _swatch; @@ -48,16 +48,37 @@ class ColorSwatch extends Color { /// /// * [Colors], which defines all of the standard material colors. class MaterialColor extends ColorSwatch { + /// Creates a color swatch with a variety of shades. const MaterialColor(int primary, Map swatch) : super(primary, swatch); + + /// The lightest shade. Color get shade50 => _swatch[50]; + + /// The second lightest shade. Color get shade100 => _swatch[100]; + + /// The third lightest shade. Color get shade200 => _swatch[200]; + + /// The fourth lightest shade. Color get shade300 => _swatch[300]; + + /// The fifth lightest shade. Color get shade400 => _swatch[400]; + + /// The default shade. Color get shade500 => _swatch[500]; + + /// The fourth darkest shade. Color get shade600 => _swatch[600]; + + /// The third darkest shade. Color get shade700 => _swatch[700]; + + /// The second darkest shade. Color get shade800 => _swatch[800]; + + /// The darkest shade. Color get shade900 => _swatch[900]; } @@ -72,11 +93,25 @@ class MaterialColor extends ColorSwatch { /// See also: /// /// * [Colors], which defines all of the standard material colors. +/// * class MaterialAccentColor extends ColorSwatch { + /// Creates a color swatch with a variety of shades appropriate for accent + /// colors. const MaterialAccentColor(int primary, Map swatch) : super(primary, swatch); + + /// The lightest shade. + Color get shade50 => _swatch[50]; + + /// The second lightest shade. Color get shade100 => _swatch[100]; + + /// The default shade. Color get shade200 => _swatch[200]; + + /// The second darkest shade. Color get shade400 => _swatch[400]; + + /// The darkest shade. Color get shade700 => _swatch[700]; } @@ -116,7 +151,6 @@ class Colors { /// Completely invisible. static const Color transparent = const Color(0x00000000); - /// Completely opaque black. static const Color black = const Color(0xFF000000); @@ -168,7 +202,6 @@ class Colors { /// Used for the background of disabled raised buttons in light themes. static const Color black12 = const Color(0x1F000000); - /// Completely opaque white. /// /// This is a good contrasting color for the [ThemeData.primaryColor] in the @@ -211,7 +244,6 @@ class Colors { /// White with 10% opacity. static const Color white10 = const Color(0x1AFFFFFF); - /// The red primary color and swatch. /// /// ```dart @@ -226,7 +258,6 @@ class Colors { /// * [redAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _redPrimaryValue = 0xFFF44336; static const MaterialColor red = const MaterialColor( _redPrimaryValue, const { @@ -242,6 +273,7 @@ class Colors { 900: const Color(0xFFB71C1C), }, ); + static const int _redPrimaryValue = 0xFFF44336; /// The red accent swatch. /// @@ -257,7 +289,6 @@ class Colors { /// * [red], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _redAccentValue = 0xFFFF5252; static const MaterialAccentColor redAccent = const MaterialAccentColor( _redAccentValue, const { @@ -267,6 +298,7 @@ class Colors { 700: const Color(0xFFD50000), }, ); + static const int _redAccentValue = 0xFFFF5252; /// The pink primary color and swatch. /// @@ -282,7 +314,6 @@ class Colors { /// * [pinkAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _pinkPrimaryValue = 0xFFE91E63; static const MaterialColor pink = const MaterialColor( _pinkPrimaryValue, const { @@ -298,6 +329,7 @@ class Colors { 900: const Color(0xFF880E4F), }, ); + static const int _pinkPrimaryValue = 0xFFE91E63; /// The pink accent color swatch. /// @@ -313,7 +345,6 @@ class Colors { /// * [pink], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _pinkAccentPrimaryValue = 0xFFFF4081; static const MaterialAccentColor pinkAccent = const MaterialAccentColor( _pinkAccentPrimaryValue, const { @@ -323,6 +354,7 @@ class Colors { 700: const Color(0xFFC51162), }, ); + static const int _pinkAccentPrimaryValue = 0xFFFF4081; /// The purple primary color and swatch. /// @@ -338,7 +370,6 @@ class Colors { /// * [purpleAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _purplePrimaryValue = 0xFF9C27B0; static const MaterialColor purple = const MaterialColor( _purplePrimaryValue, const { @@ -354,6 +385,7 @@ class Colors { 900: const Color(0xFF4A148C), }, ); + static const int _purplePrimaryValue = 0xFF9C27B0; /// The purple accent color and swatch. /// @@ -369,7 +401,6 @@ class Colors { /// * [purple], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _purpleAccentPrimaryValue = 0xFFE040FB; static const MaterialAccentColor purpleAccent = const MaterialAccentColor( _purpleAccentPrimaryValue, const { @@ -379,6 +410,7 @@ class Colors { 700: const Color(0xFFAA00FF), }, ); + static const int _purpleAccentPrimaryValue = 0xFFE040FB; /// The deep purple primary color and swatch. /// @@ -394,7 +426,6 @@ class Colors { /// * [deepPurpleAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _deepPurplePrimaryValue = 0xFF673AB7; static const MaterialColor deepPurple = const MaterialColor( _deepPurplePrimaryValue, const { @@ -410,6 +441,7 @@ class Colors { 900: const Color(0xFF311B92), }, ); + static const int _deepPurplePrimaryValue = 0xFF673AB7; /// The deep purple accent color and swatch. /// @@ -425,7 +457,6 @@ class Colors { /// * [deepPurple], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _deepPurpleAccentPrimaryValue = 0xFF7C4DFF; static const MaterialAccentColor deepPurpleAccent = const MaterialAccentColor( _deepPurpleAccentPrimaryValue, const { @@ -435,6 +466,7 @@ class Colors { 700: const Color(0xFF6200EA), }, ); + static const int _deepPurpleAccentPrimaryValue = 0xFF7C4DFF; /// The indigo primary color and swatch. /// @@ -450,7 +482,6 @@ class Colors { /// * [indigoAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _indigoPrimaryValue = 0xFF3F51B5; static const MaterialColor indigo = const MaterialColor( _indigoPrimaryValue, const { @@ -466,6 +497,7 @@ class Colors { 900: const Color(0xFF1A237E), }, ); + static const int _indigoPrimaryValue = 0xFF3F51B5; /// The indigo accent color and swatch. /// @@ -481,7 +513,6 @@ class Colors { /// * [indigo], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _indigoAccentPrimaryValue = 0xFF536DFE; static const MaterialAccentColor indigoAccent = const MaterialAccentColor( _indigoAccentPrimaryValue, const { @@ -491,6 +522,7 @@ class Colors { 700: const Color(0xFF304FFE), }, ); + static const int _indigoAccentPrimaryValue = 0xFF536DFE; /// The blue primary color and swatch. /// @@ -506,7 +538,6 @@ class Colors { /// * [blueAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _bluePrimaryValue = 0xFF2196F3; static const MaterialColor blue = const MaterialColor( _bluePrimaryValue, const { @@ -522,6 +553,7 @@ class Colors { 900: const Color(0xFF0D47A1), }, ); + static const int _bluePrimaryValue = 0xFF2196F3; /// The blue accent color and swatch. /// @@ -537,7 +569,6 @@ class Colors { /// * [blue], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _blueAccentPrimaryValue = 0xFF448AFF; static const MaterialAccentColor blueAccent = const MaterialAccentColor( _blueAccentPrimaryValue, const { @@ -547,6 +578,7 @@ class Colors { 700: const Color(0xFF2962FF), }, ); + static const int _blueAccentPrimaryValue = 0xFF448AFF; /// The light blue primary color and swatch. /// @@ -562,7 +594,6 @@ class Colors { /// * [lightBlueAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _lightBluePrimaryValue = 0xFF03A9F4; static const MaterialColor lightBlue = const MaterialColor( _lightBluePrimaryValue, const { @@ -578,6 +609,7 @@ class Colors { 900: const Color(0xFF01579B), }, ); + static const int _lightBluePrimaryValue = 0xFF03A9F4; /// The light blue accent swatch. /// @@ -593,7 +625,6 @@ class Colors { /// * [lightBlue], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _lightBlueAccentPrimaryValue = 0xFF40C4FF; static const MaterialAccentColor lightBlueAccent = const MaterialAccentColor( _lightBlueAccentPrimaryValue, const { @@ -603,6 +634,7 @@ class Colors { 700: const Color(0xFF0091EA), }, ); + static const int _lightBlueAccentPrimaryValue = 0xFF40C4FF; /// The cyan primary color and swatch. /// @@ -618,7 +650,6 @@ class Colors { /// * [cyanAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _cyanPrimaryValue = 0xFF00BCD4; static const MaterialColor cyan = const MaterialColor( _cyanPrimaryValue, const { @@ -634,6 +665,7 @@ class Colors { 900: const Color(0xFF006064), }, ); + static const int _cyanPrimaryValue = 0xFF00BCD4; /// The cyan accent color and swatch. /// @@ -649,7 +681,6 @@ class Colors { /// * [cyan], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _cyanAccentPrimaryValue = 0xFF18FFFF; static const MaterialAccentColor cyanAccent = const MaterialAccentColor( _cyanAccentPrimaryValue, const { @@ -659,6 +690,7 @@ class Colors { 700: const Color(0xFF00B8D4), }, ); + static const int _cyanAccentPrimaryValue = 0xFF18FFFF; /// The teal primary color and swatch. /// @@ -674,7 +706,6 @@ class Colors { /// * [tealAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _tealPrimaryValue = 0xFF009688; static const MaterialColor teal = const MaterialColor( _tealPrimaryValue, const { @@ -690,6 +721,7 @@ class Colors { 900: const Color(0xFF004D40), }, ); + static const int _tealPrimaryValue = 0xFF009688; /// The teal accent color and swatch. /// @@ -705,7 +737,6 @@ class Colors { /// * [teal], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _tealAccentPrimaryValue = 0xFF64FFDA; static const MaterialAccentColor tealAccent = const MaterialAccentColor( _tealAccentPrimaryValue, const { @@ -715,6 +746,7 @@ class Colors { 700: const Color(0xFF00BFA5), }, ); + static const int _tealAccentPrimaryValue = 0xFF64FFDA; /// The green primary color and swatch. /// @@ -730,7 +762,6 @@ class Colors { /// * [greenAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _greenPrimaryValue = 0xFF4CAF50; static const MaterialColor green = const MaterialColor( _greenPrimaryValue, const { @@ -746,6 +777,7 @@ class Colors { 900: const Color(0xFF1B5E20), }, ); + static const int _greenPrimaryValue = 0xFF4CAF50; /// The green accent color and swatch. /// @@ -761,7 +793,6 @@ class Colors { /// * [green], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _greenAccentPrimaryValue = 0xFF69F0AE; static const MaterialAccentColor greenAccent = const MaterialAccentColor( _greenAccentPrimaryValue, const { @@ -771,6 +802,7 @@ class Colors { 700: const Color(0xFF00C853), }, ); + static const int _greenAccentPrimaryValue = 0xFF69F0AE; /// The light green primary color and swatch. /// @@ -786,7 +818,6 @@ class Colors { /// * [lightGreenAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _lightGreenPrimaryValue = 0xFF8BC34A; static const MaterialColor lightGreen = const MaterialColor( _lightGreenPrimaryValue, const { @@ -802,6 +833,7 @@ class Colors { 900: const Color(0xFF33691E), }, ); + static const int _lightGreenPrimaryValue = 0xFF8BC34A; /// The light green accent color and swatch. /// @@ -817,7 +849,6 @@ class Colors { /// * [lightGreen], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _lightGreenAccentPrimaryValue = 0xFFB2FF59; static const MaterialAccentColor lightGreenAccent = const MaterialAccentColor( _lightGreenAccentPrimaryValue, const { @@ -827,6 +858,7 @@ class Colors { 700: const Color(0xFF64DD17), }, ); + static const int _lightGreenAccentPrimaryValue = 0xFFB2FF59; /// The lime primary color and swatch. /// @@ -842,7 +874,6 @@ class Colors { /// * [limeAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _limePrimaryValue = 0xFFCDDC39; static const MaterialColor lime = const MaterialColor( _limePrimaryValue, const { @@ -858,6 +889,7 @@ class Colors { 900: const Color(0xFF827717), }, ); + static const int _limePrimaryValue = 0xFFCDDC39; /// The lime accent primary color and swatch. /// @@ -873,7 +905,6 @@ class Colors { /// * [lime], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _limeAccentPrimaryValue = 0xFFEEFF41; static const MaterialAccentColor limeAccent = const MaterialAccentColor( _limeAccentPrimaryValue, const { @@ -883,6 +914,7 @@ class Colors { 700: const Color(0xFFAEEA00), }, ); + static const int _limeAccentPrimaryValue = 0xFFEEFF41; /// The yellow primary color and swatch. /// @@ -898,7 +930,6 @@ class Colors { /// * [yellowAccentAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _yellowPrimaryValue = 0xFFFFEB3B; static const MaterialColor yellow = const MaterialColor( _yellowPrimaryValue, const { @@ -914,6 +945,7 @@ class Colors { 900: const Color(0xFFF57F17), }, ); + static const int _yellowPrimaryValue = 0xFFFFEB3B; /// The yellow accent color and swatch. /// @@ -929,7 +961,6 @@ class Colors { /// * [yellow], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _yellowAccentPrimaryValue = 0xFFFFFF00; static const MaterialAccentColor yellowAccent = const MaterialAccentColor( _yellowAccentPrimaryValue, const { @@ -939,6 +970,7 @@ class Colors { 700: const Color(0xFFFFD600), }, ); + static const int _yellowAccentPrimaryValue = 0xFFFFFF00; /// The amber primary color and swatch. /// @@ -954,7 +986,6 @@ class Colors { /// * [amberAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _amberPrimaryValue = 0xFFFFC107; static const MaterialColor amber = const MaterialColor( _amberPrimaryValue, const { @@ -970,6 +1001,7 @@ class Colors { 900: const Color(0xFFFF6F00), }, ); + static const int _amberPrimaryValue = 0xFFFFC107; /// The amber accent color and swatch. /// @@ -985,7 +1017,6 @@ class Colors { /// * [amber], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _amberAccentPrimaryValue = 0xFFFFD740; static const MaterialAccentColor amberAccent = const MaterialAccentColor( _amberAccentPrimaryValue, const { @@ -995,6 +1026,7 @@ class Colors { 700: const Color(0xFFFFAB00), }, ); + static const int _amberAccentPrimaryValue = 0xFFFFD740; /// The orange primary color and swatch. /// @@ -1010,7 +1042,6 @@ class Colors { /// * [orangeAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _orangePrimaryValue = 0xFFFF9800; static const MaterialColor orange = const MaterialColor( _orangePrimaryValue, const { @@ -1026,6 +1057,7 @@ class Colors { 900: const Color(0xFFE65100), }, ); + static const int _orangePrimaryValue = 0xFFFF9800; /// The orange accent color and swatch. /// @@ -1041,7 +1073,6 @@ class Colors { /// * [orange], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _orangeAccentPrimaryValue = 0xFFFFAB40; static const MaterialAccentColor orangeAccent = const MaterialAccentColor( _orangeAccentPrimaryValue, const { @@ -1051,6 +1082,7 @@ class Colors { 700: const Color(0xFFFF6D00), }, ); + static const int _orangeAccentPrimaryValue = 0xFFFFAB40; /// The deep orange primary color and swatch. /// @@ -1066,7 +1098,6 @@ class Colors { /// * [deepOrangeAccent], the corresponding accent colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _deepOrangePrimaryValue = 0xFFFF5722; static const MaterialColor deepOrange = const MaterialColor( _deepOrangePrimaryValue, const { @@ -1082,6 +1113,7 @@ class Colors { 900: const Color(0xFFBF360C), }, ); + static const int _deepOrangePrimaryValue = 0xFFFF5722; /// The deep orange accent color and swatch. /// @@ -1097,7 +1129,6 @@ class Colors { /// * [deepOrange], the corresponding primary colors. /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _deepOrangeAccentPrimaryValue = 0xFFFF6E40; static const MaterialAccentColor deepOrangeAccent = const MaterialAccentColor( _deepOrangeAccentPrimaryValue, const { @@ -1107,6 +1138,7 @@ class Colors { 700: const Color(0xFFDD2C00), }, ); + static const int _deepOrangeAccentPrimaryValue = 0xFFFF6E40; /// The brown primary color and swatch. /// @@ -1123,7 +1155,6 @@ class Colors { /// /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _brownPrimaryValue = 0xFF795548; static const MaterialColor brown = const MaterialColor( _brownPrimaryValue, const { @@ -1139,6 +1170,7 @@ class Colors { 900: const Color(0xFF3E2723), }, ); + static const int _brownPrimaryValue = 0xFF795548; /// The grey primary color and swatch. /// @@ -1160,7 +1192,6 @@ class Colors { /// /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _greyPrimaryValue = 0xFF9E9E9E; static const MaterialColor grey = const MaterialColor( _greyPrimaryValue, const { @@ -1178,6 +1209,7 @@ class Colors { 900: const Color(0xFF212121), }, ); + static const int _greyPrimaryValue = 0xFF9E9E9E; /// The blue-grey primary color and swatch. /// @@ -1194,7 +1226,6 @@ class Colors { /// /// * [Theme.of], which allows you to select colors from the current theme /// rather than hard-coding colors in your build methods. - static const int _blueGreyPrimaryValue = 0xFF607D8B; static const MaterialColor blueGrey = const MaterialColor( _blueGreyPrimaryValue, const { @@ -1210,6 +1241,7 @@ class Colors { 900: const Color(0xFF263238), }, ); + static const int _blueGreyPrimaryValue = 0xFF607D8B; /// The material design primary color swatches (except grey). static const List primaries = const [ diff --git a/packages/flutter/lib/src/material/list_tile.dart b/packages/flutter/lib/src/material/list_tile.dart index c3716ab93a6..6713e88e049 100644 --- a/packages/flutter/lib/src/material/list_tile.dart +++ b/packages/flutter/lib/src/material/list_tile.dart @@ -40,10 +40,10 @@ enum MaterialListType { /// text style, which is a little smaller than the theme's [TextTheme.subhead] /// text style, which is used by default. enum ListTileStyle { - // Use a title font that's appropriate for a [ListTile] in a list. + /// Use a title font that's appropriate for a [ListTile] in a list. list, - // Use a title font that's appropriate for a [ListTile] that appears in a [Drawer]. + /// Use a title font that's appropriate for a [ListTile] that appears in a [Drawer]. drawer, } diff --git a/packages/flutter/lib/src/material/page.dart b/packages/flutter/lib/src/material/page.dart index 89a2e034a38..7893b87b2d4 100644 --- a/packages/flutter/lib/src/material/page.dart +++ b/packages/flutter/lib/src/material/page.dart @@ -75,6 +75,11 @@ class MaterialPageRoute extends PageRoute { /// Builds the primary contents of the route. final WidgetBuilder builder; + + /// Whether this route is a full-screen dialog. + /// + /// Prevents [startPopGesture] from poping the route using an edge swipe on + /// iOS. final bool fullscreenDialog; @override diff --git a/packages/flutter/lib/src/material/text_selection.dart b/packages/flutter/lib/src/material/text_selection.dart index 96a9edd7fbb..f56d6c32030 100644 --- a/packages/flutter/lib/src/material/text_selection.dart +++ b/packages/flutter/lib/src/material/text_selection.dart @@ -196,4 +196,5 @@ class _MaterialTextSelectionControls extends TextSelectionControls { } } +/// Text selection controls that follow the Material Design specification. final TextSelectionControls materialTextSelectionControls = new _MaterialTextSelectionControls(); diff --git a/packages/flutter/lib/src/widgets/editable_text.dart b/packages/flutter/lib/src/widgets/editable_text.dart index 3ecdf086f26..5ffec58c085 100644 --- a/packages/flutter/lib/src/widgets/editable_text.dart +++ b/packages/flutter/lib/src/widgets/editable_text.dart @@ -23,27 +23,70 @@ export 'package:flutter/services.dart' show TextEditingValue, TextSelection, Tex const Duration _kCursorBlinkHalfPeriod = const Duration(milliseconds: 500); +/// A controller for an editable text field. +/// +/// Whenever the user modifies a text field with an associated +/// [TextEditingController], the text field updates [value] and the controller +/// notifies its listeners. Listeners can then read the [text] and [selection] +/// properties to learn what the user has typed or how the selection has been +/// updated. +/// +/// Similarly, if you modify the [text] or [selection] properties, the text +/// field will be notified and will update itself appropriately. +/// +/// A [TextEditingController] can also be used to provide an initial value for a +/// text field. If you build a text field with a controller that already has +/// [text], the text field will use that text as its initial value. +/// +/// See also: +/// +/// * [TextField], which is a Material Design text field that can be controlled +/// with a [TextEditingController]. +/// * [EditableText], which is a raw region of editable text that can be +/// controlled with a [TextEditingController]. class TextEditingController extends ValueNotifier { + /// Creates a controller for an editable text field. + /// + /// This constructor treats a null [text] argument as if it were the empty + /// string. TextEditingController({ String text }) : super(text == null ? TextEditingValue.empty : new TextEditingValue(text: text)); + /// Creates a controller for an editiable text field from an initial [TextEditingValue]. + /// + /// This constructor treats a null [value] argument as if it were + /// [TextEditingValue.empty]. TextEditingController.fromValue(TextEditingValue value) : super(value ?? TextEditingValue.empty); + /// The current string the user is editing. String get text => value.text; set text(String newText) { value = value.copyWith(text: newText, composing: TextRange.empty); } + /// The currently selected [text]. + /// + /// If the selection is collapsed, then this property gives the offset of the + /// cursor within the text. TextSelection get selection => value.selection; set selection(TextSelection newSelection) { value = value.copyWith(selection: newSelection, composing: TextRange.empty); } + /// Set the [value] to empty. + /// + /// After calling this function, [text] will be the empty string and the + /// selection will be invalid. void clear() { value = TextEditingValue.empty; } + /// Set the composing region to an empty range. + /// + /// The composing region is the range of text that is still being composed. + /// Calling this function indicates that the user is done composing that + /// region. void clearComposing() { value = value.copyWith(composing: TextRange.empty); }