From 8d7733fdb1e22ccab0e692f7e6b1bf36720946b6 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Wed, 3 May 2017 12:55:57 -0700 Subject: [PATCH] Add more breadcrumbs around material buttons and ink wells. (#9760) --- .../flutter/lib/src/material/back_button.dart | 5 +++-- packages/flutter/lib/src/material/button.dart | 19 +++++++++++------ .../flutter/lib/src/material/flat_button.dart | 1 + .../flutter/lib/src/material/icon_button.dart | 15 +++++++++---- .../flutter/lib/src/material/ink_well.dart | 21 +++++++++++++++++-- .../lib/src/material/raised_button.dart | 11 +++++++--- .../flutter/lib/src/material/text_field.dart | 2 +- .../lib/src/widgets/gesture_detector.dart | 6 +++++- 8 files changed, 61 insertions(+), 19 deletions(-) diff --git a/packages/flutter/lib/src/material/back_button.dart b/packages/flutter/lib/src/material/back_button.dart index 5ffea5606d..7fc4c227e4 100644 --- a/packages/flutter/lib/src/material/back_button.dart +++ b/packages/flutter/lib/src/material/back_button.dart @@ -61,7 +61,7 @@ class BackButton extends StatelessWidget { } } -/// A Material Design close button. +/// A material design close button. /// /// A [CloseButton] is an [IconButton] with a "close" icon. When pressed, the /// close button calls [Navigator.maybePop] to return to the previous route. @@ -76,6 +76,7 @@ class BackButton extends StatelessWidget { /// * [BackButton], which is more appropriate for middle nodes in the /// navigation tree or where pages can be popped instantaneously with /// no user data consequence. +/// * [IconButton], to create other material design icon buttons. class CloseButton extends StatelessWidget { /// Creates a Material Design close button. const CloseButton({ Key key }) : super(key: key); @@ -84,7 +85,7 @@ class CloseButton extends StatelessWidget { Widget build(BuildContext context) { return new IconButton( icon: const Icon(Icons.close), - tooltip: 'Close', + tooltip: 'Close', // TODO(ianh): Figure out how to localize this string onPressed: () { Navigator.of(context).maybePop(); }, diff --git a/packages/flutter/lib/src/material/button.dart b/packages/flutter/lib/src/material/button.dart index 5b6b7e63bd..9baa22e3e3 100644 --- a/packages/flutter/lib/src/material/button.dart +++ b/packages/flutter/lib/src/material/button.dart @@ -20,9 +20,9 @@ import 'theme.dart'; /// /// See also: /// -/// * [ButtonTheme] -/// * [RaisedButton] -/// * [FlatButton] +/// * [ButtonTheme], which uses this enum to define the [ButtonTheme.textTheme]. +/// * [RaisedButton], which styles itself based on the ambient [ButtonTheme]. +/// * [FlatButton], which styles itself based on the ambient [ButtonTheme]. enum ButtonTextTheme { /// The button should use the normal color (e.g., black or white depending on the [ThemeData.brightness]) for its text. normal, @@ -35,9 +35,9 @@ enum ButtonTextTheme { /// /// See also: /// -/// * [ButtonTextTheme] -/// * [RaisedButton] -/// * [FlatButton] +/// * [ButtonTextTheme], which is used by [textTheme]. +/// * [RaisedButton], which styles itself based on the ambient [ButtonTheme]. +/// * [FlatButton], which styles itself based on the ambient [ButtonTheme]. class ButtonTheme extends InheritedWidget { /// Creates a button theme. /// @@ -121,6 +121,13 @@ class ButtonTheme extends InheritedWidget { /// /// MaterialButtons whose [onPressed] handler is null will be disabled. To have /// an enabled button, make sure to pass a non-null value for onPressed. +/// +/// If you want an ink-splash effect for taps, but don't want to use a button, +/// consider using [InkWell] directly. +/// +/// See also: +/// +/// * [IconButton], to create buttons that contain icons rather than text. class MaterialButton extends StatefulWidget { /// Creates a material button. /// diff --git a/packages/flutter/lib/src/material/flat_button.dart b/packages/flutter/lib/src/material/flat_button.dart index 9207b1fcb9..1cd8a246f5 100644 --- a/packages/flutter/lib/src/material/flat_button.dart +++ b/packages/flutter/lib/src/material/flat_button.dart @@ -40,6 +40,7 @@ import 'theme.dart'; /// material. /// * [DropdownButton], which offers the user a choice of a number of options. /// * [SimpleDialogOption], which is used in [SimpleDialog]s. +/// * [IconButton], to create buttons that just contain icons. /// * [InkWell], which implements the ink splash part of a flat button. /// * class FlatButton extends StatelessWidget { diff --git a/packages/flutter/lib/src/material/icon_button.dart b/packages/flutter/lib/src/material/icon_button.dart index 6628607fa4..94b7090ee2 100644 --- a/packages/flutter/lib/src/material/icon_button.dart +++ b/packages/flutter/lib/src/material/icon_button.dart @@ -23,7 +23,7 @@ const double _kMinButtonSize = 48.0; /// A material design icon button. /// /// An icon button is a picture printed on a [Material] widget that reacts to -/// touches by filling with color. +/// touches by filling with color (ink). /// /// Icon buttons are commonly used in the [AppBar.actions] field, but they can /// be used in many other places as well. @@ -33,12 +33,19 @@ const double _kMinButtonSize = 48.0; /// /// Requires one of its ancestors to be a [Material] widget. /// -/// Will be automatically sized up to the recommended 48 logical pixels if smaller. +/// The hit region of an icon button will, if possible, be at least 48.0 pixels +/// in size, regardless of the actual [iconSize]. The [alignment] controls how +/// the icon itself is positioned within the hit region. /// /// See also: /// -/// * [Icons] -/// * [AppBar] +/// * [Icons], a library of predefined icons. +/// * [BackButton], an icon button for a "back" affordance which adapts to the +/// current platform's conventions. +/// * [CloseButton], an icon button for closing pages. +/// * [AppBar], to show a toolbar at the top of an application. +/// * [RaisedButton] and [FlatButton], for buttons with text in them. +/// * [InkResponse] and [InkWell], for the ink splash effect itself. class IconButton extends StatelessWidget { /// Creates an icon button. /// diff --git a/packages/flutter/lib/src/material/ink_well.dart b/packages/flutter/lib/src/material/ink_well.dart index 18e06040e1..9c27fb7dc0 100644 --- a/packages/flutter/lib/src/material/ink_well.dart +++ b/packages/flutter/lib/src/material/ink_well.dart @@ -26,7 +26,15 @@ import 'theme.dart'; /// If a Widget uses this class directly, it should include the following line /// at the top of its [build] function to call [debugCheckHasMaterial]: /// -/// assert(debugCheckHasMaterial(context)); +/// ```dart +/// assert(debugCheckHasMaterial(context)); +/// ``` +/// +/// See also: +/// +/// * [GestureDetector], for listening for gestures without ink splashes. +/// * [RaisedButton] and [FlatButton], two kinds of buttons in material design. +/// * [IconButton], which combines [InkResponse] with an [Icon]. class InkResponse extends StatefulWidget { /// Creates an area of a [Material] that responds to touch. /// @@ -248,7 +256,16 @@ class _InkResponseState extends State { /// If a Widget uses this class directly, it should include the following line /// at the top of its [build] function to call [debugCheckHasMaterial]: /// -/// assert(debugCheckHasMaterial(context)); +/// ```dart +/// assert(debugCheckHasMaterial(context)); +/// ``` +/// +/// See also: +/// +/// * [GestureDetector], for listening for gestures without ink splashes. +/// * [RaisedButton] and [FlatButton], two kinds of buttons in material design. +/// * [InkResponse], a variant of [InkWell] that doesn't force a rectangular +/// shape on the ink reaction. class InkWell extends InkResponse { /// Creates an ink well. /// diff --git a/packages/flutter/lib/src/material/raised_button.dart b/packages/flutter/lib/src/material/raised_button.dart index 5c71921f63..19e65eb305 100644 --- a/packages/flutter/lib/src/material/raised_button.dart +++ b/packages/flutter/lib/src/material/raised_button.dart @@ -25,11 +25,16 @@ import 'theme.dart'; /// /// Requires one of its ancestors to be a [Material] widget. /// +/// If you want an ink-splash effect for taps, but don't want to use a button, +/// consider using [InkWell] directly. +/// /// See also: /// -/// * [FlatButton] -/// * [DropdownButton] -/// * [FloatingActionButton] +/// * [FlatButton], a material design button without a shadow. +/// * [DropdownButton], a button that shows options to select from. +/// * [FloatingActionButton], the round button in material applications. +/// * [IconButton], to create buttons that just contain icons. +/// * [InkWell], which implements the ink splash part of a flat button. /// * class RaisedButton extends StatelessWidget { /// Creates a raised button. diff --git a/packages/flutter/lib/src/material/text_field.dart b/packages/flutter/lib/src/material/text_field.dart index a0e219db11..e9a7bc8090 100644 --- a/packages/flutter/lib/src/material/text_field.dart +++ b/packages/flutter/lib/src/material/text_field.dart @@ -15,7 +15,7 @@ export 'package:flutter/services.dart' show TextInputType; const Duration _kTransitionDuration = const Duration(milliseconds: 200); const Curve _kTransitionCurve = Curves.fastOutSlowIn; -/// A Material Design text field. +/// A material design text field. /// /// A text field lets the user enter text, either with hardware keyboard or with /// an onscreen keyboard. diff --git a/packages/flutter/lib/src/widgets/gesture_detector.dart b/packages/flutter/lib/src/widgets/gesture_detector.dart index e0f522303b..9f59ec7086 100644 --- a/packages/flutter/lib/src/widgets/gesture_detector.dart +++ b/packages/flutter/lib/src/widgets/gesture_detector.dart @@ -52,7 +52,11 @@ typedef GestureRecognizer GestureRecognizerFactory(GestureRecognizer recognizer) /// them to the callbacks. To ignore accessibility events, set /// [excludeFromSemantics] to true. /// -/// See http://flutter.io/gestures/ for additional information. +/// See for additional information. +/// +/// Material design applications typically react to touches with ink splash +/// effects. The [InkWell] class implements this effect and can be used in place +/// of a [GestureDetector] for handling taps. class GestureDetector extends StatelessWidget { /// Creates a widget that detects gestures. ///