Add Clip enum to Material and related widgets (flutter#18576)

See details in our proposal for this breaking API change and flutter#18057. This PR setup all code paths to allow the change but doesn't change the clip behavior by itself. We'll change `defaultClipBehavior` from `Clip.antiAlias` to `Clip.none` in the following PR to change the clip behavior and update tests.

Author: liyuqian

packages/flutter/lib/painting.dart

@@ -28,6 +28,7 @@ export 'src/painting/box_decoration.dart';
 export 'src/painting/box_fit.dart';
 export 'src/painting/box_shadow.dart';
 export 'src/painting/circle_border.dart';
+export 'src/painting/clip.dart';
 export 'src/painting/colors.dart';
 export 'src/painting/debug.dart';
 export 'src/painting/decoration.dart';

packages/flutter/lib/src/material/material.dart

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:ui' show Clip, defaultClipBehavior; // ignore: deprecated_member_use
+
 import 'package:flutter/foundation.dart';
 import 'package:flutter/rendering.dart';
 import 'package:flutter/widgets.dart';
@@ -87,8 +89,9 @@ abstract class MaterialInkController {
 ///
 /// The Material widget is responsible for:
 ///
-/// 1. Clipping: Material clips its widget sub-tree to the shape specified by
-///    [shape], [type], and [borderRadius].
+/// 1. Clipping: If [clipBehavior] is not [Clip.none], Material clips its widget
+///    sub-tree to the shape specified by [shape], [type], and [borderRadius].
+///    By default, [clipBehavior] is [Clip.none] for performance considerations.
 /// 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
@@ -171,6 +174,7 @@ class Material extends StatefulWidget {
     this.textStyle,
     this.borderRadius,
     this.shape,
+    this.clipBehavior = defaultClipBehavior, // ignore: deprecated_member_use
     this.animationDuration = kThemeChangeDuration,
     this.child,
   }) : assert(type != null),
@@ -179,6 +183,7 @@ class Material extends StatefulWidget {
        assert(!(shape != null && borderRadius != null)),
        assert(animationDuration != null),
        assert(!(identical(type, MaterialType.circle) && (borderRadius != null || shape != null))),
+       assert(clipBehavior != null),
        super(key: key);
 
   /// The widget below this widget in the tree.
@@ -226,6 +231,14 @@ class Material extends StatefulWidget {
   /// zero.
   final ShapeBorder shape;
 
+  /// {@template flutter.widgets.Clip}
+  /// The content will be clipped (or not) according to this option.
+  ///
+  /// See the enum [Clip] for details of all possible options and their common
+  /// use cases.
+  /// {@endtemplate}
+  final Clip clipBehavior;
+
   /// Defines the duration of animated changes for [shape], [elevation],
   /// and [shadowColor].
   ///
@@ -329,6 +342,7 @@ class _MaterialState extends State<Material> with TickerProviderStateMixin {
         curve: Curves.fastOutSlowIn,
         duration: widget.animationDuration,
         shape: BoxShape.rectangle,
+        clipBehavior: widget.clipBehavior,
         borderRadius: BorderRadius.zero,
         elevation: widget.elevation,
         color: backgroundColor,
@@ -341,20 +355,21 @@ class _MaterialState extends State<Material> with TickerProviderStateMixin {
     final ShapeBorder shape = _getShape();
 
     if (widget.type == MaterialType.transparency)
-      return _transparentInterior(shape: shape, contents: contents);
+      return _transparentInterior(shape: shape, clipBehavior: widget.clipBehavior, contents: contents);
 
     return new _MaterialInterior(
       curve: Curves.fastOutSlowIn,
       duration: widget.animationDuration,
       shape: shape,
+      clipBehavior: widget.clipBehavior,
       elevation: widget.elevation,
       color: backgroundColor,
       shadowColor: widget.shadowColor,
       child: contents,
     );
   }
 
-  static Widget _transparentInterior({ShapeBorder shape, Widget contents}) {
+  static Widget _transparentInterior({ShapeBorder shape, Clip clipBehavior, Widget contents}) {
     return new ClipPath(
       child: new _ShapeBorderPaint(
         child: contents,
@@ -363,6 +378,7 @@ class _MaterialState extends State<Material> with TickerProviderStateMixin {
       clipper: new ShapeBorderClipper(
         shape: shape,
       ),
+      clipBehavior: clipBehavior,
     );
   }
 
@@ -582,13 +598,15 @@ class _MaterialInterior extends ImplicitlyAnimatedWidget {
     Key key,
     @required this.child,
     @required this.shape,
+    this.clipBehavior = defaultClipBehavior, // ignore: deprecated_member_use
     @required this.elevation,
     @required this.color,
     @required this.shadowColor,
     Curve curve = Curves.linear,
     @required Duration duration,
   }) : assert(child != null),
        assert(shape != null),
+       assert(clipBehavior != null),
        assert(elevation != null),
        assert(color != null),
        assert(shadowColor != null),
@@ -605,6 +623,9 @@ class _MaterialInterior extends ImplicitlyAnimatedWidget {
   /// determines the physical shape.
   final ShapeBorder shape;
 
+  /// {@macro flutter.widgets.Clip}
+  final Clip clipBehavior;
+
   /// The target z-coordinate at which to place this physical object.
   final double elevation;
 
@@ -651,6 +672,7 @@ class _MaterialInteriorState extends AnimatedWidgetBaseState<_MaterialInterior>
         shape: shape,
         textDirection: Directionality.of(context)
       ),
+      clipBehavior: widget.clipBehavior,
       elevation: _elevation.evaluate(animation),
       color: widget.color,
       shadowColor: _shadowColor.evaluate(animation),

packages/flutter/lib/src/painting/clip.dart

@@ -0,0 +1,59 @@
+// Copyright 2018 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:ui' show Canvas, Clip, Path, Paint, Rect, RRect;
+
+/// Clip utilities used by [PaintingContext] and [TestRecordingPaintingContext].
+abstract class ClipContext {
+  /// The canvas on which to paint.
+  Canvas get canvas;
+
+  void _clipAndPaint(void canvasClipCall(bool doAntiAlias), Clip clipBehavior, Rect bounds, void painter()) {
+    assert(canvasClipCall != null);
+    canvas.save();
+    switch (clipBehavior) {
+      case Clip.none:
+        break;
+      case Clip.hardEdge:
+        canvasClipCall(false);
+        break;
+      case Clip.antiAlias:
+        canvasClipCall(true);
+        break;
+      case Clip.antiAliasWithSaveLayer:
+        canvasClipCall(true);
+        canvas.saveLayer(bounds, new Paint());
+        break;
+    }
+    painter();
+    if (clipBehavior == Clip.antiAliasWithSaveLayer) {
+      canvas.restore();
+    }
+    canvas.restore();
+  }
+
+  /// Clip [canvas] with [Path] according to [Clip] and then paint. [canvas] is
+  /// restored to the pre-clip status afterwards.
+  ///
+  /// `bounds` is the saveLayer bounds used for [Clip.antiAliasWithSaveLayer].
+  void clipPathAndPaint(Path path, Clip clipBehavior, Rect bounds, void painter()) {
+    _clipAndPaint((bool doAntiAias) => canvas.clipPath(path, doAntiAlias: doAntiAias), clipBehavior, bounds, painter);
+  }
+
+  /// Clip [canvas] with [Path] according to [RRect] and then paint. [canvas] is
+  /// restored to the pre-clip status afterwards.
+  ///
+  /// `bounds` is the saveLayer bounds used for [Clip.antiAliasWithSaveLayer].
+  void clipRRectAndPaint(RRect rrect, Clip clipBehavior, Rect bounds, void painter()) {
+    _clipAndPaint((bool doAntiAias) => canvas.clipRRect(rrect, doAntiAlias: doAntiAias), clipBehavior, bounds, painter);
+  }
+
+  /// Clip [canvas] with [Path] according to [Rect] and then paint. [canvas] is
+  /// restored to the pre-clip status afterwards.
+  ///
+  /// `bounds` is the saveLayer bounds used for [Clip.antiAliasWithSaveLayer].
+  void clipRectAndPaint(Rect rect, Clip clipBehavior, Rect bounds, void painter()) {
+    _clipAndPaint((bool doAntiAias) => canvas.clipRect(rect, doAntiAlias: doAntiAias), clipBehavior, bounds, painter);
+  }
+}

packages/flutter/lib/src/rendering/layer.dart

@@ -5,7 +5,7 @@
 import 'dart:async';
 import 'dart:collection';
 import 'dart:ui' as ui show Image, ImageFilter, Picture, Scene, SceneBuilder;
-import 'dart:ui' show Offset;
+import 'dart:ui' show Clip, Offset, defaultClipBehavior; // ignore: deprecated_member_use
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/painting.dart';
@@ -605,14 +605,24 @@ class ClipRectLayer extends ContainerLayer {
   ///
   /// The [clipRect] property must be non-null before the compositing phase of
   /// the pipeline.
-  ClipRectLayer({ this.clipRect });
+  ClipRectLayer({ this.clipRect, Clip clipBehavior = Clip.antiAlias }) :
+        _clipBehavior = clipBehavior, assert(clipBehavior != null), assert(clipBehavior != Clip.none);
 
   /// The rectangle to clip in the parent's coordinate system.
   ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
   Rect clipRect;
 
+  /// {@macro flutter.clipper.clipBehavior}
+  Clip get clipBehavior => _clipBehavior;
+  Clip _clipBehavior;
+  set clipBehavior(Clip value) {
+    assert(value != null);
+    assert(value != Clip.none);
+    _clipBehavior = value;
+  }
+
   @override
   S find<S>(Offset regionOffset) {
     if (!clipRect.contains(regionOffset))
@@ -628,7 +638,7 @@ class ClipRectLayer extends ContainerLayer {
       return true;
     }());
     if (enabled)
-      builder.pushClipRect(clipRect.shift(layerOffset));
+      builder.pushClipRect(clipRect.shift(layerOffset), clipBehavior: clipBehavior);
     addChildrenToScene(builder, layerOffset);
     if (enabled)
       builder.pop();
@@ -651,14 +661,24 @@ class ClipRRectLayer extends ContainerLayer {
   ///
   /// The [clipRRect] property must be non-null before the compositing phase of
   /// the pipeline.
-  ClipRRectLayer({ this.clipRRect });
+  ClipRRectLayer({ this.clipRRect, Clip clipBehavior = Clip.antiAlias }) :
+        _clipBehavior = clipBehavior, assert(clipBehavior != null), assert(clipBehavior != Clip.none);
 
   /// The rounded-rect to clip in the parent's coordinate system.
   ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
   RRect clipRRect;
 
+  /// {@macro flutter.clipper.clipBehavior}
+  Clip get clipBehavior => _clipBehavior;
+  Clip _clipBehavior;
+  set clipBehavior(Clip value) {
+    assert(value != null);
+    assert(value != Clip.none);
+    _clipBehavior = value;
+  }
+
   @override
   S find<S>(Offset regionOffset) {
     if (!clipRRect.contains(regionOffset))
@@ -674,7 +694,7 @@ class ClipRRectLayer extends ContainerLayer {
       return true;
     }());
     if (enabled)
-      builder.pushClipRRect(clipRRect.shift(layerOffset));
+      builder.pushClipRRect(clipRRect.shift(layerOffset), clipBehavior: clipBehavior);
     addChildrenToScene(builder, layerOffset);
     if (enabled)
       builder.pop();
@@ -697,14 +717,24 @@ class ClipPathLayer extends ContainerLayer {
   ///
   /// The [clipPath] property must be non-null before the compositing phase of
   /// the pipeline.
-  ClipPathLayer({ this.clipPath });
+  ClipPathLayer({ this.clipPath, Clip clipBehavior = Clip.antiAlias }) :
+        _clipBehavior = clipBehavior, assert(clipBehavior != null), assert(clipBehavior != Clip.none);
 
   /// The path to clip in the parent's coordinate system.
   ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
   Path clipPath;
 
+  /// {@macro flutter.clipper.clipBehavior}
+  Clip get clipBehavior => _clipBehavior;
+  Clip _clipBehavior;
+  set clipBehavior(Clip value) {
+    assert(value != null);
+    assert(value != Clip.none);
+    _clipBehavior = value;
+  }
+
   @override
   S find<S>(Offset regionOffset) {
     if (!clipPath.contains(regionOffset))
@@ -720,7 +750,7 @@ class ClipPathLayer extends ContainerLayer {
       return true;
     }());
     if (enabled)
-      builder.pushClipPath(clipPath.shift(layerOffset));
+      builder.pushClipPath(clipPath.shift(layerOffset), clipBehavior: clipBehavior);
     addChildrenToScene(builder, layerOffset);
     if (enabled)
       builder.pop();
@@ -925,10 +955,12 @@ class PhysicalModelLayer extends ContainerLayer {
   /// The [clipPath], [elevation], and [color] arguments must not be null.
   PhysicalModelLayer({
     @required this.clipPath,
+    this.clipBehavior = defaultClipBehavior, // ignore: deprecated_member_use
     @required this.elevation,
     @required this.color,
     @required this.shadowColor,
   }) : assert(clipPath != null),
+       assert(clipBehavior != null),
        assert(elevation != null),
        assert(color != null),
        assert(shadowColor != null);
@@ -939,6 +971,9 @@ class PhysicalModelLayer extends ContainerLayer {
   /// (as described at [Layer]).
   Path clipPath;
 
+  /// {@macro flutter.widgets.Clip}
+  Clip clipBehavior;
+
   /// The z-coordinate at which to place this physical object.
   ///
   /// The scene must be explicitly recomposited after this property is changed
@@ -980,6 +1015,7 @@ class PhysicalModelLayer extends ContainerLayer {
         elevation: elevation,
         color: color,
         shadowColor: shadowColor,
+        clipBehavior: clipBehavior,
       );
     }
     addChildrenToScene(builder, layerOffset);