available-resources.jd revision 7f877069274c94b373478a8d0c969c9cfd93864f
1page.title=Available Resource Types 2parent.title=Resources and Assets 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9 <h2>Key classes</h2> 10 <ol> 11 <li>{@link android.content.res.Resources}</li> 12 <li>{@link android.content.res.AssetManager}</li> 13 </ol> 14 15 <h2>In this document</h2> 16 <ol> 17 <li><a href="#simplevalues">Simple Values</a> 18 <ol> 19 <li><a href="#colorvals">Color Values</a></li> 20 <li><a href="#stringresources">Strings and Styled Text</a></li> 21 <li><a href="#dimension">Dimension Values</a></li> 22 </ol> 23 </li> 24 <li><a href="#drawables">Drawables</a> 25 <ol> 26 <li><a href="#imagefileresources">Bitmap Files</a></li> 27 <li><a href="#colordrawableresources">Color Drawables</a></li> 28 <li><a href="#ninepatch">Nine-Patch (Stretchable) Images</a></li> 29 </ol> 30 </li> 31 <li><a href="#animation">Animation</a></li> 32 <li><a href="#menus">Menus</a></li> 33 <li><a href="#layoutresources">Layout</a> 34 <ol> 35 <li><a href="#customresources">Custom Layout Resources</a> 36 </ol> 37 </li> 38 <li><a href="#stylesandthemes">Styles and Themes</a></li> 39 </ol> 40 41</div> 42</div> 43 44<p>This page describes the different types of resources that you can 45externalize from your code and package with your application. </p> 46 47 48<p>For more details on how to use resources in your application, please see the 49 <a href="resources-i18n.html">Resources and Internationalization</a> 50 documentation.</p> 51 52 53<h2 id="simplevalues">Simple Values</h2> 54 55<p>All simple resource values can be expressed as a string, using various 56formats to unambiguously indicate the type of resource being created. For 57this reason, these values can be defined both as standard resources 58(under res/values/), as well as direct values supplied for 59mappings in <a href="#stylesandthemes">styles and themes</a>, and attributes in 60XML files such as <a href="#layoutresources">layouts</a>.</p> 61 62 63 64<h3 id="colorvals">Color Values</h3> 65<p> 66 A color value specifies an RGB value with an alpha channel, which can 67 be used in various places such as specifying a solid color for a {@link android.graphics.drawable.Drawable} 68 or the color to use for text. A color value always begins with 69 a pound (#) character and then followed by the Alpha-Red-Green-Blue information 70 in one of the following formats: 71</p> 72<ul> 73<li> #RGB 74<li> #ARGB 75<li> #RRGGBB 76<li> #AARRGGBB 77</ul> 78<p> 79 If you want to retrieve the color represented by a resource ID, you can call 80 the {@link android.content.res.Resources#getColor(int) Resources.getColor()} method. 81</p> 82<p> 83 <strong>Source file format:</strong> XML file requiring a 84 <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and 85 a root <code><resources></code> element containing one or more 86 <code><color></code> tags. 87</p> 88<p> 89 <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary) 90</p> 91<p> 92 <strong>Compiled resource datatype:</strong> Resource pointer to a Java int. 93</p> 94<p> 95 <strong>Resource reference name:</strong> 96</p> 97<ul> 98 <li> 99 <strong>Java:</strong> <code>R.color.<em>some_name</em></code> 100 </li> 101 <li> 102 <strong>XML:</strong> <code>@[<em>package</em>:]color/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific color) 103 </li> 104</ul> 105<p> 106 <strong>Syntax</strong> 107</p> 108<pre> 109<color name=<em>color_name</em>><em>#color_value</em></color> 110</pre> 111<dl> 112 <dt> 113 <color> 114 </dt> 115 <dd> 116 Value is a color, using web-style syntax, as describe above. Has only one attribute: 117 <ul> 118 <li> 119 <em>name</em> - The name used in referring to this color. 120 </li> 121 </ul> 122 </dd> 123</dl> 124<p> 125 <strong>Example XML Declaration</strong> 126</p> 127<p> 128 The following code declares two colors, the first fully opaque, and the 129 second translucent. 130</p> 131<pre> 132<resources> 133 <color name="opaque_red">#f00</color> 134 <color name="translucent_red">#80ff0000</color> 135</resources> 136</pre> 137<p> 138 <strong>Example Code Use</strong> 139</p> 140<p> 141 Example Java code 142</p> 143<pre> 144// Retrieve a color value. 145int color = getResources.getColor(R.color.opaque_red); 146</pre> 147<p> 148 Example XML code 149</p> 150<pre> 151<TextView android:layout_width="fill_parent" 152 android:layout_height="wrap_content" 153 android:textAlign="center" 154 android:textColor="@color/translucent_red" 155 android:text="Some Text"/> 156</pre> 157 158 159 160<h3 id="stringresources">Strings and Styled Text</h3> 161<p> 162 Strings, with optional <a href="#styledtext">simple formatting</a>, can be 163stored and retrieved as resources. You can add formatting to your string by 164using three standard HTML tags: <b>, <i>, and <u>. To 165guarantee getting an unstyled string only (the raw text) call the 166<code>toString()</code> method of the retrieved CharSequence object. 167Methods that accept string resources should be able to process these styling 168tags. 169</p> 170<p> 171 If you want to retrieve the String represented by a resource ID, you can call the {@link android.content.Context#getString(int) Context.getString()} method. 172</p> 173<p> 174 <strong>Note:</strong> If you use an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other kind of enclosing quotes: 175</p> 176<pre> 177<string name="good_example">"This'll work"</string> 178<string name="good_example_2">This\'ll also work</string> 179<string name="bad_example">This won't work!</string> 180<string name="bad_example_2">XML encodings won&apos;t work either!</string> 181</pre> 182<p> 183 <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><string></code> tags. 184</p> 185<p> 186 <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary) 187</p> 188<p> 189 <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. 190</p> 191<p> 192 <strong>Resource reference name:</strong> 193</p> 194<ul> 195 <li> 196 <strong>Java:</strong> <code>R.string.<em>some_name</em></code> 197 </li> 198 <li> 199 <strong>XML:</strong> <code>@[<em>package</em>:]string/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific string) 200 </li> 201</ul> 202<p> 203 <strong>Syntax</strong> 204</p> 205<pre> 206<string name=<em>string_name</em>><em>string_value</em></string> 207</pre> 208<dl> 209 <dt> 210 <string> 211 </dt> 212 <dd> 213 Value is a string, with optional styling tags. Has only one attribute: 214 <ul> 215 <li> 216 <em>name</em> - The name used in referring to this string. 217 </li> 218 </ul> 219 </dd> 220</dl> 221<p> 222 <strong>Example XML Declaration</strong> 223</p> 224<p> 225 The following declares two strings: the first — simple text with no 226 formatting (resulting in a CharSequence that is simply a String object) — the second includes formatting information in the string (resulting 227 in a CharSequence that is a complex data structure). If you are using the custom editor for string files in Eclipse, the HTML formatting tags will automatically be escaped and you will need to use {@link android.content.Context#getString(int) Context.getString()} and {@link android.text.Html#fromHtml} to retrieve the resource and then convert it to formatted text. 228</p> 229<pre> 230<resources> 231 <string name="simple_welcome_message">Welcome!</string> 232 <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see you.</string> 233</resources> 234</pre> 235<p> 236 <strong>Example Code Use</strong> 237</p> 238<p> 239 Example Java code 240</p> 241<pre> 242// Assign a styled string resource to a TextView 243// on the current screen. 244CharSequence str = getString(R.string.styled_welcome_message); 245TextView tv = (TextView)findViewByID(R.id.text); 246tv.setText(str); 247</pre> 248<p> 249 Example XML code 250</p> 251<pre> 252<TextView android:layout_width="fill_parent" 253 android:layout_height="wrap_content" 254 android:textAlign="center" 255 android:text="@string/simple_welcome_message"/> 256</pre> 257 258 259<h4 id="styledtext">Using Styled Text as a Format String</h4> 260<p> 261Sometimes you may want to create a styled text resource that is also used as a 262format string. This cannot be done directly because there is no way of passing 263the styled text as the format string argument of String.format() 264without stripping out the style information. The workaround is to store the 265style tags as escaped HTML tags, and then convert the escaped HTML string into 266a styled text after formatting has taken place. 267</p> 268<p> 269To use styled text as a format string, do the following. 270</p> 271<ol> 272 <li>Store your styled text resource as an escaped string, so that the HTML tags in your text resource are not interpreted as if they were XML tags: 273<pre> 274<resources> 275 <string name="search_results_resultsTextFormat">%1$d results for &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string> 276</resources> 277</pre> 278<p> 279In this example the format string has two arguments: <code>%1$d</code> is a decimal number, <code>%2$s</code> is a string. 280</p> 281</li> 282<li> 283 Make sure any String arguments are properly escaped if they might contain '<' or '&' characters. 284The {@link android.text.TextUtils#htmlEncode} method will do this: 285<pre> 286String escapedTitle = TextUtil.htmlEncode(title); 287</pre> 288</li> 289<li> 290 Use String.format() to format the HTML text, then use {@link android.text.Html#fromHtml} to convert the HTML text into styled text: 291<pre> 292String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat); 293String resultsText = String.format(resultsTextFormat, count, escapedTitle); 294CharSequence styledResults = Html.fromHtml(resultsText); 295</pre> 296</li> 297</ol> 298 299 300<h3 id="dimension"Dimension Values</h3> 301<p>You can create common dimensions to use for various screen elements by 302defining dimension values in XML. A dimension resource is a number followed by 303a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of 304measurement supported by Android:</p> 305<dl> 306 <dt>px</dt> 307 <dd>Pixels - corresponds to actual pixels on the screen.</dd> 308 309 <dt>in</dt> 310 <dd>Inches - based on the physical size of the screen.</dd> 311 312 <dt>mm</dt> 313 <dd>Millimeters - based on the physical size of the screen.</dd> 314 315 <dt>pt</dt> 316 <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd> 317 318 <dt>dp</dt> 319 <dd>Density-independent Pixels - an abstract unit that is based on the 320 physical density of the screen. These units are relative to a 160 dpi 321 screen, so one dp is one pixel on a 160 dpi screen. The ratio of 322 dp-to-pixel will change with the screen density, but not necessarily 323 in direct proportion. <strong>Note:</strong> The compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".</dd> 324 325 <dt>sp</dt> 326 <dd>Scale-independent Pixels - this is like the dp unit, but it is also 327 scaled by the user's font size preference. It is recommend you use this 328 unit when specifying font sizes, so they will be adjusted for both the 329 screen density and user's preference.</dd> 330</dl> 331 332<p>Dimension values are not normally used as raw resources, but rather as 333attribute values in XML files. You can, however, create plain resources 334containing this data type.</p> 335 336<p><strong>Source file format:</strong> XML file requiring a <code><?xml 337version="1.0" encoding="utf-8"?></code> declaration, and a root 338<code><resources></code> element containing one or more 339<code><dimen></code> tags.</p> 340 341<p><strong>Resource source file location</strong>: res/values/dimens.xml (File 342name is arbitrary; standard practice is to put all dimensions in one file 343devoted to dimensions.)</p> 344<p><strong>Compiled resource datatype:</strong> Resource pointer to a 345dimension.</p> 346<p> 347 <strong>Resource reference name:</strong> 348</p> 349<ul> 350 <li> 351 <strong>Java:</strong> <code>R.dimen.<em>some_name</em></code> 352 </li> 353 <li> 354 <strong>XML:</strong> <code>@[<em>package</em>:]dimen/<em>some_name</em></code> (where <em>some_name</em> is the <em>name</em> of a specific <code><dimen></code> element) 355 </li> 356</ul> 357<p> 358 <strong>Syntax</strong> 359</p> 360<pre> 361<dimen name=<em>dimen_name</em>><em>dimen_value</em></dimen> 362</pre> 363<dl> 364 <dt> 365 <dimen> 366 </dt> 367 <dd> 368 A valid dimension value. 369 <ul> 370 <li> 371 <em>name</em> - The name used in referring to this dimension. 372 </li> 373 </ul> 374 </dd> 375</dl> 376<p> 377 <strong>Example XML Declaration</strong> 378</p> 379<p> 380 The following code declares several dimension values. 381</p> 382<pre> 383<resources> 384 <dimen name="one_pixel">1px</dimen> 385 <dimen name="double_density">2dp</dimen> 386 <dimen name="sixteen_sp">16sp</dimen> 387</resources> 388</pre> 389<p> 390 <strong>Example Code Use</strong> 391</p> 392<p> 393 Example Java code: 394</p> 395<pre> 396float dimen = Resources.getDimen(R.dimen.one_pixel); 397</pre> 398<p> 399 Example XML code: 400</p> 401<pre> 402<TextView android:layout_width="fill_parent" 403 android:layout_height="wrap_content" 404 android:textSize="@dimen/sixteen_sp"/> 405</pre> 406 407 408<h2 id="drawables">Drawables</h2> 409 410<p>A {@link android.graphics.drawable.Drawable} is a type of resource that 411you retrieve with {@link android.content.res.Resources#getDrawable 412Resources.getDrawable()} and use to draw to the screen. There are a 413number of drawable resources that can be created.</p> 414 415 416 417<h3 id="imagefileresources">Bitmap Files</h3> 418<p>Android supports bitmap resource files in a few different formats: png 419(preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is 420compiled and referenced by the file name without the extension (so 421res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> 422 423<p> 424 <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file. 425</p> 426<p> 427 <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif. 428</p> 429<p> 430 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}. 431</p> 432<p> 433 <strong>Resource reference name:</strong> 434</p> 435<ul> 436 <li> 437 <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code> 438 </li> 439 <li> 440 <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code> 441 </li> 442</ul> 443 444<p>For more discussion and examples using drawable resources, see the discussion in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#drawable-resource#drawables">2D Graphics</a>.</p> 445 446 447<h3 id="colordrawableresources">Color Drawables</h3> 448<p>You can create a {@link android.graphics.drawable.PaintDrawable} object that is a rectangle of color, 449with optionally rounded corners. This element can be defined in any of the 450files inside res/values/.</p> 451<p><strong>Source file format:</strong> XML file requiring a <code><?xml 452version="1.0" encoding="utf-8"?></code> declaration, and a root 453<code><resources></code> element containing one or more 454<code><drawable></code> tags.</p> 455<p> 456 <strong>Resource source file location</strong>: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.) 457</p> 458<p> 459 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}. 460</p> 461<p> 462 <strong>Resource reference name:</strong> 463</p> 464<ul> 465 <li> 466 <strong>Java:</strong> <code>R.drawable.<em>some_name</em></code> 467 </li> 468 <li> 469 <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_name</em></code> (where <em>some_name</em> is the name of a specific resource) 470 </li> 471</ul> 472<p> 473 <strong>Syntax</strong> 474</p> 475<pre> 476<drawable name=<em>color_name</em>><em>color_value</em></drawable> 477</pre> 478<dl> 479 <dt> 480 <drawable> 481 </dt> 482 <dd> 483 A valid <a href="#colorvals">color value</a>. 484 <ul> 485 <li> 486 <em>name</em> - The name used in referring to this drawable. 487 </li> 488 </ul> 489 </dd> 490</dl> 491<p> 492 <strong>Example XML Declaration</strong> 493</p> 494<p> 495 The following code declares several color drawables. 496</p> 497<pre> 498<resources> 499 <drawable name="solid_red">#f00</drawable> 500 <drawable name="solid_blue">#0000ff</drawable> 501 <drawable name="solid_green">#f0f0</drawable> 502</resources> 503</pre> 504<p> 505 <strong>Example Code Use</strong> 506</p> 507<p> 508 Example Java code 509</p> 510<pre> 511// Assign a PaintDrawable as the background to 512// a TextView on the current screen. 513Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red); 514TextView tv = (TextView)findViewByID(R.id.text); 515tv.setBackground(redDrawable); 516</pre> 517<p> 518 Example XML code 519</p> 520<pre> 521<TextView android:layout_width="fill_parent" 522 android:layout_height="wrap_content" 523 android:textAlign="center" 524 android:background="@drawable/solid_red"/> 525</pre> 526 527 528<h3 id="ninepatch">Nine-Patch (stretchable) Images</h3> 529<p> 530 Android supports a stretchable bitmap image, called a 531 {@link android.graphics.NinePatch} graphic. This is a PNG image in which 532 you define stretchable sections that Android will resize to fit the object 533 at display time to accommodate variable sized sections, such as text strings. 534 You typically assign this resource to the View's background. An example use 535 of a stretchable image is the button backgrounds that Android uses; buttons 536 must stretch to accommodate strings of various lengths. 537</p> 538 539<p> 540 <strong>Source file format:</strong> PNG — one resource per file 541</p> 542<p> 543 <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png) 544</p> 545<p> 546 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}. 547</p> 548<p> 549 <strong>Resource reference name:</strong> 550</p> 551<ul> 552 <li> 553 <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code> 554 </li> 555 <li> 556 <strong>XML:</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code> 557 </li> 558</ul> 559 560 561<p>For more information and examples using NinePatch drawables, see the discussion 562in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a>.</p> 563 564 565 566<h2 id="animation">Animation</h2> 567 568<h3 id="tweenedanimation">Tweened Animation</h3> 569<p> 570 Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching. 571</p> 572<p> 573 <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration 574</p> 575<p> 576 <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml 577</p> 578<p> 579 <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}. 580</p> 581<p> 582 <strong>Resource reference name:</strong> 583</p> 584<ul> 585 <li> 586 <strong>Java:</strong> <code>R.anim.<em>some_file</em></code> 587 </li> 588 <li> 589 <strong>XML:</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code> 590 </li> 591</ul> 592<p> 593 <strong>Syntax</strong> 594</p> 595<p> 596 The file must have a single root element: this will be either a single <code><alpha></code>, <code><scale></code>, <code><translate></code>, <code><rotate></code>, interpolator element, or <code><set></code> element that holds groups of these elements (which may include another <code><set></code>). By default, all elements are applied simultaneously. To have them occur sequentially, you must specify the <code>startOffset</code> attribute. 597</p> 598<pre> 599<set android:shareInterpolator=boolean> // Only required if multiple tags are used. 600 <alpha android:fromAlpha=float 601 android:toAlpha=float > | 602 <scale android:fromXScale=float 603 android:toXScale=float 604 android:fromYScale=float 605 android:toYScale=float 606 android:pivotX=string 607 android:pivotY=string > | 608 <translate android:fromX=string 609 android:toX=string 610 android:fromY=string 611 android:toY=string > | 612 <rotate android:fromDegrees=float 613 android:toDegrees=float 614 android:pivotX=string 615 android:pivotY=string > | 616 <<em>interpolator tag</em>> 617 <set> 618</set> 619</pre> 620<p> 621 <strong>Elements and Attributes</strong> 622</p> 623<dl> 624 <dt> 625 <set> 626 </dt> 627 <dd> 628 A container that can recursively hold itself or other animations. 629 Represents an {@link android.view.animation.AnimationSet}. 630 You can include as many child elements of the same or different types as you like. 631 Supports the following attribute: 632 <ul> 633 <li> 634 <em>shareInterpolator</em> - Whether to share the same Interpolator among all immediate child elements. 635 </li> 636 </ul> 637 </dd> 638 <dt> 639 <alpha> 640 </dt> 641 <dd> 642 A fading animation. Represents an {@link android.view.animation.AlphaAnimation}. 643 Supports the following attributes: 644 <ul> 645 <li> 646 <em>fromAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. 647 </li> 648 <li> 649 <em>toAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. 650 </li> 651 </ul> 652 </dd> 653 <dt> 654 <scale> 655 </dt> 656 <dd> 657 A resizing animation. Represents a {@link android.view.animation.ScaleAnimation}. 658 You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. <code>scale</code> supports the following attributes: 659 <ul> 660 <li> 661 <em>fromXScale</em> - Starting X size, where 1.0 is no change. 662 </li> 663 <li> 664 <em>toXScale</em> - Ending X size, where 1.0 is no change. 665 </li> 666 <li> 667 <em>fromYScale</em> - Starting Y size, where 1.0 is no change. 668 </li> 669 <li> 670 <em>toYScale</em> - Ending Y size, where 1.0 is no change. 671 </li> 672 <li> 673 <em>pivotX</em> - The X coordinate of the pinned center. 674 </li> 675 <li> 676 <em>pivotY</em> - The Y coordinate of the pinned center. 677 </li> 678 </ul> 679 </dd> 680 <dt> 681 <translate> 682 </dt> 683 <dd> 684 A vertical/horizontal motion animation. 685 Represents a {@link android.view.animation.TranslateAnimation}. 686Supports the following attributes in any of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself; values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix, indicating an absolute value. 687 <ul> 688 <li> 689 <em>fromXDelta</em> - Starting X location. 690 </li> 691 <li> 692 <em>toXDelta</em> - Ending X location. 693 </li> 694 <li> 695 <em>fromYDelta</em> - Starting Y location. 696 </li> 697 <li> 698 <em>toYDelta</em> - Ending Y location. 699 </li> 700 </ul> 701 </dd> 702 <dt> 703 <rotate> 704 </dt> 705 <dd> 706 A rotation animation. Represents a {@link android.view.animation.RotateAnimation}. 707 Supports the following attributes: 708 <ul> 709 <li> 710 <em>fromDegrees</em> - Starting rotation, in degrees. 711 </li> 712 <li> 713 <em>toDegrees</em> - Ending rotation, in degrees. 714 </li> 715 <li> 716 <em>pivotX</em> - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. 717 </li> 718 <li> 719 <em>pivotY</em> - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. 720 </li> 721 </ul> 722 </dd> 723 <dt> 724 <em><interpolator tag></em> 725 </dt> 726 <dd> 727 You can also use any of the interpolator subclass elements defined in {@link android.R.styleable}. Examples include <CycleInterpolator>, <EaseInInterpolator>, and <EaseOutInterpolator>. These objects define a velocity curve that describes how quickly a visual action takes place on a timeline (fast at first and slow later, slow at first and gradually faster, and so on). 728 </dd> 729</dl> 730<p> 731In addition to the attributes defined for each element above, the elements 732<code><alpha></code>, <code><scale></code>, <code><translate></code>, 733<code><rotate></code>, and <code><set></code> all support the following attributes (inherited 734from the {@link android.view.animation.Animation} class): 735</p> 736<dl> 737 <dt><em>{@link android.R.attr#duration duration}</em></dt> 738 <dd> 739 Duration, in milliseconds, for this effect. 740 </dd> 741 <dt><em>{@link android.R.attr#startOffset startOffset}</em></dt> 742 <dd> 743 Offset start time for this effect, in milliseconds. 744 </dd> 745 <dt><em>{@link android.R.attr#fillBefore fillBefore}</em></dt> 746 <dd> 747 When set true, the animation transformation is applied before the animation begins. 748 </dd> 749 <dt><em>{@link android.R.attr#fillAfter fillAfter}</em></dt> 750 <dd> 751 When set true, the animation transformation is applied after the animation ends. 752 </dd> 753 <dt><em>{@link android.R.attr#repeatCount repeatCount}</em></dt> 754 <dd> 755 Defines the number of times the animation should repeat. 756 </dd> 757 <dt><em>{@link android.R.attr#repeatMode repeatMode}</em></dt> 758 <dd> 759 Defines the animation behavior when it reaches the end and the repeat count is greater than 0. 760 Options are to either restart or reverse the animation. 761 </dd> 762 <dt><em>{@link android.R.attr#zAdjustment zAdjustment}</em></dt> 763 <dd> 764 Defines the z-axis ordering mode to use when running the animation (normal, top, or bottom). 765 </dd> 766 <dt><em>{@link android.R.attr#interpolator interpolator}</em></dt> 767 <dd> 768 You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for EaseOutInterpolator. A list of interpolators is given in {@link android.R.anim}. To specify these, use the syntax @android:anim/<em>interpolatorName</em>. 769 </dd> 770</dl> 771 772<p>For more discussion and animation code samples, see the discussion in the 773<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#tween-animation">2D Graphics</a> document.</p> 774 775 776 777<h2 id="menus">Menus</h2> 778<p>Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as 779XML resources and inflated by your application using {@link android.view.MenuInflater}.</p> 780 781<p><strong>Source file format:</strong> XML file, one resource per file, one root tag, 782<code><?xml></code> declaration not required.</p> 783<p><strong>Resource file location:</strong> res/menu/<em>some_file</em>.xml</p> 784<p><strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.Menu} (or subclass) resource.</p> 785<p><strong>Resource reference name:</strong> </p> 786<ul><li><strong>Java:</strong> <code>R.menu.<em>some_file</em></code></li></ul> 787 788<h3>Syntax</h3> 789<p>The file must have a single root element: a <code><menu></code> element. In all, 790there are three valid elements: <code><menu></code>, <code><group></code> and <code><item></code>. The 791<code><item></code> and <code><group></code> elements must be the children of a <code><menu></code>, but <code><item></code> 792elements can also be the children of a <code><group></code>, and another <code><menu></code> element may be the child 793of an <code><item></code> (to create a Sub Menu).</p> 794<pre> 795<menu xmlns:android="http://schemas.android.com/apk/res/android"> 796 797 <item android:id="@+id/<em>example_item</em> 798 android:title="<em>Example Item</em>" 799 android:icon="<em>@drawable/example_item_icon</em>" /> 800 801 <group android:id="@+id/<em>example_group</em>"> 802 <item android:id="@+id/<em>example_item2</em> 803 android:title="<em>Example Item 2</em>" 804 android:icon="<em>@drawable/example_item2_icon</em>" /> 805 </group> 806 807 <item android:id="@+id/<em>example_submenu</em> 808 android:title="<em>Example Sub Menu</em>" > 809 <menu> 810 <item android:id="@+id/<em>example_submenu_item</em> 811 android:title="<em>Example Sub Menu Item</em>" /> 812 </menu> 813 </item> 814 815</menu> 816</pre> 817 818<h3>Elements and Attributes</h3> 819<p>All attributes must be defined with the <em>android</em> namespace (e.g., <em>android:icon="@drawable/icon"</em>).</p> 820<dl> 821 <dt><menu></dt> 822 <dd>The root of a menu. Contains <code><item></code> and <code><group></code> nodes. No attributes.</dd> 823 <dt><group></dt> 824 <dd>A menu group. Contains <code><item></code> elements. Valid attributes: 825 <ul> 826 <li><em>id</em> - A unique integer ID for the group.</li> 827 <li><em>menuCategory</em> - Value corresponding to Menu CATEGORY_* constants — defines the priority of the group. Valid values: 828 <em>container</em>, <em>system</em>, <em>secondary</em>, and <em>alternative</em>.</li> 829 <li><em>orderInCategory</em> - An integer that defines the default order of the items within the category.</li> 830 <li><em>checkableBehavior</em> - Whether the items are checkable. Valid values: 831 <em>none</em>, <em>all</em> (exclusive / radio buttons), <em>single</em> (non-exclusive / checkboxes)</li> 832 <li><em>visible</em> - Whether the group is visible. <em>true</em> or <em>false</em>.</li> 833 <li><em>enabled</em> - Whether the group is enabled. <em>true</em> or <em>false</em>.</li> 834 </ul> 835 </dd> 836 <dt><item></dt> 837 <dd>A menu item. May contain a <code><menu></code> element (for a Sub Menu). Valid attributes: 838 <ul> 839 <li><em>id</em> - A unique resource ID for the item.</li> 840 <li><em>menuCategory</em> - Used to define the menu category.</li> 841 <li><em>orderInCategory</em> - Used to define the order of the item, within a group.</li> 842 <li><em>title</em> - A string for the menu title.</li> 843 <li><em>titleCondensed</em> - A condensed string title, for situations in which the normal title is too long.</li> 844 <li><em>icon</em> - A resource identifier for a drawable icon.</li> 845 <li><em>alphabeticShortcut</em> - A character for the alphabetic shortcut key.</li> 846 <li><em>numericShortcut</em> - A number for the numeric shortcut key.</li> 847 <li><em>checkable</em> - Whether the item is checkable. <em>true</em> or <em>false</em>.</li> 848 <li><em>checked</em> - Whether the item is checked by default. <em>true</em> or <em>false</em>.</li> 849 <li><em>visible</em> - Whether the item is visible by default. <em>true</em> or <em>false</em>.</li> 850 <li><em>enabled</em> - Whether the item is enabled by default. <em>true</em> or <em>false</em>.</li> 851 </ul> 852 </dd> 853</dl> 854 855<p>For more discussion on how to create menus in XML and inflate them in your application, 856read <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.</p> 857 858 859 860<h2 id="layoutresources">Layout</h2> 861<p>Android lets you specify screen layouts using XML elements inside an XML 862file, similar to designing screen layout for a webpage in an HTML file. Each 863file contains a whole screen or a part of a screen, and is compiled into a 864View resource that can be passed in to 865{@link android.app.Activity#setContentView(int) Activity.setContentView} or used as a 866reference by other layout resource elements. Files are saved in the 867<code>res/layout/</code> folder of your project, and compiled by the Android resource 868compiler, aapt. </p> 869 870<p> Every layout XML file must evaluate to a single root 871element. First we'll describe how to use the standard XML tags understood by 872Android as it is shipped, and then we'll give a little information on how you 873can define your own custom XML elements for custom View objects. 874 875<p> The root element must have 876the Android namespace "http://schemas.android.com/apk/res/android" defined in 877the root element.</p> 878 879<p>For a complete discussion on creating layouts, see the 880<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> topic.</p> 881 882<p> <strong>Source file format:</strong> XML file 883requiring a <code><?xml version="1.0" encoding="utf-8"?></code> 884declaration, and a root element of one of the supported XML layout elements. 885</p> 886 887 888<p><strong>Resource file location</strong>: 889res/layout/<em>some_file</em>.xml.</p> 890<p> 891 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. 892</p> 893<p> 894 <strong>Resource reference name:</strong> 895</p> 896<ul> 897 <li> 898 <strong>Java:</strong> <code>R.layout.<em>some_file</em></code> 899 </li> 900 <li> 901 <strong>XML:</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code> 902 </li> 903</ul> 904<p> 905 <strong>Syntax</strong> 906</p> 907<pre> 908<<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android" 909 id="@+id/<em>string_name</em>" (attributes)> 910 <<em>widget</em> or other nested <em>ViewGroupClass</em>>+ 911 <requestFocus/>(0 or 1 per layout file, assigned to any element) 912</<em>ViewGroupClass</em>> 913</pre> 914<dl> 915 <dt> 916 <<em>ViewGroupClass</em>> 917 </dt> 918 <dd> 919 <p>The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android {@link android.widget widget} or {@link android.view.ViewGroup ViewGroup} class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <code><TextView></code> elements inside a <code><ListLayout></code>).</p> 920 <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <code><TextView id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> 921 <ul> 922 <li> 923 <em>id</em> - An ID value used to access this element in Java. Typically you will use the syntax @+id/<em>string_name</em> to generate an ID for you in the id.xml file if you haven't created one yourself. 924 </li> 925 <li> 926 <code>xmlns:android="http://schemas.android.com/apk/res/android"</code> - <em><strong>Required for the root element only.</strong></em> 927 </li> 928 </ul> 929 </dd> 930 <dt> 931 <requestFocus> 932 </dt> 933 <dd> 934 Any element representing a View object can include this empty element, which gives it's parent tag initial focus on the screen. You can have only one of these elements per file. 935 </dd> 936</dl> 937<p> 938 <strong>What Attributes Are Supported for What Elements?</strong> 939</p> 940<p> 941 Android uses the {@link android.view.LayoutInflater} class at run time to load an XML layout resource and translate it into visual elements. By default, all widget class names are supported directly as tags, but a full list of supported tags and attributes is listed in the {@link android.R.styleable} reference page. However, the attribute names are somewhat obscure. If an underscore appears in the name, this indicates that it is an attribute — typically of the element before the underscore. So, for example, <code>EditText_autoText</code> means that the <code><EditText></code> tag supports an attribute <em>autoText</em>. When you actually use the attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix "<code>android:</code>". So, for example, if {@link android.R.styleable} lists the following values: 942</p> 943<ul> 944 <li> 945 <code>TextView</code> 946 </li> 947 <li> 948 <code>TextView_lines</code> 949 </li> 950 <li> 951 <code>TextView_maxlines</code> 952 </li> 953</ul> 954<p> 955 You could create an element like this: 956</p> 957<pre> 958<TextView android:lines="10" android:maxlines="20"/> 959</pre> 960<p> 961 This would create a {@link android.widget.TextView} object and set its lines and maxlines properties. 962</p> 963<p> 964 Attributes come from three sources: 965</p> 966<ul> 967 <li> 968 <strong>Attributes exposed directly by the element.</strong> For example, <code>TextView</code> supports <code>TextView_text</code>, as discussed above. 969 </li> 970 <li> 971 <strong>Attributes exposed by all the superclasses of that element.</strong> For example, the TextView class extends the View class, so the <code><TextView></code> element supports all the attributes that the <code><View></code> element exposes — a long list, including <code>View_paddingBottom</code> and <code>View_scrollbars</code>. These too are used without the class name: <code><TextView android:paddingBottom="20" android:scrollbars="horizontal" /></code>. 972 </li> 973 <li> 974 <strong>Attributes of the object's {@link android.view.ViewGroup.LayoutParams} subclass.</strong> All View objects support a LayoutParams member (see <a href="{@docRoot}guide/topics/ui/declaring-layout.html#layout-params">Declaring Layout</a>). To set properties on an element's LayoutParams member, the attribute to use is "android:layout_<em>layoutParamsProperty</em>". For example: <code>android:layout_gravity</code> for an object wrapped by a <code><LinearLayout></code> element. Remember that each LayoutParams subclass also supports inherited attributes. Attributes exposed by each subclass are given in the format <em>someLayoutParamsSubclass</em>_Layout_layout_<em>someproperty</em>. This defines an attribute "android:layout_<em>someproperty</em>". Here is an example of how Android documentation lists the properties of the {@link android.widget.LinearLayout.LayoutParams LinearLayout.LayoutParams} class: 975 </li> 976</ul> 977<ul> 978 <li>LinearLayout_Layout // The actual object — not used. 979 </li> 980 <li>LinearLayout_Layout_layout_gravity // Exposes a <code>gravity</code> attribute 981 </li> 982 <li>LinearLayout_Layout_layout_height // Exposes a <code>height</code> attribute 983 </li> 984 <li>LinearLayout_Layout_layout_weight // Exposes a <code>weight</code> attribute 985 </li> 986 <li>LinearLayout_Layout_layout_width // Exposes a <code>width</code> attribute 987 </li> 988</ul> 989<p> 990 Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes: 991</p> 992<pre> 993<?xml version="1.0" encoding="utf-8"?> 994<!-- res/main_screen.xml --> 995<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 996 android:orientation="vertical" // The object's own orientation property 997 android:padding="4" // Inherited View property 998 android:gravity="center" // The object's own property 999 android:layout_width="fill_parent" // Parent object's LinearLayout.LayoutParams.width 1000 android:layout_height="fill_parent"> // Parent object's LinearLayout.LayoutParams.height 1001 1002 <TextView android:layout_width="fill_parent" // TextView.LayoutParams.width 1003 android:layout_height="wrap_content" // TextView.LayoutParams.height 1004 android:layout_weight="0" // TextView.LayoutParams.weight 1005 android:paddingBottom="4" // TextView.paddingBottom 1006 android:text="@string/redirect_getter"/> // TextView.text 1007 1008 <EditText id="@+id/text" 1009 android:layout_width="fill_parent" // EditText.LayoutParams.width 1010 android:layout_height="wrap_content" // EditText.LayoutParams.height 1011 android:layout_weight="0" // EditText.LinearLayoutParams.weight 1012 android:paddingBottom="4"> // EditText.paddingBottom 1013 <requestFocus /> 1014 </EditText> 1015 1016 <Button id="@+id/apply" 1017 android:layout_width="wrap_content" // Button.LayoutParams.width 1018 android:layout_height="wrap_content" // Button.LayoutParams.height 1019 android:text="@string/apply" /> // TextView.text 1020</LinearLayout> 1021</pre> 1022<p> 1023 <strong>Example Code Use</strong> 1024</p> 1025<p> 1026 The most common use is to load the XML file (located at <em>res/main_screen.xml</em>) and use it as the current screen, as shown here with the preceding file: 1027</p> 1028<pre> 1029setContentView(R.layout.main_screen); 1030</pre> 1031<p> 1032 However, layout elements can also represent repeating elements used as templates. 1033</p> 1034 1035<p>Also see <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for more information on layouts.</p> 1036 1037 1038 1039<h3 id="customresources">Custom Layout Resources</h3> 1040<p> 1041 You can define custom elements to use in layout resources. These custom elements can then be used the same as any Android layout elements: that is, you can use them and specify their attributes in other resources. The ApiDemos sample application has an example of creating a custom layout XML tag, LabelView. To create a custom element, you will need the following files: 1042</p> 1043<ul> 1044 <li> 1045 <strong>Java implementation file</strong> - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos. 1046 </li> 1047 <li> 1048 <strong>res/values/attrs.xml</strong> - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <code><declare-styleable id=<em>your_java_class_name</em>></code>. See res/layout/attrs.xml in ApiDemos. 1049 </li> 1050 <li> 1051 <strong>res/layout/<em>your_class</em>.xml</strong> [<em>optional</em>] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos. 1052 </li> 1053</ul> 1054<p> 1055 <strong>Source file format:</strong> XML file without an <code><?xml></code> declaration, and a <code><resources></code> root element containing one or more custom element tags. 1056</p> 1057<p> 1058 <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary). 1059</p> 1060<p> 1061 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. 1062</p> 1063<p> 1064 <strong>Resource reference name:</strong> R.styleable.<em>some_file</em> (Java). 1065</p> 1066 1067 1068 1069<h2 id="stylesandthemes">Styles and Themes</h2> 1070<p> 1071 A <em>style</em> is one or more attributes applied to a single element (for example, 10 point red Arial font, applied to a TextView). A style is applied as an attribute to an element in a layout XML file. 1072</p> 1073<p> 1074 A <em>theme</em> is one or more attributes applied to a whole screen — for example, you might apply the stock Android Theme.dialog theme to an activity designed to be a floating dialog box. A theme is assigned as an attribute to an Activity in the manifest file. 1075</p> 1076<p> 1077 Both styles and themes are defined in a <code><style></code> block containing one or more string or numerical values (typically color values), or references to other resources (drawables and so on). These elements support inheritance, so you could have MyBaseTheme, MyBaseTheme.Fancy, MyBaseTheme.Small, and so on. 1078</p> 1079 1080<p>For a complete discussion on styles and themes, read 1081<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> 1082 1083<p> 1084 <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><style></code> tags. 1085</p> 1086<p> 1087 <strong>Resource source file location</strong>: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard practice is to put all styles into a file named styles.xml. 1088</p> 1089<p> 1090 <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. 1091</p> 1092<p> 1093 <strong>Resource reference name:</strong> 1094</p> 1095<ul> 1096 <li> 1097 <strong>Java:</strong> <code>R.style.<em>styleID</em></code> for the whole style, <code>R.style.<em>styleID</em>.<em>itemID</em></code> for an individual setting 1098 </li> 1099 <li> 1100 <strong>XML:</strong> <code>@[<em>package</em>:]style/<em>styleID</em></code> for a whole style, <code>@[<em>package</em>:]style/<em>styleID</em>/<em>itemID</em></code> for an individual item. <strong>Note</strong>: to refer to a value in the <em>currently</em> applied theme, use "?" instead of "@" as described below (XML). 1101 </li> 1102</ul> 1103<p> 1104 <strong>Syntax</strong> 1105</p> 1106<pre> 1107<style name=<em>string</em> [parent=<em>string</em>] > 1108 <item name=<em>string</em>><em>Hex value | string value | reference</em></item>+<em> 1109</em></style> 1110</pre> 1111<dl> 1112 <dt> 1113 <style> 1114 </dt> 1115 <dd> 1116 Holds one or more <item> elements, each describing one value. This style, which is a bundle of values, can be referred to as a <em>theme</em>. 1117 <ul> 1118 <li> 1119 <em>name</em> - The name used in referring to this theme. 1120 </li> 1121 <li> 1122 <em>parent</em> - An optional parent theme. All values from the specified theme will be inherited into this theme. Any values with identical names that you specify will override inherited values. The name must be qualified by the package, but you don't need the /style directive (for example, <code>android:Theme</code> for the base Android theme, or <code>MyTheme</code> for a theme defined in your package). 1123 </li> 1124 </ul> 1125 </dd> 1126 <dt> 1127 <item> 1128 </dt> 1129 <dd> 1130 A value to use in this theme. It can be a standard string, a hex color value, or a reference to any other resource type. 1131 </dd> 1132</dl> 1133 1134<p>For examples of how to declare and apply styles and themes, read 1135<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> 1136
