A string resource provides text strings for your application with optional text styling and formatting. There are three types of resources that can provide your application with strings:
All strings are capable of applying some styling markup and formatting arguments. For information about styling and formatting strings, see the section about Formatting and Styling.
A single string that can be referenced from the application or from other resource files (such as an XML layout).
Note: A string is a simple resource that is referenced
using the value provided in the name attribute (not the name of the XML file). So, you can
combine string resources with other simple resources in the one XML file,
under one <resources> element.
res/values/filename.xml<string> element's name will be used as the
resource ID.String.R.string.string_name@string/string_name
<?xml version="1.0" encoding="utf-8"?> <resources> <string name="string_name" >text_string</string> </resources>
res/values/strings.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="hello">Hello!</string>
</resources>
This layout XML applies a string to a View:
<TextView
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="@string/hello" />
This application code retrieves a string:
String string = getString(R.string.hello);
You can use either getString(int) or
getText(int) to retieve a string. getText(int) will retain any rich text styling applied to the string.
An array of strings that can be referenced from the application.
Note: A string array is a simple resource that is referenced
using the value provided in the name attribute (not the name of the XML file). As
such, you can combine string array resources with other simple resources in the one XML file,
under one <resources> element.
res/values/filename.xml<string-array> element's name will be used as the
resource ID.Strings.R.array.string_array_name
<?xml version="1.0" encoding="utf-8"?> <resources> <string-array name="string_array_name"> <item >text_string</item> </string-array> </resources>
res/values/strings.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="planets_array">
<item>Mercury</item>
<item>Venus</item>
<item>Earth</item>
<item>Mars</item>
</string-array>
</resources>
This application code retrieves a string array:
Resources res =getResources(); String[] planets = res.getStringArray(R.array.planets_array);
A pair of strings that each provide a different plural form of the same word or phrase,
which you can collectively reference from the application. When you request the plurals
resource using a method such as getQuantityString(), you must pass a "count", which will determine the plural form you
require and return that string to you.
Note: A plurals collection is a simple resource that is
referenced using the value provided in the name attribute (not the name of the XML
file). As such, you can combine plurals resources with other simple resources in the one
XML file, under one <resources> element.
res/values/filename.xml<plurals> element's name will be used as the
resource ID.R.plurals.plural_name
<?xml version="1.0" encoding="utf-8"?> <resources> <plurals name="plural_name"> <item quantity=["one" | "other"] >text_string</item> </plurals> </resources>
res/values/strings.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<plurals name="numberOfSongsAvailable">
<item quantity="one">One song found.</item>
<item quantity="other">%d songs found.</item>
</plurals>
</resources>
Java code:
int count = getNumberOfsongsAvailable(); Resources res =getResources(); String songsFound = res.getQuantityString(R.plurals.numberOfSongsAvailable, count);
Here are a few important things you should know about how to properly format and style your string resources.
If you have an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other type of enclosing quotes. For example, here are some stings that do and don't work:
<string name="good_example">"This'll work"</string> <string name="good_example_2">This\'ll also work</string> <string name="bad_example">This doesn't work</string> <string name="bad_example_2">XML encodings don't work</string>
If you need to format your strings using String.format(String, Object...),
then you can do so by putting
your format arguments in the string resource. For example, with the following resource:
<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>
In this example, the format string has two arguments: %1$s is a string and %2$d
is a decimal number. You can format the string with arguements from your application like this:
Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);
You can add styling to your strings with HTML markup. For example:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="welcome">Welcome to <b>Android</b>!</string>
</resources>
Supported HTML elements include:
<b> for bold text.<i> for italic text.<u> for underline text.Sometimes you may want to create a styled text resource that is also used as a format
string. Normally, this won't work because the String.format(String, Object...)
method will strip all the style
information from the string. The work-around to this is to write the HTML tags with escaped
entities, which are then recovered with fromHtml(String),
after the formatting takes place. For example:
<resources> <string name="welcome_messages">Hello, %1$s! You have <b>%2$d new messages</b>.</string> </resources>
In this formatted string, a <b> element is added. Notice that the opening bracket is
HTML-escaped, using the < notation.
fromHtml(String) to
convert the HTML text into styled text:
Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);
CharSequence styledText = Html.fromHtml(text);
Because the fromHtml(String) method will format all HTML entities, be sure to
escape any possible HTML characters in the strings you use with the formatted text, using
htmlEncode(String). For instance, if you'll be passing a string argument to
String.format() that may contain characters such as
"<" or "&", then they must be escaped before formatting, so that when the formatted string
is passed through fromHtml(String), the characters come out the way they were
originally written. For example:
String escapedUsername = TextUtil.htmlEncode(username); Resources res =getResources(); String text = String.format(res.getString(R.string.welcome_messages), escapedUsername, mailCount); CharSequence styledText = Html.fromHtml(text);