From ae1f65ebd65cfe28232dd47e61b971b08afac2b5 Mon Sep 17 00:00:00 2001 From: amirh Date: Fri, 26 Jan 2018 20:09:11 -0800 Subject: [PATCH] Re-organize the Material widget's documentation. (#14303) This widget evolved over time by multiple people, I'm just trying to explain in a more direct way what the widget is currently doing. --- .../flutter/lib/src/material/material.dart | 47 ++++++++++++++++--- 1 file changed, 40 insertions(+), 7 deletions(-) diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart index bbbd6787e97..db5d64545b3 100644 --- a/packages/flutter/lib/src/material/material.dart +++ b/packages/flutter/lib/src/material/material.dart @@ -35,6 +35,15 @@ enum MaterialType { button, /// A transparent piece of material that draws ink splashes and highlights. + /// + /// While the material metaphor describes child widgets as printed on the + /// material itself and do not hide ink effects, in practice the [Material] + /// widget draws child widgets on top of the ink effects. + /// A [Material] with type transparency can be placed on top of opaque widgets + /// to show ink effects on top of them. + /// + /// Prefer using the [Ink] widget for showing ink effects on top of opaque + /// widgets. transparency } @@ -76,6 +85,17 @@ abstract class MaterialInkController { /// A piece of material. /// +/// The Material widget is responsible for: +/// +/// 1. Clipping: Material clips its widget sub-tree to the shape specified by +/// [type] and [borderRadius]. +/// 2. Elevation: Material elevates its widget sub-tree on the Z axis by +/// [elevation] pixels, and draws the appropriate shadow. +/// 3. Ink effects: Material shows ink effects implemented by [InkFeature]s +/// like [InkSplash] and [InkHighlight] below its children. +/// +/// ## The Material Metaphor +/// /// Material is the central metaphor in material design. Each piece of material /// exists at a given elevation, which influences how that piece of material /// visually relates to other pieces of material and how that material casts @@ -86,9 +106,26 @@ abstract class MaterialInkController { /// [InkSplash] and [InkHighlight] effects. To trigger a reaction on the /// material, use a [MaterialInkController] obtained via [Material.of]. /// -/// If a material has a non-zero [elevation], then the material will clip its -/// contents because content that is conceptually printing on a separate piece -/// of material cannot be printed beyond the bounds of the material. +/// In general, the features of a [Material] should not change over time (e.g. a +/// [Material] should not change its [color], [shadowColor] or [type]). The one +/// exception is the [elevation], changes to which will be animated. +/// +/// ## Shape +/// +/// The shape for material is determined by [type] and [borderRadius]. +/// +/// - If [borderRadius] is non null, the shape is a rounded rectangle, with +/// corners specified by [borderRadius]. +/// - If [borderRadius] is null, [type] determines the shape as follows: +/// - [MaterialType.canvas]: the default material shape is a rectangle. +/// - [MaterialType.card]: the default material shape is a rectangle with +/// rounded edges. The edge radii is specified by [kMaterialEdges]. +/// - [MaterialType.circle]: the default material shape is a circle. +/// - [MaterialType.button]: the default material shape is a rectangle with +/// rounded edges. The edge radii is specified by [kMaterialEdges]. +/// - [MaterialType.transparency]: the default material shape is a rectangle. +/// +/// ## Layout change notifications /// /// If the layout changes (e.g. because there's a list on the material, and it's /// been scrolled), a [LayoutChangedNotification] must be dispatched at the @@ -99,10 +136,6 @@ abstract class MaterialInkController { /// features (e.g., ink splashes and ink highlights) won't move to account for /// the new layout. /// -/// In general, the features of a [Material] should not change over time (e.g. a -/// [Material] should not change its [color], [shadowColor] or [type]). The one -/// exception is the [elevation], changes to which will be animated. -/// /// See also: /// /// * [MergeableMaterial], a piece of material that can split and remerge.