Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 1 | page.title=Application Resources |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 2 | @jd:body |
| 3 | |
| 4 | <div id="qv-wrapper"> |
| 5 | <div id="qv"> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 6 | <h2>Topics</h2> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 7 | <ol> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 8 | <li><a href="providing-resources.html">Providing Resources</a></li> |
| 9 | <li><a href="accessing-resources.html">Accessing Resources</a></li> |
| 10 | <li><a href="runtime-changes.html">Handling Runtime Changes</a></li> |
| 11 | <li><a href="localization.html">Localization</a></li> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 12 | </ol> |
| 13 | |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 14 | <h2>Reference</h2> |
| 15 | <ol> |
| 16 | <li><a href="available-resources.html">Resource Types</a></li> |
| 17 | </ol> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 18 | </div> |
| 19 | </div> |
| 20 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 21 | |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 22 | <p>You should always externalize resources such as images and strings from your application |
| 23 | code, so that you can maintain them independently. Externalizing your |
| 24 | resources also allows you to provide alternative resources that support specific device |
| 25 | configurations such as different languages or screen sizes, which becomes increasingly |
| 26 | important as more Android-powered devices become available with different configurations. In order |
Scott Main | 821ca51 | 2010-06-16 11:06:43 -0700 | [diff] [blame] | 27 | to provide compatibility with different configurations, you must organize resources in your |
| 28 | project's {@code res/} directory, using various sub-directories that group resources by type and |
| 29 | configuration.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 30 | |
Scott Main | c6cb8a7 | 2010-04-09 15:52:18 -0700 | [diff] [blame] | 31 | <div class="figure" style="width:421px"> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 32 | <img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="137" alt="" /> |
| 33 | <p class="img-caption"> |
Scott Main | 821ca51 | 2010-06-16 11:06:43 -0700 | [diff] [blame] | 34 | <strong>Figure 1.</strong> Two different devices, both using default |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 35 | resources.</p> |
| 36 | </div> |
| 37 | |
Scott Main | c6cb8a7 | 2010-04-09 15:52:18 -0700 | [diff] [blame] | 38 | <div class="figure" style="width:421px"> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 39 | <img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" /> |
| 40 | <p class="img-caption"> |
Scott Main | 821ca51 | 2010-06-16 11:06:43 -0700 | [diff] [blame] | 41 | <strong>Figure 2.</strong> Two different devices, one using alternative |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 42 | resources.</p> |
| 43 | </div> |
| 44 | |
| 45 | <p>For any type of resource, you can specify <em>default</em> and multiple |
| 46 | <em>alternative</em> resources for your application:</p> |
| 47 | <ul> |
| 48 | <li>Default resources are those that should be used regardless of |
| 49 | the device configuration or when there are no alternative resources that match the current |
| 50 | configuration.</li> |
| 51 | <li>Alternative resources are those that you've designed for use with a specific |
| 52 | configuration. To specify that a group of resources are for a specific configuration, |
| 53 | append an appropriate configuration qualifier to the directory name.</li> |
| 54 | </ul> |
| 55 | |
| 56 | <p>For example, while your default UI |
| 57 | layout is saved in the {@code res/layout/} directory, you might specify a different UI layout to |
| 58 | be used when the screen is in landscape orientation, by saving it in the {@code res/layout-land/} |
Scott Main | 821ca51 | 2010-06-16 11:06:43 -0700 | [diff] [blame] | 59 | directory. Android automatically applies the appropriate resources by matching the |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 60 | device's current configuration to your resource directory names.</p> |
| 61 | |
Scott Main | 821ca51 | 2010-06-16 11:06:43 -0700 | [diff] [blame] | 62 | <p>Figure 1 demonstrates how a collection of default resources from an application are applied |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 63 | to two different devices when there are no alternative resources available. Figure 2 shows |
| 64 | the same application with a set of alternative resources that qualify for one of the device |
| 65 | configurations, thus, the two devices uses different resources.</p> |
| 66 | |
| 67 | <p>The information above is just an introduction to how application resources work on Android. |
| 68 | The following documents provide a complete guide to how you can organize your application resources, |
| 69 | specify alternative resources, access them in your application, and more:</p> |
| 70 | |
| 71 | <dl> |
| 72 | <dt><strong><a href="providing-resources.html">Providing Resources</a></strong></dt> |
| 73 | <dd>What kinds of resources you can provide in your app, where to save them, and how to create |
| 74 | alternative resources for specific device configurations.</dd> |
| 75 | <dt><strong><a href="accessing-resources.html">Accessing Resources</a></strong></dt> |
| 76 | <dd>How to use the resources you've provided, either by referencing them from your application |
| 77 | code or from other XML resources.</dd> |
| 78 | <dt><strong><a href="runtime-changes.html">Handling Runtime Changes</a></strong></dt> |
| 79 | <dd>How to manage configuration changes that occur while your Activity is running.</dd> |
| 80 | <dt><strong><a href="localization.html">Localization</a></strong></dt> |
| 81 | <dd>A bottom-up guide to localizing your application using alternative resources. While this is |
| 82 | just one specific use of alternative resources, it is very important in order to reach more |
| 83 | users.</dd> |
| 84 | <dt><strong><a href="available-resources.html">Resource Types</a></strong></dt> |
| 85 | <dd>A reference of various resource types you can provide, describing their XML elements, |
| 86 | attributes, and syntax. For example, this reference shows you how to create a resource for |
| 87 | application menus, drawables, animations, and more.</dd> |
| 88 | </dl> |
| 89 | |
| 90 | <!-- |
| 91 | <h2>Raw Assets</h2> |
| 92 | |
| 93 | <p>An alternative to saving files in {@code res/} is to save files in the {@code |
| 94 | assets/} directory. This should only be necessary if you need direct access to original files and |
| 95 | directories by name. Files saved in the {@code assets/} directory will not be given a resource |
| 96 | ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can |
| 97 | query data in the {@code assets/} directory like an ordinary file system, search through the |
| 98 | directory and |
| 99 | read raw data using {@link android.content.res.AssetManager}. For example, this can be more useful |
| 100 | when dealing with textures for a game. However, if you only need to read raw data from a file |
| 101 | (such as a video or audio file), then you should save files into the {@code res/raw/} directory and |
| 102 | then read a stream of bytes using {@link android.content.res.Resources#openRawResource(int)}. This |
| 103 | is uncommon, but if you need direct access to original files in {@code assets/}, refer to the {@link |
| 104 | android.content.res.AssetManager} documentation.</p> |
| 105 | --> |