drawable-resource.jd revision cf0ca99a22d65615d78f727cfb8ecf324a9b32c4
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_hovered=["true" | "false"] 645 android:state_selected=["true" | "false"] 646 android:state_checkable=["true" | "false"] 647 android:state_checked=["true" | "false"] 648 android:state_enabled=["true" | "false"] 649 android:state_window_focused=["true" | "false"] /> 650</selector> 651</pre> 652</dd> 653 654<dt>elements:</dt> 655 656<dd> 657<dl class="tag-list"> 658 659 <dt id="selector-element"><code><selector></code></dt> 660 <dd><strong>Required.</strong> This must be the root element. Contains one or more {@code 661<item>} elements. 662 <p class="caps">attributes:</p> 663 <dl class="atn-list"> 664 <dt><code>xmlns:android</code></dt> 665 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 666 <code>"http://schemas.android.com/apk/res/android"</code>. 667 <dt><code>android:constantSize</code></dt> 668 <dd><em>Boolean</em>. "true" if the drawable's reported internal size remains constant as the state 669changes (the size is the maximum of all of the states); "false" if the size varies based on 670the current state. Default is false.</dd> 671 <dt><code>android:dither</code></dt> 672 <dd><em>Boolean</em>. "true" to enable dithering of the bitmap if the bitmap does not have the same pixel 673configuration as the screen (for instance, an ARGB 8888 bitmap with an RGB 565 screen); "false" to 674disable dithering. Default is true.</dd> 675 <dt><code>android:variablePadding</code></dt> 676 <dd><em>Boolean</em>. "true" if the drawable's padding should change based on the current 677state that is selected; "false" if the padding should stay the same (based on the maximum 678padding of all the states). Enabling this feature requires that you deal with 679performing layout when the state changes, which is often not supported. Default is false.</dd> 680 </dl> 681 </dd> 682 <dt id="item-element"><code><item></code></dt> 683 <dd>Defines a drawable to use during certain states, as described by its attributes. Must be a 684child of a <code><selector></code> element. 685 <p class="caps">attributes:</p> 686 <dl class="atn-list"> 687 <dt><code>android:drawable</code></dt> 688 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable resource.</dd> 689 <dt><code>android:state_pressed</code></dt> 690 <dd><em>Boolean</em>. "true" if this item should be used when the object is pressed (such as when a button 691is touched/clicked); "false" if this item should be used in the default, non-pressed state.</dd> 692 <dt><code>android:state_focused</code></dt> 693 <dd><em>Boolean</em>. "true" if this item should be used when the object is focused (such as when a button 694is highlighted using the trackball/d-pad); "false" if this item should be used in the default, 695non-focused state.</dd> 696 <dt><code>android:state_hovered</code></dt> 697 <dd><em>Boolean</em>. "true" if this item should be used when the object is being hovered 698by a cursor; "false" if this item should be used in the default, non-hovered state. Often, this 699drawable may be the same drawable used for the "focused" state. 700 <p>Introduced in API level 14.</p></dd> 701 <dt><code>android:state_selected</code></dt> 702 <dd><em>Boolean</em>. "true" if this item should be used when the object is selected (such as when a 703tab is opened); "false" if this item should be used when the object is not selected.</dd> 704 <dt><code>android:state_checkable</code></dt> 705 <dd><em>Boolean</em>. "true" if this item should be used when the object is checkable; "false" if this 706item should be used when the object is not checkable. (Only useful if the object can 707transition between a checkable and non-checkable widget.)</dd> 708 <dt><code>android:state_checked</code></dt> 709 <dd><em>Boolean</em>. "true" if this item should be used when the object is checked; "false" if it 710should be used when the object is un-checked.</dd> 711 <dt><code>android:state_enabled</code></dt> 712 <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled (capable of 713receiving touch/click events); "false" if it should be used when the object is disabled.</dd> 714 <dt><code>android:state_window_focused</code></dt> 715 <dd><em>Boolean</em>. "true" if this item should be used when the application window has focus (the 716application is in the foreground), "false" if this item should be used when the application 717window does not have focus (for example, if the notification shade is pulled down or a dialog appears).</dd> 718 </dl> 719 <p class="note"><strong>Note:</strong> Remember that Android applies the first item in the state list that 720matches the current state of the object. So, if the first item in the list contains 721none of the state attributes above, then it is applied every time, which is why your 722default value should always be last (as demonstrated in the following example).</p> 723 </dd> 724 725</dl> 726</dd> <!-- end elements and attributes --> 727 728<dt>example:</dt> 729 730<dd>XML file saved at <code>res/drawable/button.xml</code>: 731<pre> 732<?xml version="1.0" encoding="utf-8"?> 733<selector xmlns:android="http://schemas.android.com/apk/res/android"> 734 <item android:state_pressed="true" 735 android:drawable="@drawable/button_pressed" /> <!-- pressed --> 736 <item android:state_focused="true" 737 android:drawable="@drawable/button_focused" /> <!-- focused --> 738 <item android:state_hovered="true" 739 android:drawable="@drawable/button_focused" /> <!-- hovered --> 740 <item android:drawable="@drawable/button_normal" /> <!-- default --> 741</selector> 742</pre> 743 744<p>This layout XML applies the state list drawable to a Button:</p> 745<pre> 746<Button 747 android:layout_height="wrap_content" 748 android:layout_width="wrap_content" 749 android:background="@drawable/button" /> 750</pre> 751</dd> <!-- end example --> 752 753<dt>see also:</dt> 754<dd> 755<ul> 756 <li>{@link android.graphics.drawable.StateListDrawable}</li> 757</ul> 758</dd> 759 760</dl> 761 762 763 764 765 766 767 768 769<h2 id="LevelList">Level List</h2> 770 771<p>A Drawable that manages a number of alternate Drawables, each assigned a maximum numerical 772value. Setting the level value of the drawable with {@link 773android.graphics.drawable.Drawable#setLevel(int) setLevel()} loads the drawable resource in the 774level list that has a {@code android:maxLevel} value greater than or equal to the value 775passed to the method.</p> 776 777<dl class="xml"> 778 779<dt>file location:</dt> 780<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 781The filename is used as the resource ID.</dd> 782 783<dt>compiled resource datatype:</dt> 784<dd>Resource pointer to a {@link android.graphics.drawable.LevelListDrawable}.</dd> 785 786<dt>resource reference:</dt> 787 788<dd> 789In Java: <code>R.drawable.<em>filename</em></code><br/> 790In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 791</dd> 792 793<dt>syntax:</dt> 794 795<dd> 796<pre class="stx"> 797<?xml version="1.0" encoding="utf-8"?> 798<<a href="#levellist-element">level-list</a> 799 xmlns:android="http://schemas.android.com/apk/res/android" > 800 <<a href="#levellist-item-element">item</a> 801 android:drawable="@drawable/<i>drawable_resource</i>" 802 android:maxLevel="<i>integer</i>" 803 android:minLevel="<i>integer</i>" /> 804</level-list> 805</pre> 806</dd> 807 808<dt>elements:</dt> 809 810<dd> 811<dl class="tag-list"> 812 813 <dt id="levellist-element"><code><level-list></code></dt> 814 <dd>This must be the root element. Contains one or more {@code <item>} elements. 815 <p class="caps">attributes:</p> 816 <dl class="atn-list"> 817 <dt><code>xmlns:android</code></dt> 818 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 819 <code>"http://schemas.android.com/apk/res/android"</code>. 820 </dl> 821 </dd> 822 823 <dt id="levellist-item-element"><code><item></code></dt> 824 <dd>Defines a drawable to use at a certain level. 825 <p class="caps">attributes:</p> 826 <dl class="atn-list"> 827 <dt><code>android:drawable</code></dt> 828 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 829resource to be inset.</dd> 830 <dt><code>android:maxLevel</code></dt> 831 <dd><em>Integer</em>. The maximum level allowed for this item.</dd> 832 <dt><code>android:minLevel</code></dt> 833 <dd><em>Integer</em>. The minimum level allowed for this item.</dd> 834 </dl> 835 </dd> 836</dl> 837 838</dd> 839 840<dt>example:</dt> 841 842<dd> 843 844<pre> 845<?xml version="1.0" encoding="utf-8"?> 846<level-list xmlns:android="http://schemas.android.com/apk/res/android" > 847 <item 848 android:drawable="@drawable/status_off" 849 android:maxLevel="0" /> 850 <item 851 android:drawable="@drawable/status_on" 852 android:maxLevel="1" /> 853</level-list> 854</pre> 855<p>Once this is applied to a {@link android.view.View}, the level can be changed with {@link 856android.graphics.drawable.Drawable#setLevel(int) setLevel()} or {@link 857android.widget.ImageView#setImageLevel(int) setImageLevel()}.</p> 858 859</dd> 860 861<dt>see also:</dt> 862 863<dd> 864<ul> 865 <li>{@link android.graphics.drawable.LevelListDrawable}</li> 866</ul> 867</dd> 868 869</dl> 870 871 872 873 874 875 876<h2 id="Transition">Transition Drawable</h2> 877 878<p>A {@link android.graphics.drawable.TransitionDrawable} is a drawable object 879that can cross-fade between the two drawable resources.</p> 880 881<p>Each drawable is represented by an {@code <item>} element inside a single {@code 882<transition>} element. No more than two items are supported. To transition forward, call 883{@link android.graphics.drawable.TransitionDrawable#startTransition(int) startTransition()}. To 884transition backward, call {@link android.graphics.drawable.TransitionDrawable#reverseTransition(int) 885reverseTransition()}.</p> 886 887<dl class="xml"> 888 889<dt>file location:</dt> 890<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 891The filename is used as the resource ID.</dd> 892 893<dt>compiled resource datatype:</dt> 894<dd>Resource pointer to a {@link android.graphics.drawable.TransitionDrawable}.</dd> 895 896<dt>resource reference:</dt> 897 898<dd> 899In Java: <code>R.drawable.<em>filename</em></code><br/> 900In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 901</dd> 902 903<dt>syntax:</dt> 904 905<dd> 906<pre class="stx"> 907<?xml version="1.0" encoding="utf-8"?> 908<<a href="#transition-element">transition</a> 909xmlns:android="http://schemas.android.com/apk/res/android" > 910 <<a href="#transition-item-element">item</a> 911 android:drawable="@[package:]drawable/<em>drawable_resource</em>" 912 android:id="@[+][<em>package</em>:]id/<i>resource_name</i>" 913 android:top="<em>dimension</em>" 914 android:right="<em>dimension</em>" 915 android:bottom="<em>dimension</em>" 916 android:left="<em>dimension</em>" /> 917</transition> 918</pre> 919</dd> 920 921<dt>elements:</dt> 922 923<dd> 924<dl class="tag-list"> 925 926 <dt id="transition-element"><code><transition></code></dt> 927 <dd><strong>Required.</strong> This must be the root element. Contains one or more {@code 928<item>} elements. 929 <p class="caps">attributes:</p> 930 <dl class="atn-list"> 931 <dt><code>xmlns:android</code></dt> 932 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 933 <code>"http://schemas.android.com/apk/res/android"</code>. 934 </dl> 935 </dd> 936 <dt id="transition-item-element"><code><item></code></dt> 937 <dd>Defines a drawable to use as part of the drawable transition. 938Must be a child of a <code><transition></code> element. Accepts child {@code <bitmap>} 939elements. 940 <p class="caps">attributes:</p> 941 <dl class="atn-list"> 942 <dt><code>android:drawable</code></dt> 943 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 944resource.</dd> 945 <dt><code>android:id</code></dt> 946 <dd><em>Resource ID</em>. A unique resource ID for this drawable. To create a new resource 947ID for this item, use the form: 948<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 949ID. You can use this identifier to 950retrieve and modify the drawable with {@link android.view.View#findViewById(int) 951View.findViewById()} or {@link android.app.Activity#findViewById(int) Activity.findViewById()}.</dd> 952 <dt><code>android:top</code></dt> 953 <dd><em>Integer</em>. The top offset in pixels.</dd> 954 <dt><code>android:right</code></dt> 955 <dd><em>Integer</em>. The right offset in pixels.</dd> 956 <dt><code>android:bottom</code></dt> 957 <dd><em>Integer</em>. The bottom offset in pixels.</dd> 958 <dt><code>android:left</code></dt> 959 <dd><em>Integer</em>. The left offset in pixels.</dd> 960 </dl> 961 </dd> 962 963</dl> 964</dd> <!-- end elements and attributes --> 965 966<dt>example:</dt> 967 968<dd>XML file saved at <code>res/drawable/transition.xml</code>: 969<pre> 970<?xml version="1.0" encoding="utf-8"?> 971<transition xmlns:android="http://schemas.android.com/apk/res/android"> 972 <item android:drawable="@drawable/on" /> 973 <item android:drawable="@drawable/off" /> 974</transition> 975</pre> 976 977<p>This layout XML applies the drawable to a View:</p> 978<pre> 979<ImageButton 980 android:id="@+id/button" 981 android:layout_height="wrap_content" 982 android:layout_width="wrap_content" 983 android:src="@drawable/transition" /> 984</pre> 985 986<p>And the following code performs a 500ms transition from the first item to the second:</p> 987<pre> 988ImageButton button = (ImageButton) findViewById(R.id.button); 989TransitionDrawable drawable = (TransitionDrawable) button.getDrawable(); 990drawable.startTransition(500); 991</pre> 992 993</dd> <!-- end example --> 994 995<dt>see also:</dt> 996 997<dd> 998<ul> 999 <li>{@link android.graphics.drawable.TransitionDrawable}</li> 1000</ul> 1001</dd> 1002 1003</dl> 1004 1005 1006 1007 1008 1009<h2 id="Inset">Inset Drawable</h2> 1010 1011<p>A drawable defined in XML that insets another drawable by a specified distance. This is useful 1012when a View needs a background that is smaller than the View's actual bounds.</p> 1013 1014<dl class="xml"> 1015 1016<dt>file location:</dt> 1017<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1018The filename is used as the resource ID.</dd> 1019 1020<dt>compiled resource datatype:</dt> 1021<dd>Resource pointer to a {@link android.graphics.drawable.InsetDrawable}.</dd> 1022 1023<dt>resource reference:</dt> 1024 1025<dd> 1026In Java: <code>R.drawable.<em>filename</em></code><br/> 1027In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1028</dd> 1029 1030<dt>syntax:</dt> 1031 1032<dd> 1033<pre class="stx"> 1034<?xml version="1.0" encoding="utf-8"?> 1035<<a href="#inset-element">inset</a> 1036 xmlns:android="http://schemas.android.com/apk/res/android" 1037 android:drawable="@drawable/<i>drawable_resource</i>" 1038 android:insetTop="<i>dimension</i>" 1039 android:insetRight="<i>dimension</i>" 1040 android:insetBottom="<i>dimension</i>" 1041 android:insetLeft="<i>dimension</i>" /> 1042</pre> 1043</dd> 1044 1045<dt>elements:</dt> 1046 1047<dd> 1048<dl class="tag-list"> 1049 1050 <dt id="inset-element"><code><inset></code></dt> 1051 <dd>Defines the inset drawable. This must be the root element. 1052 <p class="caps">attributes:</p> 1053 <dl class="atn-list"> 1054 <dt><code>xmlns:android</code></dt> 1055 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1056 <code>"http://schemas.android.com/apk/res/android"</code>. 1057 <dt><code>android:drawable</code></dt> 1058 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 1059resource to be inset.</dd> 1060 <dt><code>android:insetTop</code></dt> 1061 <dd><em>Dimension</em>. The top inset, as a dimension value or <a 1062href="more-resources.html#Dimension">dimension resource</a></dd> 1063 <dt><code>android:insetRight</code></dt> 1064 <dd><em>Dimension</em>. The right inset, as a dimension value or <a 1065href="more-resources.html#Dimension">dimension resource</a></dd> 1066 <dt><code>android:insetBottom</code></dt> 1067 <dd><em>Dimension</em>. The bottom inset, as a dimension value or <a 1068href="more-resources.html#Dimension">dimension resource</a></dd> 1069 <dt><code>android:insetLeft</code></dt> 1070 <dd><em>Dimension</em>. The left inset, as a dimension value or <a 1071href="more-resources.html#Dimension">dimension resource</a></dd> 1072 </dl> 1073 </dd> 1074</dl> 1075 1076</dd> 1077 1078<dt>example:</dt> 1079 1080<dd> 1081<pre> 1082<?xml version="1.0" encoding="utf-8"?> 1083<inset xmlns:android="http://schemas.android.com/apk/res/android" 1084 android:drawable="@drawable/background" 1085 android:insetTop="10dp" 1086 android:insetLeft="10dp" /> 1087</pre> 1088</dd> 1089 1090<dt>see also:</dt> 1091 1092<dd> 1093<ul> 1094 <li>{@link android.graphics.drawable.InsetDrawable}</li> 1095</ul> 1096</dd> 1097 1098</dl> 1099 1100 1101 1102 1103 1104 1105 1106 1107<h2 id="Clip">Clip Drawable</h2> 1108 1109<p>A drawable defined in XML that clips another drawable based on this Drawable's current level. You 1110can control how much the child drawable gets clipped in width and height based on the level, as well 1111as a gravity to control where it is placed in its overall container. Most often used to implement 1112things like progress bars.</p> 1113 1114<dl class="xml"> 1115 1116<dt>file location:</dt> 1117<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1118The filename is used as the resource ID.</dd> 1119 1120<dt>compiled resource datatype:</dt> 1121<dd>Resource pointer to a {@link android.graphics.drawable.ClipDrawable}.</dd> 1122 1123<dt>resource reference:</dt> 1124 1125<dd> 1126In Java: <code>R.drawable.<em>filename</em></code><br/> 1127In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1128</dd> 1129 1130<dt>syntax:</dt> 1131 1132<dd> 1133<pre class="stx"> 1134<?xml version="1.0" encoding="utf-8"?> 1135<<a href="#clip-element">clip</a> 1136 xmlns:android="http://schemas.android.com/apk/res/android" 1137 android:drawable="@drawable/<i>drawable_resource</i>" 1138 android:clipOrientation=["horizontal" | "vertical"] 1139 android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" | 1140 "fill_vertical" | "center_horizontal" | "fill_horizontal" | 1141 "center" | "fill" | "clip_vertical" | "clip_horizontal"] /> 1142</pre> 1143</dd> 1144 1145<dt>elements:</dt> 1146 1147<dd> 1148<dl class="tag-list"> 1149 1150 <dt id="clip-element"><code><clip></code></dt> 1151 <dd>Defines the clip drawable. This must be the root element. 1152 <p class="caps">attributes:</p> 1153 <dl class="atn-list"> 1154 <dt><code>xmlns:android</code></dt> 1155 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1156 <code>"http://schemas.android.com/apk/res/android"</code>. 1157 <dt><code>android:drawable</code></dt> 1158 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 1159resource to be clipped.</dd> 1160 <dt><code>android:clipOrientation</code></dt> 1161 <dd><em>Keyword</em>. The orientation for the clip. 1162 <p>Must be one of the following constant values:</p> 1163<table> 1164<tr><th>Value</th><th>Description</th></tr> 1165<tr><td><code>horizontal</code></td> 1166<td>Clip the drawable horizontally.</td></tr> 1167<tr><td><code>vertical</code></td> 1168<td>Clip the drawable vertically.</td></tr> 1169</table> 1170 </dd> 1171 <dt><code>android:gravity</code></dt> 1172 <dd><em>Keyword</em>. Specifies where to clip within the drawable. 1173 <p>Must be one or more (separated by '|') of the following constant values:</p> 1174<table> 1175<tr><th>Value</th><th>Description</th></tr> 1176<tr><td><code>top</code></td> 1177<td>Put the object at the top of its container, not changing its size. When {@code 1178clipOrientation} is {@code "vertical"}, clipping occurs at the bottom of the drawable.</td></tr> 1179<tr><td><code>bottom</code></td> 1180<td>Put the object at the bottom of its container, not changing its size. When {@code 1181clipOrientation} is {@code "vertical"}, clipping occurs at the top of the drawable.</td></tr> 1182<tr><td><code>left</code></td> 1183<td>Put the object at the left edge of its container, not changing its size. This is the 1184default. When {@code clipOrientation} is {@code "horizontal"}, clipping occurs at the right side of 1185the drawable. This is the default.</td></tr> 1186<tr><td><code>right</code></td> 1187<td>Put the object at the right edge of its container, not changing its size. When {@code 1188clipOrientation} is {@code "horizontal"}, clipping occurs at the left side of 1189the drawable.</td></tr> 1190<tr><td><code>center_vertical</code></td> 1191<td>Place object in the vertical center of its container, not changing its size. Clipping behaves 1192the same as when gravity is {@code "center"}.</td></tr> 1193<tr><td><code>fill_vertical</code></td> 1194<td>Grow the vertical size of the object if needed so it completely fills its container. When {@code 1195clipOrientation} is {@code "vertical"}, no clipping occurs because the drawable fills the 1196vertical space (unless the drawable level is 0, in which case it's not visible).</td></tr> 1197<tr><td><code>center_horizontal</code></td> 1198<td>Place object in the horizontal center of its container, not changing its size. 1199Clipping behaves the same as when gravity is {@code "center"}.</td></tr> 1200<tr><td><code>fill_horizontal</code></td> 1201<td>Grow the horizontal size of the object if needed so it completely fills its container. When 1202{@code clipOrientation} is {@code "horizontal"}, no clipping occurs because the drawable fills the 1203horizontal space (unless the drawable level is 0, in which case it's not visible). 1204</td></tr> 1205<tr><td><code>center</code></td> 1206<td>Place the object in the center of its container in both the vertical and horizontal axis, not 1207changing its size. When {@code 1208clipOrientation} is {@code "horizontal"}, clipping occurs on the left and right. When {@code 1209clipOrientation} is {@code "vertical"}, clipping occurs on the top and bottom.</td></tr> 1210<tr><td><code>fill</code></td> 1211<td>Grow the horizontal and vertical size of the object if needed so it completely fills its 1212container. No clipping occurs because the drawable fills the 1213horizontal and vertical space (unless the drawable level is 0, in which case it's not 1214visible).</td></tr> 1215<tr><td><code>clip_vertical</code></td> 1216<td>Additional option that can be set to have the top and/or bottom edges of the child clipped to 1217its container's bounds. The clip is based on the vertical gravity: a top gravity clips the 1218bottom edge, a bottom gravity clips the top edge, and neither clips both edges. 1219</td></tr> 1220<tr><td><code>clip_horizontal</code></td> 1221<td>Additional option that can be set to have the left and/or right edges of the child clipped to 1222its container's bounds. The clip is based on the horizontal gravity: a left gravity clips 1223the right edge, a right gravity clips the left edge, and neither clips both edges. 1224</td></tr> 1225</table></dd> 1226 </dl> 1227 </dd> 1228</dl> 1229 1230</dd> <!-- end elements and attributes --> 1231 1232<dt>example:</dt> 1233 1234<dd>XML file saved at <code>res/drawable/clip.xml</code>: 1235<pre> 1236<?xml version="1.0" encoding="utf-8"?> 1237<clip xmlns:android="http://schemas.android.com/apk/res/android" 1238 android:drawable="@drawable/android" 1239 android:clipOrientation="horizontal" 1240 android:gravity="left" /> 1241</clip> 1242</pre> 1243 <p>The following layout XML applies the clip drawable to a View:</p> 1244<pre> 1245<ImageView 1246 android:id="@+id/image" 1247 android:background="@drawable/clip" 1248 android:layout_height="wrap_content" 1249 android:layout_width="wrap_content" /> 1250</pre> 1251 1252 <p>The following code gets the drawable and increases the amount of clipping in order to 1253progressively reveal the image:</p> 1254<pre> 1255ImageView imageview = (ImageView) findViewById(R.id.image); 1256ClipDrawable drawable = (ClipDrawable) imageview.getDrawable(); 1257drawable.setLevel(drawable.getLevel() + 1000); 1258</pre> 1259 1260<p>Increasing the level reduces the amount of clipping and slowly reveals the image. Here it is 1261at a level of 7000:</p> 1262<img src="{@docRoot}images/resources/clip.png" alt="" /> 1263 1264<p class="note"><strong>Note:</strong> The default level is 0, which is fully clipped so the image 1265is not visible. When the level is 10,000, the image is not clipped and completely visible.</p> 1266</dd> <!-- end example --> 1267 1268<dt>see also:</dt> 1269 1270<dd> 1271<ul> 1272 <li>{@link android.graphics.drawable.ClipDrawable}</li> 1273</ul> 1274</dd> 1275 1276</dl> 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286<h2 id="Scale">Scale Drawable</h2> 1287 1288<p>A drawable defined in XML that changes the size of another drawable based on its current 1289level.</p> 1290 1291<dl class="xml"> 1292 1293<dt>file location:</dt> 1294<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1295The filename is used as the resource ID.</dd> 1296 1297<dt>compiled resource datatype:</dt> 1298<dd>Resource pointer to a {@link android.graphics.drawable.ScaleDrawable}.</dd> 1299 1300<dt>resource reference:</dt> 1301 1302<dd> 1303In Java: <code>R.drawable.<em>filename</em></code><br/> 1304In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1305</dd> 1306 1307<dt>syntax:</dt> 1308 1309<dd> 1310<pre class="stx"> 1311<?xml version="1.0" encoding="utf-8"?> 1312<<a href="#scale-element">scale</a> 1313 xmlns:android="http://schemas.android.com/apk/res/android" 1314 android:drawable="@drawable/<i>drawable_resource</i>" 1315 android:scaleGravity=["top" | "bottom" | "left" | "right" | "center_vertical" | 1316 "fill_vertical" | "center_horizontal" | "fill_horizontal" | 1317 "center" | "fill" | "clip_vertical" | "clip_horizontal"] 1318 android:scaleHeight="<i>percentage</i>" 1319 android:scaleWidth="<i>percentage</i>" /> 1320</pre> 1321</dd> 1322 1323<dt>elements:</dt> 1324 1325<dd> 1326<dl class="tag-list"> 1327 1328 <dt id="scale-element"><code><scale></code></dt> 1329 <dd>Defines the scale drawable. This must be the root element. 1330 <p class="caps">attributes:</p> 1331 <dl class="atn-list"> 1332 <dt><code>xmlns:android</code></dt> 1333 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1334 <code>"http://schemas.android.com/apk/res/android"</code>. 1335 <dt><code>android:drawable</code></dt> 1336 <dd><em>Drawable resource</em>. <strong>Required</strong>. Reference to a drawable 1337resource.</dd> 1338 <dt><code>android:scaleGravity</code></dt> 1339 <dd><em>Keyword</em>. Specifies the gravity position after scaling. 1340 <p>Must be one or more (separated by '|') of the following constant values:</p> 1341<table> 1342<tr><th>Value</th><th>Description</th></tr> 1343<tr><td><code>top</code></td> 1344<td>Put the object at the top of its container, not changing its size.</td></tr> 1345<tr><td><code>bottom</code></td> 1346<td>Put the object at the bottom of its container, not changing its size. </td></tr> 1347<tr><td><code>left</code></td> 1348<td>Put the object at the left edge of its container, not changing its size. This is the 1349default.</td></tr> 1350<tr><td><code>right</code></td> 1351<td>Put the object at the right edge of its container, not changing its size. </td></tr> 1352<tr><td><code>center_vertical</code></td> 1353<td>Place object in the vertical center of its container, not changing its size. </td></tr> 1354<tr><td><code>fill_vertical</code></td> 1355<td>Grow the vertical size of the object if needed so it completely fills its container. </td></tr> 1356<tr><td><code>center_horizontal</code></td> 1357<td>Place object in the horizontal center of its container, not changing its size. </td></tr> 1358<tr><td><code>fill_horizontal</code></td> 1359<td>Grow the horizontal size of the object if needed so it completely fills its container. 1360</td></tr> 1361<tr><td><code>center</code></td> 1362<td>Place the object in the center of its container in both the vertical and horizontal axis, not 1363changing its size. </td></tr> 1364<tr><td><code>fill</code></td> 1365<td>Grow the horizontal and vertical size of the object if needed so it completely fills its 1366container. </td></tr> 1367<tr><td><code>clip_vertical</code></td> 1368<td>Additional option that can be set to have the top and/or bottom edges of the child clipped to 1369its container's bounds. The clip is based on the vertical gravity: a top gravity clips the 1370bottom edge, a bottom gravity clips the top edge, and neither clips both edges. 1371</td></tr> 1372<tr><td><code>clip_horizontal</code></td> 1373<td>Additional option that can be set to have the left and/or right edges of the child clipped to 1374its container's bounds. The clip is based on the horizontal gravity: a left gravity clips 1375the right edge, a right gravity clips the left edge, and neither clips both edges. 1376</td></tr> 1377</table></dd> 1378 <dt><code>android:scaleHeight</code></dt> 1379 <dd><em>Percentage</em>. The scale height, expressed as a percentage of the drawable's 1380bound. The value's format is XX%. For instance: 100%, 12.5%, etc.</dd> 1381 <dt><code>android:scaleWidth</code></dt> 1382 <dd><em>Percentage</em>. The scale width, expressed as a percentage of the drawable's 1383bound. The value's format is XX%. For instance: 100%, 12.5%, etc.</dd> 1384 </dl> 1385 </dd> 1386</dl> 1387 1388</dd> 1389 1390<dt>example:</dt> 1391 1392<dd> 1393<pre class="stx"> 1394<?xml version="1.0" encoding="utf-8"?> 1395<scale xmlns:android="http://schemas.android.com/apk/res/android" 1396 android:drawable="@drawable/logo" 1397 android:scaleGravity="center_vertical|center_horizontal" 1398 android:scaleHeight="80%" 1399 android:scaleWidth="80%" /> 1400</pre> 1401</dd> 1402 1403<dt>see also:</dt> 1404<dd> 1405<ul> 1406 <li>{@link android.graphics.drawable.ScaleDrawable}</li> 1407</ul> 1408</dd> 1409 1410</dl> 1411 1412 1413 1414 1415 1416 1417 1418<h2 id="Shape">Shape Drawable</h2> 1419 1420<p>This is a generic shape defined in XML.</p> 1421 1422<dl class="xml"> 1423 1424<dt>file location:</dt> 1425<dd><code>res/drawable/<em>filename</em>.xml</code><br/> 1426The filename is used as the resource ID.</dd> 1427 1428<dt>compiled resource datatype:</dt> 1429<dd>Resource pointer to a {@link android.graphics.drawable.GradientDrawable}.</dd> 1430 1431<dt>resource reference:</dt> 1432 1433<dd> 1434In Java: <code>R.drawable.<em>filename</em></code><br/> 1435In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> 1436</dd> 1437 1438<dt>syntax:</dt> 1439 1440<dd> 1441<pre class="stx"> 1442<?xml version="1.0" encoding="utf-8"?> 1443<<a href="#shape-element">shape</a> 1444 xmlns:android="http://schemas.android.com/apk/res/android" 1445 android:shape=["rectangle" | "oval" | "line" | "ring"] > 1446 <<a href="#corners-element">corners</a> 1447 android:radius="<em>integer</em>" 1448 android:topLeftRadius="<em>integer</em>" 1449 android:topRightRadius="<em>integer</em>" 1450 android:bottomLeftRadius="<em>integer</em>" 1451 android:bottomRightRadius="<em>integer</em>" /> 1452 <<a href="#gradient-element">gradient</a> 1453 android:angle="<em>integer</em>" 1454 android:centerX="<em>integer</em>" 1455 android:centerY="<em>integer</em>" 1456 android:centerColor="<em>integer</em>" 1457 android:endColor="<em>color</em>" 1458 android:gradientRadius="<em>integer</em>" 1459 android:startColor="<em>color</em>" 1460 android:type=["linear" | "radial" | "sweep"] 1461 android:useLevel=["true" | "false"] /> 1462 <<a href="#padding-element">padding</a> 1463 android:left="<em>integer</em>" 1464 android:top="<em>integer</em>" 1465 android:right="<em>integer</em>" 1466 android:bottom="<em>integer</em>" /> 1467 <<a href="#size-element">size</a> 1468 android:width="<em>integer</em>" 1469 android:height="<em>integer</em>" /> 1470 <<a href="#solid-element">solid</a> 1471 android:color="<em>color</em>" /> 1472 <<a href="#stroke-element">stroke</a> 1473 android:width="<em>integer</em>" 1474 android:color="<em>color</em>" 1475 android:dashWidth="<em>integer</em>" 1476 android:dashGap="<em>integer</em>" /> 1477</shape> 1478</pre> 1479</dd> 1480 1481<dt>elements:</dt> 1482 1483<dd> 1484<dl class="tag-list"> 1485 1486 <dt id="shape-element"><code><shape></code></dt> 1487 <dd>The shape drawable. This must be the root element. 1488 <p class="caps">attributes:</p> 1489 <dl class="atn-list"> 1490 <dt><code>xmlns:android</code></dt> 1491 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 1492 <code>"http://schemas.android.com/apk/res/android"</code>. 1493 <dt><code>android:shape</code></dt> 1494 <dd><em>Keyword</em>. Defines the type of shape. Valid values are: 1495 <table> 1496 <tr><th>Value</th><th>Desciption</th></tr> 1497 <tr><td>{@code "rectangle"}</td> 1498 <td>A rectangle that fills the containing View. This is the default shape.</td></tr> 1499 <tr><td>{@code "oval"}</td> 1500 <td>An oval shape that fits the dimensions of the containing View.</td></tr> 1501 <tr><td>{@code "line"}</td> 1502 <td>A horizontal line that spans the width of the containing View. This 1503 shape requires the {@code <stroke>} element to define the width of the 1504 line.</td></tr> 1505 <tr><td>{@code "ring"}</td> 1506 <td>A ring shape.</td></tr> 1507 </table> 1508 </dd> 1509 </dl> 1510 <p>The following attributes are used only when {@code android:shape="ring"}:</p> 1511 <dl class="atn-list"> 1512 <dt><code>android:innerRadius</code></dt> 1513 <dd><em>Dimension</em>. The radius for the 1514inner part of the ring (the hole in the middle), as a dimension value or <a 1515href="more-resources.html#Dimension">dimension resource</a>.</dd> 1516 <dt><code>android:innerRadiusRatio</code></dt> 1517 <dd><em>Float</em>. The radius for the inner 1518part of the ring, expressed as a ratio of the ring's width. For instance, if {@code 1519android:innerRadiusRatio="5"}, then the inner radius equals the ring's width divided by 5. This 1520value is overridden by {@code android:innerRadius}. Default value is 9.</dd> 1521 <dt><code>android:thickness</code></dt> 1522 <dd><em>Dimension</em>. The thickness of the 1523ring, as a dimension value or <a 1524href="more-resources.html#Dimension">dimension resource</a>.</dd> 1525 <dt><code>android:thicknessRatio</code></dt> 1526 <dd><em>Float</em>. The thickness of the ring, 1527expressed as a ratio of the ring's width. For instance, if {@code android:thicknessRatio="2"}, then 1528the thickness equals the ring's width divided by 2. This value is overridden by {@code 1529android:innerRadius}. Default value is 3.</dd> 1530 <dt><code>android:useLevel</code></dt> 1531 <dd><em>Boolean</em>. "true" if this is used as 1532a {@link android.graphics.drawable.LevelListDrawable}. This should normally be "false" 1533 or your shape may not appear.</dd> 1534 </dl> 1535 <dt id="corners-element"><code><corners></code></dt> 1536 <dd>Creates rounded corners for the shape. Applies only when the shape is a rectangle. 1537 <p class="caps">attributes:</p> 1538 <dl class="atn-list"> 1539 <dt><code>android:radius</code></dt> 1540 <dd><em>Dimension</em>. The radius for all corners, as a dimension value or <a 1541href="more-resources.html#Dimension">dimension resource</a>. This is overridden for each 1542corner by the following attributes.</dd> 1543 <dt><code>android:topLeftRadius</code></dt> 1544 <dd><em>Dimension</em>. The radius for the top-left corner, as a dimension value or <a 1545href="more-resources.html#Dimension">dimension resource</a>.</dd> 1546 <dt><code>android:topRightRadius</code></dt> 1547 <dd><em>Dimension</em>. The radius for the top-right corner, as a dimension value or <a 1548href="more-resources.html#Dimension">dimension resource</a>.</dd> 1549 <dt><code>android:bottomLeftRadius</code></dt> 1550 <dd><em>Dimension</em>. The radius for the bottom-left corner, as a dimension value or <a 1551href="more-resources.html#Dimension">dimension resource</a>.</dd> 1552 <dt><code>android:bottomRightRadius</code></dt> 1553 <dd><em>Dimension</em>. The radius for the bottom-right corner, as a dimension value or <a 1554href="more-resources.html#Dimension">dimension resource</a>.</dd> 1555 </dl> 1556 <p class="note"><strong>Note:</strong> Every corner must (initially) be provided a corner 1557radius greater than 1, or else no corners are rounded. If you want specific corners 1558to <em>not</em> be rounded, a work-around is to use {@code android:radius} to set a default corner 1559radius greater than 1, but then override each and every corner with the values you really 1560want, providing zero ("0dp") where you don't want rounded corners.</p> 1561 </dd> 1562 <dt id="gradient-element"><code><gradient></code></dt> 1563 <dd>Specifies a gradient color for the shape. 1564 <p class="caps">attributes:</p> 1565 <dl class="atn-list"> 1566 <dt><code>android:angle</code></dt> 1567 <dd><em>Integer</em>. The angle for the gradient, in degrees. 0 is left to right, 90 is 1568bottom to top. It must be a multiple of 45. Default is 0.</dd> 1569 <dt><code>android:centerX</code></dt> 1570 <dd><em>Float</em>. The relative X-position for the center of the gradient (0 - 1.0).</dd> 1571 <dt><code>android:centerY</code></dt> 1572 <dd><em>Float</em>. The relative Y-position for the center of the gradient (0 - 1.0).</dd> 1573 <dt><code>android:centerColor</code></dt> 1574 <dd><em>Color</em>. Optional color that comes between the start and end colors, as a 1575hexadecimal value or <a href="more-resources.html#Color">color resource</a>.</dd> 1576 <dt><code>android:endColor</code></dt> 1577 <dd><em>Color</em>. The ending color, as a hexadecimal 1578value or <a href="more-resources.html#Color">color resource</a>.</dd> 1579 <dt><code>android:gradientRadius</code></dt> 1580 <dd><em>Float</em>. The radius for the gradient. Only applied when {@code 1581android:type="radial"}.</dd> 1582 <dt><code>android:startColor</code></dt> 1583 <dd><em>Color</em>. The starting color, as a hexadecimal 1584value or <a href="more-resources.html#Color">color resource</a>.</dd> 1585 <dt><code>android:type</code></dt> 1586 <dd><em>Keyword</em>. The type of gradient pattern to apply. Valid values are: 1587 <table> 1588 <tr><th>Value</th><th>Description</th></tr> 1589 <tr><td>{@code "linear"}</td> 1590 <td>A linear gradient. This is the default.</td></tr> 1591 <tr><td>{@code "radial"}</td> 1592 <td>A radial gradient. The start color is the center color.</td></tr> 1593 <tr><td>{@code "sweep"}</td> 1594 <td>A sweeping line gradient. </td></tr> 1595 </table> 1596 </dd> 1597 <dt><code>android:useLevel</code></dt> 1598 <dd><em>Boolean</em>. "true" if this is used as a {@link 1599android.graphics.drawable.LevelListDrawable}.</dd> 1600 </dl> 1601 </dd> 1602 <dt id="padding-element"><code><padding></code></dt> 1603 <dd>Padding to apply to the containing View element (this pads the position of the View 1604content, not the shape). 1605 <p class="caps">attributes:</p> 1606 <dl class="atn-list"> 1607 <dt><code>android:left</code></dt> 1608 <dd><em>Dimension</em>. Left padding, as a dimension value or <a 1609href="more-resources.html#Dimension">dimension resource</a>.</dd> 1610 <dt><code>android:top</code></dt> 1611 <dd><em>Dimension</em>. Top padding, as a dimension value or <a 1612href="more-resources.html#Dimension">dimension resource</a>.</dd> 1613 <dt><code>android:right</code></dt> 1614 <dd><em>Dimension</em>. Right padding, as a dimension value or <a 1615href="more-resources.html#Dimension">dimension resource</a>.</dd> 1616 <dt><code>android:bottom</code></dt> 1617 <dd><em>Dimension</em>. Bottom padding, as a dimension value or <a 1618href="more-resources.html#Dimension">dimension resource</a>.</dd> 1619 </dl> 1620 </dd> 1621 <dt id="size-element"><code><size></code></dt> 1622 <dd>The size of the shape. 1623 <p class="caps">attributes:</p> 1624 <dl class="atn-list"> 1625 <dt><code>android:height</code></dt> 1626 <dd><em>Dimension</em>. The height of the shape, as a dimension value or <a 1627href="more-resources.html#Dimension">dimension resource</a>.</dd> 1628 <dt><code>android:width</code></dt> 1629 <dd><em>Dimension</em>. The width of the shape, as a dimension value or <a 1630href="more-resources.html#Dimension">dimension resource</a>.</dd> 1631 </dl> 1632 <p class="note"><strong>Note:</strong> The shape scales to the size of the container 1633View proportionate to the dimensions defined here, by default. When you use the shape in an {@link 1634android.widget.ImageView}, you can restrict scaling by setting the <a 1635href="{@docRoot}reference/android/widget/ImageView.html#attr_android:scaleType">{@code 1636android:scaleType}</a> to {@code "center"}.</p> 1637 </dd> 1638 <dt id="solid-element"><code><solid></code></dt> 1639 <dd>A solid color to fill the shape. 1640 <p class="caps">attributes:</p> 1641 <dl class="atn-list"> 1642 <dt><code>android:color</code></dt> 1643 <dd><em>Color</em>. The color to apply to the shape, as a hexadecimal 1644value or <a href="more-resources.html#Color">color resource</a>.</dd> 1645 </dl> 1646 </dd> 1647 <dt id="stroke-element"><code><stroke></code></dt> 1648 <dd>A stroke line for the shape. 1649 <p class="caps">attributes:</p> 1650 <dl class="atn-list"> 1651 <dt><code>android:width</code></dt> 1652 <dd><em>Dimension</em>. The thickness of the line, as a dimension value or <a 1653href="more-resources.html#Dimension">dimension resource</a>.</dd> 1654 <dt><code>android:color</code></dt> 1655 <dd><em>Color</em>. The color of the line, as a 1656hexadecimal value or <a href="more-resources.html#Color">color resource</a>.</dd> 1657 <dt><code>android:dashGap</code></dt> 1658 <dd><em>Dimension</em>. The distance between line dashes, as a dimension value or <a 1659href="more-resources.html#Dimension">dimension resource</a>. Only valid if {@code 1660android:dashWidth} is set.</dd> 1661 <dt><code>android:dashWidth</code></dt> 1662 <dd><em>Dimension</em>. The size of each dash line, as a dimension value or <a 1663href="more-resources.html#Dimension">dimension resource</a>. Only valid if {@code 1664android:dashGap} is set.</dd> 1665 </dl> 1666 </dd> 1667 1668</dl> 1669</dd> <!-- end elements and attributes --> 1670 1671<dt>example:</dt> 1672 1673<dd>XML file saved at <code>res/drawable/gradient_box.xml</code>: 1674<pre> 1675<?xml version="1.0" encoding="utf-8"?> 1676<shape xmlns:android="http://schemas.android.com/apk/res/android" 1677 android:shape="rectangle"> 1678 <gradient 1679 android:startColor="#FFFF0000" 1680 android:endColor="#80FF00FF" 1681 android:angle="45"/> 1682 <padding android:left="7dp" 1683 android:top="7dp" 1684 android:right="7dp" 1685 android:bottom="7dp" /> 1686 <corners android:radius="8dp" /> 1687</shape> 1688</pre> 1689 1690 <p>This layout XML applies the shape drawable to a View:</p> 1691<pre> 1692<TextView 1693 android:background="@drawable/gradient_box" 1694 android:layout_height="wrap_content" 1695 android:layout_width="wrap_content" /> 1696</pre> 1697 1698 <p>This application code gets the shape drawable and applies it to a View:</p> 1699<pre> 1700Resources res = {@link android.content.Context#getResources()}; 1701Drawable shape = res. {@link android.content.res.Resources#getDrawable(int) getDrawable}(R.drawable.gradient_box); 1702 1703TextView tv = (TextView)findViewByID(R.id.textview); 1704tv.setBackground(shape); 1705</pre> 1706</dd> <!-- end example --> 1707 1708<dt>see also:</dt> 1709 1710<dd> 1711<ul> 1712 <li>{@link android.graphics.drawable.ShapeDrawable}</li> 1713</ul> 1714</dd> 1715 1716</dl> 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730