Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 1 | page.title=More Resource Types |
| 2 | parent.title=Resource Types |
| 3 | parent.link=available-resources.html |
| 4 | @jd:body |
| 5 | |
| 6 | <p>This page defines more types of resources you can externalize, including:</p> |
| 7 | |
| 8 | <dl> |
| 9 | <dt><a href="#Bool">Bool</a></dt> |
| 10 | <dd>XML resource that carries a boolean value.</dd> |
| 11 | <dt><a href="#Color">Color</a></dt> |
| 12 | <dd>XML resource that carries a color value (a hexadecimal color).</dd> |
| 13 | <dt><a href="#Dimension">Dimension</a></dt> |
| 14 | <dd>XML resource that carries a dimension value (with a unit of measure).</dd> |
Scott Main | dfe5c20 | 2010-06-08 15:54:52 -0700 | [diff] [blame] | 15 | <dt><a href="#Id">ID</a></dt> |
| 16 | <dd>XML resource that provides a unique identifier for application resources and |
| 17 | components.</dd> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 18 | <dt><a href="#Integer">Integer</a></dt> |
| 19 | <dd>XML resource that carries an integer value.</dd> |
| 20 | <dt><a href="#IntegerArray">Integer Array</a></dt> |
| 21 | <dd>XML resource that provides an array of integers.</dd> |
| 22 | <dt><a href="#TypedArray">Typed Array</a></dt> |
| 23 | <dd>XML resource that provides a {@link android.content.res.TypedArray} (which you can use |
| 24 | for an array of drawables).</dd> |
| 25 | </dl> |
| 26 | |
| 27 | |
| 28 | |
| 29 | |
| 30 | <h2 id="Bool">Bool</h2> |
| 31 | |
| 32 | <p>A boolean value defined in XML.</p> |
| 33 | |
| 34 | <p class="note"><strong>Note:</strong> A bool is a simple resource that is referenced |
| 35 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 36 | such, you can combine bool resources with other simple resources in the one XML file, |
| 37 | under one {@code <resources>} element.</p> |
| 38 | |
| 39 | <dl class="xml"> |
| 40 | |
| 41 | <dt>file location:</dt> |
| 42 | <dd><code>res/values/<em>filename</em>.xml</code><br/> |
| 43 | The filename is arbitrary. The {@code <bool>} element's {@code name} will be used as the resource |
| 44 | ID.</dd> |
| 45 | |
| 46 | <dt>resource reference:</dt> |
| 47 | <dd> |
| 48 | In Java: <code>R.bool.<em>bool_name</em></code><br/> |
| 49 | In XML: <code>@[<em>package</em>:]bool/<em>bool_name</em></code> |
| 50 | </dd> |
| 51 | |
| 52 | <dt>syntax:</dt> |
| 53 | <dd> |
| 54 | <pre class="stx"> |
| 55 | <?xml version="1.0" encoding="utf-8"?> |
| 56 | <<a href="#bool-resources-element">resources</a>> |
| 57 | <<a href="#bool-element">bool</a> |
| 58 | name="<em>bool_name</em>" |
| 59 | >[true | false]</bool> |
| 60 | </resources> |
| 61 | </pre> |
| 62 | </dd> |
| 63 | |
| 64 | <dt>elements:</dt> |
| 65 | <dd> |
| 66 | <dl class="tag-list"> |
| 67 | |
| 68 | <dt id="bool-resources-element"><code><resources></code></dt> |
| 69 | <dd><strong>Required.</strong> This must be the root node. |
| 70 | <p>No attributes.</p> |
| 71 | </dd> |
| 72 | <dt id="bool-element"><code><bool></code></dt> |
| 73 | <dd>A boolean value: {@code true} or {@code false}. |
| 74 | <p class="caps">attributes:</p> |
| 75 | <dl class="atn-list"> |
| 76 | <dt><code>name</code></dt> |
| 77 | <dd><em>String</em>. A name for the bool value. This will be used as the resource ID.</dd> |
| 78 | </dl> |
| 79 | </dd> |
| 80 | |
| 81 | </dl> |
| 82 | </dd> <!-- end elements and attributes --> |
| 83 | |
| 84 | <dt>example:</dt> |
| 85 | <dd>XML file saved at <code>res/values-small/bools.xml</code>: |
| 86 | <pre> |
| 87 | <?xml version="1.0" encoding="utf-8"?> |
| 88 | <resources> |
| 89 | <bool name="screen_small">true</bool> |
| 90 | <bool name="adjust_view_bounds">true</bool> |
| 91 | </resources> |
| 92 | </pre> |
| 93 | |
| 94 | <p>This application code retrieves the boolean:</p> |
| 95 | <pre> |
| 96 | Resources res = {@link android.content.Context#getResources()}; |
| 97 | boolean screenIsSmall = res.{@link android.content.res.Resources#getBoolean(int) getBoolean}(R.bool.screen_small); |
| 98 | </pre> |
| 99 | <p>This layout XML uses the boolean for an attribute:</p> |
| 100 | <pre> |
| 101 | <ImageView |
| 102 | android:layout_height="fill_parent" |
| 103 | android:layout_width="fill_parent" |
| 104 | android:src="@drawable/logo" |
| 105 | android:adjustViewBounds="@bool/adjust_view_bounds" /> |
| 106 | </pre> |
| 107 | </dd> <!-- end example --> |
| 108 | |
| 109 | </dl> |
| 110 | |
| 111 | |
| 112 | |
| 113 | |
| 114 | <h2 id="Color">Color</h2> |
| 115 | |
| 116 | <p>A color value defined in XML. |
Scott Main | 2316d62 | 2010-07-20 09:59:35 -0700 | [diff] [blame] | 117 | The color is specified with an RGB value and alpha channel. You can use a color resource |
| 118 | any place that accepts a hexadecimal color value. You can also use a color resource when a |
| 119 | drawable resource is expected in XML (for example, {@code android:drawable="@color/green"}).</p> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 120 | |
| 121 | <p>The value always begins with a pound (#) character and then followed by the |
| 122 | Alpha-Red-Green-Blue information in one of the following formats:</p> |
| 123 | <ul> |
| 124 | <li>#<em>RGB</em></li> |
| 125 | <li>#<em>ARGB</em></li> |
| 126 | <li>#<em>RRGGBB</em></li> |
| 127 | <li>#<em>AARRGGBB</em></li> |
| 128 | </ul> |
| 129 | |
| 130 | <p class="note"><strong>Note:</strong> A color is a simple resource that is referenced |
| 131 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 132 | such, you can combine color resources with other simple resources in the one XML file, |
| 133 | under one {@code <resources>} element.</p> |
| 134 | |
| 135 | <dl class="xml"> |
| 136 | |
| 137 | <dt>file location:</dt> |
| 138 | <dd><code>res/values/colors.xml</code><br/> |
| 139 | The filename is arbitrary. The {@code <color>} element's {@code name} will be used as the |
| 140 | resource ID.</dd> |
| 141 | |
| 142 | <dt>resource reference:</dt> |
| 143 | <dd> |
| 144 | In Java: <code>R.color.<em>color_name</em></code><br/> |
| 145 | In XML: <code>@[<em>package</em>:]color/<em>color_name</em></code> |
| 146 | </dd> |
| 147 | |
| 148 | <dt>syntax:</dt> |
| 149 | <dd> |
| 150 | <pre class="stx"> |
| 151 | <?xml version="1.0" encoding="utf-8"?> |
| 152 | <<a href="#color-resources-element">resources</a>> |
| 153 | <<a href="#color-element">color</a> |
| 154 | name="<em>color_name</em>" |
| 155 | ><em>hex_color</em></color> |
| 156 | </resources> |
| 157 | </pre> |
| 158 | </dd> |
| 159 | |
| 160 | <dt>elements:</dt> |
| 161 | <dd> |
| 162 | <dl class="tag-list"> |
| 163 | |
| 164 | <dt id="color-resources-element"><code><resources></code></dt> |
| 165 | <dd><strong>Required.</strong> This must be the root node. |
| 166 | <p>No attributes.</p> |
| 167 | </dd> |
| 168 | <dt id="color-element"><code><color></code></dt> |
| 169 | <dd>A color expressed in hexadecimal, as described above. |
| 170 | <p class="caps">attributes:</p> |
| 171 | <dl class="atn-list"> |
| 172 | <dt><code>name</code></dt> |
| 173 | <dd><em>String</em>. A name for the color. This will be used as the resource ID. |
| 174 | </dd> |
| 175 | </dl> |
| 176 | </dd> |
| 177 | |
| 178 | </dl> |
| 179 | </dd> <!-- end elements and attributes --> |
| 180 | |
| 181 | <dt>example:</dt> |
| 182 | <dd>XML file saved at <code>res/values/colors.xml</code>: |
| 183 | <pre> |
| 184 | <?xml version="1.0" encoding="utf-8"?> |
| 185 | <resources> |
| 186 | <color name="opaque_red">#f00</color> |
| 187 | <color name="translucent_red">#80ff0000</color> |
| 188 | </resources> |
| 189 | </pre> |
| 190 | |
| 191 | <p>This application code retrieves the color resource:</p> |
| 192 | <pre> |
| 193 | Resources res = {@link android.content.Context#getResources()}; |
| 194 | int color = res.{@link android.content.res.Resources#getColor(int) getColor}(R.color.opaque_red); |
| 195 | </pre> |
| 196 | <p>This layout XML applies the color to an attribute:</p> |
| 197 | <pre> |
| 198 | <TextView |
| 199 | android:layout_width="fill_parent" |
| 200 | android:layout_height="wrap_content" |
| 201 | android:textColor="@color/translucent_red" |
| 202 | android:text="Hello"/> |
| 203 | </pre> |
| 204 | </dd> <!-- end example --> |
| 205 | |
| 206 | </dl> |
| 207 | |
| 208 | |
| 209 | |
| 210 | |
| 211 | |
| 212 | <h2 id="Dimension">Dimension</h2> |
| 213 | |
| 214 | <p>A dimension value defined in XML. A dimension |
| 215 | is specified with a number followed by a unit of measure. |
| 216 | For example: 10px, 2in, 5sp. The following units of measure are supported by Android:</p> |
| 217 | <dl> |
| 218 | <dt>{@code dp}</dt> |
| 219 | <dd>Density-independent Pixels - an abstract unit that is based on the physical density of the screen. |
| 220 | These units are relative to a 160 dpi screen, so one dp is one pixel on a 160 dpi screen. The ratio of |
| 221 | dp-to-pixel will change with the screen density, but not necessarily in direct proportion. The |
| 222 | compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".</dd> |
| 223 | <dt>{@code sp}</dt> |
| 224 | <dd>Scale-independent Pixels - this is like the dp unit, but it is also scaled by the user's font |
| 225 | size preference. It is recommend you use this unit when specifying font sizes, so they will be adjusted |
| 226 | for both the screen density and the user's preference.</dd> |
| 227 | <dt>{@code pt}</dt> |
| 228 | <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd> |
| 229 | <dt>{@code px}</dt> |
| 230 | <dd>Pixels - corresponds to actual pixels on the screen. This unit of measure is not recommended because |
| 231 | the actual representation can vary across devices; each devices may have a different number of pixels |
| 232 | per inch and may have more or fewer total pixels available on the screen.</dd> |
| 233 | <dt>{@code mm}</dt> |
| 234 | <dd>Millimeters - based on the physical size of the screen.</dd> |
| 235 | <dt>{@code in}</dt> |
| 236 | <dd>Inches - based on the physical size of the screen.</dd> |
| 237 | </dl> |
| 238 | |
| 239 | <p class="note"><strong>Note:</strong> A dimension is a simple resource that is referenced |
| 240 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 241 | such, you can combine dimension resources with other simple resources in the one XML file, |
| 242 | under one {@code <resources>} element.</p> |
| 243 | |
| 244 | <dl class="xml"> |
| 245 | |
| 246 | <dt>file location:</dt> |
| 247 | <dd><code>res/values/<em>filename</em>.xml</code><br/> |
| 248 | The filename is arbitrary. The {@code <dimen>} element's {@code name} will be used as the |
| 249 | resource ID.</dd> |
| 250 | |
| 251 | <dt>resource reference:</dt> |
| 252 | <dd> |
| 253 | In Java: <code>R.dimen.<em>dimension_name</em></code><br/> |
| 254 | In XML: <code>@[<em>package</em>:]dimen/<em>dimension_name</em></code> |
| 255 | </dd> |
| 256 | |
| 257 | <dt>syntax:</dt> |
| 258 | <dd> |
| 259 | <pre class="stx"> |
| 260 | <?xml version="1.0" encoding="utf-8"?> |
| 261 | <<a href="#dimen-resources-element">resources</a>> |
| 262 | <<a href="#dimen-element">dimen</a> |
| 263 | name="<em>dimension_name</em>" |
| 264 | ><em>dimension</em></dimen> |
| 265 | </resources> |
| 266 | </pre> |
| 267 | </dd> |
| 268 | |
| 269 | <dt>elements:</dt> |
| 270 | <dd> |
| 271 | <dl class="tag-list"> |
| 272 | |
| 273 | <dt id="dimen-resources-element"><code><resources></code></dt> |
| 274 | <dd><strong>Required.</strong> This must be the root node. |
| 275 | <p>No attributes.</p> |
| 276 | </dd> |
| 277 | <dt id="dimen-element"><code><dimen></code></dt> |
| 278 | <dd>A dimension, represented by a float, followed by a unit of measurement (dp, sp, pt, px, mm, in), |
| 279 | as described above. |
| 280 | <p class="caps">attributes:</p> |
| 281 | <dl class="atn-list"> |
| 282 | <dt><code>name</code></dt> |
| 283 | <dd><em>String</em>. A name for the dimension. This will be used as the resource ID. |
| 284 | </dd> |
| 285 | </dl> |
| 286 | </dd> |
| 287 | |
| 288 | </dl> |
| 289 | </dd> <!-- end elements and attributes --> |
| 290 | |
| 291 | <dt>example:</dt> |
| 292 | <dd>XML file saved at <code>res/values/dimens.xml</code>: |
| 293 | <pre> |
| 294 | <?xml version="1.0" encoding="utf-8"?> |
| 295 | <resources> |
| 296 | <dimen name="textview_height">25dp</dimen> |
| 297 | <dimen name="textview_width">150dp</dimen> |
| 298 | <dimen name="ball_radius">30dp</dimen> |
| 299 | <dimen name="font_size">16sp</dimen> |
| 300 | </resources> |
| 301 | </pre> |
| 302 | |
| 303 | <p>This application code retrieves a dimension:</p> |
| 304 | <pre> |
| 305 | Resources res = {@link android.content.Context#getResources()}; |
| 306 | float fontSize = res.{@link android.content.res.Resources#getDimension(int) getDimension}(R.dimen.font_size); |
| 307 | </pre> |
| 308 | <p>This layout XML applies dimensions to attributes:</p> |
| 309 | <pre> |
| 310 | <TextView |
| 311 | android:layout_height="@dimen/textview_height" |
| 312 | android:layout_width="@dimen/textview_width" |
Scott Main | 8dd87ad | 2010-08-04 17:33:33 -0700 | [diff] [blame] | 313 | android:textSize="@dimen/font_size"/> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 314 | </pre> |
| 315 | </dl> |
| 316 | </dd> <!-- end example --> |
| 317 | |
| 318 | </dl> |
| 319 | |
| 320 | |
| 321 | |
| 322 | |
| 323 | |
| 324 | |
Scott Main | dfe5c20 | 2010-06-08 15:54:52 -0700 | [diff] [blame] | 325 | <h2 id="Id">ID</h2> |
| 326 | |
| 327 | <p>A unique resource ID defined in XML. Using the name you provide in the {@code <item>} |
| 328 | element, the Android developer tools create a unique integer in your project's {@code |
| 329 | R.java} class, which you can use as an |
| 330 | identifier for an application resources (for example, a {@link android.view.View} in your UI layout) |
| 331 | or a unique integer for use in your application code (for example, as an ID for a dialog or a |
| 332 | result code).</p> |
| 333 | |
| 334 | <p class="note"><strong>Note:</strong> An ID is a simple resource that is referenced |
| 335 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 336 | such, you can combine ID resources with other simple resources in the one XML file, |
| 337 | under one {@code <resources>} element. Also, remember that an ID resources does not reference |
| 338 | an actual resource item; it is simply a unique ID that you can attach to other resources or use |
| 339 | as a unique integer in your application.</p> |
| 340 | |
| 341 | <dl class="xml"> |
| 342 | |
| 343 | <dt>file location:</dt> |
| 344 | <dd><code>res/values/<em>filename.xml</em></code><br/> |
| 345 | The filename is arbitrary.</dd> |
| 346 | |
| 347 | <dt>resource reference:</dt> |
| 348 | <dd> |
| 349 | In Java: <code>R.id.<em>name</em></code><br/> |
| 350 | In XML: <code>@[<em>package</em>:]id/<em>name</em></code> |
| 351 | </dd> |
| 352 | |
| 353 | <dt>syntax:</dt> |
| 354 | <dd> |
| 355 | <pre class="stx"> |
| 356 | <?xml version="1.0" encoding="utf-8"?> |
| 357 | <<a href="#id-resources-element">resources</a>> |
| 358 | <<a href="#id-item-element">item</a> |
| 359 | type="id" |
| 360 | name="<em>id_name</em>" /> |
| 361 | </resources> |
| 362 | </pre> |
| 363 | </dd> |
| 364 | |
| 365 | <dt>elements:</dt> |
| 366 | <dd> |
| 367 | <dl class="tag-list"> |
| 368 | |
| 369 | <dt id="integer-resources-element"><code><resources></code></dt> |
| 370 | <dd><strong>Required.</strong> This must be the root node. |
| 371 | <p>No attributes.</p> |
| 372 | </dd> |
| 373 | <dt id="integer-element"><code><integer></code></dt> |
| 374 | <dd>Defines a unique ID. Takes no value, only attributes. |
| 375 | <p class="caps">attributes:</p> |
| 376 | <dl class="atn-list"> |
| 377 | <dt><code>type</code></dt> |
| 378 | <dd>Must be "id".</dd> |
| 379 | <dt><code>name</code></dt> |
| 380 | <dd><em>String</em>. A unique name for the ID.</dd> |
| 381 | </dl> |
| 382 | </dd> |
| 383 | |
| 384 | </dl> |
| 385 | </dd> <!-- end elements and attributes --> |
| 386 | |
| 387 | <dt>example:</dt> |
| 388 | <dd> |
| 389 | <p>XML file saved at <code>res/values/ids.xml</code>:</p> |
| 390 | <pre> |
| 391 | <?xml version="1.0" encoding="utf-8"?> |
| 392 | <resources> |
| 393 | <item type="id" name="button_ok" /> |
| 394 | <item type="id" name="dialog_exit" /> |
| 395 | </resources> |
| 396 | </pre> |
| 397 | |
| 398 | <p>Then, this layout snippet uses the "button_ok" ID for a Button widget:</p> |
| 399 | <pre> |
| 400 | <Button android:id="<b>@id/button_ok</b>" |
| 401 | style="@style/button_style" /> |
| 402 | </pre> |
| 403 | |
| 404 | <p>Notice that the {@code android:id} value does not include the plus sign in the ID reference, |
| 405 | because the ID already exists, as defined in the {@code ids.xml} example above. (When you specify an |
| 406 | ID to an XML resource using the plus sign—in the format {@code |
| 407 | android:id="@+id/name"}—it means that the "name" ID does not exist and should be created.)</p> |
| 408 | |
| 409 | <p>As another example, the following code snippet uses the "dialog_exit" ID as a unique identifier |
| 410 | for a dialog:</p> |
| 411 | <pre> |
| 412 | {@link android.app.Activity#showDialog(int) showDialog}(<b>R.id.dialog_exit</b>); |
| 413 | </pre> |
| 414 | <p>In the same application, the "dialog_exit" ID is compared when creating a dialog:</p> |
| 415 | <pre> |
| 416 | protected Dialog {@link android.app.Activity#onCreateDialog(int)}(int id) { |
| 417 | Dialog dialog; |
| 418 | switch(id) { |
| 419 | case <b>R.id.dialog_exit</b>: |
| 420 | ... |
| 421 | break; |
| 422 | default: |
| 423 | dialog = null; |
| 424 | } |
| 425 | return dialog; |
| 426 | } |
| 427 | </pre> |
| 428 | </dd> <!-- end example --> |
| 429 | |
| 430 | |
| 431 | </dl> |
| 432 | |
| 433 | |
| 434 | |
| 435 | |
| 436 | |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 437 | <h2 id="Integer">Integer</h2> |
| 438 | |
| 439 | <p>An integer defined in XML.</p> |
| 440 | |
| 441 | <p class="note"><strong>Note:</strong> An integer is a simple resource that is referenced |
| 442 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 443 | such, you can combine integer resources with other simple resources in the one XML file, |
| 444 | under one {@code <resources>} element.</p> |
| 445 | |
| 446 | <dl class="xml"> |
| 447 | |
| 448 | <dt>file location:</dt> |
| 449 | <dd><code>res/values/<em>filename.xml</em></code><br/> |
| 450 | The filename is arbitrary. The {@code <integer>} element's {@code name} will be used as the |
| 451 | resource ID.</dd> |
| 452 | |
| 453 | <dt>resource reference:</dt> |
| 454 | <dd> |
| 455 | In Java: <code>R.integer.<em>integer_name</em></code><br/> |
| 456 | In XML: <code>@[<em>package</em>:]integer/<em>integer_name</em></code> |
| 457 | </dd> |
| 458 | |
| 459 | <dt>syntax:</dt> |
| 460 | <dd> |
| 461 | <pre class="stx"> |
| 462 | <?xml version="1.0" encoding="utf-8"?> |
| 463 | <<a href="#integer-resources-element">resources</a>> |
| 464 | <<a href="#integer-element">integer</a> |
| 465 | name="<em>integer_name</em>" |
Scott Main | dfe5c20 | 2010-06-08 15:54:52 -0700 | [diff] [blame] | 466 | ><em>integer</em></integer> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 467 | </resources> |
| 468 | </pre> |
| 469 | </dd> |
| 470 | |
| 471 | <dt>elements:</dt> |
| 472 | <dd> |
| 473 | <dl class="tag-list"> |
| 474 | |
| 475 | <dt id="integer-resources-element"><code><resources></code></dt> |
| 476 | <dd><strong>Required.</strong> This must be the root node. |
| 477 | <p>No attributes.</p> |
| 478 | </dd> |
| 479 | <dt id="integer-element"><code><integer></code></dt> |
| 480 | <dd>An integer. |
| 481 | <p class="caps">attributes:</p> |
| 482 | <dl class="atn-list"> |
| 483 | <dt><code>name</code></dt> |
| 484 | <dd><em>String</em>. A name for the integer. This will be used as the resource ID. |
| 485 | </dd> |
| 486 | </dl> |
| 487 | </dd> |
| 488 | |
| 489 | </dl> |
| 490 | </dd> <!-- end elements and attributes --> |
| 491 | |
| 492 | <dt>example:</dt> |
| 493 | <dd> |
| 494 | <p>XML file saved at <code>res/values/integers.xml</code>:</p> |
| 495 | <pre> |
| 496 | <?xml version="1.0" encoding="utf-8"?> |
| 497 | <resources> |
Scott Main | dfe5c20 | 2010-06-08 15:54:52 -0700 | [diff] [blame] | 498 | <integer name="max_speed">75</integer> |
| 499 | <integer name="min_speed">5</integer> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 500 | </resources> |
| 501 | </pre> |
| 502 | <p>This application code retrieves an integer:</p> |
| 503 | <pre> |
| 504 | Resources res = {@link android.content.Context#getResources()}; |
| 505 | int maxSpeed = res.{@link android.content.res.Resources#getInteger(int) getInteger}(R.integer.max_speed); |
| 506 | </pre> |
| 507 | </dd> <!-- end example --> |
| 508 | |
| 509 | |
| 510 | </dl> |
| 511 | |
| 512 | |
| 513 | |
| 514 | |
| 515 | |
| 516 | <h2 id="IntegerArray">Integer Array</h2> |
| 517 | |
| 518 | <p>An array of integers defined in XML.</p> |
| 519 | |
| 520 | <p class="note"><strong>Note:</strong> An integer array is a simple resource that is referenced |
| 521 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 522 | such, you can combine integer array resources with other simple resources in the one XML file, |
| 523 | under one {@code <resources>} element.</p> |
| 524 | |
| 525 | |
| 526 | <dl class="xml"> |
| 527 | |
| 528 | <dt>file location:</dt> |
| 529 | <dd><code>res/values/<em>filename</em>.xml</code><br/> |
| 530 | The filename is arbitrary. The {@code <integer-array>} element's {@code name} will be used as the |
| 531 | resource ID.</dd> |
| 532 | |
| 533 | <dt>compiled resource datatype:</dt> |
| 534 | <dd>Resource pointer to an array of integers.</dd> |
| 535 | |
| 536 | <dt>resource reference:</dt> |
| 537 | <dd> |
| 538 | In Java: <code>R.array.<em>string_array_name</em></code><br/> |
| 539 | In XML: <code>@[<em>package</em>:]array.<em>integer_array_name</em></code> |
| 540 | </dd> |
| 541 | |
| 542 | <dt>syntax:</dt> |
| 543 | <dd> |
| 544 | <pre class="stx"> |
| 545 | <?xml version="1.0" encoding="utf-8"?> |
| 546 | <<a href="#integer-array-resources-element">resources</a>> |
| 547 | <<a href="#integer-array-element">integer-array</a> |
| 548 | name="<em>integer_array_name</em>"> |
| 549 | <<a href="#integer-array-item-element">item</a> |
| 550 | ><em>integer</em></item> |
| 551 | </integer-array> |
| 552 | </resources> |
| 553 | </pre> |
| 554 | </dd> |
| 555 | |
| 556 | <dt>elements:</dt> |
| 557 | <dd> |
| 558 | <dl class="tag-list"> |
| 559 | <dt id="integer-array-resources-element"><code><resources></code></dt> |
| 560 | <dd><strong>Required.</strong> This must be the root node. |
| 561 | <p>No attributes.</p> |
| 562 | </dd> |
| 563 | <dt id="integer-array-element"><code><string-array></code></dt> |
| 564 | <dd>Defines an array of integers. Contains one or more child {@code <item>} elements. |
| 565 | <p class="caps">attributes:</p> |
| 566 | <dl class="atn-list"> |
| 567 | <dt><code>android:name</code></dt> |
| 568 | <dd><em>String</em>. A name for the array. This name will be used as the resource |
| 569 | ID to reference the array.</dd> |
| 570 | </dl> |
| 571 | </dd> |
| 572 | <dt id="integer-array-item-element"><code><item></code></dt> |
| 573 | <dd>An integer. The value can be a referenced to another |
| 574 | integer resource. Must be a child of a {@code <integer-array>} element. |
| 575 | <p>No attributes.</p> |
| 576 | </dd> |
| 577 | </dl> |
| 578 | </dd> <!-- end elements --> |
| 579 | |
| 580 | <dt>example:</dt> |
| 581 | <dd>XML file saved at <code>res/values/integers.xml</code>: |
| 582 | <pre> |
| 583 | <?xml version="1.0" encoding="utf-8"?> |
| 584 | <resources> |
| 585 | <integer-array name="bits"> |
| 586 | <item>4</item> |
| 587 | <item>8</item> |
| 588 | <item>16</item> |
| 589 | <item>32</item> |
| 590 | </integer-array> |
| 591 | </resources> |
| 592 | </pre> |
| 593 | |
| 594 | <p>This application code retrieves the integer array:</p> |
| 595 | <pre> |
| 596 | Resources res = {@link android.content.Context#getResources()}; |
| 597 | int[] bits = res.{@link android.content.res.Resources#getIntArray(int) getIntArray}(R.array.bits); |
| 598 | </pre> |
| 599 | </dd> <!-- end example --> |
| 600 | |
| 601 | </dl> |
| 602 | |
| 603 | |
| 604 | |
| 605 | |
| 606 | |
| 607 | <h2 id="TypedArray">Typed Array</h2> |
| 608 | |
| 609 | <p>A {@link android.content.res.TypedArray} defined in XML. You can use |
| 610 | this to create an array of other resources, such as drawables. Note that the array |
| 611 | is not required to be homogeneous, so you can create an array of mixed resource types, but |
| 612 | you must be aware of what and where the data types are in the array so that you can properly obtain |
| 613 | each item with the {@link android.content.res.TypedArray}'s {@code get...()} methods.</p> |
| 614 | |
| 615 | <p class="note"><strong>Note:</strong> A typed array is a simple resource that is referenced |
| 616 | using the value provided in the {@code name} attribute (not the name of the XML file). As |
| 617 | such, you can combine typed array resources with other simple resources in the one XML file, |
| 618 | under one {@code <resources>} element.</p> |
| 619 | |
| 620 | |
| 621 | <dl class="xml"> |
| 622 | |
| 623 | <dt>file location:</dt> |
| 624 | <dd><code>res/values/<em>filename</em>.xml</code><br/> |
| 625 | The filename is arbitrary. The {@code <array>} element's {@code name} will be used as the |
| 626 | resource ID.</dd> |
| 627 | |
| 628 | <dt>compiled resource datatype:</dt> |
| 629 | <dd>Resource pointer to a {@link android.content.res.TypedArray}.</dd> |
| 630 | |
| 631 | <dt>resource reference:</dt> |
| 632 | <dd> |
| 633 | In Java: <code>R.array.<em>array_name</em></code><br/> |
| 634 | In XML: <code>@[<em>package</em>:]array.<em>array_name</em></code> |
| 635 | </dd> |
| 636 | |
| 637 | <dt>syntax:</dt> |
| 638 | <dd> |
| 639 | <pre class="stx"> |
| 640 | <?xml version="1.0" encoding="utf-8"?> |
| 641 | <<a href="#array-resources-element">resources</a>> |
| 642 | <<a href="#array-element">array</a> |
| 643 | name="<em>integer_array_name</em>"> |
| 644 | <<a href="#array-item-element">item</a>><em>resource</em></item> |
| 645 | </array> |
| 646 | </resources> |
| 647 | </pre> |
| 648 | </dd> |
| 649 | |
| 650 | <dt>elements:</dt> |
| 651 | <dd> |
| 652 | <dl class="tag-list"> |
| 653 | <dt id="array-resources-element"><code><resources></code></dt> |
| 654 | <dd><strong>Required.</strong> This must be the root node. |
| 655 | <p>No attributes.</p> |
| 656 | </dd> |
| 657 | <dt id="array-element"><code><array></code></dt> |
| 658 | <dd>Defines an array. Contains one or more child {@code <item>} elements. |
| 659 | <p class="caps">attributes:</p> |
| 660 | <dl class="atn-list"> |
| 661 | <dt><code>android:name</code></dt> |
| 662 | <dd><em>String</em>. A name for the array. This name will be used as the resource |
| 663 | ID to reference the array.</dd> |
| 664 | </dl> |
| 665 | </dd> |
| 666 | <dt id="array-item-element"><code><item></code></dt> |
| 667 | <dd>A generic resource. The value can be a reference to a resource or a simple data type. |
| 668 | Must be a child of an {@code <array>} element. |
| 669 | <p>No attributes.</p> |
| 670 | </dd> |
| 671 | </dl> |
| 672 | </dd> <!-- end elements --> |
| 673 | |
| 674 | <dt>example:</dt> |
| 675 | <dd>XML file saved at <code>res/values/arrays.xml</code>: |
| 676 | <pre> |
| 677 | <?xml version="1.0" encoding="utf-8"?> |
| 678 | <resources> |
| 679 | <array name="icons"> |
| 680 | <item>@drawable/home</item> |
| 681 | <item>@drawable/settings</item> |
| 682 | <item>@drawable/logout</item> |
| 683 | </array> |
| 684 | <array name="colors"> |
| 685 | <item>#FFFF0000</item> |
| 686 | <item>#FF00FF00</item> |
| 687 | <item>#FF0000FF</item> |
| 688 | </array> |
| 689 | </resources> |
| 690 | </pre> |
| 691 | |
| 692 | <p>This application code retrieves each array and then obtains the first entry in each array:</p> |
| 693 | <pre> |
| 694 | Resources res = {@link android.content.Context#getResources()}; |
| 695 | TypedArray icons = res.{@link android.content.res.Resources#obtainTypedArray(int) obtainTypedArray}(R.array.icons); |
| 696 | Drawable drawable = icons.{@link android.content.res.TypedArray#getDrawable(int) getDrawable}(0); |
| 697 | |
| 698 | TypedArray colors = res.{@link android.content.res.Resources#obtainTypedArray(int) obtainTypedArray}(R.array.icons); |
| 699 | int color = colors.{@link android.content.res.TypedArray#getColor(int,int) getColor}(0,0); |
| 700 | </pre> |
| 701 | </dd> <!-- end example --> |
| 702 | |
| 703 | </dl> |
| 704 | |
| 705 | |
| 706 | |
| 707 | |
| 708 | |
| 709 | |
| 710 | |
| 711 | |
| 712 | |
| 713 | |
| 714 | <!-- TODO |
| 715 | |
| 716 | |
| 717 | <h2>Styleable Attribute</h2> |
| 718 | |
| 719 | |
| 720 | <dl class="xml"> |
| 721 | |
| 722 | <dt>syntax:</dt> |
| 723 | <dd> |
| 724 | <pre class="stx"> |
| 725 | </pre> |
| 726 | </dd> |
| 727 | |
| 728 | <dt>file location:</dt> |
| 729 | <dd><code>res/</code></dd> |
| 730 | |
| 731 | <dt>compiled resource datatype:</dt> |
| 732 | <dd>Resource pointer to a {@link android.view.Menu} (or subclass) resource.</dd> |
| 733 | |
| 734 | <dt>resource reference:</dt> |
| 735 | <dd>Java: <code>R.</code><br/> |
| 736 | XML: |
| 737 | </dd> |
| 738 | |
| 739 | <dt>elements and attributes:</dt> |
| 740 | <dd> |
| 741 | <dl class="attr"> |
| 742 | |
| 743 | <dt><code></code></dt> |
| 744 | <dd></dd> |
| 745 | <dt><code></code></dt> |
| 746 | <dd>Valid attributes: |
| 747 | <dl> |
| 748 | <dt><code></code></dt> |
| 749 | <dd> |
| 750 | </dd> |
| 751 | <dt><code></code></dt> |
| 752 | <dd> |
| 753 | </dd> |
| 754 | </dl> |
| 755 | </dd> |
| 756 | |
| 757 | </dl> |
| 758 | </dd> |
| 759 | |
| 760 | <dt>example:</dt> |
| 761 | <dd> |
| 762 | <dl> |
| 763 | |
| 764 | <dt>XML file saved at <code>res/</code>:</dt> |
| 765 | <dd> |
| 766 | <pre> |
| 767 | |
| 768 | </pre> |
| 769 | </dd> |
| 770 | |
| 771 | <dt>Java code :</dt> |
| 772 | <dd> |
| 773 | <pre> |
| 774 | |
| 775 | </pre> |
| 776 | </dd> |
| 777 | |
| 778 | </dl> |
| 779 | </dd> |
| 780 | |
| 781 | |
| 782 | <dt>see also:</dt> |
| 783 | <dd> |
| 784 | <ul> |
| 785 | <li></li> |
| 786 | </ul> |
| 787 | </dd> |
| 788 | |
| 789 | </dl> |
| 790 | |
| 791 | |
| 792 | |
| 793 | |
| 794 | |
| 795 | |
| 796 | --> |
| 797 | |
| 798 | |
| 799 | |
| 800 | |