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 | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 31 | <div class="figure" style="width:429px"> |
| 32 | <img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="167" alt="" /> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 33 | <p class="img-caption"> |
Scott Main | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 34 | <strong>Figure 1.</strong> Two different devices, each using the default layout |
| 35 | (the app provides no alternative layouts).</p> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 36 | </div> |
| 37 | |
Scott Main | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 38 | <div class="figure" style="width:429px"> |
| 39 | <img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 40 | <p class="img-caption"> |
Scott Main | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 41 | <strong>Figure 2.</strong> Two different devices, each using a different layout provided |
| 42 | for different screen sizes.</p> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 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 |
Scott Main | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 57 | layout is saved in the {@code res/layout/} directory, you might specify a different layout to |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 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 | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 62 | <p>Figure 1 illustrates how the system applies the same layout for |
| 63 | two different devices when there are no alternative resources available. Figure 2 shows |
| 64 | the same application when it adds an alternative layout resource for larger screens.</p> |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 65 | |
Scott Main | e63163a | 2012-01-03 10:10:21 -0800 | [diff] [blame] | 66 | <p>The following documents provide a complete guide to how you can organize your application resources, |
Scott Main | f940a1f | 2010-02-09 18:48:27 -0800 | [diff] [blame] | 67 | specify alternative resources, access them in your application, and more:</p> |
| 68 | |
| 69 | <dl> |
| 70 | <dt><strong><a href="providing-resources.html">Providing Resources</a></strong></dt> |
| 71 | <dd>What kinds of resources you can provide in your app, where to save them, and how to create |
| 72 | alternative resources for specific device configurations.</dd> |
| 73 | <dt><strong><a href="accessing-resources.html">Accessing Resources</a></strong></dt> |
| 74 | <dd>How to use the resources you've provided, either by referencing them from your application |
| 75 | code or from other XML resources.</dd> |
| 76 | <dt><strong><a href="runtime-changes.html">Handling Runtime Changes</a></strong></dt> |
| 77 | <dd>How to manage configuration changes that occur while your Activity is running.</dd> |
| 78 | <dt><strong><a href="localization.html">Localization</a></strong></dt> |
| 79 | <dd>A bottom-up guide to localizing your application using alternative resources. While this is |
| 80 | just one specific use of alternative resources, it is very important in order to reach more |
| 81 | users.</dd> |
| 82 | <dt><strong><a href="available-resources.html">Resource Types</a></strong></dt> |
| 83 | <dd>A reference of various resource types you can provide, describing their XML elements, |
| 84 | attributes, and syntax. For example, this reference shows you how to create a resource for |
| 85 | application menus, drawables, animations, and more.</dd> |
| 86 | </dl> |
| 87 | |
| 88 | <!-- |
| 89 | <h2>Raw Assets</h2> |
| 90 | |
| 91 | <p>An alternative to saving files in {@code res/} is to save files in the {@code |
| 92 | assets/} directory. This should only be necessary if you need direct access to original files and |
| 93 | directories by name. Files saved in the {@code assets/} directory will not be given a resource |
| 94 | ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can |
| 95 | query data in the {@code assets/} directory like an ordinary file system, search through the |
| 96 | directory and |
| 97 | read raw data using {@link android.content.res.AssetManager}. For example, this can be more useful |
| 98 | when dealing with textures for a game. However, if you only need to read raw data from a file |
| 99 | (such as a video or audio file), then you should save files into the {@code res/raw/} directory and |
| 100 | then read a stream of bytes using {@link android.content.res.Resources#openRawResource(int)}. This |
| 101 | is uncommon, but if you need direct access to original files in {@code assets/}, refer to the {@link |
| 102 | android.content.res.AssetManager} documentation.</p> |
| 103 | --> |