From 8c5759624c71ef701cba6751a030328481b4a83c Mon Sep 17 00:00:00 2001 From: Derek Sollenberger Date: Thu, 9 Feb 2017 14:17:55 -0500 Subject: [PATCH] Deprecate Canvas clipping for arbitrary Region.Ops. Operations that can expand the clip are difficult to support and don't fit the parent child model that is used by the view system. Test: compile Bug: 14650725 Change-Id: I67e99d3e1a1eb0b231910ee5d277a38e8a953dc4 --- api/current.txt | 13 ++- api/system-current.txt | 13 ++- api/test-current.txt | 13 ++- graphics/java/android/graphics/Canvas.java | 96 +++++++++++++++++++++- 4 files changed, 122 insertions(+), 13 deletions(-) diff --git a/api/current.txt b/api/current.txt index 96b96dbdaecde..068ffb0fd89a5 100644 --- a/api/current.txt +++ b/api/current.txt @@ -12296,13 +12296,18 @@ package android.graphics { public class Canvas { ctor public Canvas(); ctor public Canvas(android.graphics.Bitmap); - method public boolean clipPath(android.graphics.Path, android.graphics.Region.Op); + method public boolean clipOutPath(android.graphics.Path); + method public boolean clipOutRect(android.graphics.RectF); + method public boolean clipOutRect(android.graphics.Rect); + method public boolean clipOutRect(float, float, float, float); + method public boolean clipOutRect(int, int, int, int); + method public deprecated boolean clipPath(android.graphics.Path, android.graphics.Region.Op); method public boolean clipPath(android.graphics.Path); - method public boolean clipRect(android.graphics.RectF, android.graphics.Region.Op); - method public boolean clipRect(android.graphics.Rect, android.graphics.Region.Op); + method public deprecated boolean clipRect(android.graphics.RectF, android.graphics.Region.Op); + method public deprecated boolean clipRect(android.graphics.Rect, android.graphics.Region.Op); method public boolean clipRect(android.graphics.RectF); method public boolean clipRect(android.graphics.Rect); - method public boolean clipRect(float, float, float, float, android.graphics.Region.Op); + method public deprecated boolean clipRect(float, float, float, float, android.graphics.Region.Op); method public boolean clipRect(float, float, float, float); method public boolean clipRect(int, int, int, int); method public void concat(android.graphics.Matrix); diff --git a/api/system-current.txt b/api/system-current.txt index 3a58bf4c8d7a8..bf1fa59a3edb1 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -12864,13 +12864,18 @@ package android.graphics { public class Canvas { ctor public Canvas(); ctor public Canvas(android.graphics.Bitmap); - method public boolean clipPath(android.graphics.Path, android.graphics.Region.Op); + method public boolean clipOutPath(android.graphics.Path); + method public boolean clipOutRect(android.graphics.RectF); + method public boolean clipOutRect(android.graphics.Rect); + method public boolean clipOutRect(float, float, float, float); + method public boolean clipOutRect(int, int, int, int); + method public deprecated boolean clipPath(android.graphics.Path, android.graphics.Region.Op); method public boolean clipPath(android.graphics.Path); - method public boolean clipRect(android.graphics.RectF, android.graphics.Region.Op); - method public boolean clipRect(android.graphics.Rect, android.graphics.Region.Op); + method public deprecated boolean clipRect(android.graphics.RectF, android.graphics.Region.Op); + method public deprecated boolean clipRect(android.graphics.Rect, android.graphics.Region.Op); method public boolean clipRect(android.graphics.RectF); method public boolean clipRect(android.graphics.Rect); - method public boolean clipRect(float, float, float, float, android.graphics.Region.Op); + method public deprecated boolean clipRect(float, float, float, float, android.graphics.Region.Op); method public boolean clipRect(float, float, float, float); method public boolean clipRect(int, int, int, int); method public void concat(android.graphics.Matrix); diff --git a/api/test-current.txt b/api/test-current.txt index 36f5835188b3a..c448b2776e9d5 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -12330,13 +12330,18 @@ package android.graphics { public class Canvas { ctor public Canvas(); ctor public Canvas(android.graphics.Bitmap); - method public boolean clipPath(android.graphics.Path, android.graphics.Region.Op); + method public boolean clipOutPath(android.graphics.Path); + method public boolean clipOutRect(android.graphics.RectF); + method public boolean clipOutRect(android.graphics.Rect); + method public boolean clipOutRect(float, float, float, float); + method public boolean clipOutRect(int, int, int, int); + method public deprecated boolean clipPath(android.graphics.Path, android.graphics.Region.Op); method public boolean clipPath(android.graphics.Path); - method public boolean clipRect(android.graphics.RectF, android.graphics.Region.Op); - method public boolean clipRect(android.graphics.Rect, android.graphics.Region.Op); + method public deprecated boolean clipRect(android.graphics.RectF, android.graphics.Region.Op); + method public deprecated boolean clipRect(android.graphics.Rect, android.graphics.Region.Op); method public boolean clipRect(android.graphics.RectF); method public boolean clipRect(android.graphics.Rect); - method public boolean clipRect(float, float, float, float, android.graphics.Region.Op); + method public deprecated boolean clipRect(float, float, float, float, android.graphics.Region.Op); method public boolean clipRect(float, float, float, float); method public boolean clipRect(int, int, int, int); method public void concat(android.graphics.Matrix); diff --git a/graphics/java/android/graphics/Canvas.java b/graphics/java/android/graphics/Canvas.java index 85723456399a0..23e73059db6f0 100644 --- a/graphics/java/android/graphics/Canvas.java +++ b/graphics/java/android/graphics/Canvas.java @@ -677,7 +677,14 @@ public class Canvas extends BaseCanvas { * @param rect The rect to intersect with the current clip * @param op How the clip is modified * @return true if the resulting clip is non-empty + * + * @deprecated Region.Op values other than {@link Region.Op#INTERSECT} and + * {@link Region.Op#DIFFERENCE} have the ability to expand the clip. The canvas clipping APIs + * are intended to only expand the clip as a result of a restore operation. This enables a view + * parent to clip a canvas to clearly define the maximal drawing area of its children. The + * recommended alternative calls are {@link #clipRect(RectF)} and {@link #clipOutRect(RectF)}; */ + @Deprecated public boolean clipRect(@NonNull RectF rect, @NonNull Region.Op op) { return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom, op.nativeInt); @@ -690,7 +697,14 @@ public class Canvas extends BaseCanvas { * @param rect The rectangle to intersect with the current clip. * @param op How the clip is modified * @return true if the resulting clip is non-empty + * + * @deprecated Region.Op values other than {@link Region.Op#INTERSECT} and + * {@link Region.Op#DIFFERENCE} have the ability to expand the clip. The canvas clipping APIs + * are intended to only expand the clip as a result of a restore operation. This enables a view + * parent to clip a canvas to clearly define the maximal drawing area of its children. The + * recommended alternative calls are {@link #clipRect(Rect)} and {@link #clipOutRect(Rect)}; */ + @Deprecated public boolean clipRect(@NonNull Rect rect, @NonNull Region.Op op) { return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom, op.nativeInt); @@ -708,6 +722,18 @@ public class Canvas extends BaseCanvas { Region.Op.INTERSECT.nativeInt); } + /** + * Set the clip to the difference of the current clip and the specified rectangle, which is + * expressed in local coordinates. + * + * @param rect The rectangle to perform a difference op with the current clip. + * @return true if the resulting clip is non-empty + */ + public boolean clipOutRect(@NonNull RectF rect) { + return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom, + Region.Op.DIFFERENCE.nativeInt); + } + /** * Intersect the current clip with the specified rectangle, which is * expressed in local coordinates. @@ -720,6 +746,18 @@ public class Canvas extends BaseCanvas { Region.Op.INTERSECT.nativeInt); } + /** + * Set the clip to the difference of the current clip and the specified rectangle, which is + * expressed in local coordinates. + * + * @param rect The rectangle to perform a difference op with the current clip. + * @return true if the resulting clip is non-empty + */ + public boolean clipOutRect(@NonNull Rect rect) { + return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom, + Region.Op.DIFFERENCE.nativeInt); + } + /** * Modify the current clip with the specified rectangle, which is * expressed in local coordinates. @@ -734,7 +772,15 @@ public class Canvas extends BaseCanvas { * clip * @param op How the clip is modified * @return true if the resulting clip is non-empty + * + * @deprecated Region.Op values other than {@link Region.Op#INTERSECT} and + * {@link Region.Op#DIFFERENCE} have the ability to expand the clip. The canvas clipping APIs + * are intended to only expand the clip as a result of a restore operation. This enables a view + * parent to clip a canvas to clearly define the maximal drawing area of its children. The + * recommended alternative calls are {@link #clipRect(float,float,float,float)} and + * {@link #clipOutRect(float,float,float,float)}; */ + @Deprecated public boolean clipRect(float left, float top, float right, float bottom, @NonNull Region.Op op) { return nClipRect(mNativeCanvasWrapper, left, top, right, bottom, op.nativeInt); @@ -758,6 +804,21 @@ public class Canvas extends BaseCanvas { Region.Op.INTERSECT.nativeInt); } + /** + * Set the clip to the difference of the current clip and the specified rectangle, which is + * expressed in local coordinates. + * + * @param left The left side of the rectangle used in the difference operation + * @param top The top of the rectangle used in the difference operation + * @param right The right side of the rectangle used in the difference operation + * @param bottom The bottom of the rectangle used in the difference operation + * @return true if the resulting clip is non-empty + */ + public boolean clipOutRect(float left, float top, float right, float bottom) { + return nClipRect(mNativeCanvasWrapper, left, top, right, bottom, + Region.Op.DIFFERENCE.nativeInt); + } + /** * Intersect the current clip with the specified rectangle, which is * expressed in local coordinates. @@ -776,13 +837,36 @@ public class Canvas extends BaseCanvas { Region.Op.INTERSECT.nativeInt); } + /** + * Set the clip to the difference of the current clip and the specified rectangle, which is + * expressed in local coordinates. + * + * @param left The left side of the rectangle used in the difference operation + * @param top The top of the rectangle used in the difference operation + * @param right The right side of the rectangle used in the difference operation + * @param bottom The bottom of the rectangle used in the difference operation + * @return true if the resulting clip is non-empty + */ + public boolean clipOutRect(int left, int top, int right, int bottom) { + return nClipRect(mNativeCanvasWrapper, left, top, right, bottom, + Region.Op.DIFFERENCE.nativeInt); + } + /** * Modify the current clip with the specified path. * * @param path The path to operate on the current clip * @param op How the clip is modified * @return true if the resulting is non-empty + * + * @deprecated Region.Op values other than {@link Region.Op#INTERSECT} and + * {@link Region.Op#DIFFERENCE} have the ability to expand the clip. The canvas clipping APIs + * are intended to only expand the clip as a result of a restore operation. This enables a view + * parent to clip a canvas to clearly define the maximal drawing area of its children. The + * recommended alternative calls are {@link #clipPath(Path)} and + * {@link #clipOutPath(Path)}; */ + @Deprecated public boolean clipPath(@NonNull Path path, @NonNull Region.Op op) { return nClipPath(mNativeCanvasWrapper, path.readOnlyNI(), op.nativeInt); } @@ -791,12 +875,22 @@ public class Canvas extends BaseCanvas { * Intersect the current clip with the specified path. * * @param path The path to intersect with the current clip - * @return true if the resulting is non-empty + * @return true if the resulting clip is non-empty */ public boolean clipPath(@NonNull Path path) { return clipPath(path, Region.Op.INTERSECT); } + /** + * Set the clip to the difference of the current clip and the specified path. + * + * @param path The path used in the difference operation + * @return true if the resulting clip is non-empty + */ + public boolean clipOutPath(@NonNull Path path) { + return clipPath(path, Region.Op.DIFFERENCE); + } + /** * Modify the current clip with the specified region. Note that unlike * clipRect() and clipPath() which transform their arguments by the