firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add more dartdoc to material.dart (#3261)

Browse Source 
Now past halfway though material.dart by files.
This commit is contained in:
Adam Barth 2016-04-12 12:41:59 -07:00
parent 2f60932df9
commit 69f994446b
14 changed files with 164 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
examples/material_gallery/lib/demo/flexible_space_demo.dart
View File

@ -124,7 +124,7 @@ class FlexibleSpaceDemoState extends State<FlexibleSpaceDemo> {
],
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

4
examples/material_gallery/lib/gallery/home.dart
View File

@ -84,8 +84,8 @@ class GalleryHomeState extends State<GalleryHome> {
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,

33
packages/flutter/lib/src/material/flexible_space_bar.dart
View File

@ -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]
/// * <https://www.google.com/design/spec/patterns/scrolling-techniques.html>
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<FlexibleSpaceBar> {
final List<Widget> children = <Widget>[];
// 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<FlexibleSpaceBar> {
opacity: new Tween<double>(begin: 1.0, end: 0.0).evaluate(opacityCurve),
child: new SizedBox(
height: appBarHeight + statusBarHeight,
child: config.image
child: config.background
)
)
));

21
packages/flutter/lib/src/material/floating_action_button.dart
View File

@ -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]
/// * <https://www.google.com/design/spec/components/buttons-floating-action-button.html>
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

16
packages/flutter/lib/src/material/grid_tile.dart
View File

@ -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]
/// * <https://www.google.com/design/spec/components/grid-lists.html>
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);
}

39
packages/flutter/lib/src/material/grid_tile_bar.dart
View File

@ -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]
/// * <https://www.google.com/design/spec/components/grid-lists.html#grid-lists-specs>
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

3
packages/flutter/lib/src/material/icon.dart
View File

@ -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,

13
packages/flutter/lib/src/material/icon_button.dart
View File

@ -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,

5
packages/flutter/lib/src/material/icon_theme.dart
View File

@ -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.

9
packages/flutter/lib/src/material/icon_theme_data.dart
View File

@ -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),

9
packages/flutter/lib/src/material/icons.dart
View File

@ -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

27
packages/flutter/lib/src/material/ink_well.dart
View File

@ -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<bool> 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<T extends InkResponse> extends State<T> {
config.onHighlightChanged(value);
}
void _handleTapDown(Point position) {
RenderBox referenceBox = context.findRenderObject();
assert(Material.of(context) != null);
@ -97,7 +109,7 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
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<T extends InkResponse> extends State<T> {
///
/// 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
);
}

5
packages/flutter/lib/src/material/list_item.dart
View File

@ -26,6 +26,11 @@ import 'theme.dart';
/// * [CircleAvatar]
/// * <https://www.google.com/design/spec/components/lists.html>
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,

4
packages/flutter/lib/src/material/popup_menu.dart
View File

@ -407,6 +407,10 @@ class PopupMenuButton<T> extends StatefulWidget {
final PopupMenuItemSelected<T> 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.