Outline.java revision 9a347f199284ad8bcb8a81bfbd306fe0b1a710ba
1/* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.graphics; 18 19import android.annotation.NonNull; 20import android.graphics.drawable.Drawable; 21import android.view.View; 22 23/** 24 * Defines a simple shape, used for bounding graphical regions. 25 * <p> 26 * Can be used with a View, or computed by a Drawable, to drive the shape of shadows cast by a 27 * View, or to clip the contents of the View. 28 * 29 * @see View#setOutline(Outline) 30 * @see Drawable#getOutline(Outline) 31 */ 32public final class Outline { 33 /** @hide */ 34 public Path mPath; 35 36 /** @hide */ 37 public Rect mRect; 38 /** @hide */ 39 public float mRadius; 40 41 /** @hide */ 42 public boolean mIsFilled; 43 44 /** 45 * Constructs an empty Outline. Call one of the setter methods to make 46 * the outline valid for use with a View. 47 */ 48 public Outline() {} 49 50 /** 51 * Constructs an Outline with a copy of the data in src. 52 */ 53 public Outline(@NonNull Outline src) { 54 set(src); 55 } 56 57 /** 58 * Sets the outline to be empty. 59 * 60 * @see #isEmpty() 61 */ 62 public void setEmpty() { 63 mPath = null; 64 mRect = null; 65 mRadius = 0; 66 mIsFilled = true; 67 } 68 69 /** 70 * Returns whether the Outline is empty. 71 * <p> 72 * Outlines are empty when constructed, or if {@link #setEmpty()} is called, 73 * until a setter method is called 74 * 75 * @see #setEmpty() 76 */ 77 public boolean isEmpty() { 78 return mRect == null && mPath == null; 79 } 80 81 82 /** 83 * Returns whether the outline can be used to clip a View. 84 * 85 * Currently, only outlines that can be represented as a rectangle, circle, or round rect 86 * support clipping. 87 * 88 * @see {@link View#setClipToOutline(boolean)} 89 */ 90 public boolean canClip() { 91 return !isEmpty() && mRect != null; 92 } 93 94 /** 95 * Sets whether the outline represents a fully opaque area. 96 * 97 * A filled outline is assumed, by the drawing system, to fully cover content beneath it, 98 * meaning content beneath may be optimized away. 99 */ 100 public void setFilled(boolean isFilled) { 101 mIsFilled = isFilled; 102 } 103 104 /** 105 * Returns whether the outline represents a fully opaque area. 106 */ 107 public boolean isFilled() { 108 return !isEmpty() && mIsFilled; 109 } 110 111 /** 112 * Replace the contents of this Outline with the contents of src. 113 * 114 * @param src Source outline to copy from. 115 */ 116 public void set(@NonNull Outline src) { 117 if (src.mPath != null) { 118 if (mPath == null) { 119 mPath = new Path(); 120 } 121 mPath.set(src.mPath); 122 mRect = null; 123 } 124 if (src.mRect != null) { 125 if (mRect == null) { 126 mRect = new Rect(); 127 } 128 mRect.set(src.mRect); 129 } 130 mRadius = src.mRadius; 131 mIsFilled = src.mIsFilled; 132 } 133 134 /** 135 * Sets the Outline to the rounded rect defined by the input rect, and corner radius. 136 */ 137 public void setRect(int left, int top, int right, int bottom) { 138 setRoundRect(left, top, right, bottom, 0.0f); 139 } 140 141 /** 142 * Convenience for {@link #setRect(int, int, int, int)} 143 */ 144 public void setRect(@NonNull Rect rect) { 145 setRect(rect.left, rect.top, rect.right, rect.bottom); 146 } 147 148 /** 149 * Sets the Outline to the rounded rect defined by the input rect, and corner radius. 150 * 151 * Passing a zero radius is equivalent to calling {@link #setRect(int, int, int, int)} 152 */ 153 public void setRoundRect(int left, int top, int right, int bottom, float radius) { 154 if (mRect == null) mRect = new Rect(); 155 mRect.set(left, top, right, bottom); 156 mRadius = radius; 157 mPath = null; 158 mIsFilled = true; 159 } 160 161 /** 162 * Convenience for {@link #setRoundRect(int, int, int, int, float)} 163 */ 164 public void setRoundRect(@NonNull Rect rect, float radius) { 165 setRoundRect(rect.left, rect.top, rect.right, rect.bottom, radius); 166 } 167 168 /** 169 * Sets the outline to the oval defined by input rect. 170 */ 171 public void setOval(int left, int top, int right, int bottom) { 172 if ((bottom - top) == (right - left)) { 173 // represent circle as round rect, for efficiency, and to enable clipping 174 setRoundRect(left, top, right, bottom, (bottom - top) / 2.0f); 175 return; 176 } 177 if (mPath == null) mPath = new Path(); 178 mPath.reset(); 179 mPath.addOval(left, top, right, bottom, Path.Direction.CW); 180 mRect = null; 181 mIsFilled = true; 182 } 183 184 /** 185 * Convenience for {@link #setOval(int, int, int, int)} 186 */ 187 public void setOval(@NonNull Rect rect) { 188 setOval(rect.left, rect.top, rect.right, rect.bottom); 189 } 190 191 /** 192 * Sets the Constructs an Outline from a {@link android.graphics.Path#isConvex() convex path}. 193 */ 194 public void setConvexPath(@NonNull Path convexPath) { 195 if (!convexPath.isConvex()) { 196 throw new IllegalArgumentException("path must be convex"); 197 } 198 if (mPath == null) mPath = new Path(); 199 200 mPath.set(convexPath); 201 mRect = null; 202 mRadius = -1.0f; 203 mIsFilled = true; 204 } 205} 206