drawable-resource.jd revision dfe5c204403bc56c29bb36410574eab8b1950417
1page.title=Drawable Resources 2parent.title=Resource Types 3parent.link=available-resources.html 4@jd:body 5 6<div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>See also</h2> 9 <ol> 10 <li><a href="{@docRoot}guide/topics/graphics/2d-graphics.html">2D Graphics</a></li> 11 </ol> 12 </div> 13</div> 14 15<p>A drawable resource is a general concept for a graphic that you 16can retrieve with {@link android.content.res.Resources#getDrawable(int)} 17and draw on the screen. There are several different types of drawables:</p> 18<dl> 19 <dt><a href="#Bitmap">Bitmap File</a><dt> 20 <dd>A bitmap graphic file ({@code .png}, {@code .jpg}, or {@code .gif}). 21 Creates a {@link android.graphics.drawable.BitmapDrawable}.</dd> 22 <dt><a href="#NinePatch">Nine-Patch File</a></dt> 23 <dd>A PNG file with stretchable regions to allow image resizing based on content ({@code 24.9.png}). Creates a {@link android.graphics.drawable.NinePatchDrawable}.</dd> 25 <dt><a href="#LayerList">Layer List</a></dt> 26 <dd>A Drawable that manages an array of other Drawables. These are drawn in array order, so the 27element with the largest index is be drawn on top. Creates a {@link 28android.graphics.drawable.LayerDrawable}.</dd> 29 <dt><a href="#StateList">State List</a></dt> 30 <dd>An XML file that references different bitmap graphics 31 for different states (for example, to use a different image when a button is pressed). 32 Creates a {@link android.graphics.drawable.StateListDrawable}.</dd> 33 <dt><a href="#LevelList">Level List</a></dt> 34 <dd>An XML file that defines a Drawable that manages a number of alternate Drawables, each 35assigned a maximum numerical value. Creates a {@link 36android.graphics.drawable.LevelListDrawable}.</dd> 37 <dt><a href="#Transition">Transition Drawable</a></dt> 38 <dd>An XML file that defines a Drawable that can cross-fade between two drawable resources. 39Creates a {@link android.graphics.drawable.TransitionDrawable}.</dd> 40 <dt><a href="#Clip">Clip Drawable</a></dt> 41 <dd>An XML file that defines a drawable that clips another Drawable based on this Drawable's 42current level value. Creates a {@link android.graphics.drawable.ClipDrawable}.</dd> 43 <dt><a href="#Scale">Scale Drawable</a></dt> 44 <dd>An XML file that defines a drawable that changes the size of another Drawable based on its 45current level value. Creates a {@link android.graphics.drawable.ScaleDrawable}</dd> 46 <dt><a href="#Shape">Shape Drawable</a></dt> 47 <dd>An XML file that defines a geometric shape, including colors and gradients. 48 Creates a {@link android.graphics.drawable.ShapeDrawable}.</dd> 49</dl> 50 51<p>Also see the <a href="animation-resource.html">Animation Resource</a> document for how to 52create an {@link android.graphics.drawable.AnimationDrawable}.</p> 53 54 55 56 57<h2 id="Bitmap">Bitmap</h2> 58 59<p>A bitmap image. Android supports bitmap files in a three formats: 60{@code .png} (preferred), {@code .jpg} (acceptable), {@code .gif} (discouraged).</p> 61 62<p>You can reference a bitmap file directly, using the filename as the resource ID, or create an 63alias resource ID in XML.</p> 64 65<p class="note"><strong>Note:</strong> Bitmap files may be automatically optimized with lossless 66image compression by the <a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For 67example, a true-color PNG that does not require more than 256 colors may be converted to an 8-bit 68PNG with a color palette. This will result in an image of equal quality but which requires less 69memory. So be aware that the image binaries placed in this directory can change during the build. If 70you plan on reading an image as a bit stream in order to convert it to a bitmap, put your images in 71the <code>res/raw/</code> folder instead, where they will not be optimized.</p> 72 73 74<h3 id="BitmapFile">Bitmap File</h3> 75 76<p>A bitmap file is a {@code .png}, {@code .jpg}, or {@code .gif} file. Android creates a {@link 77android.graphics.drawable.Drawable} 78resource for any of these files when you save them in the {@code res/drawable/} directory.</p> 79 80<dl class="xml"> 81 82<dt>file location:</dt> 83<dd><code>res/drawable/<em>filename</em>.png</code> ({@code .png}, {@code .jpg}, or {@code .gif})<br/> 84The filename is used as the resource ID.</dd> 85 86<dt>compiled resource datatype:</dt> 87<dd>Resource pointer to a {@link android.graphics.drawable.BitmapDrawable}.</dd> 88 89<dt>resource reference:</dt> 90<dd> 91In Java: <code>R.drawable.<em>filename</em></code></li><br/> 92In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 93</dd> 94 95<dt>example:</dt> 96 97<dd>With an image saved at <code>res/drawable/myimage.png</code>, this layout XML applies 98the image to a View: 99<pre> 100<ImageView 101 android:layout_height="wrap_content" 102 android:layout_width="wrap_content" 103 android:src="@drawable/myimage" /> 104</pre> 105<p>The following application code retrieves the image as a {@link 106android.graphics.drawable.Drawable}:</p> 107<pre> 108Resources res = {@link android.content.Context#getResources()}; 109Drawable drawable = res.{@link android.content.res.Resources#getDrawable(int) getDrawable}(R.drawable.myimage); 110</pre> 111</dd> 112 113<dt>see also:</dt> 114<dd> 115<ul> 116 <li><a href="{@docRoot}guide/topics/graphics/2d-graphics.html">2D Graphics</a></li> 117 <li>{@link android.graphics.drawable.BitmapDrawable}</li> 118</ul> 119</dd> 120 121</dl> 122 123 124 125 126<h3 id="XmlBitmap">XML Bitmap</h3> 127 128<p>An XML bitmap is a resource defined in XML that points to a bitmap file. The effect is an alias for a 129raw bitmap file. The XML can specify additional properties for the bitmap such as dithering and tiling.</p> 130 131<p class="note"><strong>Note:</strong> You can use a {@code <bitmap>} element as a child of 132an {@code <item>} element. For 133example, when creating a <a href="#StateList">state list</a> or <a href="#LayerList">layer list</a>, 134you can exclude the {@code android:drawable} 135attribute from an {@code <item>} element and nest a {@code <bitmap>} inside it 136that defines the drawable item.</p> 137 138<dl class="xml"> 139 140<dt>file location:</dt> 141<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 142The filename is used as the resource ID.</dd> 143 144<dt>compiled resource datatype:</dt> 145<dd>Resource pointer to a {@link android.graphics.drawable.BitmapDrawable}.</dd> 146 147<dt>resource reference:</dt> 148<dd> 149In Java: <code>R.drawable.<em>filename</em></code></li><br/> 150In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 151</dd> 152 153<dt>syntax:</dt> 154<dd> 155<pre class="stx"> 156<?xml version="1.0" encoding="utf-8"?> 157<<a href="#bitmap-element">bitmap</a> 158 xmlns:android="http://schemas.android.com/apk/res/android" 159 android:src="@[package:]drawable/<em>drawable_resource</em>" 160 android:antialias=["true" | "false"] 161 android:dither=["true" | "false"] 162 android:filter=["true" | "false"] 163 android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" | 164 "fill_vertical" | "center_horizontal" | "fill_horizontal" | 165 "center" | "fill" | "clip_vertical" | "clip_horizontal"] 166 android:tileMode=["disabled" | "clamp" | "repeat" | "mirror"] /> 167</pre> 168</dd> 169 170 171<dt>elements:</dt> 172<dd> 173<dl class="tag-list"> 174 175 <dt id="bitmap-element"><code><bitmap></code></dt> 176 <dd>Defines the bitmap source and its properties. 177 <p class="caps">attributes:</p> 178 <dl class="atn-list"> 179 <dt><code>xmlns:android</code></dt> 180 <dd><em>String</em>. Defines the XML namespace, which must be 181 <code>"http://schemas.android.com/apk/res/android"</code>. This is required only if the 182<code><bitmap></code> is the root element—it is not needed when the 183<code><bitmap></code> is nested inside an <code><item></code>.</dd> 184 <dt><code>android:src</code></dt> 185 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 186resource.</dd> 187 <dt><code>android:antialias</code></dt> 188 <dd><em>Boolean</em>. Enables or disables antialiasing.</dd> 189 <dt><code>android:dither</code></dt> 190 <dd><em>Boolean</em>. Enables or disables dithering of the bitmap if the bitmap does not 191have the same pixel configuration as the screen (for instance: a ARGB 8888 bitmap with an RGB 565 192screen).</dd> 193 <dt><code>android:filter</code></dt> 194 <dd><em>Boolean</em>. Enables or disables bitmap filtering. Filtering is used when the 195bitmap is shrunk or stretched to smooth its apperance.</dd> 196 <dt><code>android:gravity</code></dt> 197 <dd><em>Keyword</em>. Defines the gravity for the bitmap. The gravity indicates where to 198position the drawable in its container if the bitmap is smaller than the container. 199 <p>Must be one or more (separated by '|') of the following constant values:</p> 200<table> 201<tr><th>Value</th><th>Description</th></tr> 202<tr><td><code>top</code></td> 203<td>Put the object at the top of its container, not changing its size.</td></tr> 204<tr><td><code>bottom</code></td> 205<td>Put the object at the bottom of its container, not changing its size. </td></tr> 206<tr><td><code>left</code></td> 207<td>Put the object at the left edge of its container, not changing its size. </td></tr> 208<tr><td><code>right</code></td> 209<td>Put the object at the right edge of its container, not changing its size. </td></tr> 210<tr><td><code>center_vertical</code></td> 211<td>Place object in the vertical center of its container, not changing its size. </td></tr> 212<tr><td><code>fill_vertical</code></td> 213<td>Grow the vertical size of the object if needed so it completely fills its container. </td></tr> 214<tr><td><code>center_horizontal</code></td> 215<td>Place object in the horizontal center of its container, not changing its size. </td></tr> 216<tr><td><code>fill_horizontal</code></td> 217<td>Grow the horizontal size of the object if needed so it completely fills its container. 218</td></tr> 219<tr><td><code>center</code></td> 220<td>Place the object in the center of its container in both the vertical and horizontal axis, not 221changing its size. </td></tr> 222<tr><td><code>fill</code></td> 223<td>Grow the horizontal and vertical size of the object if needed so it completely fills its 224container. This is the default.</td></tr> 225<tr><td><code>clip_vertical</code></td> 226<td>Additional option that can be set to have the top and/or bottom edges of the child clipped to 227its container's bounds. The clip is based on the vertical gravity: a top gravity clips the 228bottom edge, a bottom gravity clips the top edge, and neither clips both edges. 229</td></tr> 230<tr><td><code>clip_horizontal</code></td> 231<td>Additional option that can be set to have the left and/or right edges of the child clipped to 232its container's bounds. The clip is based on the horizontal gravity: a left gravity clips 233the right edge, a right gravity clips the left edge, and neither clips both edges. 234</td></tr> 235</table> 236 </dd> 237 <dt><code>android:tileMode</code></dt> 238 <dd><em>Keyword</em>. Defines the tile mode. When the tile mode is enabled, the bitmap is 239repeated. Gravity is ignored when the tile mode is enabled. 240 <p>Must be one of the following constant values:</p> 241<table> 242<tr><th>Value</th><th>Description</th></tr> 243<tr><td><code>disabled</code></td> 244<td>Do not tile the bitmap. This is the default value.</td></tr> 245<tr><td><code>clamp</code></td> 246<td>Replicates the edge color if the shader draws outside of its original bounds</td></tr> 247<tr><td><code>repeat</code></td> 248<td>Repeats the shader's image horizontally and vertically.</td></tr> 249<tr><td><code>mirror</code></td> 250<td>Repeats the shader's image horizontally and vertically, alternating mirror images so that 251adjacent images always seam.</td></tr> 252</table> 253 254 </dd> 255 </dl> 256 </dd> 257 258</dl> 259</dd> <!-- end elements and attributes --> 260 261<dt>example:</dt> 262<dd> 263<pre> 264<?xml version="1.0" encoding="utf-8"?> 265<bitmap xmlns:android="http://schemas.android.com/apk/res/android" 266 android:src="@drawable/icon" 267 android:tileMode="repeat" /> 268</pre> 269 270</dd> 271 272<dt>see also:</dt> 273<dd> 274<ul> 275 <li>{@link android.graphics.drawable.BitmapDrawable}</li> 276 <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AliasResources">Creating 277alias resources</a> 278</ul> 279</dd> 280 281</dl> 282 283 284 285 286 287 288<h2 id="NinePatch">Nine-Patch</h2> 289 290<p>A {@link android.graphics.NinePatch} is a PNG image in which you can define stretchable regions 291that Android scales when content within the View exceeds the normal image bounds. You 292typically assign this type of image as the background of a View that has at least one dimension set 293to {@code "wrap_content"}, and when the View grows to accomodate the content, the Nine-Patch image 294is also scaled to match the size of the View. An example use of a Nine-Patch image is the 295background used by Android's standard {@link android.widget.Button} widget, which must stretch to 296accommodate the text (or image) inside the button.</p> 297 298<p>Same as with a normal <a href="#Bitmap">bitmap</a>, you can reference a Nine-Patch file directly 299or from a resource defined by XML.</p> 300 301<p>For a complete discussion about how to create a Nine-Patch file with stretchable regions, 302see the <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a> 303document.</p> 304 305 306<h3 id="NinePatchFile">Nine-Patch File</h3> 307 308<dl class="xml"> 309 310<dt>file location:</dt> 311<dd><code>res/drawable/<em>filename</em>.9.png</code><br/> 312The filename is used as the resource ID.</dd> 313 314<dt>compiled resource datatype:</dt> 315<dd>Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable}.</dd> 316 317<dt>resource reference:</dt> 318 319<dd> 320In Java: <code>R.drawable.<em>filename</em></code><br/> 321In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 322</dd> 323 324<dt>example:</dt> 325 326<dd>With an image saved at <code>res/drawable/myninepatch.9.png</code>, this layout XML 327applies the Nine-Patch to a View: 328<pre> 329<Button 330 android:layout_height="wrap_content" 331 android:layout_width="wrap_content" 332 android:background="@drawable/myninepatch" /> 333</pre> 334</dd> 335 336<dt>see also:</dt> 337 338<dd> 339<ul> 340 <li><a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a></li> 341 <li>{@link android.graphics.drawable.NinePatchDrawable}</li> 342</ul> 343</dd> 344 345</dl> 346 347 348 349 350<h3 id="NinePatchXml">XML Nine-Patch</h3> 351 352<p>An XML Nine-Patch is a resource defined in XML that points to a Nine-Patch file. The XML can 353specify dithering for the image.</p> 354 355<dl class="xml"> 356 357<dt>file location:</dt> 358<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 359The filename is used as the resource ID.</dd> 360 361<dt>compiled resource datatype:</dt> 362<dd>Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable}.</dd> 363 364<dt>resource reference:</dt> 365 366<dd> 367In Java: <code>R.drawable.<em>filename</em></code><br/> 368In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 369</dd> 370 371 372<dt>syntax:</dt> 373 374<dd> 375<pre class="stx"> 376<?xml version="1.0" encoding="utf-8"?> 377<<a href="#bitmap-element">nine-patch</a> 378 xmlns:android="http://schemas.android.com/apk/res/android" 379 android:src="@[package:]drawable/<em>drawable_resource</em>" 380 android:dither=["true" | "false"] /> 381</pre> 382</dd> 383 384 385<dt>elements:</dt> 386 387<dd> 388<dl class="tag-list"> 389 390 <dt id="layerlist-element"><code><bitmap></code></dt> 391 <dd>Defines the bitmap source and its properties. 392 <p class="caps">attributes:</p> 393 <dl class="atn-list"> 394 <dt><code>xmlns:android</code></dt> 395 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 396 <code>"http://schemas.android.com/apk/res/android"</code>. 397 <dt><code>android:src</code></dt> 398 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a Nine-Patch 399file.</dd> 400 <dt><code>android:dither</code></dt> 401 <dd><em>Boolean</em>. Enables or disables dithering of the bitmap if the bitmap does not 402have the same pixel configuration as the screen (for instance: a ARGB 8888 bitmap with an RGB 565 403screen).</dd> 404 </dl> 405 </dd> 406</dl> 407</dd> 408 409 410<dt>example:</dt> 411 412<dd> 413<pre class="stx"> 414<?xml version="1.0" encoding="utf-8"?> 415<nine-patch xmlns:android="http://schemas.android.com/apk/res/android" 416 android:src="@drawable/myninepatch" 417 android:dither="false" /> 418</pre> 419</dd> 420</dl> 421 422 423 424 425 426 427<h2 id="LayerList">Layer List</h2> 428 429<p>A {@link android.graphics.drawable.LayerDrawable} is a drawable object 430that manages an array of other drawables. Each drawable in the list is drawn in the order of the 431list—the last drawable in the list is drawn on top.</p> 432 433<p>Each drawable is represented by an {@code <item>} element inside a single {@code 434<layer-list>} element.</p> 435 436<dl class="xml"> 437 438<dt>file location:</dt> 439<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 440The filename is used as the resource ID.</dd> 441 442<dt>compiled resource datatype:</dt> 443<dd>Resource pointer to a {@link android.graphics.drawable.LayerDrawable}.</dd> 444 445<dt>resource reference:</dt> 446 447<dd> 448In Java: <code>R.drawable.<em>filename</em></code><br/> 449In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 450</dd> 451 452<dt>syntax:</dt> 453 454<dd> 455<pre class="stx"> 456<?xml version="1.0" encoding="utf-8"?> 457<<a href="#layerlist-element">layer-list</a> 458 xmlns:android="http://schemas.android.com/apk/res/android" > 459 <<a href="#layerlist-item-element">item</a> 460 android:drawable="@[package:]drawable/<em>drawable_resource</em>" 461 android:id="@[+][<em>package</em>:]id/<i>resource_name</i>" 462 android:top="<em>dimension</em>" 463 android:right="<em>dimension</em>" 464 android:bottom="<em>dimension</em>" 465 android:left="<em>dimension</em>" /> 466</selector> 467</pre> 468</dd> 469 470<dt>elements:</dt> 471 472<dd> 473<dl class="tag-list"> 474 475 <dt id="layerlist-element"><code><layer-list></code></dt> 476 <dd><strong>Required.</strong> This must be the root element. Contains one or more {@code 477<item>} elements. 478 <p class="caps">attributes:</p> 479 <dl class="atn-list"> 480 <dt><code>xmlns:android</code></dt> 481 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 482 <code>"http://schemas.android.com/apk/res/android"</code>. 483 </dl> 484 </dd> 485 <dt id="layerlist-item-element"><code><item></code></dt> 486 <dd>Defines a drawable to place in the layer drawable, in a position defined by its attributes. 487Must be a child of a <code><selector></code> element. Accepts child {@code <bitmap>} 488elements. 489 <p class="caps">attributes:</p> 490 <dl class="atn-list"> 491 <dt><code>android:drawable</code></dt> 492 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 493resource.</dd> 494 <dt><code>android:id</code></dt> 495 <dd><em>Resource ID</em>. A unique resource ID for this drawable. To create a new resource 496ID for this item, use the form: 497<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 498ID. You can use this identifier to 499retrieve and modify the drawable with {@link android.view.View#findViewById(int) 500View.findViewById()} or {@link android.app.Activity#findViewById(int) Activity.findViewById()}.</dd> 501 <dt><code>android:top</code></dt> 502 <dd><em>Integer</em>. The top offset in pixels.</dd> 503 <dt><code>android:right</code></dt> 504 <dd><em>Integer</em>. The right offset in pixels.</dd> 505 <dt><code>android:bottom</code></dt> 506 <dd><em>Integer</em>. The bottom offset in pixels.</dd> 507 <dt><code>android:left</code></dt> 508 <dd><em>Integer</em>. The left offset in pixels.</dd> 509 </dl> 510 <p>All drawable items are scaled to fit the size of the containing View, by default. Thus, 511placing your images in a layer list at different positions might increase the size of the View and 512some images scale as appropriate. To avoid 513scaling items in the list, use a {@code <bitmap>} element inside the {@code 514<item>} element to specify the drawable and define the gravity to something that does not 515scale, such as {@code "center"}. For example, the following {@code <item>} defines an item 516that scales to fit its container View:</p> 517<pre> 518<item android:drawable="@drawable/image" /> 519</pre> 520 521<p>To avoid scaling, the following example uses a {@code <bitmap>} element with centered 522gravity:</p> 523<pre> 524<item> 525 <bitmap android:src="<b>@drawable/image</b>" 526 android:gravity="center" /> 527</item> 528</pre> 529 </dd> 530 531</dl> 532</dd> <!-- end elements and attributes --> 533 534<dt>example:</dt> 535 536<dd>XML file saved at <code>res/drawable/layers.xml</code>: 537<pre> 538<?xml version="1.0" encoding="utf-8"?> 539<layer-list xmlns:android="http://schemas.android.com/apk/res/android"> 540 <item> 541 <bitmap android:src="@drawable/android_red" 542 android:gravity="center" /> 543 </item> 544 <item android:top="10dp" android:left="10dp"> 545 <bitmap android:src="@drawable/android_green" 546 android:gravity="center" /> 547 </item> 548 <item android:top="20dp" android:left="20dp"> 549 <bitmap android:src="@drawable/android_blue" 550 android:gravity="center" /> 551 </item> 552</layer-list> 553</pre> 554<p>Notice that this example uses a nested {@code <bitmap>} element to define the drawable 555resource for each item with a "center" gravity. This ensures that none of the images are scaled to 556fit the size of the container, due to resizing caused by the offset images.</p> 557 558<p>This layout XML applies the drawable to a View:</p> 559<pre> 560<ImageView 561 android:layout_height="wrap_content" 562 android:layout_width="wrap_content" 563 android:src="@drawable/layers" /> 564</pre> 565 566<p>The result is a stack of increasingly offset images:</p> 567<img src="{@docRoot}images/resources/layers.png" alt="" /> 568</dd> <!-- end example --> 569 570<dt>see also:</dt> 571<dd> 572<ul> 573 <li>{@link android.graphics.drawable.LayerDrawable}</li> 574</ul> 575</dd> 576 577</dl> 578 579 580 581 582 583 584 585 586<h2 id="StateList">State List</h2> 587 588<p>A {@link android.graphics.drawable.StateListDrawable} is a drawable object defined in XML 589that uses a several different images to represent the same graphic, depending on the state of 590the object. For example, a {@link 591android.widget.Button} widget can exist in one of several different states (pressed, focused, 592or niether) and, using a state list drawable, you can provide a different background image for each 593state.</p> 594 595<p>You can describe the state list in an XML file. Each graphic is represented by an {@code 596<item>} element inside a single {@code <selector>} element. Each {@code <item>} 597uses various attributes to describe the state in which it should be used as the graphic for the 598drawable.</p> 599 600<p>During each state change, the state list is traversed top to bottom and the first item that 601matches the current state is used—the selection is <em>not</em> based on the "best 602match," but simply the first item that meets the minimum criteria of the state.</p> 603 604<dl class="xml"> 605 606<dt>file location:</dt> 607<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 608The filename is used as the resource ID.</dd> 609 610<dt>compiled resource datatype:</dt> 611<dd>Resource pointer to a {@link android.graphics.drawable.StateListDrawable}.</dd> 612 613<dt>resource reference:</dt> 614 615<dd> 616In Java: <code>R.drawable.<em>filename</em></code><br/> 617In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 618</dd> 619 620<dt>syntax:</dt> 621 622<dd> 623<pre class="stx"> 624<?xml version="1.0" encoding="utf-8"?> 625<<a href="#selector-element">selector</a> xmlns:android="http://schemas.android.com/apk/res/android" 626 android:constantSize=["true" | "false"] 627 android:dither=["true" | "false"] 628 android:variablePadding=["true" | "false"] > 629 <<a href="#item-element">item</a> 630 android:drawable="@[package:]drawable/<em>drawable_resource</em>" 631 android:state_pressed=["true" | "false"] 632 android:state_focused=["true" | "false"] 633 android:state_selected=["true" | "false"] 634 android:state_active=["true" | "false"] 635 android:state_checkable=["true" | "false"] 636 android:state_checked=["true" | "false"] 637 android:state_enabled=["true" | "false"] 638 android:state_window_focused=["true" | "false"] /> 639</selector> 640</pre> 641</dd> 642 643<dt>elements:</dt> 644 645<dd> 646<dl class="tag-list"> 647 648 <dt id="selector-element"><code><selector></code></dt> 649 <dd><strong>Required.</strong> This must be the root element. Contains one or more {@code 650<item>} elements. 651 <p class="caps">attributes:</p> 652 <dl class="atn-list"> 653 <dt><code>xmlns:android</code></dt> 654 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 655 <code>"http://schemas.android.com/apk/res/android"</code>. 656 <dt><code>android:constantSize</code></dt> 657 <dd><em>Boolean</em>. "true" if the drawable's reported internal size remains constant as the state 658changes (the size is the maximum of all of the states); "false" if the size varies based on 659the current state. Default is false.</dd> 660 <dt><code>android:dither</code></dt> 661 <dd><em>Boolean</em>. "true" to enable dithering of the bitmap if the bitmap does not have the same pixel 662configuration as the screen (for instance, an ARGB 8888 bitmap with an RGB 565 screen); "false" to 663disable dithering. Default is true.</dd> 664 <dt><code>android:variablePadding</code></dt> 665 <dd><em>Boolean</em>. "true" if the drawable's padding should change based on the current 666state that is selected; "false" if the padding should stay the same (based on the maximum 667padding of all the states). Enabling this feature requires that you deal with 668performing layout when the state changes, which is often not supported. Default is false.</dd> 669 </dl> 670 </dd> 671 <dt id="item-element"><code><item></code></dt> 672 <dd>Defines a drawable to use during certain states, as described by its attributes. Must be a 673child of a <code><selector></code> element. 674 <p class="caps">attributes:</p> 675 <dl class="atn-list"> 676 <dt><code>android:drawable</code></dt> 677 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable resource.</dd> 678 <dt><code>android:state_pressed</code></dt> 679 <dd><em>Boolean</em>. "true" if this item should be used when the object is pressed (such as when a button 680is touched/clicked); "false" if this item should be used in the default, non-pressed state.</dd> 681 <dt><code>android:state_focused</code></dt> 682 <dd><em>Boolean</em>. "true" if this item should be used when the object is focused (such as when a button 683is highlighted using the trackball/d-pad); "false" if this item should be used in the default, 684non-focused state.</dd> 685 <dt><code>android:state_selected</code></dt> 686 <dd><em>Boolean</em>. "true" if this item should be used when the object is selected (such as when a 687tab is opened); "false" if this item should be used when the object is not selected.</dd> 688 <dt><code>android:state_checkable</code></dt> 689 <dd><em>Boolean</em>. "true" if this item should be used when the object is checkable; "false" if this 690item should be used when the object is not checkable. (Only useful if the object can 691transition between a checkable and non-checkable widget.)</dd> 692 <dt><code>android:state_checked</code></dt> 693 <dd><em>Boolean</em>. "true" if this item should be used when the object is checked; "false" if it 694should be used when the object is un-checked.</dd> 695 <dt><code>android:state_enabled</code></dt> 696 <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled (capable of 697receiving touch/click events); "false" if it should be used when the object is disabled.</dd> 698 <dt><code>android:state_window_focused</code></dt> 699 <dd><em>Boolean</em>. "true" if this item should be used when the application window has focus (the 700application is in the foreground), "false" if this item should be used when the application 701window does not have focus (for example, if the notification shade is pulled down or a dialog appears).</dd> 702 </dl> 703 <p class="note"><strong>Note:</strong> Remember that Android applies the first item in the state list that 704matches the current state of the object. So, if the first item in the list contains 705none of the state attributes above, then it is applied every time, which is why your 706default value should always be last (as demonstrated in the following example).</p> 707 </dd> 708 709</dl> 710</dd> <!-- end elements and attributes --> 711 712<dt>example:</dt> 713 714<dd>XML file saved at <code>res/drawable/button.xml</code>: 715<pre> 716<?xml version="1.0" encoding="utf-8"?> 717<selector xmlns:android="http://schemas.android.com/apk/res/android"> 718 <item android:state_pressed="true" 719 android:drawable="@drawable/button_pressed" /> <!-- pressed --> 720 <item android:state_focused="true" 721 android:drawable="@drawable/button_focused" /> <!-- focused --> 722 <item android:drawable="@drawable/button_normal" /> <!-- default --> 723</selector> 724</pre> 725 726<p>This layout XML applies the drawable to a View:</p> 727<pre> 728<ImageView 729 android:layout_height="wrap_content" 730 android:layout_width="wrap_content" 731 android:src="@drawable/button" /> 732</pre> 733</dd> <!-- end example --> 734 735<dt>see also:</dt> 736<dd> 737<ul> 738 <li>{@link android.graphics.drawable.StateListDrawable}</li> 739</ul> 740</dd> 741 742</dl> 743 744 745 746 747 748 749 750 751<h2 id="LevelList">Level List</h2> 752 753<p>A Drawable that manages a number of alternate Drawables, each assigned a maximum numerical 754value. Setting the level value of the drawable with {@link 755android.graphics.drawable.Drawable#setLevel(int) setLevel()} loads the drawable resource in the 756level list that has a {@code android:maxLevel} value greater than or equal to the value 757passed to the method.</p> 758 759<dl class="xml"> 760 761<dt>file location:</dt> 762<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 763The filename is used as the resource ID.</dd> 764 765<dt>compiled resource datatype:</dt> 766<dd>Resource pointer to a {@link android.graphics.drawable.LevelListDrawable}.</dd> 767 768<dt>resource reference:</dt> 769 770<dd> 771In Java: <code>R.drawable.<em>filename</em></code><br/> 772In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 773</dd> 774 775<dt>syntax:</dt> 776 777<dd> 778<pre class="stx"> 779<?xml version="1.0" encoding="utf-8"?> 780<<a href="#levellist-element">level-list</a> 781 xmlns:android="http://schemas.android.com/apk/res/android" > 782 <<a href="#levellist-item-element">item</a> 783 android:drawable="@drawable/<i>drawable_resource</i>" 784 android:maxLevel="<i>integer</i>" 785 android:minLevel="<i>integer</i>" /> 786</level-list> 787</pre> 788</dd> 789 790<dt>elements:</dt> 791 792<dd> 793<dl class="tag-list"> 794 795 <dt id="levellist-element"><code><level-list></code></dt> 796 <dd>This must be the root element. Contains one or more {@code <item>} elements. 797 <p class="caps">attributes:</p> 798 <dl class="atn-list"> 799 <dt><code>xmlns:android</code></dt> 800 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 801 <code>"http://schemas.android.com/apk/res/android"</code>. 802 </dl> 803 </dd> 804 805 <dt id="levellist-item-element"><code><item></code></dt> 806 <dd>Defines a drawable to use at a certain level. 807 <p class="caps">attributes:</p> 808 <dl class="atn-list"> 809 <dt><code>android:drawable</code></dt> 810 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 811resource to be inset.</dd> 812 <dt><code>android:maxLevel</code></dt> 813 <dd><em>Integer</em>. The maximum level allowed for this item.</dd> 814 <dt><code>android:minLevel</code></dt> 815 <dd><em>Integer</em>. The minimum level allowed for this item.</dd> 816 </dl> 817 </dd> 818</dl> 819 820</dd> 821 822<dt>example:</dt> 823 824<dd> 825 826<pre> 827<?xml version="1.0" encoding="utf-8"?> 828<level-list xmlns:android="http://schemas.android.com/apk/res/android" > 829 <item 830 android:drawable="@drawable/status_off" 831 android:maxLevel="0" /> 832 <item 833 android:drawable="@drawable/status_on" 834 android:maxLevel="1" /> 835</level-list> 836</pre> 837<p>Once this is applied to a {@link android.view.View}, the level can be changed with {@link 838android.graphics.drawable.Drawable#setLevel(int) setLevel()} or {@link 839android.widget.ImageView#setImageLevel(int) setImageLevel()}.</p> 840 841</dd> 842 843<dt>see also:</dt> 844 845<dd> 846<ul> 847 <li>{@link android.graphics.drawable.LevelListDrawable}</li> 848</ul> 849</dd> 850 851</dl> 852 853 854 855 856 857 858<h2 id="Transition">Transition Drawable</h2> 859 860<p>A {@link android.graphics.drawable.TransitionDrawable} is a drawable object 861that can cross-fade between the two drawable resources.</p> 862 863<p>Each drawable is represented by an {@code <item>} element inside a single {@code 864<transition>} element. No more than two items are supported. To transition forward, call 865{@link android.graphics.drawable.TransitionDrawable#startTransition(int) startTransition()}. To 866transition backward, call {@link android.graphics.drawable.TransitionDrawable#reverseTransition(int) 867reverseTransition()}.</p> 868 869<dl class="xml"> 870 871<dt>file location:</dt> 872<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 873The filename is used as the resource ID.</dd> 874 875<dt>compiled resource datatype:</dt> 876<dd>Resource pointer to a {@link android.graphics.drawable.TransitionDrawable}.</dd> 877 878<dt>resource reference:</dt> 879 880<dd> 881In Java: <code>R.drawable.<em>filename</em></code><br/> 882In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 883</dd> 884 885<dt>syntax:</dt> 886 887<dd> 888<pre class="stx"> 889<?xml version="1.0" encoding="utf-8"?> 890<<a href="#transition-element">layer-list</a> 891xmlns:android="http://schemas.android.com/apk/res/android" > 892 <<a href="#transition-item-element">item</a> 893 android:drawable="@[package:]drawable/<em>drawable_resource</em>" 894 android:id="@[+][<em>package</em>:]id/<i>resource_name</i>" 895 android:top="<em>dimension</em>" 896 android:right="<em>dimension</em>" 897 android:bottom="<em>dimension</em>" 898 android:left="<em>dimension</em>" /> 899</selector> 900</pre> 901</dd> 902 903<dt>elements:</dt> 904 905<dd> 906<dl class="tag-list"> 907 908 <dt id="transition-element"><code><transition></code></dt> 909 <dd><strong>Required.</strong> This must be the root element. Contains one or more {@code 910<item>} elements. 911 <p class="caps">attributes:</p> 912 <dl class="atn-list"> 913 <dt><code>xmlns:android</code></dt> 914 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 915 <code>"http://schemas.android.com/apk/res/android"</code>. 916 </dl> 917 </dd> 918 <dt id="transition-item-element"><code><item></code></dt> 919 <dd>Defines a drawable to place in the layer drawable, in a position defined by its attributes. 920Must be a child of a <code><selector></code> element. Accepts child {@code <bitmap>} 921elements. 922 <p class="caps">attributes:</p> 923 <dl class="atn-list"> 924 <dt><code>android:drawable</code></dt> 925 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 926resource.</dd> 927 <dt><code>android:id</code></dt> 928 <dd><em>Resource ID</em>. A unique resource ID for this drawable. To create a new resource 929ID for this item, use the form: 930<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 931ID. You can use this identifier to 932retrieve and modify the drawable with {@link android.view.View#findViewById(int) 933View.findViewById()} or {@link android.app.Activity#findViewById(int) Activity.findViewById()}.</dd> 934 <dt><code>android:top</code></dt> 935 <dd><em>Integer</em>. The top offset in pixels.</dd> 936 <dt><code>android:right</code></dt> 937 <dd><em>Integer</em>. The right offset in pixels.</dd> 938 <dt><code>android:bottom</code></dt> 939 <dd><em>Integer</em>. The bottom offset in pixels.</dd> 940 <dt><code>android:left</code></dt> 941 <dd><em>Integer</em>. The left offset in pixels.</dd> 942 </dl> 943 </dd> 944 945</dl> 946</dd> <!-- end elements and attributes --> 947 948<dt>example:</dt> 949 950<dd>XML file saved at <code>res/drawable/transition.xml</code>: 951<pre> 952<?xml version="1.0" encoding="utf-8"?> 953<transition xmlns:android="http://schemas.android.com/apk/res/android"> 954 <item android:drawable="@drawable/on" /> 955 <item android:drawable="@drawable/off" /> 956</layer-list> 957</pre> 958 959<p>This layout XML applies the drawable to a View:</p> 960<pre> 961<ImageButton 962 android:id="@+id/button" 963 android:layout_height="wrap_content" 964 android:layout_width="wrap_content" 965 android:src="@drawable/transition" /> 966</pre> 967 968<p>And the following code performs a 500ms transition from the first item to the second:</p> 969<pre> 970ImageButton button = (ImageButton) findViewById(R.id.button); 971TransitionDrawable drawable = (TransitionDrawable) button.getDrawable(); 972drawable.startTransition(500); 973</pre> 974 975</dd> <!-- end example --> 976 977<dt>see also:</dt> 978 979<dd> 980<ul> 981 <li>{@link android.graphics.drawable.TransitionDrawable}</li> 982</ul> 983</dd> 984 985</dl> 986 987 988 989 990 991 992 993 994<h2 id="Inset">Inset Drawable</h2> 995 996<p>A drawable defined in XML that insets another drawable by a specified distance. This is used when 997a View needs a background that is smaller than the View's actual bounds.</p> 998 999<dl class="xml"> 1000 1001<dt>file location:</dt> 1002<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1003The filename is used as the resource ID.</dd> 1004 1005<dt>compiled resource datatype:</dt> 1006<dd>Resource pointer to a {@link android.graphics.drawable.InsetDrawable}.</dd> 1007 1008<dt>resource reference:</dt> 1009 1010<dd> 1011In Java: <code>R.drawable.<em>filename</em></code><br/> 1012In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1013</dd> 1014 1015<dt>syntax:</dt> 1016 1017<dd> 1018<pre class="stx"> 1019<?xml version="1.0" encoding="utf-8"?> 1020<<a href="#inset-element">inset</a> 1021 xmlns:android="http://schemas.android.com/apk/res/android" 1022 android:drawable="@drawable/<i>drawable_resource</i>" 1023 android:insetTop="<i>dimension</i>" 1024 android:insetRight="<i>dimension</i>" 1025 android:insetBottom="<i>dimension</i>" 1026 android:insetLeft="<i>dimension</i>" /> 1027</pre> 1028</dd> 1029 1030<dt>elements:</dt> 1031 1032<dd> 1033<dl class="tag-list"> 1034 1035 <dt id="inset-element"><code><inset></code></dt> 1036 <dd>Defines the inset drawable. This must be the root element. 1037 <p class="caps">attributes:</p> 1038 <dl class="atn-list"> 1039 <dt><code>xmlns:android</code></dt> 1040 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1041 <code>"http://schemas.android.com/apk/res/android"</code>. 1042 <dt><code>android:drawable</code></dt> 1043 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 1044resource to be inset.</dd> 1045 <dt><code>android:insetTop</code></dt> 1046 <dd><em>Dimension</em>. The top inset, as a dimension value or <a 1047href="more-resources.html#Dimension">dimension resource</a></dd> 1048 <dt><code>android:insetRight</code></dt> 1049 <dd><em>Dimension</em>. The right inset, as a dimension value or <a 1050href="more-resources.html#Dimension">dimension resource</a></dd> 1051 <dt><code>android:insetBottom</code></dt> 1052 <dd><em>Dimension</em>. The bottom inset, as a dimension value or <a 1053href="more-resources.html#Dimension">dimension resource</a></dd> 1054 <dt><code>android:insetLeft</code></dt> 1055 <dd><em>Dimension</em>. The left inset, as a dimension value or <a 1056href="more-resources.html#Dimension">dimension resource</a></dd> 1057 </dl> 1058 </dd> 1059</dl> 1060 1061</dd> 1062 1063<dt>example:</dt> 1064 1065<dd> 1066<pre> 1067<?xml version="1.0" encoding="utf-8"?> 1068<inset xmlns:android="http://schemas.android.com/apk/res/android" 1069 android:drawable="@drawable/background" 1070 android:insetTop="10dp" 1071 android:insetLeft="10dp" /> 1072</pre> 1073</dd> 1074 1075<dt>see also:</dt> 1076 1077<dd> 1078<ul> 1079 <li>{@link android.graphics.drawable.InsetDrawable}</li> 1080</ul> 1081</dd> 1082 1083</dl> 1084 1085 1086 1087 1088 1089 1090 1091 1092<h2 id="Clip">Clip Drawable</h2> 1093 1094<p>A drawable defined in XML that clips another drawable based on this Drawable's current level. You 1095can control how much the child drawable gets clipped in width and height based on the level, as well 1096as a gravity to control where it is placed in its overall container. Most often used to implement 1097things like progress bars.</p> 1098 1099<dl class="xml"> 1100 1101<dt>file location:</dt> 1102<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1103The filename is used as the resource ID.</dd> 1104 1105<dt>compiled resource datatype:</dt> 1106<dd>Resource pointer to a {@link android.graphics.drawable.ClipDrawable}.</dd> 1107 1108<dt>resource reference:</dt> 1109 1110<dd> 1111In Java: <code>R.drawable.<em>filename</em></code><br/> 1112In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1113</dd> 1114 1115<dt>syntax:</dt> 1116 1117<dd> 1118<pre class="stx"> 1119<?xml version="1.0" encoding="utf-8"?> 1120<<a href="#clip-element">clip</a> 1121 xmlns:android="http://schemas.android.com/apk/res/android" 1122 android:drawable="@drawable/<i>drawable_resource</i>" 1123 android:clipOrientation=["horizontal" | "vertical"] 1124 android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" | 1125 "fill_vertical" | "center_horizontal" | "fill_horizontal" | 1126 "center" | "fill" | "clip_vertical" | "clip_horizontal"] /> 1127</pre> 1128</dd> 1129 1130<dt>elements:</dt> 1131 1132<dd> 1133<dl class="tag-list"> 1134 1135 <dt id="clip-element"><code><clip></code></dt> 1136 <dd>Defines the clip drawable. This must be the root element. 1137 <p class="caps">attributes:</p> 1138 <dl class="atn-list"> 1139 <dt><code>xmlns:android</code></dt> 1140 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1141 <code>"http://schemas.android.com/apk/res/android"</code>. 1142 <dt><code>android:drawable</code></dt> 1143 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 1144resource to be clipped.</dd> 1145 <dt><code>android:clipOrientation</code></dt> 1146 <dd><em>Keyword</em>. The orientation for the clip. 1147 <p>Must be one of the following constant values:</p> 1148<table> 1149<tr><th>Value</th><th>Description</th></tr> 1150<tr><td><code>horizontal</code></td> 1151<td>Clip the drawable horizontally.</td></tr> 1152<tr><td><code>vertical</code></td> 1153<td>Clip the drawable vertically.</td></tr> 1154</table> 1155 </dd> 1156 <dt><code>android:gravity</code></dt> 1157 <dd><em>Keyword</em>. Specifies where to clip within the drawable. 1158 <p>Must be one or more (separated by '|') of the following constant values:</p> 1159<table> 1160<tr><th>Value</th><th>Description</th></tr> 1161<tr><td><code>top</code></td> 1162<td>Put the object at the top of its container, not changing its size. When {@code 1163clipOrientation} is {@code "vertical"}, clipping occurs at the bottom of the drawable.</td></tr> 1164<tr><td><code>bottom</code></td> 1165<td>Put the object at the bottom of its container, not changing its size. When {@code 1166clipOrientation} is {@code "vertical"}, clipping occurs at the top of the drawable.</td></tr> 1167<tr><td><code>left</code></td> 1168<td>Put the object at the left edge of its container, not changing its size. This is the 1169default. When {@code clipOrientation} is {@code "horizontal"}, clipping occurs at the right side of 1170the drawable. This is the default.</td></tr> 1171<tr><td><code>right</code></td> 1172<td>Put the object at the right edge of its container, not changing its size. When {@code 1173clipOrientation} is {@code "horizontal"}, clipping occurs at the left side of 1174the drawable.</td></tr> 1175<tr><td><code>center_vertical</code></td> 1176<td>Place object in the vertical center of its container, not changing its size. Clipping behaves 1177the same as when gravity is {@code "center"}.</td></tr> 1178<tr><td><code>fill_vertical</code></td> 1179<td>Grow the vertical size of the object if needed so it completely fills its container. When {@code 1180clipOrientation} is {@code "vertical"}, no clipping occurs because the drawable fills the 1181vertical space (unless the drawable level is 0, in which case it's not visible).</td></tr> 1182<tr><td><code>center_horizontal</code></td> 1183<td>Place object in the horizontal center of its container, not changing its size. 1184Clipping behaves the same as when gravity is {@code "center"}.</td></tr> 1185<tr><td><code>fill_horizontal</code></td> 1186<td>Grow the horizontal size of the object if needed so it completely fills its container. When 1187{@code clipOrientation} is {@code "horizontal"}, no clipping occurs because the drawable fills the 1188horizontal space (unless the drawable level is 0, in which case it's not visible). 1189</td></tr> 1190<tr><td><code>center</code></td> 1191<td>Place the object in the center of its container in both the vertical and horizontal axis, not 1192changing its size. When {@code 1193clipOrientation} is {@code "horizontal"}, clipping occurs on the left and right. When {@code 1194clipOrientation} is {@code "vertical"}, clipping occurs on the top and bottom.</td></tr> 1195<tr><td><code>fill</code></td> 1196<td>Grow the horizontal and vertical size of the object if needed so it completely fills its 1197container. No clipping occurs because the drawable fills the 1198horizontal and vertical space (unless the drawable level is 0, in which case it's not 1199visible).</td></tr> 1200<tr><td><code>clip_vertical</code></td> 1201<td>Additional option that can be set to have the top and/or bottom edges of the child clipped to 1202its container's bounds. The clip is based on the vertical gravity: a top gravity clips the 1203bottom edge, a bottom gravity clips the top edge, and neither clips both edges. 1204</td></tr> 1205<tr><td><code>clip_horizontal</code></td> 1206<td>Additional option that can be set to have the left and/or right edges of the child clipped to 1207its container's bounds. The clip is based on the horizontal gravity: a left gravity clips 1208the right edge, a right gravity clips the left edge, and neither clips both edges. 1209</td></tr> 1210</table></dd> 1211 </dl> 1212 </dd> 1213</dl> 1214 1215</dd> <!-- end elements and attributes --> 1216 1217<dt>example:</dt> 1218 1219<dd>XML file saved at <code>res/drawable/clip.xml</code>: 1220<pre> 1221<?xml version="1.0" encoding="utf-8"?> 1222<shape xmlns:android="http://schemas.android.com/apk/res/android" 1223 android:drawable="@drawable/android" 1224 android:clipOrientation="horizontal" 1225 android:gravity="left" /> 1226</shape> 1227</pre> 1228 <p>The following layout XML applies the clip drawable to a View:</p> 1229<pre> 1230<ImageView 1231 android:id="@+id/image" 1232 android:background="@drawable/clip" 1233 android:layout_height="wrap_content" 1234 android:layout_width="wrap_content" /> 1235</pre> 1236 1237 <p>The following code gets the drawable and increases the amount of clipping in order to 1238progressively reveal the image:</p> 1239<pre> 1240ImageView imageview = (ImageView) findViewById(R.id.image); 1241ClipDrawable drawable = (ClipDrawable) imageview.getDrawable(); 1242drawable.setLevel(drawable.getLevel() + 1000); 1243</pre> 1244 1245<p>Increasing the level reduces the amount of clipping and slowly reveals the image. Here it is 1246at a level of 7000:</p> 1247<img src="{@docRoot}images/resources/clip.png" alt="" /> 1248 1249<p class="note"><strong>Note:</strong> The default level is 0, which is fully clipped so the image 1250is not visible. When the level is 10,000, the image is not clipped and completely visible.</p> 1251</dd> <!-- end example --> 1252 1253<dt>see also:</dt> 1254 1255<dd> 1256<ul> 1257 <li>{@link android.graphics.drawable.ClipDrawable}</li> 1258</ul> 1259</dd> 1260 1261</dl> 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271<h2 id="Scale">Scale Drawable</h2> 1272 1273<p>A drawable defined in XML that changes the size of another drawable based on its current 1274level.</p> 1275 1276<dl class="xml"> 1277 1278<dt>file location:</dt> 1279<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1280The filename is used as the resource ID.</dd> 1281 1282<dt>compiled resource datatype:</dt> 1283<dd>Resource pointer to a {@link android.graphics.drawable.ScaleDrawable}.</dd> 1284 1285<dt>resource reference:</dt> 1286 1287<dd> 1288In Java: <code>R.drawable.<em>filename</em></code><br/> 1289In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1290</dd> 1291 1292<dt>syntax:</dt> 1293 1294<dd> 1295<pre class="stx"> 1296<?xml version="1.0" encoding="utf-8"?> 1297<<a href="#scale-element">scale</a> 1298 xmlns:android="http://schemas.android.com/apk/res/android" 1299 android:drawable="@drawable/<i>drawable_resource</i>" 1300 android:scaleGravity=["top" | "bottom" | "left" | "right" | "center_vertical" | 1301 "fill_vertical" | "center_horizontal" | "fill_horizontal" | 1302 "center" | "fill" | "clip_vertical" | "clip_horizontal"] 1303 android:scaleHeight="<i>percentage</i>" 1304 android:scaleWidth="<i>percentage</i>" /> 1305</pre> 1306</dd> 1307 1308<dt>elements:</dt> 1309 1310<dd> 1311<dl class="tag-list"> 1312 1313 <dt id="scale-element"><code><scale></code></dt> 1314 <dd>Defines the scale drawable. This must be the root element. 1315 <p class="caps">attributes:</p> 1316 <dl class="atn-list"> 1317 <dt><code>xmlns:android</code></dt> 1318 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1319 <code>"http://schemas.android.com/apk/res/android"</code>. 1320 <dt><code>android:drawable</code></dt> 1321 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 1322resource.</dd> 1323 <dt><code>android:scaleGravity</code></dt> 1324 <dd><em>Keyword</em>. Specifies the gravity position after scaling. 1325 <p>Must be one or more (separated by '|') of the following constant values:</p> 1326<table> 1327<tr><th>Value</th><th>Description</th></tr> 1328<tr><td><code>top</code></td> 1329<td>Put the object at the top of its container, not changing its size.</td></tr> 1330<tr><td><code>bottom</code></td> 1331<td>Put the object at the bottom of its container, not changing its size. </td></tr> 1332<tr><td><code>left</code></td> 1333<td>Put the object at the left edge of its container, not changing its size. This is the 1334default.</td></tr> 1335<tr><td><code>right</code></td> 1336<td>Put the object at the right edge of its container, not changing its size. </td></tr> 1337<tr><td><code>center_vertical</code></td> 1338<td>Place object in the vertical center of its container, not changing its size. </td></tr> 1339<tr><td><code>fill_vertical</code></td> 1340<td>Grow the vertical size of the object if needed so it completely fills its container. </td></tr> 1341<tr><td><code>center_horizontal</code></td> 1342<td>Place object in the horizontal center of its container, not changing its size. </td></tr> 1343<tr><td><code>fill_horizontal</code></td> 1344<td>Grow the horizontal size of the object if needed so it completely fills its container. 1345</td></tr> 1346<tr><td><code>center</code></td> 1347<td>Place the object in the center of its container in both the vertical and horizontal axis, not 1348changing its size. </td></tr> 1349<tr><td><code>fill</code></td> 1350<td>Grow the horizontal and vertical size of the object if needed so it completely fills its 1351container. </td></tr> 1352<tr><td><code>clip_vertical</code></td> 1353<td>Additional option that can be set to have the top and/or bottom edges of the child clipped to 1354its container's bounds. The clip is based on the vertical gravity: a top gravity clips the 1355bottom edge, a bottom gravity clips the top edge, and neither clips both edges. 1356</td></tr> 1357<tr><td><code>clip_horizontal</code></td> 1358<td>Additional option that can be set to have the left and/or right edges of the child clipped to 1359its container's bounds. The clip is based on the horizontal gravity: a left gravity clips 1360the right edge, a right gravity clips the left edge, and neither clips both edges. 1361</td></tr> 1362</table></dd> 1363 <dt><code>android:scaleHeight</code></dt> 1364 <dd><em>Percentage</em>. The scale height, expressed as a percentage of the drawable's 1365bound. The value's format is XX%. For instance: 100%, 12.5%, etc.</dd> 1366 <dt><code>android:scaleWidth</code></dt> 1367 <dd><em>Percentage</em>. The scale width, expressed as a percentage of the drawable's 1368bound. The value's format is XX%. For instance: 100%, 12.5%, etc.</dd> 1369 </dl> 1370 </dd> 1371</dl> 1372 1373</dd> 1374 1375<dt>example:</dt> 1376 1377<dd> 1378<pre class="stx"> 1379<?xml version="1.0" encoding="utf-8"?> 1380<scale xmlns:android="http://schemas.android.com/apk/res/android" 1381 android:drawable="@drawable/logo" 1382 android:scaleGravity="center_vertical|center_horizontal" 1383 android:scaleHeight="80%" 1384 android:scaleWidth="80%" /> 1385</pre> 1386</dd> 1387 1388<dt>see also:</dt> 1389<dd> 1390<ul> 1391 <li>{@link android.graphics.drawable.ScaleDrawable}</li> 1392</ul> 1393</dd> 1394 1395</dl> 1396 1397 1398 1399 1400 1401 1402 1403<h2 id="Shape">Shape Drawable</h2> 1404 1405<p>This is a generic shape defined in XML.</p> 1406 1407<dl class="xml"> 1408 1409<dt>file location:</dt> 1410<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1411The filename is used as the resource ID.</dd> 1412 1413<dt>compiled resource datatype:</dt> 1414<dd>Resource pointer to a {@link android.graphics.drawable.ShapeDrawable}.</dd> 1415 1416<dt>resource reference:</dt> 1417 1418<dd> 1419In Java: <code>R.drawable.<em>filename</em></code><br/> 1420In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1421</dd> 1422 1423<dt>syntax:</dt> 1424 1425<dd> 1426<pre class="stx"> 1427<?xml version="1.0" encoding="utf-8"?> 1428<<a href="#shape-element">shape</a> 1429 xmlns:android="http://schemas.android.com/apk/res/android" 1430 android:shape=["rectangle" | "oval" | "line" | "ring"] > 1431 <<a href="#corners-element">corners</a> 1432 android:radius="<em>integer</em>" 1433 android:topLeftRadius="<em>integer</em>" 1434 android:topRightRadius="<em>integer</em>" 1435 android:bottomLeftRadius="<em>integer</em>" 1436 android:bottomRightRadius="<em>integer</em>" /> 1437 <<a href="#gradient-element">gradient</a> 1438 android:angle="<em>integer</em>" 1439 android:centerX="<em>integer</em>" 1440 android:centerY="<em>integer</em>" 1441 android:centerColor="<em>integer</em>" 1442 android:endColor="<em>color</em>" 1443 android:gradientRadius="<em>integer</em>" 1444 android:startColor="<em>color</em>" 1445 android:type=["linear" | "radial" | "sweep"] 1446 android:usesLevel=["true" | "false"] /> 1447 <<a href="#padding-element">padding</a> 1448 android:left="<em>integer</em>" 1449 android:top="<em>integer</em>" 1450 android:right="<em>integer</em>" 1451 android:bottom="<em>integer</em>" /> 1452 <<a href="#size-element">size</a> 1453 android:width="<em>integer</em>" 1454 android:color="<em>color</em>" 1455 android:dashWidth="<em>integer</em>" 1456 android:dashGap="<em>integer</em>" /> 1457 <<a href="#solid-element">solid</a> 1458 android:color="<em>color</em>" /> 1459 <<a href="#stroke-element">stroke</a> 1460 android:width="<em>integer</em>" 1461 android:color="<em>color</em>" 1462 android:dashWidth="<em>integer</em>" 1463 android:dashGap="<em>integer</em>" /> 1464</shape> 1465</pre> 1466</dd> 1467 1468<dt>elements:</dt> 1469 1470<dd> 1471<dl class="tag-list"> 1472 1473 <dt id="shape-element"><code><shape></code></dt> 1474 <dd>The shape drawable. This must be the root element. 1475 <p class="caps">attributes:</p> 1476 <dl class="atn-list"> 1477 <dt><code>xmlns:android</code></dt> 1478 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1479 <code>"http://schemas.android.com/apk/res/android"</code>. 1480 <dt><code>android:shape</code></dt> 1481 <dd><em>Keyword</em>. Defines the type of shape. Valid values are: 1482 <table> 1483 <tr><th>Value</th><th>Desciption</th></tr> 1484 <tr><td>{@code "rectangle"}</td> 1485 <td>A rectangle that fills the containing View. This is the default shape.</td></tr> 1486 <tr><td>{@code "oval"}</td> 1487 <td>An oval shape that fits the dimensions of the containing View.</td></tr> 1488 <tr><td>{@code "line"}</td> 1489 <td>A horizontal line that spans the width of the containing View. This 1490 shape requires the {@code <stroke>} element to define the width of the 1491 line.</td></tr> 1492 <tr><td>{@code "ring"}</td> 1493 <td>A ring shape.</td></tr> 1494 </table> 1495 </dd> 1496 </dl> 1497 <p>The following attributes are used only when {@code android:shape="ring"}:</p> 1498 <dl class="atn-list"> 1499 <dt><code>android:innerRadius</code></dt> 1500 <dd><em>Dimension</em>. The radius for the 1501inner part of the ring (the hole in the middle), as a dimension value or <a 1502href="more-resources.html#Dimension">dimension resource</a>.</dd> 1503 <dt><code>android:innerRadiusRatio</code></dt> 1504 <dd><em>Float</em>. The radius for the inner 1505part of the ring, expressed as a ratio of the ring's width. For instance, if {@code 1506android:innerRadiusRatio="5"}, then the inner radius equals the ring's width divided by 5. This 1507value is overridden by {@code android:innerRadius}. Default value is 9.</dd> 1508 <dt><code>android:thickness</code></dt> 1509 <dd><em>Dimension</em>. The thickness of the 1510ring, as a dimension value or <a 1511href="more-resources.html#Dimension">dimension resource</a>.</dd> 1512 <dt><code>android:thicknessRatio</code></dt> 1513 <dd><em>Float</em>. The thickness of the ring, 1514expressed as a ratio of the ring's width. For instance, if {@code android:thicknessRatio="2"}, then 1515the thickness equals the ring's width divided by 2. This value is overridden by {@code 1516android:innerRadius}. Default value is 3.</dd> 1517 <dt><code>android:useLevel</code></dt> 1518 <dd><em>Boolean</em>. "true" if this is used as 1519a {@link android.graphics.drawable.LevelListDrawable}. This should normally be "false" 1520 or your shape may not appear.</dd> 1521 </dl> 1522 <dt id="corners-element"><code><corners></code></dt> 1523 <dd>Creates rounded corners for the shape. Applies only when the shape is a rectangle. 1524 <p class="caps">attributes:</p> 1525 <dl class="atn-list"> 1526 <dt><code>android:radius</code></dt> 1527 <dd><em>Dimension</em>. The radius for all corners, as a dimension value or <a 1528href="more-resources.html#Dimension">dimension resource</a>. This is overridden for each 1529corner by the following attributes.</dd> 1530 <dt><code>android:topLeftRadius</code></dt> 1531 <dd><em>Dimension</em>. The radius for the top-left corner, as a dimension value or <a 1532href="more-resources.html#Dimension">dimension resource</a>.</dd> 1533 <dt><code>android:topRightRadius</code></dt> 1534 <dd><em>Dimension</em>. The radius for the top-right corner, as a dimension value or <a 1535href="more-resources.html#Dimension">dimension resource</a>.</dd> 1536 <dt><code>android:bottomLeftRadius</code></dt> 1537 <dd><em>Dimension</em>. The radius for the bottom-left corner, as a dimension value or <a 1538href="more-resources.html#Dimension">dimension resource</a>.</dd> 1539 <dt><code>android:bottomRightRadius</code></dt> 1540 <dd><em>Dimension</em>. The radius for the bottom-right corner, as a dimension value or <a 1541href="more-resources.html#Dimension">dimension resource</a>.</dd> 1542 </dl> 1543 <p class="note"><strong>Note:</strong> Every corner must (initially) be provided a corner 1544radius greater than 1, or else no corners are rounded. If you want specific corners 1545to <em>not</em> be rounded, a work-around is to use {@code android:radius} to set a default corner 1546radius greater than 1, but then override each and every corner with the values you really 1547want, providing zero ("0dp") where you don't want rounded corners.</p> 1548 </dd> 1549 <dt id="gradient-element"><code><gradient></code></dt> 1550 <dd>Specifies a gradient color for the shape. 1551 <p class="caps">attributes:</p> 1552 <dl class="atn-list"> 1553 <dt><code>android:angle</code></dt> 1554 <dd><em>Integer</em>. The angle for the gradient, in degrees. 0 is left to right, 90 is 1555bottom to top. It must be a multiple of 45. Default is 0.</dd> 1556 <dt><code>android:centerX</code></dt> 1557 <dd><em>Float</em>. The relative X-position for the center of the gradient (0 - 1.0). 1558Does not apply when {@code android:type="linear"}.</dd> 1559 <dt><code>android:centerY</code></dt> 1560 <dd><em>Float</em>. The relative Y-position for the center of the gradient (0 - 1.0). 1561Does not apply when {@code android:type="linear"}.</dd> 1562 <dt><code>android:centerColor</code></dt> 1563 <dd><em>Color</em>. Optional color that comes between the start and end colors, as a 1564hexadecimal value or <a href="more-resources.html#Color">color resource</a>.</dd> 1565 <dt><code>android:endColor</code></dt> 1566 <dd><em>Color</em>. The ending color, as a hexadecimal 1567value or <a href="more-resources.html#Color">color resource</a>.</dd> 1568 <dt><code>android:gradientRadius</code></dt> 1569 <dd><em>Float</em>. The radius for the gradient. Only applied when {@code 1570android:type="radial"}.</dd> 1571 <dt><code>android:startColor</code></dt> 1572 <dd><em>Color</em>. The starting color, as a hexadecimal 1573value or <a href="more-resources.html#Color">color resource</a>.</dd> 1574 <dt><code>android:type</code></dt> 1575 <dd><em>Keyword</em>. The type of gradient pattern to apply. Valid values are: 1576 <table> 1577 <tr><th>Value</th><th>Description</th></tr> 1578 <tr><td>{@code "linear"}</td> 1579 <td>A linear gradient. This is the default.</td></tr> 1580 <tr><td>{@code "radial"}</td> 1581 <td>A radial gradient. The start color is the center color.</td></tr> 1582 <tr><td>{@code "sweep"}</td> 1583 <td>A sweeping line gradient. </td></tr> 1584 </table> 1585 </dd> 1586 <dt><code>android:useLevel</code></dt> 1587 <dd><em>Boolean</em>. "true" if this is used as a {@link 1588android.graphics.drawable.LevelListDrawable}.</dd> 1589 </dl> 1590 </dd> 1591 <dt id="padding-element"><code><padding></code></dt> 1592 <dd>Padding to apply to the containing View element (this pads the position of the View 1593content, not the shape). 1594 <p class="caps">attributes:</p> 1595 <dl class="atn-list"> 1596 <dt><code>android:left</code></dt> 1597 <dd><em>Dimension</em>. Left padding, as a dimension value or <a 1598href="more-resources.html#Dimension">dimension resource</a>.</dd> 1599 <dt><code>android:top</code></dt> 1600 <dd><em>Dimension</em>. Top padding, as a dimension value or <a 1601href="more-resources.html#Dimension">dimension resource</a>.</dd> 1602 <dt><code>android:right</code></dt> 1603 <dd><em>Dimension</em>. Right padding, as a dimension value or <a 1604href="more-resources.html#Dimension">dimension resource</a>.</dd> 1605 <dt><code>android:bottom</code></dt> 1606 <dd><em>Dimension</em>. Bottom padding, as a dimension value or <a 1607href="more-resources.html#Dimension">dimension resource</a>.</dd> 1608 </dl> 1609 </dd> 1610 <dt id="solid-element"><code><size></code></dt> 1611 <dd>The size of the shape. 1612 <p class="caps">attributes:</p> 1613 <dl class="atn-list"> 1614 <dt><code>android:height</code></dt> 1615 <dd><em>Dimension</em>. The height of the shape, as a dimension value or <a 1616href="more-resources.html#Dimension">dimension resource</a>.</dd> 1617 <dt><code>android:width</code></dt> 1618 <dd><em>Dimension</em>. The width of the shape, as a dimension value or <a 1619href="more-resources.html#Dimension">dimension resource</a>.</dd> 1620 </dl> 1621 <p class="note"><strong>Note:</strong> The shape scales to the size of the container 1622View proportionate to the dimensions defined here, by default. When you use the shape in an {@link 1623android.widget.ImageView}, you can restrict scaling by setting the <a 1624href="{@docRoot}reference/android/widget/ImageView.html#attr_android:scaleType">{@code 1625android:scaleType}</a> to {@code "center"}.</p> 1626 </dd> 1627 <dt id="solid-element"><code><solid></code></dt> 1628 <dd>A solid color to fill the shape. 1629 <p class="caps">attributes:</p> 1630 <dl class="atn-list"> 1631 <dt><code>android:color</code></dt> 1632 <dd><em>Color</em>. The color to apply to the shape, as a hexadecimal 1633value or <a href="more-resources.html#Color">color resource</a>.</dd> 1634 </dl> 1635 </dd> 1636 <dt id="stroke-element"><code><stroke></code></dt> 1637 <dd>A stroke line for the shape. 1638 <p class="caps">attributes:</p> 1639 <dl class="atn-list"> 1640 <dt><code>android:width</code></dt> 1641 <dd><em>Dimension</em>. The thickness of the line, as a dimension value or <a 1642href="more-resources.html#Dimension">dimension resource</a>.</dd> 1643 <dt><code>android:color</code></dt> 1644 <dd><em>Color</em>. The color of the line, as a 1645hexadecimal value or <a href="more-resources.html#Color">color resource</a>.</dd> 1646 <dt><code>android:dashGap</code></dt> 1647 <dd><em>Dimension</em>. The distance between line dashes, as a dimension value or <a 1648href="more-resources.html#Dimension">dimension resource</a>. Only valid if {@code 1649android:dashWidth} is set.</dd> 1650 <dt><code>android:dashWidth</code></dt> 1651 <dd><em>Dimension</em>. The size of each dash line, as a dimension value or <a 1652href="more-resources.html#Dimension">dimension resource</a>. Only valid if {@code 1653android:dashGap} is set.</dd> 1654 </dl> 1655 </dd> 1656 1657</dl> 1658</dd> <!-- end elements and attributes --> 1659 1660<dt>example:</dt> 1661 1662<dd>XML file saved at <code>res/drawable/gradient_box.xml</code>: 1663<pre> 1664<?xml version="1.0" encoding="utf-8"?> 1665<shape xmlns:android="http://schemas.android.com/apk/res/android" 1666 android:shape="rectangle"> 1667 <gradient 1668 android:startColor="#FFFF0000" 1669 android:endColor="#80FF00FF" 1670 android:angle="45"/> 1671 <padding android:left="7dp" 1672 android:top="7dp" 1673 android:right="7dp" 1674 android:bottom="7dp" /> 1675 <corners android:radius="8dp" /> 1676</shape> 1677</pre> 1678 1679 <p>This layout XML applies the shape drawable to a View:</p> 1680<pre> 1681<TextView 1682 android:background="@drawable/gradient_box" 1683 android:layout_height="wrap_content" 1684 android:layout_width="wrap_content" /> 1685</pre> 1686 1687 <p>This application code gets the shape drawable and applies it to a View:</p> 1688<pre> 1689Resources res = {@link android.content.Context#getResources()}; 1690Drawable shape = res. {@link android.content.res.Resources#getDrawable(int) getDrawable}(R.drawable.gradient_box); 1691 1692TextView tv = (TextView)findViewByID(R.id.textview); 1693tv.setBackground(shape); 1694</pre> 1695</dd> <!-- end example --> 1696 1697<dt>see also:</dt> 1698 1699<dd> 1700<ul> 1701 <li>{@link android.graphics.drawable.ShapeDrawable}</li> 1702</ul> 1703</dd> 1704 1705</dl> 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719