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