available-resources.jd revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c
1page.title=Available Resource Types 2@jd:body 3 4<p>This page describes the different types of resources that you can 5externalize from your code and package with your application. They fall into 6the following groups:</p> 7<ul> 8 <li><a href="#simplevalues">Simple Values</a></li> 9 <li><a href="#drawables">Drawables</a></li> 10 <li><a href="#animation">Animation</a></li> 11 <li><a href="#layoutresources">Layout</a></li> 12 <li><a href="#stylesandthemes">Styles and Themes</a></li> 13</ul> 14 15<p>For more details on how to use resources in your application, please see the 16 <a href="{@docRoot}devel/resources-i18n.html">Resources and i18n</a> 17 documentation.</p> 18 19<a name="simplevalues" id="simplevalues"></a> 20<h2>Simple Values</h2> 21 22<p>All simple resource values can be expressed as a string, using various 23formats to unambiguously indicate the type of resource being created. For 24this reason, these values can be defined both as standard resources 25(under res/values), as well as direct values supplied for 26mappings in <a href="#stylesandthemes">styles and themes</a>, and attributes in 27XML files such as <a href="#layoutresources">layouts</a>.</p> 28 29<ul> 30 <li><a href="#colorvals">Colors</a></li> 31 <li><a href="#stringresources">Strings and Styled Text</a></li> 32 <li><a href="#dimension">Dimensions</a></li> 33</ul> 34 35 36<a name="colorvals" id="colorvals"></a> 37<h3>Color Values</h3> 38<p> 39 A color value specifies an RGB value with an alpha channel, which can 40 be used in various places such as specifying a solid color for a Drawable 41 or the color to use for text. A color value always begins with 42 a '#' character and then is followed by the alpha-red-green-blue information 43 in one of the following formats: 44</p> 45<ul> 46<li> #RGB 47<li> #ARGB 48<li> #RRGGBB 49<li> #AARRGGBB 50</ul> 51<p> 52 If you want to retrieve the color represented by a resource ID, you can call 53 the {@link android.content.res.Resources#getColor(int) Resources.getColor()} method. 54</p> 55<p> 56 <strong>Source file format:</strong> XML file requiring a 57 <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and 58 a root <code><resources></code> element containing one or more 59 <code><color></code> tags. 60</p> 61<p> 62 <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary) 63</p> 64<p> 65 <strong>Compiled resource datatype:</strong> Resource pointer to a Java int. 66</p> 67<p> 68 <strong>Resource reference name:</strong> 69</p> 70<ul> 71 <li> 72 <strong>Java</strong> <code>R.color.<em>some_name</em></code> 73 </li> 74 <li> 75 <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) 76 </li> 77</ul> 78<p> 79 <strong>Syntax</strong> 80</p> 81<pre> 82<color name=<em>color_name</em>><em>#color_value</em></color> 83</pre> 84<dl> 85 <dt> 86 <color> 87 </dt> 88 <dd> 89 Value is a color, using web-style syntax, as describe above. Has only one attribute: 90 <ul> 91 <li> 92 <em>name</em> - The name used in referring to this color. 93 </li> 94 </ul> 95 </dd> 96</dl> 97<p> 98 <strong>Example XML Declaration</strong> 99</p> 100<p> 101 The following code declares two colors, the first fully opaque, and the 102 second translucent. 103</p> 104<pre> 105<resources> 106 <color name="opaque_red">#f00</color> 107 <color name="translucent_red">#80ff0000</color> 108</resources> 109</pre> 110<p> 111 <strong>Example Code Use</strong> 112</p> 113<p> 114 Example Java code 115</p> 116<pre> 117// Retrieve a color value. 118int color = getResources.getColor(R.color.opaque_red); 119</pre> 120<p> 121 Example XML code 122</p> 123<pre> 124<TextView android:layout_width="fill_parent" 125 android:layout_height="wrap_content" 126 android:textAlign="center" 127 android:textColor="@color/translucent_red" 128 android:text="Some Text"/> 129</pre> 130 131<a name="stringresources" id="stringresources"></a> 132<h3>Strings and Styled Text</h3> 133<p> 134 Strings, with optional <a href="#styledtext">simple formatting</a>, can be 135stored and retrieved as resources. You can add formatting to your string by 136using three standard HTML tags: <b>, <i>, and <u>. To 137guarantee getting an unstyled string only (the raw text) call the 138<code>toString()</code> method of the retrieved CharSequence object. 139Methods that accept string resources should be able to process these styling 140tags. 141</p> 142<p> 143 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. 144</p> 145<p> 146 <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: 147</p> 148<pre> 149<string name="good_example">"This'll work"</string> 150<string name="good_example_2">This\'ll also work</string> 151<string name="bad_example">This won't work!</string> 152<string name="bad_example_2">XML encodings won&apos;t work either!</string> 153</pre> 154<p> 155 <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. 156</p> 157<p> 158 <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary) 159</p> 160<p> 161 <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. 162</p> 163<p> 164 <strong>Resource reference name:</strong> 165</p> 166<ul> 167 <li> 168 <strong>Java</strong> <code>R.string.<em>some_name</em></code> 169 </li> 170 <li> 171 <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) 172 </li> 173</ul> 174<p> 175 <strong>Syntax</strong> 176</p> 177<pre> 178<string name=<em>string_name</em>><em>string_value</em></string> 179</pre> 180<dl> 181 <dt> 182 <string> 183 </dt> 184 <dd> 185 Value is a string, with optional styling tags. Has only one attribute: 186 <ul> 187 <li> 188 <em>name</em> - The name used in referring to this string. 189 </li> 190 </ul> 191 </dd> 192</dl> 193<p> 194 <strong>Example XML Declaration</strong> 195</p> 196<p> 197 The following declares two strings: the first — simple text with no 198 formatting (resulting in a CharSequence that is simply a String object) — the second includes formatting information in the string (resulting 199 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 retreive the resource and then convert it to formatted text. 200</p> 201<pre> 202<resources> 203 <string name="simple_welcome_message">Welcome!</string> 204 <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see you.</string> 205</resources> 206</pre> 207<p> 208 <strong>Example Code Use</strong> 209</p> 210<p> 211 Example Java code 212</p> 213<pre> 214// Assign a styled string resource to a TextView 215// on the current screen. 216CharSequence str = getString(R.string.styled_welcome_message); 217TextView tv = (TextView)findViewByID(R.id.text); 218tv.setText(str); 219</pre> 220<p> 221 Example XML code 222</p> 223<pre> 224<TextView android:layout_width="fill_parent" 225 android:layout_height="wrap_content" 226 android:textAlign="center" 227 android:text="@string/simple_welcome_message"/> 228</pre> 229 230<a name="styledtext" id="styledtext"></a> 231<h4>Using Styled Text as a Format String</h4> 232<p> 233Sometimes you may want to create a styled text resource that is also used as a 234format string. This cannot be done directly because there is no way of passing 235the styled text as the format string argument of String.format() 236without stripping out the style information. The workaround is to store the 237style tags as escaped HTML tags, and then convert the escaped HTML string into 238a styled text after formatting has taken place. 239</p> 240<p> 241To use styled text as a format string, do the following. 242</p> 243<ol> 244 <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: 245<pre> 246<resources> 247 <string name="search_results_resultsTextFormat">%1$d results for &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string> 248</resources> 249</pre> 250<p> 251In this example the format string has two arguments: <code>%1$d</code> is a decimal number, <code>%2$s</code> is a string. 252</p> 253</li> 254<li> 255 Make sure any String arguments are properly escaped if they might contain '<' or '&' characters. 256The {@link android.text.TextUtils#htmlEncode} method will do this: 257<pre> 258String escapedTitle = TextUtil.htmlEncode(title); 259</pre> 260</li> 261<li> 262 Use String.format() to format the HTML text, then use {@link android.text.Html#fromHtml} to convert the HTML text into styled text: 263<pre> 264String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat); 265String resultsText = String.format(resultsTextFormat, count, escapedTitle); 266CharSequence styledResults = Html.fromHtml(resultsText); 267</pre> 268</li> 269</ol> 270 271<a name="dimension" id="dimension"></a> 272<h3>Dimension Values</h3> 273<p>You can create common dimensions to use for various screen elements by 274defining dimension values in XML. A dimension resource is a number followed by 275a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of 276measurement supported by Android:</p> 277<dl> 278 <dt>px</dt> 279 <dd>Pixels - corresponds to actual pixels on the screen.</dd> 280 281 <dt>in</dt> 282 <dd>Inches - based on the physical size of the screen.</dd> 283 284 <dt>mm</dt> 285 <dd>Millimeters - based on the physical size of the screen.</dd> 286 287 <dt>pt</dt> 288 <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd> 289 290 <dt>dp</dt> 291 <dd>Density-independent Pixels - an abstract unit that is based on the 292 physical density of the screen. These units are relative to a 160 dpi 293 screen, so one dp is one pixel on a 160 dpi screen. The ratio of 294 dp-to-pixel will change with the screen density, but not necessarily 295 in direct proportion. <strong>Note:</strong> The compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".</dd> 296 297 <dt>sp</dt> 298 <dd>Scale-independent Pixels - this is like the dp unit, but it is also 299 scaled by the user's font size preference. It is recommend you use this 300 unit when specifying font sizes, so they will be adjusted for both the 301 screen density and user's preference.</dd> 302</dl> 303 304<p>Dimension values are not normally used as raw resources, but rather as 305attribute values in XML files. You can, however, create plain resources 306containing this data type.</p> 307 308<p><strong>Source file format:</strong> XML file requiring a <code><?xml 309version="1.0" encoding="utf-8"?></code> declaration, and a root 310<code><resources></code> element containing one or more 311<code><dimen></code> tags.</p> 312 313<p><strong>Resource source file location</strong>: res/values/dimens.xml (File 314name is arbitrary; standard practice is to put all dimensions in one file 315devoted to dimensions.)</p> 316<p><strong>Compiled resource datatype:</strong> Resource pointer to a 317dimension.</p> 318<p> 319 <strong>Resource reference name:</strong> 320</p> 321<ul> 322 <li> 323 <strong>Java</strong> <code>R.dimen.<em>some_name</em></code> 324 </li> 325 <li> 326 <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) 327 </li> 328</ul> 329<p> 330 <strong>Syntax</strong> 331</p> 332<pre> 333<dimen name=<em>dimen_name</em>><em>dimen_value</em></dimen> 334</pre> 335<dl> 336 <dt> 337 <dimen> 338 </dt> 339 <dd> 340 A valid dimension value. 341 <ul> 342 <li> 343 <em>name</em> - The name used in referring to this dimension. 344 </li> 345 </ul> 346 </dd> 347</dl> 348<p> 349 <strong>Example XML Declaration</strong> 350</p> 351<p> 352 The following code declares several dimension values. 353</p> 354<pre> 355<resources> 356 <dimen name="one_pixel">1px</dimen> 357 <dimen name="double_density">2dp</dimen> 358 <dimen name="sixteen_sp">16sp</dimen> 359</resources> 360</pre> 361<p> 362 <strong>Example Code Use</strong> 363</p> 364<p> 365 Example Java code: 366</p> 367<pre> 368float dimen = Resources.getDimen(R.dimen.one_pixel); 369</pre> 370<p> 371 Example XML code: 372</p> 373<pre> 374<TextView android:layout_width="fill_parent" 375 android:layout_height="wrap_content" 376 android:textSize="@dimen/sixteen_sp"/> 377</pre> 378 379<a name="drawables" id="drawables"></a> 380<h2>Drawables</h2> 381 382<p>A {@link android.graphics.drawable.Drawable} is a type of resource that 383you retrieve with {@link android.content.res.Resources#getDrawable 384Resources.getDrawable()} and use to draw to the screen. There are a 385number of drawable resources that can be created.</p> 386 387<ul> 388 <li><a href="#imagefileresources">Bitmap Drawables</a></li> 389 <li><a href="#colordrawableresources">Color Drawables</a></li> 390 <li><a href="#ninepatch">Nine Patch (Stretchable) Drawables</a></li> 391</ul> 392 393<a name="imagefileresources" id="imagefileresources"></a> 394<h3>Bitmap files</h3> 395<p>Android supports bitmap resource files in a few different formats: png 396(preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is 397compiled and referenced by the file name without the extension (so 398res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> 399 400<p> 401 <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file. 402</p> 403<p> 404 <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif. 405</p> 406<p> 407 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}. 408</p> 409<p> 410 <strong>Resource reference name:</strong> 411</p> 412<ul> 413 <li> 414 <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> 415 </li> 416 <li> 417 <strong>XML</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code> 418 </li> 419</ul> 420<p> 421 <strong>Example Code Use</strong> 422</p> 423<p> 424 The following Java snippet demonstrates loading an {@link android.widget.ImageView ImageView} object with a single bitmap from a list of bitmap resources. ImageView is a basic display rectangle for graphics (animations or still images). 425</p> 426<pre> 427// Load an array with BitmapDrawable resources. 428private Integer[] mThumbIds = { 429 R.drawable.sample_thumb_0, 430 R.drawable.sample_thumb_1, 431 R.drawable.sample_thumb_2, 432 R.drawable.sample_thumb_3, 433 R.drawable.sample_thumb_4 434}; 435 436// Load and return a view with an image. 437public View getView(int position, ViewGroup parent) 438{ 439 ImageView i = new ImageView(mContext); 440 i.setImageResource(mThumbIds[position]); 441 i.setAdjustViewBounds(true); 442 i.setLayoutParams(new Gallery.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)); 443 i.setBackground(android.R.drawable.picture_frame); 444 return i; 445} 446</pre> 447<p> 448 This XML example demonstrates loading a bitmap file (chat_icon.png) in an ImageView. 449</p> 450<pre> 451<ImageView id="@+id/icon" 452 android:layout_width="wrap_content" 453 android:layout_height="wrap_content" 454 android:tint="#FF000000" 455 android:src="@drawable/chat_icon"/> 456</pre> 457 458<a name="colordrawableresources" id="colordrawableresources"></a> 459<h3>Color Drawables</h3> 460<p>You can create a {@link android.graphics.drawable.PaintDrawable} object that is a rectangle of color, 461with optionally rounded corners. This element can be defined in any of the 462files inside res/values/.</p> 463<p><strong>Source file format:</strong> XML file requiring a <code><?xml 464version="1.0" encoding="utf-8"?></code> declaration, and a root 465<code><resources></code> element containing one or more 466<code><drawable></code> tags.</p> 467<p> 468 <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="{@docRoot}devel/resources-i18n.html#numericcolorresources">numeric color values</a>.) 469</p> 470<p> 471 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}. 472</p> 473<p> 474 <strong>Resource reference name:</strong> 475</p> 476<ul> 477 <li> 478 <strong>Java</strong> <code>R.drawable.<em>some_name</em></code> 479 </li> 480 <li> 481 <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) 482 </li> 483</ul> 484<p> 485 <strong>Syntax</strong> 486</p> 487<pre> 488<drawable name=<em>color_name</em>><em>color_value</em></drawable> 489</pre> 490<dl> 491 <dt> 492 <drawable> 493 </dt> 494 <dd> 495 A valid <a href="#colorvals">color value</a>. 496 <ul> 497 <li> 498 <em>name</em> - The name used in referring to this drawable. 499 </li> 500 </ul> 501 </dd> 502</dl> 503<p> 504 <strong>Example XML Declaration</strong> 505</p> 506<p> 507 The following code declares several color drawables. 508</p> 509<pre> 510<resources> 511 <drawable name="solid_red">#f00</drawable> 512 <drawable name="solid_blue">#0000ff</drawable> 513 <drawable name="solid_green">#f0f0</drawable> 514</resources> 515</pre> 516<p> 517 <strong>Example Code Use</strong> 518</p> 519<p> 520 Example Java code 521</p> 522<pre> 523// Assign a PaintDrawable as the background to 524// a TextView on the current screen. 525Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red); 526TextView tv = (TextView)findViewByID(R.id.text); 527tv.setBackground(redDrawable); 528</pre> 529<p> 530 Example XML code 531</p> 532<pre> 533<TextView android:layout_width="fill_parent" 534 android:layout_height="wrap_content" 535 android:textAlign="center" 536 android:background="@drawable/solid_red"/> 537</pre> 538 539<a name="ninepatch" id="ninepatch"></a> 540<h3>Nine-Patch Stretchable Image</h3> 541<p> 542 Android supports a stretchable bitmap image, called a 543 {@link android.graphics.NinePatch} graphic. This is a PNG image in which 544 you define stretchable sections that Android will resize to fit the object 545 at display time to accommodate variable sized sections, such as text strings. 546 You typically assign this resource to the View's background. An example use 547 of a stretchable image is the button backgrounds that Android uses; buttons 548 must stretch to accommodate strings of various lengths. 549</p> 550<p> 551 A NinePatch drawing is a standard PNG image that includes a 1 pixel wide 552 border. This border is used to define the stretchable and static areas of 553 the screen. You indicate a stretchable section by drawing one or more 1 pixel 554 wide black lines in the left or top part of this border. You can have as 555 many stretchable sections as you want. The relative size of the stretchable 556 sections stays the same, so the largest sections always remain the largest. 557</p> 558<p> 559 You can also define an optional drawable section of the image (effectively, 560 the padding lines) by drawing a line on the right and bottom lines. If you 561 do not draw these lines, the first top and left lines will be used. 562</p> 563<p> 564 If a View object sets this graphic as a background and then specifies the 565 View object's text, it will stretch itself so that all the text fits inside 566 the area designated by the right and bottom lines (if included). If the 567 padding lines are not included, Android uses the left and top lines to 568 define the writeable area. 569</p> 570<p>The <a href="{@docRoot}reference/draw9patch.html">Draw 9-patch</a> tool offers 571 an extremely handy way to create your NinePatch images, using a 572 WYSIWYG graphics editor. 573</p> 574<p> 575 Here is a sample NinePatch file used to define a button. 576</p> 577<p> 578 <img src="{@docRoot}images/ninepatch_raw.png" alt="Raw ninepatch file 579 showing the definition lines"> 580</p> 581<p> 582 This ninepatch uses one single stretchable area, and it also defines a drawable area. 583</p> 584<p> 585 <strong>Source file format:</strong> PNG — one resource per file 586</p> 587<p> 588 <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png) 589</p> 590<p> 591 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}. 592</p> 593<p> 594 <strong>Resource reference name:</strong> 595</p> 596<ul> 597 <li> 598 <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> 599 </li> 600 <li> 601 <strong>XML</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code> 602 </li> 603</ul> 604<p> 605 <strong>Example XML Code</strong> 606</p> 607<p> 608 Note that the width and height are set to "wrap_content" to make the button fit neatly around the text. 609</p> 610<pre> 611<Button id="@+id/tiny" 612 android:layout_width="wrap_content" 613 android:layout_height="wrap_content" 614 android:layout_alignParentTop="true" 615 android:layout_centerInParent="true" 616 android:text="Tiny" 617 android:textSize="8sp" 618 android:background="@drawable/my_button_background"/> 619 620<Button id="@+id/big" 621 android:layout_width="wrap_content" 622 android:layout_height="wrap_content" 623 android:layout_alignParentBottom="true" 624 android:layout_centerInParent="true" 625 android:text="Biiiiiiig text!" 626 android:textSize="30sp" 627 android:background="@drawable/my_button_background"/> 628</pre> 629<p> 630 Here are the two buttons based on this XML and the NinePatch graphic shown above. Notice how the width and height of the button varies with the text, and the background image stretches to accommodate it. 631</p> 632<p> 633 <img src="{@docRoot}images/ninepatch_examples.png" alt="Two buttons based on the NinePatch button background"> 634</p> 635 636<a name="animation" id="animation"></a> 637<h2>Animation</h2> 638<a name="tweenedanimation" id="tweenedanimation"></a> 639<h3> 640 Tweened Animation 641</h3> 642<p> 643 Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching. 644</p> 645<p> 646 <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration 647</p> 648<p> 649 <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml 650</p> 651<p> 652 <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}. 653</p> 654<p> 655 <strong>Resource reference name:</strong> 656</p> 657<ul> 658 <li> 659 <strong>Java</strong> <code>R.anim.<em>some_file</em></code> 660 </li> 661 <li> 662 <strong>XML</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code> 663 </li> 664</ul> 665<p> 666 <strong>Syntax</strong> 667</p> 668<p> 669 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, as shown in the example code. 670</p> 671<pre> 672<set android:shareInterpolator=boolean> // Only required if multiple tags are used. 673 <alpha android:fromAlpha=float 674 android:toAlpha=float > | 675 <scale android:fromXScale=float 676 android:toXScale=float 677 android:fromYScale=float 678 android:toYScale=float 679 android:pivotX=string 680 android:pivotY=string> | 681 <translate android:fromX=string 682 android:toX=string 683 android:fromY=string 684 android:toY=string> | 685 <rotate android:fromDegrees=float 686 android:toDegrees=float 687 android:pivotX=string 688 android:pivotY=string /> | 689 <<em>interpolator tag</em>> 690 <set> 691</set> 692</pre> 693<p> 694 <strong>Elements and Attributes</strong> 695</p> 696<dl> 697 <dt> 698 <set> 699 </dt> 700 <dd> 701 The outermost tag, which can recursively hold itself or other animations. You can include as many child elements of the same or different types as you like. Supports the following attribute: 702 <ul> 703 <li> 704 <em>shareInterpolator</em> - Whether to share the same Interpolator among all immediate child elements. 705 </li> 706 </ul> 707 </dd> 708 <dt> 709 <alpha> 710 </dt> 711 <dd> 712 A fading animation, compiled to {@link android.view.animation.AlphaAnimation}. Supports the following attributes: 713 <ul> 714 <li> 715 <em>fromAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. 716 </li> 717 <li> 718 <em>toAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. 719 </li> 720 </ul> 721 </dd> 722 <dt> 723 <scale> 724 </dt> 725 <dd> 726 A resizing animation, compiled to {@link android.view.animation.ScaleAnimation}. 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: 727 <ul> 728 <li> 729 <em>fromXScale</em> - Starting X size, where 1.0 is no change. 730 </li> 731 <li> 732 <em>toXScale</em> - Ending X size, where 1.0 is no change. 733 </li> 734 <li> 735 <em>fromYScale</em> - Starting Y size, where 1.0 is no change. 736 </li> 737 <li> 738 <em>toYScale</em> - Ending Y size, where 1.0 is no change. 739 </li> 740 <li> 741 <em>pivotX</em> - The X coordinate of the pinned center. 742 </li> 743 <li> 744 <em>pivotY</em> - The Y coordinate of the pinned center. 745 </li> 746 </ul> 747 </dd> 748 <dt> 749 <translate> 750 </dt> 751 <dd> 752 A motion animation that moves a visual element within its parent element. It is equivalent to {@link android.view.animation.TranslateAnimation}. 753Supports 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. 754 <ul> 755 <li> 756 <em>fromXDelta</em> - Starting X location. 757 </li> 758 <li> 759 <em>toXDelta</em> - Ending X location. 760 </li> 761 <li> 762 <em>fromYDelta</em> - Starting Y location. 763 </li> 764 <li> 765 <em>toYDelta</em> - Ending Y location. 766 </li> 767 </ul> 768 </dd> 769 <dt> 770 <rotate> 771 </dt> 772 <dd> 773 A rotation animation, compiled to {@link android.view.animation.RotateAnimation}. Supports the following attributes: 774 <ul> 775 <li> 776 <em>fromDegrees</em> - Starting rotation, in degrees. 777 </li> 778 <li> 779 <em>toDegrees</em> - Ending rotation, in degrees. 780 </li> 781 <li> 782 <em>pivotX</em> - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. 783 </li> 784 <li> 785 <em>pivotY</em> - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. 786 </li> 787 </ul> 788 </dd> 789 <dt> 790 <em><interpolator tag></em> 791 </dt> 792 <dd> 793 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). 794 </dd> 795</dl> 796<p> 797 Note that alpha, scale, rotate, translate all support the following attributes from the base animation class, BaseAnimation: 798</p> 799<dl> 800 <dt> 801 <em>duration</em> 802 </dt> 803 <dd> 804 Duration, in milliseconds, for this effect. 805 </dd> 806 <dt> 807 <em>startOffset</em> 808 </dt> 809 <dd> 810 Offset start time for this effect, in milliseconds. 811 </dd> 812 <dt> 813 <em>fillBefore</em> 814 </dt> 815 <dd> 816 Equivalent to {@link android.view.animation.Animation#setFillBefore animation.Animation.setFillBefore()}. 817 </dd> 818 <dt> 819 <em>fillAfter</em> 820 </dt> 821 <dd> 822 Equivalent to {@link android.view.animation.Animation#setFillAfter animation.Animation.setFillAfter()}. 823 </dd> 824 <dt> 825 <em>interpolator</em> 826 </dt> 827 <dd> 828 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>. 829 </dd> 830</dl> 831<p> 832 <strong>Example XML Declaration</strong> 833</p> 834<p> 835 The following XML from the ApiDemos application is used to stretch, then simultaneously spin and rotate a block of text. 836</p> 837<pre> 838<set android:shareInterpolator="false"> 839 <scale 840 android:interpolator="@android:anim/ease_in_out_interpolator" 841 android:fromXScale="1.0" 842 android:toXScale="1.4" 843 android:fromYScale="1.0" 844 android:toYScale="0.6" 845 android:pivotX="50%" 846 android:pivotY="50%" 847 android:fillAfter="false" 848 android:duration="700" /> 849 <set android:interpolator="@android:anim/ease_in_interpolator"> 850 <scale 851 android:fromXScale="1.4" 852 android:toXScale="0.0" 853 android:fromYScale="0.6" 854 android:toYScale="0.0" 855 android:pivotX="50%" 856 android:pivotY="50%" 857 android:startOffset="700" 858 android:duration="400" 859 android:fillBefore="false" /> 860 <rotate 861 android:fromDegrees="0" 862 android:toDegrees="-45" 863 android:toYScale="0.0" 864 android:pivotX="50%" 865 android:pivotY="50%" 866 android:startOffset="700" 867 android:duration="400" /> 868 </set> 869</set> 870</pre> 871<p> 872 The following Java code loads animations called res/anim/hyperspace_in.xml and res/anim/hyperspace_out.xml into a {@link android.widget.ViewFlipper}. 873</p> 874<pre> 875mFlipper.setInAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_in)); 876mFlipper.setOutAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_out)); 877</pre> 878 879<a name="layoutresources" id="layoutresources"></a> 880<h2>Layout</h2> 881<p> 882 Android lets you specify screen layouts using XML elements inside an XML file, similar to designing screen layout for a webpage in an HTML file. Each file contains a whole screen or a part of a screen, and is compiled into a View resource that can be passed in to {@link android.app.Activity#setContentView(int) Activity.setContentView} or used as a reference by other layout resource elements. Files are saved in the res/layout/ folder of your project, and compiled by the Android resource compiler aapt. 883</p> 884<p> 885 Every layout XML file must evaluate to a single root element. First we'll describe how to use the standard XML tags understood by Android as it is shipped, and then we'll give a little information on how you can define your own custom XML elements for custom View objects. See <a href="{@docRoot}devel/implementing-ui.html">Implementing a User Interface</a> for details about the visual elements that make up a screen. 886</p> 887<p> 888 The root element must have the Android namespace "http://schemas.android.com/apk/res/android" defined in the root element 889</p> 890<p> 891 <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root element of one of the supported XML layout elements. 892</p> 893<p> 894 <strong>Resource file location</strong>: res/layout/<em>some_file</em>.xml. 895</p> 896<p> 897 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. 898</p> 899<p> 900 <strong>Resource reference name:</strong> 901</p> 902<ul> 903 <li> 904 <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> 905 </li> 906 <li> 907 <strong>XML</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code> 908 </li> 909</ul> 910<p> 911 <strong>Syntax</strong> 912</p> 913<pre> 914<<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android" 915 id="@+id/<em>string_name</em>" (attributes)> 916 <<em>widget</em> or other nested <em>ViewGroupClass</em>>+ 917 <requestFocus/>(0 or 1 per layout file, assigned to any element) 918</<em>ViewGroupClass</em>> 919</pre> 920<dl> 921 <dt> 922 <<em>ViewGroupClass</em>> 923 </dt> 924 <dd> 925 <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> 926 <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> 927 <ul> 928 <li> 929 <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. 930 </li> 931 <li> 932 <code>xmlns:android="http://schemas.android.com/apk/res/android"</code> - <em><strong>Required for the root element only.</strong></em> 933 </li> 934 </ul> 935 </dd> 936 <dt> 937 <requestFocus> 938 </dt> 939 <dd> 940 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. 941 </dd> 942</dl> 943<p> 944 <strong>What Attributes Are Supported for What Elements?</strong> 945</p> 946<p> 947 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: 948</p> 949<ul> 950 <li> 951 <code>TextView</code> 952 </li> 953 <li> 954 <code>TextView_lines</code> 955 </li> 956 <li> 957 <code>TextView_maxlines</code> 958 </li> 959</ul> 960<p> 961 You could create an element like this: 962</p> 963<pre> 964<TextView android:lines="10" android:maxlines="20"/> 965</pre> 966<p> 967 This would create a {@link android.widget.TextView} object and set its lines and maxlines properties. 968</p> 969<p> 970 Attributes come from three sources: 971</p> 972<ul> 973 <li> 974 <strong>Attributes exposed directly by the element.</strong> For example, <code>TextView</code> supports <code>TextView_text</code>, as discussed above. 975 </li> 976 <li> 977 <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>. 978 </li> 979 <li> 980 <strong>Attributes of the object's {@link android.view.ViewGroup.LayoutParams} subclass.</strong> All View objects support a LayoutParams member (see <a href="{@docRoot}devel/ui/layout.html">LayoutParams in Implementing a UI</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: 981 </li> 982</ul> 983<ul> 984 <li>LinearLayout_Layout // The actual object — not used. 985 </li> 986 <li>LinearLayout_Layout_layout_gravity // Exposes a <code>gravity</code> attribute 987 </li> 988 <li>LinearLayout_Layout_layout_height // Exposes a <code>height</code> attribute 989 </li> 990 <li>LinearLayout_Layout_layout_weight // Exposes a <code>weight</code> attribute 991 </li> 992 <li>LinearLayout_Layout_layout_width // Exposes a <code>width</code> attribute 993 </li> 994</ul> 995<p> 996 Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes: 997</p> 998<pre> 999<?xml version="1.0" encoding="utf-8"?> 1000<!-- res/main_screen.xml --> 1001<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 1002 android:orientation="vertical" // The object's own orientation property 1003 android:padding="4" // Inherited View property 1004 android:gravity="center" // The object's own property 1005 android:layout_width="fill_parent" // Parent object's LinearLayout.LayoutParams.width 1006 android:layout_height="fill_parent"> // Parent object's LinearLayout.LayoutParams.height 1007 1008 <TextView android:layout_width="fill_parent" // TextView.LayoutParams.width 1009 android:layout_height="wrap_content" // TextView.LayoutParams.height 1010 android:layout_weight="0" // TextView.LayoutParams.weight 1011 android:paddingBottom="4" // TextView.paddingBottom 1012 android:text="@string/redirect_getter"/> // TextView.text 1013 1014 <EditText id="@+id/text" 1015 android:layout_width="fill_parent" // EditText.LayoutParams.width 1016 android:layout_height="wrap_content" // EditText.LayoutParams.height 1017 android:layout_weight="0" // EditText.LinearLayoutParams.weight 1018 android:paddingBottom="4"> // EditText.paddingBottom 1019 <requestFocus /> 1020 </EditText> 1021 1022 <Button id="@+id/apply" 1023 android:layout_width="wrap_content" // Button.LayoutParams.width 1024 android:layout_height="wrap_content" // Button.LayoutParams.height 1025 android:text="@string/apply" /> // TextView.text 1026</LinearLayout> 1027</pre> 1028<p> 1029 <strong>Example Code Use</strong> 1030</p> 1031<p> 1032 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: 1033</p> 1034<pre> 1035setContentView(R.layout.main_screen); 1036</pre> 1037<p> 1038 However, layout elements can also represent repeating elements used as templates. 1039</p> 1040<a name="customresources" id="customresources"></a> 1041<h3>Custom Layout Resources</h3> 1042<p> 1043 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: 1044</p> 1045<ul> 1046 <li> 1047 <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. 1048 </li> 1049 <li> 1050 <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. 1051 </li> 1052 <li> 1053 <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. 1054 </li> 1055</ul> 1056<p> 1057 <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. 1058</p> 1059<p> 1060 <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary). 1061</p> 1062<p> 1063 <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. 1064</p> 1065<p> 1066 <strong>Resource reference name:</strong> R.styleable.<em>some_file</em> (Java). 1067</p> 1068 1069<a name="stylesandthemes" id="stylesandthemes"></a> 1070<h2>Styles and Themes</h2> 1071<p> 1072 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. 1073</p> 1074<p> 1075 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. 1076</p> 1077<p> 1078 Both styles and themes are defined in a <style> 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. 1079</p> 1080<p> 1081 <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. 1082</p> 1083<p> 1084 <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. 1085</p> 1086<p> 1087 <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. 1088</p> 1089<p> 1090 <strong>Resource reference name:</strong> 1091</p> 1092<ul> 1093 <li> 1094 <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 1095 </li> 1096 <li> 1097 <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). 1098 </li> 1099</ul> 1100<p> 1101 <strong>Syntax</strong> 1102</p> 1103<pre> 1104<style name=<em>string</em> [parent=<em>string</em>] > 1105 <item name=<em>string</em>><em>Hex value | string value | reference</em></item>+<em> 1106</em></style> 1107</pre> 1108<dl> 1109 <dt> 1110 <style> 1111 </dt> 1112 <dd> 1113 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>. 1114 <ul> 1115 <li> 1116 <em>name</em> - The name used in referring to this theme. 1117 </li> 1118 <li> 1119 <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). 1120 </li> 1121 </ul> 1122 </dd> 1123 <dt> 1124 <item> 1125 </dt> 1126 <dd> 1127 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. 1128 </dd> 1129</dl> 1130<p> 1131 <strong>Example: Declaring a Style in XML</strong> 1132</p> 1133<pre> 1134<?xml version="1.0" encoding="utf-8"?> 1135<resources> 1136 <style name="SpecialText"> 1137 <item name="android:textSize">18sp</item> 1138 <item name="android:textColor">#008</item> 1139 </style> 1140</resources> 1141</pre> 1142<p> 1143 <strong>Example: Referencing a Declared Style from an XML Resource</strong> 1144</p> 1145<p> 1146 The following layout XML file applies the previously defined style to a single text box. 1147</p> 1148<pre> 1149<!-- MainPageLayout.xml --> 1150<?xml version="1.0" encoding="utf-8"?> 1151<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 1152 android:layout_height="fill_parent" 1153 android:layout_width="fill_parent" 1154 android:orientation="vertical" 1155 android:scrollbars="vertical" 1156 id="main_frame"> 1157 <EditText id="@+id/text1" 1158 style="@style/SpecialText" 1159 android:layout_width="fill_parent" 1160 android:layout_height="wrap_content" 1161 android:text="Hello, World!" /> 1162</LinearLayout> 1163</pre> 1164 1165 1166<p> 1167 <strong>Example XML Declaration of a Theme</strong> 1168</p> 1169<p> 1170 The following example defines a theme, "ThemeNew," which creates new theme items, 1171 refers to some previously defined theme items (values beginning with '@'), 1172 and refers to package resources (values beginning with '?'). 1173</p> 1174<pre> 1175<style name="ThemeNew"> 1176 <item name="windowFrame">@drawable/screen_frame</item> 1177 <item name="windowBackground">@drawable/screen_background_white</item> 1178 <item name="panelForegroundColor">#FF000000</item> 1179 <item name="panelBackgroundColor">#FFFFFFFF</item> 1180 <item name="panelTextColor">?panelForegroundColor</item> 1181 <item name="panelTextSize">14</item> 1182 <item name="menuItemTextColor">?panelTextColor</item> 1183 <item name="menuItemTextSize">?panelTextSize</item> 1184</style> 1185</pre> 1186<p> 1187 Notice that, to reference a value from the currently loaded theme, we use 1188 a question-mark (?) instead of the at-symbol (@), in the reference string. 1189 You must refer to such a specific <code><item></code> by its name in 1190 the currently loaded theme. This can be used in XML resources only. 1191</p> 1192 1193<p> 1194 <strong>Example Code Use of a Theme</strong> 1195</p> 1196<p> 1197 The following Java snippet demonstrates loading a style set (i.e., a theme). 1198</p> 1199<pre> 1200setTheme(R.style.ThemeNew); 1201</pre> 1202<p> 1203 The following XML applies an Android theme to a whole file (in this case, the Android dialog theme, to make the screen a floating dialog screen). 1204</p> 1205<pre> 1206<!-- AndroidManifest.xml --> 1207<manifest xmlns:android="http://schemas.android.com/apk/res/android" 1208 package="com.example.codelab.rssexample"> 1209 <activity class="AddRssItem" android:label="@string/add_item_label" android:theme="@android:style/Theme.Dialog"/> 1210</manifest> 1211</pre> 1212
