From 69f994446b312766e8cab1f7733a4fdf4fb18265 Mon Sep 17 00:00:00 2001 From: Adam Barth Date: Tue, 12 Apr 2016 12:41:59 -0700 Subject: [PATCH] Add more dartdoc to material.dart (#3261) Now past halfway though material.dart by files. --- .../lib/demo/flexible_space_demo.dart | 2 +- .../material_gallery/lib/gallery/home.dart | 4 +- .../lib/src/material/flexible_space_bar.dart | 33 ++++++++++++++-- .../src/material/floating_action_button.dart | 21 ++++++++-- .../flutter/lib/src/material/grid_tile.dart | 16 +++++++- .../lib/src/material/grid_tile_bar.dart | 39 ++++++++++++++++--- packages/flutter/lib/src/material/icon.dart | 3 ++ .../flutter/lib/src/material/icon_button.dart | 13 ++++++- .../flutter/lib/src/material/icon_theme.dart | 5 +++ .../lib/src/material/icon_theme_data.dart | 9 +++++ packages/flutter/lib/src/material/icons.dart | 9 +++++ .../flutter/lib/src/material/ink_well.dart | 27 ++++++++++--- .../flutter/lib/src/material/list_item.dart | 5 +++ .../flutter/lib/src/material/popup_menu.dart | 4 ++ 14 files changed, 164 insertions(+), 26 deletions(-) diff --git a/examples/material_gallery/lib/demo/flexible_space_demo.dart b/examples/material_gallery/lib/demo/flexible_space_demo.dart index e1f5ca6fd9..187b8be403 100644 --- a/examples/material_gallery/lib/demo/flexible_space_demo.dart +++ b/examples/material_gallery/lib/demo/flexible_space_demo.dart @@ -124,7 +124,7 @@ class FlexibleSpaceDemoState extends State { ], flexibleSpace: new FlexibleSpaceBar( title : new Text('Ali Connors'), - image: new AssetImage( + background: new AssetImage( name: 'packages/flutter_gallery_assets/ali_connors.png', fit: ImageFit.cover, height: _appBarHeight diff --git a/examples/material_gallery/lib/gallery/home.dart b/examples/material_gallery/lib/gallery/home.dart index adee9e575b..57fb85fa78 100644 --- a/examples/material_gallery/lib/gallery/home.dart +++ b/examples/material_gallery/lib/gallery/home.dart @@ -84,8 +84,8 @@ class GalleryHomeState extends State { appBar: new AppBar( expandedHeight: _kFlexibleSpaceMaxHeight, flexibleSpace: new FlexibleSpaceBar( - image: new GalleryHeader(), - title: new Text("Flutter gallery") + title: new Text("Flutter gallery"), + background: new GalleryHeader() ) ), scrollableKey: _listKey, diff --git a/packages/flutter/lib/src/material/flexible_space_bar.dart b/packages/flutter/lib/src/material/flexible_space_bar.dart index a8a55ac7eb..c6724c2673 100644 --- a/packages/flutter/lib/src/material/flexible_space_bar.dart +++ b/packages/flutter/lib/src/material/flexible_space_bar.dart @@ -11,11 +11,36 @@ import 'constants.dart'; import 'scaffold.dart'; import 'theme.dart'; +/// The part of a material design [AppBar] that expands and collapses. +/// +/// Most commonly used in in the [AppBar.flexibleSpace] field, a flexible space +/// bar expands and contracts as the app scrolls so that the [AppBar] reaches +/// from the top of the app to the top of the scrolling contents of the app. +/// +/// Requires one of its ancestors to be a [Scaffold] widget because the +/// [Scaffold] coordinates the scrolling effect between the flexible space and +/// its body. +/// +/// See also: +/// * [AppBar] +/// * [Scaffold] +/// * class FlexibleSpaceBar extends StatefulWidget { - FlexibleSpaceBar({ Key key, this.title, this.image }) : super(key: key); + /// Creates a flexible space bar. + /// + /// Most commonly used in the [AppBar.flexibleSpace] field. Requires one of + /// its ancestors to be a [Scaffold] widget. + FlexibleSpaceBar({ Key key, this.title, this.background }) : super(key: key); + /// The primary contents of the flexible space bar when expanded. + /// + /// Typically a [Text] widget. final Widget title; - final Widget image; + + /// Shown behind the [title] when expanded. + /// + /// Typically an [AssetImage] widget with [AssetImage.fit] set to [ImageFit.cover]. + final Widget background; @override _FlexibleSpaceBarState createState() => new _FlexibleSpaceBarState(); @@ -47,7 +72,7 @@ class _FlexibleSpaceBarState extends State { final List children = []; // background image - if (config.image != null) { + if (config.background != null) { final double fadeStart = (appBarHeight - toolBarHeight * 2.0) / appBarHeight; final double fadeEnd = (appBarHeight - toolBarHeight) / appBarHeight; final CurvedAnimation opacityCurve = new CurvedAnimation( @@ -63,7 +88,7 @@ class _FlexibleSpaceBarState extends State { opacity: new Tween(begin: 1.0, end: 0.0).evaluate(opacityCurve), child: new SizedBox( height: appBarHeight + statusBarHeight, - child: config.image + child: config.background ) ) )); diff --git a/packages/flutter/lib/src/material/floating_action_button.dart b/packages/flutter/lib/src/material/floating_action_button.dart index 67893aaa67..f0defa8758 100644 --- a/packages/flutter/lib/src/material/floating_action_button.dart +++ b/packages/flutter/lib/src/material/floating_action_button.dart @@ -19,24 +19,29 @@ const double _kSizeMini = 40.0; const Duration _kChildSegue = const Duration(milliseconds: 400); const Interval _kChildSegueInterval = const Interval(0.65, 1.0); -/// A material design "floating action button". +/// A material design floating action button. /// /// A floating action button is a circular icon button that hovers over content -/// to promote a primary action in the application. +/// to promote a primary action in the application. Floating action buttons are +/// most commonly used in the [Scaffold.floatingActionButton] field. /// /// Use at most a single floating action button per screen. Floating action /// buttons should be used for positive actions such as "create", "share", or /// "navigate". /// /// If the [onPressed] callback is not specified or null, then the button will -/// be disabled, will not react to touch. +/// be disabled and will not react to touch. /// /// See also: /// +/// * [Scaffold] /// * [RaisedButton] /// * [FlatButton] /// * class FloatingActionButton extends StatefulWidget { + /// Creates a floating action button. + /// + /// Most commonly used in the [Scaffold.floatingActionButton] field. const FloatingActionButton({ Key key, this.child, @@ -51,6 +56,10 @@ class FloatingActionButton extends StatefulWidget { /// The widget below this widget in the tree. final Widget child; + /// Text that describes the action that will occur when the button is pressed. + /// + /// This text is displayed when the user long-presses on the button and is + /// used for accessibility. final String tooltip; /// The color to use when filling the button. @@ -66,8 +75,14 @@ class FloatingActionButton extends StatefulWidget { /// The z-coordinate at which to place this button. final int elevation; + /// The z-coordinate at which to place this button when the user is touching the button. final int highlightElevation; + /// Controls the size of this button. + /// + /// By default, floating action buttons are non-mini and have a height and + /// width of 56.0 logical pixels. Mini floating action buttons have a height + /// and width of 40.0 logical pixels. final bool mini; @override diff --git a/packages/flutter/lib/src/material/grid_tile.dart b/packages/flutter/lib/src/material/grid_tile.dart index 09d93a644b..7e07a36cee 100644 --- a/packages/flutter/lib/src/material/grid_tile.dart +++ b/packages/flutter/lib/src/material/grid_tile.dart @@ -4,9 +4,21 @@ import 'package:flutter/widgets.dart'; -/// Creates a [Stack] with the header anchored across the top or a footer across the -/// bottom. The [GridTileBar] class can be used to create grid tile headers and footers. +/// A tile in a material design grid list. +/// +/// A grid list is a [ScrollableGrid] of tiles in a vertical and horizontal +/// array. Each tile typically contains some visually rich content (e.g., an +/// image) together with a [GridTileBar] in either a [header] or a [footer]. +/// +/// See also: +/// +/// * [ScrollableGrid] +/// * [GridTileBar] +/// * class GridTile extends StatelessWidget { + /// Creates a grid tile. + /// + /// Must have a child. Does not typically have both a header and a footer. GridTile({ Key key, this.header, this.footer, this.child }) : super(key: key) { assert(child != null); } diff --git a/packages/flutter/lib/src/material/grid_tile_bar.dart b/packages/flutter/lib/src/material/grid_tile_bar.dart index f35aa9d129..cea4362189 100644 --- a/packages/flutter/lib/src/material/grid_tile_bar.dart +++ b/packages/flutter/lib/src/material/grid_tile_bar.dart @@ -9,13 +9,21 @@ import 'icon_theme.dart'; import 'icon_theme_data.dart'; import 'typography.dart'; - -/// Typically used to stack a one or two line header or footer on a Grid tile. -/// The layout is based on the "Grid Lists" section of the Material Design spec: -/// https://www.google.com/design/spec/components/grid-lists.html#grid-lists-specs -/// For a one-line header specify [title] and to add a second line specify [subtitle]. -/// Use [leading] or [trailing] to add an icon. +/// A header used in a material design [GridTile]. +/// +/// Typically used to add a one or two line header or footer on a [GridTile]. +/// +/// For a one-line header, include a [title] widget. To add a second line, also +/// include a [subtitle] wiget. Use [leading] or [trailing] to add an icon. +/// +/// See also: +/// +/// * [GridTile] +/// * class GridTileBar extends StatelessWidget { + /// Creates a grid tile bar. + /// + /// Typically used to with [GridTile]. GridTileBar({ Key key, this.backgroundColor, @@ -25,10 +33,29 @@ class GridTileBar extends StatelessWidget { this.trailing }) : super(key: key); + /// The color to paint behind the child widgets. + /// + /// Defaults to transparent. final Color backgroundColor; + + /// A widget to display before the title. + /// + /// Typically an [Icon] or an [IconButton] widget. final Widget leading; + + /// The primary content of the list item. + /// + /// Typically a [Text] widget. final Widget title; + + /// Additional content displayed below the title. + /// + /// Typically a [Text] widget. final Widget subtitle; + + /// A widget to display after the title. + /// + /// Typically an [Icon] or an [IconButton] widget. final Widget trailing; @override diff --git a/packages/flutter/lib/src/material/icon.dart b/packages/flutter/lib/src/material/icon.dart index c6fb7217c8..3679f8b1f5 100644 --- a/packages/flutter/lib/src/material/icon.dart +++ b/packages/flutter/lib/src/material/icon.dart @@ -28,6 +28,9 @@ import 'theme.dart'; /// * [IconButton], for interactive icons /// * [Icons], for the list of available icons for use with this class class Icon extends StatelessWidget { + /// Creates an icon. + /// + /// The size argument is required to be non-null. Icon({ Key key, this.icon, diff --git a/packages/flutter/lib/src/material/icon_button.dart b/packages/flutter/lib/src/material/icon_button.dart index 62fbde3bd5..213c55bc2d 100644 --- a/packages/flutter/lib/src/material/icon_button.dart +++ b/packages/flutter/lib/src/material/icon_button.dart @@ -11,21 +11,30 @@ import 'ink_well.dart'; import 'theme.dart'; import 'tooltip.dart'; -/// A material design "icon button". +/// A material design icon button. /// /// An icon button is a picture printed on a [Material] widget that reacts to /// touches by filling with color. /// -/// Use icon buttons on toolbars. +/// Icon buttons are commonly used in the [AppBar.actions] field, but they can +/// be used in many other places as well. /// /// If the [onPressed] callback is not specified or null, then the button will /// be disabled, will not react to touch. /// +/// Requires one of its ancestors to be a [Material] widget. +/// /// See also: /// /// * [Icons] /// * [AppBar] class IconButton extends StatelessWidget { + /// Creates an icon button. + /// + /// Icon buttons are commonly used in the [AppBar.actions] field, but they can + /// be used in many other places as well. + /// + /// Requires one of its ancestors to be a [Material] widget. const IconButton({ Key key, this.size: 24.0, diff --git a/packages/flutter/lib/src/material/icon_theme.dart b/packages/flutter/lib/src/material/icon_theme.dart index e9e356239f..1376bb0fb1 100644 --- a/packages/flutter/lib/src/material/icon_theme.dart +++ b/packages/flutter/lib/src/material/icon_theme.dart @@ -6,7 +6,11 @@ import 'package:flutter/widgets.dart'; import 'icon_theme_data.dart'; +/// Controls the color and opacity of icons in a widget subtree. class IconTheme extends InheritedWidget { + /// Creates an icon theme that controls the color and opacity of descendant widgets. + /// + /// Both data and child arguments are required to be non-null. IconTheme({ Key key, this.data, @@ -16,6 +20,7 @@ class IconTheme extends InheritedWidget { assert(child != null); } + /// The color and opacity to use for icons in this subtree. final IconThemeData data; /// The data from the closest instance of this class that encloses the given context. diff --git a/packages/flutter/lib/src/material/icon_theme_data.dart b/packages/flutter/lib/src/material/icon_theme_data.dart index f80c7d2ddc..de1ee0856b 100644 --- a/packages/flutter/lib/src/material/icon_theme_data.dart +++ b/packages/flutter/lib/src/material/icon_theme_data.dart @@ -5,7 +5,14 @@ import 'dart:ui' as ui show lerpDouble; import 'dart:ui' show Color, hashValues; +/// Defines the color and opacity of icons. +/// +/// Used by [IconTheme] to control the color and opacity of icons in a widget +/// subtree. class IconThemeData { + /// Creates an icon theme data. + /// + /// The given opacity applies to both explicit and default icon colors. const IconThemeData({ this.color, this.opacity }); /// The default color for icons. @@ -14,8 +21,10 @@ class IconThemeData { /// An opacity to apply to both explicit and default icon colors. final double opacity; + /// Normalizes the given opacity to be between 0.0 and 1.0 (inclusive). double get clampedOpacity => (opacity ?? 1.0).clamp(0.0, 1.0); + /// Linearly interpolate between two icon theme data objects. static IconThemeData lerp(IconThemeData begin, IconThemeData end, double t) { return new IconThemeData( color: Color.lerp(begin.color, end.color, t), diff --git a/packages/flutter/lib/src/material/icons.dart b/packages/flutter/lib/src/material/icons.dart index fac118ed2c..ed6ab2a0e3 100644 --- a/packages/flutter/lib/src/material/icons.dart +++ b/packages/flutter/lib/src/material/icons.dart @@ -2,8 +2,17 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +/// A description of a material design icon. +/// +/// See [Icons] for a number of predefined icons. class IconData { + /// Creates icon data. + /// + /// Rarely used directly. Instead, consider using one of the predefined icons + /// from the [Icons] collection. const IconData(this.codePoint); + + /// The unicode code point at which this icon is stored in the icon font. final int codePoint; @override diff --git a/packages/flutter/lib/src/material/ink_well.dart b/packages/flutter/lib/src/material/ink_well.dart index 093b957b3a..08717233d6 100644 --- a/packages/flutter/lib/src/material/ink_well.dart +++ b/packages/flutter/lib/src/material/ink_well.dart @@ -12,7 +12,7 @@ import 'debug.dart'; import 'material.dart'; import 'theme.dart'; -/// An area of a Material that responds to touch. Has a configurable shape and +/// An area of a [Material] that responds to touch. Has a configurable shape and /// can be configured to clip splashes that extend outside its bounds or not. /// /// For a variant of this widget that is specialised for rectangular areas that @@ -25,6 +25,9 @@ import 'theme.dart'; /// /// assert(debugCheckHasMaterial(context)); class InkResponse extends StatefulWidget { + /// Creates an area of a [Material] that responds to touch. + /// + /// Must have an ancestor [Material] widget in which to cause ink reactions. InkResponse({ Key key, this.child, @@ -32,23 +35,33 @@ class InkResponse extends StatefulWidget { this.onDoubleTap, this.onLongPress, this.onHighlightChanged, - this.containedInWell: false, + this.containedInkWell: false, this.highlightShape: BoxShape.circle }) : super(key: key); /// The widget below this widget in the tree. final Widget child; + /// Called when the user taps this part of the material final GestureTapCallback onTap; + /// Called when the user double taps this part of the material. final GestureTapCallback onDoubleTap; + /// Called when the user long-presses on this part of the material. final GestureLongPressCallback onLongPress; + /// Called when this part of the material either becomes highlighted or stops behing highlighted. + /// + /// The value passed to the callback is true if this part of the material has + /// become highlighted and false if this part of the material has stopped + /// being highlighted. final ValueChanged onHighlightChanged; - final bool containedInWell; + /// Whether this ink response should be clipped its bounds. + final bool containedInkWell; + /// The shape (e.g., circle, rectangle) to use for the highlight drawn around this part of the material. final BoxShape highlightShape; @override @@ -88,7 +101,6 @@ class _InkResponseState extends State { config.onHighlightChanged(value); } - void _handleTapDown(Point position) { RenderBox referenceBox = context.findRenderObject(); assert(Material.of(context) != null); @@ -97,7 +109,7 @@ class _InkResponseState extends State { referenceBox: referenceBox, position: referenceBox.globalToLocal(position), color: Theme.of(context).splashColor, - containedInWell: config.containedInWell, + containedInWell: config.containedInkWell, onRemoved: () { if (_splashes != null) { assert(_splashes.contains(splash)); @@ -188,6 +200,9 @@ class _InkResponseState extends State { /// /// assert(debugCheckHasMaterial(context)); class InkWell extends InkResponse { + /// Creates an ink well. + /// + /// Must have an ancestor [Material] widget in which to cause ink reactions. InkWell({ Key key, Widget child, @@ -202,7 +217,7 @@ class InkWell extends InkResponse { onDoubleTap: onDoubleTap, onLongPress: onLongPress, onHighlightChanged: onHighlightChanged, - containedInWell: true, + containedInkWell: true, highlightShape: BoxShape.rectangle ); } diff --git a/packages/flutter/lib/src/material/list_item.dart b/packages/flutter/lib/src/material/list_item.dart index d8ff4a6257..100031cde7 100644 --- a/packages/flutter/lib/src/material/list_item.dart +++ b/packages/flutter/lib/src/material/list_item.dart @@ -26,6 +26,11 @@ import 'theme.dart'; /// * [CircleAvatar] /// * class ListItem extends StatelessWidget { + /// Creates a list item. + /// + /// If [isThreeLine] is true, then [subtitle] must not be null. + /// + /// Requires one of its ancestors to be a [Material] widget. ListItem({ Key key, this.leading, diff --git a/packages/flutter/lib/src/material/popup_menu.dart b/packages/flutter/lib/src/material/popup_menu.dart index da946118bb..1c5546a828 100644 --- a/packages/flutter/lib/src/material/popup_menu.dart +++ b/packages/flutter/lib/src/material/popup_menu.dart @@ -407,6 +407,10 @@ class PopupMenuButton extends StatefulWidget { final PopupMenuItemSelected onSelected; + /// Text that describes the action that will occur when the button is pressed. + /// + /// This text is displayed when the user long-presses on the button and is + /// used for accessibility. final String tooltip; /// The z-coordinate at which to place the menu when open.