1 /* 2 * Copyright (C) 2006 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 17 package android.graphics; 18 19 import android.compat.annotation.UnsupportedAppUsage; 20 21 /** 22 * The NinePatch class permits drawing a bitmap in nine or more sections. 23 * Essentially, it allows the creation of custom graphics that will scale the 24 * way that you define, when content added within the image exceeds the normal 25 * bounds of the graphic. For a thorough explanation of a NinePatch image, 26 * read the discussion in the 27 * <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D 28 * Graphics</a> document. 29 * <p> 30 * The <a href="{@docRoot}guide/developing/tools/draw9patch.html">Draw 9-Patch</a> 31 * tool offers an extremely handy way to create your NinePatch images, 32 * using a WYSIWYG graphics editor. 33 * </p> 34 */ 35 @android.ravenwood.annotation.RavenwoodKeepWholeClass 36 public class NinePatch { 37 /** 38 * Struct of inset information attached to a 9 patch bitmap. 39 * 40 * Present on a 9 patch bitmap if it optical insets were manually included, 41 * or if outline insets were automatically included by aapt. 42 * 43 * @hide For use by NinePatchDrawable, but must not be used outside the module. 44 */ 45 public static class InsetStruct { 46 @SuppressWarnings({"UnusedDeclaration"}) // called from JNI InsetStruct(int opticalLeft, int opticalTop, int opticalRight, int opticalBottom, int outlineLeft, int outlineTop, int outlineRight, int outlineBottom, float outlineRadius, int outlineAlpha, float decodeScale)47 InsetStruct(int opticalLeft, int opticalTop, int opticalRight, int opticalBottom, 48 int outlineLeft, int outlineTop, int outlineRight, int outlineBottom, 49 float outlineRadius, int outlineAlpha, float decodeScale) { 50 opticalRect = new Rect(opticalLeft, opticalTop, opticalRight, opticalBottom); 51 opticalRect.scale(decodeScale); 52 53 outlineRect = scaleInsets(outlineLeft, outlineTop, 54 outlineRight, outlineBottom, decodeScale); 55 56 this.outlineRadius = outlineRadius * decodeScale; 57 this.outlineAlpha = outlineAlpha / 255.0f; 58 } 59 60 public final Rect opticalRect; 61 public final Rect outlineRect; 62 public final float outlineRadius; 63 public final float outlineAlpha; 64 65 /** 66 * Scales up the rect by the given scale, ceiling values, so actual outline Rect 67 * grows toward the inside. 68 */ scaleInsets(int left, int top, int right, int bottom, float scale)69 public static Rect scaleInsets(int left, int top, int right, int bottom, float scale) { 70 if (scale == 1.0f) { 71 return new Rect(left, top, right, bottom); 72 } 73 74 Rect result = new Rect(); 75 result.left = (int) Math.ceil(left * scale); 76 result.top = (int) Math.ceil(top * scale); 77 result.right = (int) Math.ceil(right * scale); 78 result.bottom = (int) Math.ceil(bottom * scale); 79 return result; 80 } 81 } 82 83 @UnsupportedAppUsage 84 private final Bitmap mBitmap; 85 86 /** 87 * Used by native code. This pointer is an instance of Res_png_9patch*. 88 * 89 * @hide for use by android.graphics, but must not be used outside the module. 90 */ 91 @UnsupportedAppUsage 92 public long mNativeChunk; 93 94 private Paint mPaint; 95 private String mSrcName; 96 97 /** 98 * Create a drawable projection from a bitmap to nine patches. 99 * 100 * @param bitmap The bitmap describing the patches. 101 * @param chunk The 9-patch data chunk describing how the underlying bitmap 102 * is split apart and drawn. 103 */ NinePatch(Bitmap bitmap, byte[] chunk)104 public NinePatch(Bitmap bitmap, byte[] chunk) { 105 this(bitmap, chunk, null); 106 } 107 108 /** 109 * Create a drawable projection from a bitmap to nine patches. 110 * 111 * @param bitmap The bitmap describing the patches. 112 * @param chunk The 9-patch data chunk describing how the underlying 113 * bitmap is split apart and drawn. 114 * @param srcName The name of the source for the bitmap. Might be null. 115 */ NinePatch(Bitmap bitmap, byte[] chunk, String srcName)116 public NinePatch(Bitmap bitmap, byte[] chunk, String srcName) { 117 mBitmap = bitmap; 118 mSrcName = srcName; 119 mNativeChunk = validateNinePatchChunk(chunk); 120 } 121 122 @Override finalize()123 protected void finalize() throws Throwable { 124 try { 125 if (mNativeChunk != 0) { 126 // only attempt to destroy correctly initialized chunks 127 nativeFinalize(mNativeChunk); 128 mNativeChunk = 0; 129 } 130 } finally { 131 super.finalize(); 132 } 133 } 134 135 /** 136 * Returns the name of this NinePatch object if one was specified 137 * when calling the constructor. 138 */ getName()139 public String getName() { 140 return mSrcName; 141 } 142 143 /** 144 * Returns the paint used to draw this NinePatch. The paint can be null. 145 * 146 * @see #setPaint(Paint) 147 * @see #draw(Canvas, Rect) 148 * @see #draw(Canvas, RectF) 149 */ getPaint()150 public Paint getPaint() { 151 return mPaint; 152 } 153 154 /** 155 * Sets the paint to use when drawing the NinePatch. 156 * 157 * @param p The paint that will be used to draw this NinePatch. 158 * 159 * @see #getPaint() 160 * @see #draw(Canvas, Rect) 161 * @see #draw(Canvas, RectF) 162 */ setPaint(Paint p)163 public void setPaint(Paint p) { 164 mPaint = p; 165 } 166 167 /** 168 * Returns the bitmap used to draw this NinePatch. 169 */ getBitmap()170 public Bitmap getBitmap() { 171 return mBitmap; 172 } 173 174 /** 175 * Draws the NinePatch. This method will use the paint returned by {@link #getPaint()}. 176 * 177 * @param canvas A container for the current matrix and clip used to draw the NinePatch. 178 * @param location Where to draw the NinePatch. 179 */ draw(Canvas canvas, RectF location)180 public void draw(Canvas canvas, RectF location) { 181 canvas.drawPatch(this, location, mPaint); 182 } 183 184 /** 185 * Draws the NinePatch. This method will use the paint returned by {@link #getPaint()}. 186 * 187 * @param canvas A container for the current matrix and clip used to draw the NinePatch. 188 * @param location Where to draw the NinePatch. 189 */ draw(Canvas canvas, Rect location)190 public void draw(Canvas canvas, Rect location) { 191 canvas.drawPatch(this, location, mPaint); 192 } 193 194 /** 195 * Draws the NinePatch. This method will ignore the paint returned 196 * by {@link #getPaint()} and use the specified paint instead. 197 * 198 * @param canvas A container for the current matrix and clip used to draw the NinePatch. 199 * @param location Where to draw the NinePatch. 200 * @param paint The Paint to draw through. 201 */ draw(Canvas canvas, Rect location, Paint paint)202 public void draw(Canvas canvas, Rect location, Paint paint) { 203 canvas.drawPatch(this, location, paint); 204 } 205 206 /** 207 * Return the underlying bitmap's density, as per 208 * {@link Bitmap#getDensity() Bitmap.getDensity()}. 209 */ getDensity()210 public int getDensity() { 211 return mBitmap.mDensity; 212 } 213 214 /** 215 * Returns the intrinsic width, in pixels, of this NinePatch. This is equivalent 216 * to querying the width of the underlying bitmap returned by {@link #getBitmap()}. 217 */ getWidth()218 public int getWidth() { 219 return mBitmap.getWidth(); 220 } 221 222 /** 223 * Returns the intrinsic height, in pixels, of this NinePatch. This is equivalent 224 * to querying the height of the underlying bitmap returned by {@link #getBitmap()}. 225 */ getHeight()226 public int getHeight() { 227 return mBitmap.getHeight(); 228 } 229 230 /** 231 * Indicates whether this NinePatch contains transparent or translucent pixels. 232 * This is equivalent to calling <code>getBitmap().hasAlpha()</code> on this 233 * NinePatch. 234 */ hasAlpha()235 public final boolean hasAlpha() { 236 return mBitmap.hasAlpha(); 237 } 238 239 /** 240 * Returns a {@link Region} representing the parts of the NinePatch that are 241 * completely transparent. 242 * 243 * @param bounds The location and size of the NinePatch. 244 * 245 * @return null if the NinePatch has no transparent region to 246 * report, else a {@link Region} holding the parts of the specified bounds 247 * that are transparent. 248 */ getTransparentRegion(Rect bounds)249 public final Region getTransparentRegion(Rect bounds) { 250 long r = nativeGetTransparentRegion(mBitmap.getNativeInstance(), 251 mNativeChunk, bounds); 252 return r != 0 ? new Region(r) : null; 253 } 254 255 /** 256 * Verifies that the specified byte array is a valid 9-patch data chunk. 257 * 258 * @param chunk A byte array representing a 9-patch data chunk. 259 * 260 * @return True if the specified byte array represents a 9-patch data chunk, 261 * false otherwise. 262 */ isNinePatchChunk(byte[] chunk)263 public native static boolean isNinePatchChunk(byte[] chunk); 264 265 /** 266 * Validates the 9-patch chunk and throws an exception if the chunk is invalid. 267 * If validation is successful, this method returns a native Res_png_9patch* 268 * object used by the renderers. 269 */ validateNinePatchChunk(byte[] chunk)270 private static native long validateNinePatchChunk(byte[] chunk); nativeFinalize(long chunk)271 private static native void nativeFinalize(long chunk); nativeGetTransparentRegion(long bitmapHandle, long chunk, Rect location)272 private static native long nativeGetTransparentRegion(long bitmapHandle, long chunk, 273 Rect location); 274 } 275