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

Re-organize the Material widget's documentation. (#14303)

Browse Source 
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.
This commit is contained in:
amirh 2018-01-26 20:09:11 -08:00 committed by GitHub
parent 6854e81bdb
commit ae1f65ebd6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
packages/flutter/lib/src/material/material.dart
View File

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