This page describes the different types of resources that you can externalize from your code and package with your application.
For more details on how to use resources in your application, please see the Resources and Internationalization documentation.
All simple resource values can be expressed as a string, using various formats to unambiguously indicate the type of resource being created. For this reason, these values can be defined both as standard resources (under res/values/), as well as direct values supplied for mappings in styles and themes, and attributes in XML files such as layouts.
A color value specifies an RGB value with an alpha channel, which can be used in various places such as specifying a solid color for a {@link android.graphics.drawable.Drawable} or the color to use for text. A color value always begins with a pound (#) character and then followed by the Alpha-Red-Green-Blue information in one of the following formats:
If you want to retrieve the color represented by a resource ID, you can call the {@link android.content.res.Resources#getColor(int) Resources.getColor()} method.
Source file format: XML file requiring a
<?xml version="1.0" encoding="utf-8"?> declaration, and
a root <resources> element containing one or more
<color> tags.
Resource source file location: {@code res/values/colors.xml} (File name is arbitrary.)
Compiled resource datatype: Resource pointer to a Java int.
Resource reference name:
R.color.some_name
@[package:]color/some_name (where some_name is the name of a specific color)
Syntax
<color name=color_name>#color_value</color>
Example XML Declaration
The following code declares two colors, the first fully opaque, and the second translucent.
<resources> <color name="opaque_red">#f00</color> <color name="translucent_red">#80ff0000</color> </resources>
Example Code Use
Example Java code
// Retrieve a color value. int color = getResources.getColor(R.color.opaque_red);
Example XML code
<TextView android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:textAlign="center"
android:textColor="@color/translucent_red"
android:text="Some Text"/>
Strings, with optional simple formatting, can be
stored and retrieved as resources. You can add formatting to your string by
using three standard HTML tags: <b>, <i>, and <u>. To
guarantee getting an unstyled string only (the raw text) call the
toString() method of the retrieved CharSequence object.
Methods that accept string resources should be able to process these styling
tags.
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.
Note: 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:
<string name="good_example">"This'll work"</string> <string name="good_example_2">This\'ll also work</string> <string name="bad_example">This won't work!</string> <string name="bad_example_2">XML encodings won't work either!</string>
Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <string> tags.
Resource source file location: {@code res/values/strings.xml} (File name is arbitrary.)
Compiled resource datatype: Resource pointer to a Java CharSequence.
Resource reference name:
R.string.some_name
@[package:]string/some_name (where some_name is the name of a specific string)
Syntax
<string name=string_name>string_value</string>
Example XML Declaration
The following declares two strings: the first — simple text with no formatting (resulting in a CharSequence that is simply a String object) — the second includes formatting information in the string (resulting 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 retrieve the resource and then convert it to formatted text.
<resources> <string name="simple_welcome_message">Welcome!</string> <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see you.</string> </resources>
Example Code Use
Example Java code
// Assign a styled string resource to a TextView // on the current screen. CharSequence str = getString(R.string.styled_welcome_message); TextView tv = (TextView)findViewByID(R.id.text); tv.setText(str);
Example XML code
<TextView android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:textAlign="center"
android:text="@string/simple_welcome_message"/>
Sometimes you may want to create a styled text resource that is also used as a format string. This cannot be done directly because there is no way of passing the styled text as the format string argument of String.format() without stripping out the style information. The workaround is to store the style tags as escaped HTML tags, and then convert the escaped HTML string into a styled text after formatting has taken place.
To use styled text as a format string, do the following.
<resources> <string name="search_results_resultsTextFormat">%1$d results for <b>&quot;%2$s&quot;</b></string> </resources>
In this example the format string has two arguments: %1$d is a decimal number, %2$s is a string.
String escapedTitle = TextUtil.htmlEncode(title);
String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat); String resultsText = String.format(resultsTextFormat, count, escapedTitle); CharSequence styledResults = Html.fromHtml(resultsText);
You can create common dimensions to use for various screen elements by defining dimension values in XML. A dimension resource is a number followed by a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of measurement supported by Android:
Dimension values are not normally used as raw resources, but rather as attribute values in XML files. You can, however, create plain resources containing this data type.
Source file format: XML file requiring a <?xml
version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more
<dimen> tags.
Resource source file location: {@code res/values/dimens.xml} (File name is arbitrary, but standard practice is to put all dimensions in one file devoted to dimensions.)
Compiled resource datatype: Resource pointer to a dimension.
Resource reference name:
R.dimen.some_name
@[package:]dimen/some_name (where some_name is the name of a specific <dimen> element)
Syntax
<dimen name=dimen_name>dimen_value</dimen>
Example XML Declaration
The following code declares several dimension values.
<resources>
<dimen name="one_pixel">1px</dimen>
<dimen name="double_density">2dp</dimen>
<dimen name="sixteen_sp">16sp</dimen>
</resources>
Example Code Use
Example Java code:
float dimen = Resources.getDimen(R.dimen.one_pixel);
Example XML code:
<TextView android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:textSize="@dimen/sixteen_sp"/>
A {@link android.graphics.drawable.Drawable} is a type of resource that you retrieve with {@link android.content.res.Resources#getDrawable Resources.getDrawable()} and use to draw to the screen. There are a number of drawable resources that can be created.
Android supports bitmap resource files in a few different formats: png (preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is compiled and referenced by the file name without the extension (so res/drawable/my_picture.png would be referenced as R.drawable.my_picture).
Source file formats: png (preferred), jpg (acceptable), gif (discouraged). One resource per file.
Resource file location: {@code res/drawable/some_file.png}
Compiled resource datatype: Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}.
Resource reference name:
R.drawable.some_file
@[package:]drawable/some_file
For more discussion and examples using drawable resources, see the discussion in 2D Graphics.
You can create a {@link android.graphics.drawable.PaintDrawable} object that is a rectangle of color, with optionally rounded corners. This element can be defined in any of the files inside res/values/.
Source file format: XML file requiring a <?xml
version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more
<drawable> tags.
Resource source file location: {@code res/values/colors.xml} (File name is arbitrary, but standard practice is to put the PaintDrawable items in the file along with the numeric color values.)
Compiled resource datatype: Resource pointer to a {@link android.graphics.drawable.PaintDrawable}.
Resource reference name:
R.drawable.some_name
@[package:]drawable/some_name (where some_name is the name of a specific resource)
Syntax
<drawable name=color_name>color_value</drawable>
Example XML Declaration
The following code declares several color drawables.
<resources>
<drawable name="solid_red">#f00</drawable>
<drawable name="solid_blue">#0000ff</drawable>
<drawable name="solid_green">#f0f0</drawable>
</resources>
Example Code Use
Example Java code
// Assign a PaintDrawable as the background to // a TextView on the current screen. Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red); TextView tv = (TextView)findViewByID(R.id.text); tv.setBackground(redDrawable);
Example XML code
<TextView android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:textAlign="center"
android:background="@drawable/solid_red"/>
Android supports a stretchable bitmap image, called a {@link android.graphics.NinePatch} graphic. This is a PNG image in which you define stretchable sections that Android will resize to fit the object at display time to accommodate variable sized sections, such as text strings. You typically assign this resource to the View's background. An example use of a stretchable image is the button backgrounds that Android uses; buttons must stretch to accommodate strings of various lengths.
Source file format: PNG — one resource per file
Resource source file location: {@code res/drawable/some_name.9.png} (Filename must end in {@code .9.png})
Compiled resource datatype: Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}.
Resource reference name:
R.drawable.some_file
@[package:]drawable.some_file
For more information and examples using NinePatch drawables, see the discussion in 2D Graphics.
Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching.
Source file format: XML file, one resource per file, one root tag with no <?xml> declaration
Resource file location: {@code res/anim/some_file.xml}
Compiled resource datatype: Resource pointer to an {@link android.view.animation.Animation}.
Resource reference name:
R.anim.some_file
@[package:]anim/some_file
Syntax
The file must have a single root element: this will be either a single <alpha>, <scale>, <translate>, <rotate>, interpolator element, or <set> element that holds groups of these elements (which may include another <set>). By default, all elements are applied simultaneously. To have them occur sequentially, you must specify the startOffset attribute.
<set android:shareInterpolator=boolean> // Only required if multiple tags are used.
<alpha android:fromAlpha=float
android:toAlpha=float > |
<scale android:fromXScale=float
android:toXScale=float
android:fromYScale=float
android:toYScale=float
android:pivotX=string
android:pivotY=string > |
<translate android:fromX=string
android:toX=string
android:fromY=string
android:toY=string > |
<rotate android:fromDegrees=float
android:toDegrees=float
android:pivotX=string
android:pivotY=string > |
<interpolator tag>
<set>
</set>
Elements and Attributes
scale supports the following attributes:
In addition to the attributes defined for each element above, the elements
<alpha>, <scale>, <translate>,
<rotate>, and <set> all support the following attributes (inherited
from the {@link android.view.animation.Animation} class):
For more discussion and animation code samples, see the discussion in the 2D Graphics document.
Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as XML resources and inflated by your application using {@link android.view.MenuInflater}.
Source file format: XML file, one resource per file, one root tag,
<?xml> declaration not required.
Resource file location: res/menu/some_file.xml
Compiled resource datatype: Resource pointer to a {@link android.view.Menu} (or subclass) resource.
Resource reference name:
R.menu.some_fileThe file must have a single root element: a <menu> element. In all,
there are three valid elements: <menu>, <group> and <item>. The
<item> and <group> elements must be the children of a <menu>, but <item>
elements can also be the children of a <group>, and another <menu> element may be the child
of an <item> (to create a Sub Menu).
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/example_item
android:title="Example Item"
android:icon="@drawable/example_item_icon" />
<group android:id="@+id/example_group">
<item android:id="@+id/example_item2
android:title="Example Item 2"
android:icon="@drawable/example_item2_icon" />
</group>
<item android:id="@+id/example_submenu
android:title="Example Sub Menu" >
<menu>
<item android:id="@+id/example_submenu_item
android:title="Example Sub Menu Item" />
</menu>
</item>
</menu>
All attributes must be defined with the android namespace (e.g., android:icon="@drawable/icon").
<item> and <group> nodes. No attributes.<item> elements. Valid attributes:
<menu> element (for a Sub Menu). Valid attributes:
For more discussion on how to create menus in XML and inflate them in your application, read Creating Menus.
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.
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.
The root element must have the Android namespace "http://schemas.android.com/apk/res/android" defined in the root element.
For a complete discussion on creating layouts, see the User Interface topic.
Source file format: XML file
requiring a <?xml version="1.0" encoding="utf-8"?>
declaration, and a root element of one of the supported XML layout elements.
Resource file location: res/layout/some_file.xml.
Compiled resource datatype: Resource pointer to a {@link android.view.View} (or subclass) resource.
Resource reference name:
R.layout.some_file
@[package:]layout/some_file
Syntax
<ViewGroupClass xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/string_name" (attributes)>
<widget or other nested ViewGroupClass>+
<requestFocus/>(0 or 1 per layout file, assigned to any element)
</ViewGroupClass>
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 <TextView> elements inside a <ListLayout>).
If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <EditText> is the corresponding XML element for the EditText class. It exposes its own unique attributes (EditText_numeric), as well as all attributes supported by <TextView> and <View>. For the id attribute of a tag in XML, you should use a special syntax: "@+id/somestringvalue". 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: <TextView android:id="@+id/nameTextbox"/>, and refer to it this way in Java: findViewById(R.id.nameTextbox). All elements support the following values:
xmlns:android="http://schemas.android.com/apk/res/android" - Required for the root element only.
What Attributes Are Supported for What Elements?
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, EditText_autoText means that the <EditText> tag supports an attribute autoText. When you actually use the attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix "android:". So, for example, if {@link android.R.styleable} lists the following values:
TextView
TextView_lines
TextView_maxlines
You could create an element like this:
<TextView android:lines="10" android:maxlines="20"/>
This would create a {@link android.widget.TextView} object and set its lines and maxlines properties.
Attributes come from three sources:
TextView supports TextView_text, as discussed above.
<TextView> element supports all the attributes that the <View> element exposes — a long list, including View_paddingBottom and View_scrollbars. These too are used without the class name: <TextView android:paddingBottom="20" android:scrollbars="horizontal" />.
android:layout_gravity for an object wrapped by a <LinearLayout> element. Remember that each LayoutParams subclass also supports inherited attributes. Attributes exposed by each subclass are given in the format someLayoutParamsSubclass_Layout_layout_someproperty. This defines an attribute "android:layout_someproperty". Here is an example of how Android documentation lists the properties of the {@link android.widget.LinearLayout.LayoutParams LinearLayout.LayoutParams} class:
gravity attribute
height attribute
weight attribute
width attribute
Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes:
<?xml version="1.0" encoding="utf-8"?>
<!-- res/main_screen.xml -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical" // The object's own orientation property
android:padding="4" // Inherited View property
android:gravity="center" // The object's own property
android:layout_width="fill_parent" // Parent object's LinearLayout.LayoutParams.width
android:layout_height="fill_parent"> // Parent object's LinearLayout.LayoutParams.height
<TextView android:layout_width="fill_parent" // TextView.LayoutParams.width
android:layout_height="wrap_content" // TextView.LayoutParams.height
android:layout_weight="0" // TextView.LayoutParams.weight
android:paddingBottom="4" // TextView.paddingBottom
android:text="@string/redirect_getter"/> // TextView.text
<EditText android:id="@+id/text"
android:layout_width="fill_parent" // EditText.LayoutParams.width
android:layout_height="wrap_content" // EditText.LayoutParams.height
android:layout_weight="0" // EditText.LinearLayoutParams.weight
android:paddingBottom="4"> // EditText.paddingBottom
<requestFocus />
</EditText>
<Button android:id="@+id/apply"
android:layout_width="wrap_content" // Button.LayoutParams.width
android:layout_height="wrap_content" // Button.LayoutParams.height
android:text="@string/apply" /> // TextView.text
</LinearLayout>
Example Code Use
The most common use is to load the XML file (located at res/main_screen.xml) and use it as the current screen, as shown here with the preceding file:
setContentView(R.layout.main_screen);
However, layout elements can also represent repeating elements used as templates.
Also see User Interface for more information on layouts.
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:
<declare-styleable name=your_java_class_name>. See res/values/attrs.xml in ApiDemos.
Source file format: XML file without an <?xml> declaration, and a <resources> root element containing one or more custom element tags.
Resource file location: {@code res/values/attrs.xml} (File name is arbitrary.)
Compiled resource datatype: Resource pointer to a {@link android.view.View} (or subclass) resource.
Resource reference name: R.styleable.some_file (Java).
A style 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.
A theme 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.
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.
For a complete discussion on styles and themes, read Applying Styles and Themes.
Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <style> tags.
Resource source file location: {@code res/values/styles.xml} (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.)
Compiled resource datatype: Resource pointer to a Java CharSequence.
Resource reference name:
R.style.styleID for the whole style, R.style.styleID.itemID for an individual setting
@[package:]style/styleID for a whole style, @[package:]style/styleID/itemID for an individual item. Note: to refer to a value in the currently applied theme, use "?" instead of "@" as described below (XML).
Syntax
<style name=string [parent=string] > <item name=string>Hex value | string value | reference</item>+ </style>
android:Theme for the base Android theme, or MyTheme for a theme defined in your package).
For examples of how to declare and apply styles and themes, read Applying Styles and Themes.
To make search appear to the user as a seamless system-wide feature, the Android framework offers APIs that let applications control how they are searched. Applications can customize how search is invoked, how the search dialog looks, and what type of search results are available, including suggestions that are shown as the user types.
In order to utilize the Android search framework, an application must provide a search configuration in the form of an XML resource. This section describes the search configuration XML in terms of its syntax and usage. For a more complete discussion about how to implement search features for your application, see {@link android.app.SearchManager}.
Source file format:
XML file requiring a <?xml version="1.0" encoding="utf-8"?>
declaration, and a root <searchable> element.
Resource source file location: {@code res/xml/searchable.xml} (The file name is arbitrary, but standard practice is to use searchable.xml.)
Compiled resource datatype: Resource pointer to an xml object.
Resource reference name:
R.xml.filename.
@[package:]xml/filename (e.g., @xml/searchable).
Syntax
<searchable xmlns:android="http://schemas.android.com/apk/res/android
android:label="@string/search_label"
... >
<actionkey
android:keycode="KEYCODE_CALL"
... >
</searchable>
More than one of the above values for searchMode can be used at once. For
example, you can declare two modes at once, like this:
searchMode="queryRewriteFromData|queryRewriteFromText"
If you have defined a content provider to generate search suggestions, you need to provide some more searchable metadata in order to configure communications with the content provider. The following are additional {@code <searchable>} attributes for use when providing search suggestions:
Beyond providing search suggestions while using your application's local search, you can also configure your search suggestions to be made available to Quick Search Box, which will allow users so receive search suggestions from your application content from outside your application. The following are additional {@code <searchable>} attributes for use when providing search suggestions to Quick Search Box:
To enable voice search for your Activity, you can add fields to the searchable metadata that enable and configure voice search. The following are additional {@code <searchable>} attributes for use when implementing voice search: