Outline.java revision 921ec4464720ebe5f07a4dcb6e18b86e27baba6e
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.FloatRange; 20import android.annotation.NonNull; 21import android.annotation.Nullable; 22import android.graphics.drawable.Drawable; 23 24/** 25 * Defines a simple shape, used for bounding graphical regions. 26 * <p> 27 * Can be computed for a View, or computed by a Drawable, to drive the shape of 28 * shadows cast by a View, or to clip the contents of the View. 29 * 30 * @see android.view.ViewOutlineProvider 31 * @see android.view.View#setOutlineProvider(android.view.ViewOutlineProvider) 32 * @see Drawable#getOutline(Outline) 33 */ 34public final class Outline { 35 /** @hide */ 36 public Path mPath; 37 38 /** @hide */ 39 public Rect mRect; 40 /** @hide */ 41 public float mRadius; 42 /** @hide */ 43 public float mAlpha; 44 45 /** 46 * Constructs an empty Outline. Call one of the setter methods to make 47 * the outline valid for use with a View. 48 */ 49 public Outline() {} 50 51 /** 52 * Constructs an Outline with a copy of the data in src. 53 */ 54 public Outline(@NonNull Outline src) { 55 set(src); 56 } 57 58 /** 59 * Sets the outline to be empty. 60 * 61 * @see #isEmpty() 62 */ 63 public void setEmpty() { 64 mPath = null; 65 mRect = null; 66 mRadius = 0; 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 * <p> 85 * Currently, only Outlines that can be represented as a rectangle, circle, 86 * or round rect support clipping. 87 * 88 * @see {@link android.view.View#setClipToOutline(boolean)} 89 */ 90 public boolean canClip() { 91 return !isEmpty() && mRect != null; 92 } 93 94 /** 95 * Sets the alpha represented by the Outline - the degree to which the 96 * producer is guaranteed to be opaque over the Outline's shape. 97 * <p> 98 * An alpha value of <code>0.0f</code> either represents completely 99 * transparent content, or content that isn't guaranteed to fill the shape 100 * it publishes. 101 * <p> 102 * Content producing a fully opaque (alpha = <code>1.0f</code>) outline is 103 * assumed by the drawing system to fully cover content beneath it, 104 * meaning content beneath may be optimized away. 105 */ 106 public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) { 107 mAlpha = alpha; 108 } 109 110 /** 111 * Returns the alpha represented by the Outline. 112 */ 113 public float getAlpha() { 114 return mAlpha; 115 } 116 117 /** 118 * Replace the contents of this Outline with the contents of src. 119 * 120 * @param src Source outline to copy from. 121 */ 122 public void set(@NonNull Outline src) { 123 if (src.mPath != null) { 124 if (mPath == null) { 125 mPath = new Path(); 126 } 127 mPath.set(src.mPath); 128 mRect = null; 129 } 130 if (src.mRect != null) { 131 if (mRect == null) { 132 mRect = new Rect(); 133 } 134 mRect.set(src.mRect); 135 } 136 mRadius = src.mRadius; 137 mAlpha = src.mAlpha; 138 } 139 140 /** 141 * Sets the Outline to the rounded rect defined by the input rect, and 142 * corner radius. 143 */ 144 public void setRect(int left, int top, int right, int bottom) { 145 setRoundRect(left, top, right, bottom, 0.0f); 146 } 147 148 /** 149 * Convenience for {@link #setRect(int, int, int, int)} 150 */ 151 public void setRect(@NonNull Rect rect) { 152 setRect(rect.left, rect.top, rect.right, rect.bottom); 153 } 154 155 /** 156 * Sets the Outline to the rounded rect defined by the input rect, and corner radius. 157 * <p> 158 * Passing a zero radius is equivalent to calling {@link #setRect(int, int, int, int)} 159 */ 160 public void setRoundRect(int left, int top, int right, int bottom, float radius) { 161 if (left >= right || top >= bottom) { 162 setEmpty(); 163 return; 164 } 165 166 if (mRect == null) mRect = new Rect(); 167 mRect.set(left, top, right, bottom); 168 mRadius = radius; 169 mPath = null; 170 } 171 172 /** 173 * Convenience for {@link #setRoundRect(int, int, int, int, float)} 174 */ 175 public void setRoundRect(@NonNull Rect rect, float radius) { 176 setRoundRect(rect.left, rect.top, rect.right, rect.bottom, radius); 177 } 178 179 /** 180 * Populates {@code outBounds} with the outline bounds, if set, and returns 181 * {@code true}. If no outline bounds are set, or if a path has been set 182 * via {@link #setConvexPath(Path)}, returns {@code false}. 183 * 184 * @param outRect the rect to populate with the outline bounds, if set 185 * @return {@code true} if {@code outBounds} was populated with outline 186 * bounds, or {@code false} if no outline bounds are set 187 */ 188 public boolean getRect(@NonNull Rect outRect) { 189 if (mRect == null) { 190 return false; 191 } 192 outRect.set(mRect); 193 return true; 194 } 195 196 /** 197 * Returns the rounded rect radius, if set, or {@code -1} if a path has 198 * been set via {@link #setConvexPath(Path)}. A return value of {@code 0} 199 * indicates a non-rounded rect. 200 * 201 * @return the rounded rect radius or {@code -1} 202 */ 203 public float getRadius() { 204 return mRadius; 205 } 206 207 /** 208 * Sets the outline to the oval defined by input rect. 209 */ 210 public void setOval(int left, int top, int right, int bottom) { 211 if (left >= right || top >= bottom) { 212 setEmpty(); 213 return; 214 } 215 216 if ((bottom - top) == (right - left)) { 217 // represent circle as round rect, for efficiency, and to enable clipping 218 setRoundRect(left, top, right, bottom, (bottom - top) / 2.0f); 219 return; 220 } 221 222 if (mPath == null) mPath = new Path(); 223 mPath.reset(); 224 mPath.addOval(left, top, right, bottom, Path.Direction.CW); 225 mRect = null; 226 } 227 228 /** 229 * Convenience for {@link #setOval(int, int, int, int)} 230 */ 231 public void setOval(@NonNull Rect rect) { 232 setOval(rect.left, rect.top, rect.right, rect.bottom); 233 } 234 235 /** 236 * Sets the Constructs an Outline from a 237 * {@link android.graphics.Path#isConvex() convex path}. 238 */ 239 public void setConvexPath(@NonNull Path convexPath) { 240 if (convexPath.isEmpty()) { 241 setEmpty(); 242 return; 243 } 244 245 if (!convexPath.isConvex()) { 246 throw new IllegalArgumentException("path must be convex"); 247 } 248 if (mPath == null) mPath = new Path(); 249 250 mPath.set(convexPath); 251 mRect = null; 252 mRadius = -1.0f; 253 } 254 255 /** 256 * Offsets the Outline by (dx,dy) 257 */ 258 public void offset(int dx, int dy) { 259 if (mRect != null) { 260 mRect.offset(dx, dy); 261 } else if (mPath != null) { 262 mPath.offset(dx, dy); 263 } 264 } 265} 266