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