Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8c575962 authored by Derek Sollenberger's avatar Derek Sollenberger
Browse files

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
parent 3eacb58a

api/current.txt

+9 −4
Original line number Original line Diff line number Diff line
@@ -12296,13 +12296,18 @@ package android.graphics { 
  public class Canvas {

  public class Canvas {

    ctor public Canvas();

    ctor public Canvas();

    ctor public Canvas(android.graphics.Bitmap);

    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 clipPath(android.graphics.Path);

    method public boolean clipRect(android.graphics.RectF, android.graphics.Region.Op);

    method public deprecated 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.Rect, android.graphics.Region.Op);

    method public boolean clipRect(android.graphics.RectF);

    method public boolean clipRect(android.graphics.RectF);

    method public boolean clipRect(android.graphics.Rect);

    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(float, float, float, float);

    method public boolean clipRect(int, int, int, int);

    method public boolean clipRect(int, int, int, int);

    method public void concat(android.graphics.Matrix);

    method public void concat(android.graphics.Matrix);

api/system-current.txt

+9 −4
Original line number Original line Diff line number Diff line
@@ -12864,13 +12864,18 @@ package android.graphics { 
  public class Canvas {

  public class Canvas {

    ctor public Canvas();

    ctor public Canvas();

    ctor public Canvas(android.graphics.Bitmap);

    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 clipPath(android.graphics.Path);

    method public boolean clipRect(android.graphics.RectF, android.graphics.Region.Op);

    method public deprecated 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.Rect, android.graphics.Region.Op);

    method public boolean clipRect(android.graphics.RectF);

    method public boolean clipRect(android.graphics.RectF);

    method public boolean clipRect(android.graphics.Rect);

    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(float, float, float, float);

    method public boolean clipRect(int, int, int, int);

    method public boolean clipRect(int, int, int, int);

    method public void concat(android.graphics.Matrix);

    method public void concat(android.graphics.Matrix);

api/test-current.txt

+9 −4
Original line number Original line Diff line number Diff line
@@ -12330,13 +12330,18 @@ package android.graphics { 
  public class Canvas {

  public class Canvas {

    ctor public Canvas();

    ctor public Canvas();

    ctor public Canvas(android.graphics.Bitmap);

    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 clipPath(android.graphics.Path);

    method public boolean clipRect(android.graphics.RectF, android.graphics.Region.Op);

    method public deprecated 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.Rect, android.graphics.Region.Op);

    method public boolean clipRect(android.graphics.RectF);

    method public boolean clipRect(android.graphics.RectF);

    method public boolean clipRect(android.graphics.Rect);

    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(float, float, float, float);

    method public boolean clipRect(int, int, int, int);

    method public boolean clipRect(int, int, int, int);

    method public void concat(android.graphics.Matrix);

    method public void concat(android.graphics.Matrix);

graphics/java/android/graphics/Canvas.java

+95 −1
Original line number Original line Diff line number Diff line
@@ -677,7 +677,14 @@ public class Canvas extends BaseCanvas { 
     * @param rect The rect to intersect with the current clip

     * @param rect The rect to intersect with the current clip

     * @param op How the clip is modified

     * @param op How the clip is modified

     * @return true if the resulting clip is non-empty

     * @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) {

    public boolean clipRect(@NonNull RectF rect, @NonNull Region.Op op) {

        return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

        return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

                op.nativeInt);

                op.nativeInt);
@@ -690,7 +697,14 @@ public class Canvas extends BaseCanvas { 
     * @param rect The rectangle to intersect with the current clip.

     * @param rect The rectangle to intersect with the current clip.

     * @param op How the clip is modified

     * @param op How the clip is modified

     * @return true if the resulting clip is non-empty

     * @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) {

    public boolean clipRect(@NonNull Rect rect, @NonNull Region.Op op) {

        return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

        return nClipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

                op.nativeInt);

                op.nativeInt);
@@ -708,6 +722,18 @@ public class Canvas extends BaseCanvas { 
                Region.Op.INTERSECT.nativeInt);

                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

     * Intersect the current clip with the specified rectangle, which is

     * expressed in local coordinates.

     * expressed in local coordinates.
@@ -720,6 +746,18 @@ public class Canvas extends BaseCanvas { 
                Region.Op.INTERSECT.nativeInt);

                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

     * Modify the current clip with the specified rectangle, which is

     * expressed in local coordinates.

     * expressed in local coordinates.
@@ -734,7 +772,15 @@ public class Canvas extends BaseCanvas { 
     *               clip

     *               clip

     * @param op     How the clip is modified

     * @param op     How the clip is modified

     * @return       true if the resulting clip is non-empty

     * @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,

    public boolean clipRect(float left, float top, float right, float bottom,

            @NonNull Region.Op op) {

            @NonNull Region.Op op) {

        return nClipRect(mNativeCanvasWrapper, left, top, right, bottom, op.nativeInt);

        return nClipRect(mNativeCanvasWrapper, left, top, right, bottom, op.nativeInt);
@@ -758,6 +804,21 @@ public class Canvas extends BaseCanvas { 
                Region.Op.INTERSECT.nativeInt);

                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

     * Intersect the current clip with the specified rectangle, which is

     * expressed in local coordinates.

     * expressed in local coordinates.
@@ -776,13 +837,36 @@ public class Canvas extends BaseCanvas { 
                Region.Op.INTERSECT.nativeInt);

                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.

        * Modify the current clip with the specified path.

     *

     *

     * @param path The path to operate on the current clip

     * @param path The path to operate on the current clip

     * @param op   How the clip is modified

     * @param op   How the clip is modified

     * @return     true if the resulting is non-empty

     * @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) {

    public boolean clipPath(@NonNull Path path, @NonNull Region.Op op) {

        return nClipPath(mNativeCanvasWrapper, path.readOnlyNI(), op.nativeInt);

        return nClipPath(mNativeCanvasWrapper, path.readOnlyNI(), op.nativeInt);

    }

    }
@@ -791,12 +875,22 @@ public class Canvas extends BaseCanvas { 
     * Intersect the current clip with the specified path.

     * Intersect the current clip with the specified path.

     *

     *

     * @param path The path to intersect with the current clip

     * @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) {

    public boolean clipPath(@NonNull Path path) {

        return clipPath(path, Region.Op.INTERSECT);

        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

     * Modify the current clip with the specified region. Note that unlike

     * clipRect() and clipPath() which transform their arguments by the

     * clipRect() and clipPath() which transform their arguments by the