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