diff --git a/api/current.txt b/api/current.txt index d4811f0e54668..ccbaebb4005b7 100644 --- a/api/current.txt +++ b/api/current.txt @@ -12302,13 +12302,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 781134d1dac5b..326ca48aada60 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -12891,13 +12891,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 79b95a011bf94..f35610664890a 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -12336,13 +12336,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