| <html> |
| <head> |
| <script type="text/javascript" src="http://www.corp.google.com/style/prettify.js"></script> |
| <script src="http://www.corp.google.com/eng/techpubs/include/navbar.js" type="text/javascript"></script> |
| </head> |
| |
| <body> |
| |
| <p>Contains classes for accessing and publishing data |
| on the device. It includes three main categories of APIs: |
| the {@link android.content.res.Resources Resources} for |
| retrieving resource data associated with an application; |
| {@link android.content.ContentProvider Content Providers} and |
| {@link android.content.ContentResolver ContentResolver} for managing and |
| publishing persistent data associated with an application; and |
| the {@link android.content.pm.PackageManager Package Manager} |
| for finding out information about the application packages installed |
| on the device.</p> |
| |
| <p>In addition, the {@link android.content.Context Context} abstract class |
| is a base API for pulling these pieces together, allowing you to access |
| an application's resources and transfer data between applications.</p> |
| |
| <p>This package builds on top of the lower-level Android packages |
| {@link android.database}, {@link android.text}, |
| {@link android.graphics.drawable}, {@link android.graphics}, |
| {@link android.os}, and {@link android.util}.</p> |
| |
| <ol> |
| <li> <a href="#Resources">Resources</a> |
| <ol> |
| <li> <a href="#ResourcesTerminology">Terminology</a> |
| <li> <a href="#ResourcesQuickStart">Examples</a> |
| <ol> |
| <li> <a href="#UsingSystemResources">Using System Resources</a> |
| <li> <a href="#StringResources">String Resources</a> |
| <li> <a href="#ColorResources">Color Resources</a> |
| <li> <a href="#DrawableResources">Drawable Resources</a> |
| <li> <a href="#LayoutResources">Layout Resources</a> |
| <li> <a href="#ReferencesToResources">References to Resources</a> |
| <li> <a href="#ReferencesToThemeAttributes">References to Theme Attributes</a> |
| <li> <a href="#StyleResources">Style Resources</a> |
| <li> <a href="#StylesInLayoutResources">Styles in Layout Resources</a> |
| </ol> |
| </ol> |
| </ol> |
| |
| <a name="Resources"></a> |
| <h2>Resources</h2> |
| |
| <p>This topic includes a terminology list associated with resources, and a series |
| of examples of using resources in code. For a complete guide on creating and |
| using resources, see the document on <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources |
| and Internationalization</a>. For a reference on the supported Android resource types, |
| see <a href="{@docRoot}guide/topics/resources/available-resources.html">Available Resource Types</a>.</p> |
| <p>The Android resource system keeps track of all non-code |
| assets associated with an application. You use the |
| {@link android.content.res.Resources Resources} class to access your |
| application's resources; the Resources instance associated with your |
| application can generally be found through |
| {@link android.content.Context#getResources Context.getResources()}.</p> |
| <p>An application's resources are compiled into the application |
| binary at build time for you by the build system. To use a resource, |
| you must install it correctly in the source tree and build your |
| application. As part of the build process, Java symbols for each |
| of the resources are generated that you can use in your source |
| code -- this allows the compiler to verify that your application code matches |
| up with the resources you defined.</p> |
| |
| <p>The rest of this section is organized as a tutorial on how to |
| use resources in an application.</p> |
| |
| <a name="ResourcesTerminology"></a> |
| <h3>Terminology</h3> |
| |
| <p>The resource system brings a number of different pieces together to |
| form the final complete resource functionality. To help understand the |
| overall system, here are some brief definitions of the core concepts and |
| components you will encounter in using it:</p> |
| |
| <p><b>Asset</b>: A single blob of data associated with an application. This |
| includes Java object files, graphics (such as PNG images), XML files, etc. |
| These files are organized in a directory hierarchy that, during final packaging |
| of the application, is bundled together into a single ZIP file.</p> |
| |
| <p><b>aapt</b>: The tool that generates the final ZIP file of application |
| assets. In addition to collecting raw assets together, it also parses |
| resource definitions into binary asset data.</p> |
| |
| <p><b>Resource Table</b>: A special asset that aapt generates for you, |
| describing all of the resources contained in an application/package. |
| This file is accessed for you by the Resources class; it is not touched |
| directly by applications.</p> |
| |
| <p><b>Resource</b>: An entry in the Resource Table describing a single |
| named value. Broadly, there are two types of resources: primitives and |
| bags.</p> |
| |
| <p><b>Resource Identifier</b>: In the Resource Table all resources are |
| identified by a unique integer number. In source code (resource descriptions, |
| XML files, Java code) you can use symbolic names that stand as constants for |
| the actual resource identifier integer.</p> |
| |
| <p><b>Primitive Resource</b>: All primitive resources can be written as a |
| simple string, using formatting to describe a variety of primitive types |
| included in the resource system: integers, colors, strings, references to |
| other resources, etc. Complex resources, such as bitmaps and XML |
| describes, are stored as a primitive string resource whose value is the path |
| of the underlying Asset holding its actual data.</p> |
| |
| <p><b>Bag Resource</b>: A special kind of resource entry that, instead of a |
| simple string, holds an arbitrary list of name/value pairs. Each name is |
| itself a resource identifier, and each value can hold |
| the same kinds of string formatted data as a normal resource. Bags also |
| support inheritance: a bag can inherit the values from another bag, selectively |
| replacing or extending them to generate its own contents.</p> |
| |
| <p><b>Kind</b>: The resource kind is a way to organize resource identifiers |
| for various purposes. For example, drawable resources are used to |
| instantiate Drawable objects, so their data is a primitive resource containing |
| either a color constant or string path to a bitmap or XML asset. Other |
| common resource kinds are string (localized string primitives), color |
| (color primitives), layout (a string path to an XML asset describing a view |
| layout), and style (a bag resource describing user interface attributes). |
| There is also a standard "attr" resource kind, which defines the resource |
| identifiers to be used for naming bag items and XML attributes</p> |
| |
| <p><b>Style</b>: The name of the resource kind containing bags that are used |
| to supply a set of user interface attributes. For example, a TextView class may |
| be given a style resource that defines its text size, color, and alignment. |
| In a layout XML file, you associate a style with a bag using the "style" |
| attribute, whose value is the name of the style resource.</p> |
| |
| <p><b>Style Class</b>: Specifies a related set of attribute resources. |
| This data is not placed in the resource table itself, but used to generate |
| Java constants that make it easier for you to retrieve values out of |
| a style resource and/or XML tag's attributes. For example, the |
| Android platform defines a "View" style class that |
| contains all of the standard view attributes: padding, visibility, |
| background, etc.; when View is inflated it uses this style class to |
| retrieve those values from the XML file (at which point style and theme |
| information is applied as approriate) and load them into its instance.</p> |
| |
| <p><b>Configuration</b>: For any particular resource identifier, there may be |
| multiple different available values depending on the current configuration. |
| The configuration includes the locale (language and country), screen |
| orientation, screen density, etc. The current configuration is used to |
| select which resource values are in effect when the resource table is |
| loaded.</p> |
| |
| <p><b>Theme</b>: A standard style resource that supplies global |
| attribute values for a particular context. For example, when writing a |
| Activity the application developer can select a standard theme to use, such |
| as the Theme.White or Theme.Black styles; this style supplies information |
| such as the screen background image/color, default text color, button style, |
| text editor style, text size, etc. When inflating a layout resource, most |
| values for widgets (the text color, selector, background) if not explicitly |
| set will come from the current theme; style and attribute |
| values supplied in the layout can also assign their value from explicitly |
| named values in the theme attributes if desired.</p> |
| |
| <p><b>Overlay</b>: A resource table that does not define a new set of resources, |
| but instead replaces the values of resources that are in another resource table. |
| Like a configuration, this is applied at load time |
| to the resource data; it can add new configuration values (for example |
| strings in a new locale), replace existing values (for example change |
| the standard white background image to a "Hello Kitty" background image), |
| and modify resource bags (for example change the font size of the Theme.White |
| style to have an 18 pt font size). This is the facility that allows the |
| user to select between different global appearances of their device, or |
| download files with new appearances.</p> |
| |
| <a name="ResourcesQuickStart"></a> |
| <h3>Examples</h3> |
| |
| <p>This section gives a few quick examples you can use to make your own resources. |
| For more details on how to define and use resources, see <a |
| href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources and |
| Internationalization</a>. </p> |
| |
| <a name="UsingSystemResources"></a> |
| <h4>Using System Resources</h4> |
| |
| <p>Many resources included with the system are available to applications. |
| All such resources are defined under the class "android.R". For example, |
| you can display the standard application icon in a screen with the following |
| code:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| requestScreenFeatures(FEATURE_BADGE_IMAGE); |
| |
| super.onStart(); |
| |
| setBadgeResource(android.R.drawable.sym_def_app_icon); |
| } |
| } |
| </pre> |
| |
| <p>In a similar way, this code will apply to your screen the standard |
| "green background" visual treatment defined by the system:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| super.onStart(); |
| |
| setTheme(android.R.style.Theme_Black); |
| } |
| } |
| </pre> |
| |
| <a name="StringResources"></a> |
| <h4>String Resources</h4> |
| |
| <p>String resources are defined using an XML resource description syntax. |
| The file or multiple files containing these resources can be given any name |
| (as long as it has a .xml suffix) and placed at an appropriate location in |
| the source tree for the desired configuration (locale/orientation/density). |
| |
| <p>Here is a simple resource file describing a few strings:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <string id="mainLabel">Hello <u>th<ignore>e</ignore>re</u>, <i>you</i> <b>Activity</b>!</string> |
| <string id="back">Back</string> |
| <string id="clear">Clear</string> |
| </resources> |
| </pre> |
| |
| <p>Typically this file will be called "strings.xml", and must be placed |
| in the <code>values</code> directory:</p> |
| |
| <pre> |
| MyApp/res/values/strings.xml |
| </pre> |
| |
| <p>The strings can now be retrieved by your application through the |
| symbol specified in the "id" attribute:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| super.onStart(); |
| |
| String back = getResources().getString(R.string.back).toString(); |
| back = getString(R.string.back).toString(); // synonym |
| } |
| } |
| </pre> |
| |
| <p>Unlike system resources, the resource symbol (the R class) we are using |
| here comes from our own application's package, not android.R.</p> |
| |
| <p>Note that the "mainLabel" string is complex, including style information. |
| To support this, the <code>getString()</code> method returns a |
| <code>CharSequence</code> object that you can pass to a |
| <code>TextView</code> to retain those style. This is why code |
| must call <code>toString()</code> on the returned resource if it wants |
| a raw string.</p> |
| |
| <a name="ColorResources"></a> |
| <h4>Color Resources</h4> |
| |
| <p>Color resources are created in a way very similar to string resources, |
| but with the <color> resource tag. The data for these resources |
| must be a hex color constant of the form "#rgb", "#argb", "#rrggbb", or |
| "#aarrggbb". The alpha channel is 0xff (or 0xf) for opaque and 0 |
| for transparent.</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <color id="opaque_red">#ffff0000</color> |
| <color id="transparent_red">#80ff0000</color> |
| <color id="opaque_blue">#0000ff</color> |
| <color id="opaque_green">#0f0</color> |
| </resources> |
| </pre> |
| |
| <p>While color definitions could be placed in the same resource file |
| as the previously shown string data, usually you will place the colors in |
| their own file:</p> |
| |
| <pre> |
| MyApp/res/values/colors.xml |
| </pre> |
| |
| <p>The colors can now be retrieved by your application through the |
| symbol specified in the "id" attribute:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| super.onStart(); |
| |
| int red = getResources().getColor(R.color.opaque_red); |
| } |
| } |
| </pre> |
| |
| <a name="DrawableResources"></a> |
| <h4>Drawable Resources</h4> |
| |
| <p>For simple drawable resources, all you need to do is place your |
| image in a special resource sub-directory called "drawable". Files here |
| are things that can be handled by an implementation of the |
| {@link android.graphics.drawable.Drawable Drawable} class, often bitmaps |
| (such as PNG images) but also various kinds of XML descriptions |
| for selectors, gradients, etc.</p> |
| |
| <p>The drawable files will be scanned by the |
| resource tool, automatically generating a resource entry for each found. |
| For example the file <code>res/drawable/<myimage>.<ext></code> |
| will result in a resource symbol named "myimage" (without the extension). Note |
| that these file names <em>must</em> be valid Java identifiers, and should |
| have only lower-case letters.</p> |
| |
| <p>For example, to use your own custom image as a badge in a screen, |
| you can place the image here:</p> |
| |
| <pre> |
| MyApp/res/drawable/my_badge.png |
| </pre> |
| |
| <p>The image can then be used in your code like this:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| requestScreenFeatures(FEATURE_BADGE_IMAGE); |
| |
| super.onStart(); |
| |
| setBadgeResource(R.drawable.my_badge); |
| } |
| } |
| </pre> |
| |
| <p>For drawables that are a single solid color, you can also define them |
| in a resource file very much like colors shown previously. The only |
| difference is that here we use the <drawable> tag to create a |
| drawable resource.</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <drawable id="opaque_red">#ffff0000</drawable> |
| <drawable id="transparent_red">#80ff0000</drawable> |
| <drawable id="opaque_blue">#0000ff</drawable> |
| <drawable id="opaque_green">#0f0</drawable> |
| </resources> |
| </pre> |
| |
| <p>These resource entries are often placed in the same resource file |
| as color definitions:</p> |
| |
| <pre> |
| MyApp/res/values/colors.xml |
| </pre> |
| |
| <a name="LayoutResources"></a> |
| <h4>Layout Resources</h4> |
| |
| <p>Layout resources describe a view hierarchy configuration that is |
| generated at runtime. These resources are XML files placed in the |
| resource directory "layout", and are how you should create the content |
| views inside of your screen (instead of creating them by hand) so that |
| they can be themed, styled, configured, and overlayed.</p> |
| |
| <p>Here is a simple layout resource consisting of a single view, a text |
| editor:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text" |
| android:layout_width="fill-parent" android:layout_height="fill-parent" |
| android:text="Hello, World!" /> |
| </root> |
| </pre> |
| |
| <p>To use this layout, it can be placed in a file like this:</p> |
| |
| <pre> |
| MyApp/res/layout/my_layout.xml |
| </pre> |
| |
| <p>The layout can then be instantiated in your screen like this:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| super.onStart(); |
| setContentView(R.layout.my_layout); |
| } |
| } |
| </pre> |
| |
| <p>Note that there are a number of visual attributes that can be supplied |
| to TextView (including textSize, textColor, and textStyle) that we did |
| not define in the previous example; in such a sitation, the default values for |
| those attributes come from the theme. If we want to customize them, we |
| can supply them explicitly in the XML file:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text" |
| android:layout_width="match_parent" android:layout_height="match_parent" |
| <b>android:textSize="18" android:textColor="#008"</b> |
| android:text="Hello, World!" /> |
| </root> |
| </pre> |
| |
| <p>However, usually these kinds of attributes (those being attributes that |
| usually make sense to vary with theme or overlay) should be defined through |
| the theme or separate style resource. Later we will see how this is done.</p> |
| |
| <a name="ReferencesToResources"></a> |
| <h4>References to Resources</h4> |
| |
| <p>A value supplied in an attribute (or resource) can also be a reference to |
| a resource. This is often used in layout files to supply strings (so they |
| can be localized) and images (which exist in another file), though a reference |
| can be do any resource type including colors and integers.</p> |
| |
| <p>For example, if we have the previously defined color resources, we can |
| write a layout file that sets the text color size to be the value contained in |
| one of those resources:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text" |
| android:layout_width="match_parent" android:layout_height="match_parent" |
| <b>android:textColor="@color/opaque_red"</b> |
| android:text="Hello, World!" /> |
| </root> |
| </pre> |
| |
| <p>Note here the use of the '@' prefix to introduce a resource reference -- the |
| text following that is the name of a resource in the form |
| of <code>@[package:]type/name</code>. In this case we didn't need to specify |
| the package because we are referencing a resource in our own package. To |
| reference a system resource, you would need to write:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text" |
| android:layout_width="match_parent" android:layout_height="match_parent" |
| android:textColor="@<b>android:</b>color/opaque_red" |
| android:text="Hello, World!" /> |
| </root> |
| </pre> |
| |
| <p>As another example, you should always use resource references when supplying |
| strings in a layout file so that they can be localized:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text" |
| android:layout_width="match_parent" android:layout_height="match_parent" |
| android:textColor="@android:color/opaque_red" |
| android:text="@string/hello_world" /> |
| </root> |
| </pre> |
| |
| <p>This facility can also be used to create references between resources. |
| For example, we can create new drawable resources that are aliases for |
| existing images:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <drawable id="my_background">@android:drawable/theme2_background</drawable> |
| </resources> |
| </pre> |
| |
| <a name="ReferencesToThemeAttributes"></a> |
| <h4>References to Theme Attributes</h4> |
| |
| <p>Another kind of resource value allows you to reference the value of an |
| attribute in the current theme. This attribute reference can <em>only</em> |
| be used in style resources and XML attributes; it allows you to customize the |
| look of UI elements by changing them to standard variations supplied by the |
| current theme, instead of supplying more concrete values.</p> |
| |
| <p>As an example, we can use this in our layout to set the text color to |
| one of the standard colors defined in the base system theme:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text" |
| android:layout_width="match_parent" android:layout_height="match_parent" |
| <b>android:textColor="?android:textDisabledColor"</b> |
| android:text="@string/hello_world" /> |
| </root> |
| </pre> |
| |
| <p>Note that this is very similar to a resource reference, except we are using |
| an '?' prefix instead of '@'. When you use this markup, you are supplying |
| the name of an attribute resource that will be looked up in the theme -- |
| because the resource tool knows that an attribute resource is expected, |
| you do not need to explicitly state the type (which would be |
| <code>?android:attr/android:textDisabledColor</code>).</p> |
| |
| <p>Other than using this resource identifier to find the value in the |
| theme instead of raw resources, the name syntax is identical to the '@' format: |
| <code>?[package:]type/name</code> with the type here being optional.</p> |
| |
| <a name="StyleResources"></a> |
| <h4>Style Resources</h4> |
| |
| <p>A style resource is a set of name/value pairs describing a group |
| of related attributes. There are two main uses for these resources: |
| defining overall visual themes, and describing a set of visual attributes |
| to apply to a class in a layout resource. In this section we will look |
| at their use to describe themes; later we will look at using them in |
| conjunction with layouts.</p> |
| |
| <p>Like strings, styles are defined through a resource XML file. In the |
| situation where we want to define a new theme, we can create a custom theme |
| style that inherits from one of the standard system themes:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <style id="Theme" parent="android:Theme.White"> |
| <item id="android:foregroundColor">#FFF8D96F</item> |
| <item id="android:textColor">@color/opaque_blue</item> |
| <item id="android:textSelectedColor">?android:textColor</item> |
| </style> |
| </resources> |
| </pre> |
| |
| <p>Typically these resource definitions will be placed in a file |
| called "styles.xml" , and must be placed in the <code>values</code> |
| directory:</p> |
| |
| <pre> |
| MyApp/res/values/styles.xml |
| </pre> |
| |
| <p>Similar to how we previously used a system style for an Activity theme, |
| you can apply this style to your Activity:</p> |
| |
| <pre class="prettyprint"> |
| public class MyActivity extends Activity |
| { |
| public void onStart() |
| { |
| super.onStart(); |
| |
| setTheme(R.style.Theme); |
| } |
| } |
| </pre> |
| |
| <p>In the style resource shown here, we used the <code>parent</code> |
| attribute to specify another style resource from which it inherits |
| its values -- in this case the <code>Theme.White</code> system resource:</p> |
| |
| <pre> |
| <style id="Home" parent="android:Theme.White"> |
| ... |
| </style> |
| </pre> |
| |
| <p>Note, when doing this, that you must use the "android" prefix in front |
| to tell the compiler the namespace to look in for the resource -- |
| the resources you are specifying here are in your application's namespace, |
| not the system. This explicit namespace specification ensures that names |
| the application uses will not accidentally conflict with those defined by |
| the system.</p> |
| |
| <p>If you don't specify an explicit parent style, it will be inferred |
| from the style name -- everything before the final '.' in the name of the |
| style being defined is taken as the parent style name. Thus, to make |
| another style in your application that inherits from this base Theme style, |
| you can write:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <style id="Theme.WhiteText"> |
| <item id="android:foregroundColor">#FFFFFFFF</item> |
| <item id="android:textColor">?android:foregroundColor</item> |
| </style> |
| </resources> |
| </pre> |
| |
| <p>This results in the symbol <code>R.style.Theme_WhiteText</code> that |
| can be used in Java just like we did with <code>R.style.Theme</code> |
| above.</p> |
| |
| <a name="StylesInLayoutResources"></a> |
| <h4>Styles in Layout Resources</h4> |
| |
| <p>Often you will have a number fo views in a layout that all use the same |
| set of attributes, or want to allow resource overlays to modify the values of |
| attributes. Style resources can be used for both of these purposes, to put |
| attribute definitions in a single place that can be references by multiple |
| XML tags and modified by overlays. To do this, you simply define a |
| new style resource with the desired values:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <style id="SpecialText"> |
| <item id="android:textSize">18</item> |
| <item id="android:textColor">#008</item> |
| </style> |
| </resources> |
| </pre> |
| |
| <p>You can now apply this style to your TextView in the XML file:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <root> |
| <EditText id="text1" <b>style="@style/SpecialText"</b> |
| android:layout_width="match_parent" android:layout_height="wrap_content" |
| android:text="Hello, World!" /> |
| <EditText id="text2" <b>style="@style/SpecialText"</b> |
| android:layout_width="match_parent" android:layout_height="wrap_content" |
| android:text="I love you all." /> |
| </root></pre> |
| <h4> </h4> |
| |
| </body> |
| </html> |
| |