445 lines
15 KiB
Plaintext
445 lines
15 KiB
Plaintext
page.title=String Resources
|
|
parent.title=Resource Types
|
|
parent.link=available-resources.html
|
|
@jd:body
|
|
|
|
<p>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:</p>
|
|
|
|
<dl>
|
|
<dt><a href="#String">String</a></dt>
|
|
<dd>XML resource that provides a single string.</dd>
|
|
<dt><a href="#StringArray">String Array</a></dt>
|
|
<dd>XML resource that provides an array of strings.</dd>
|
|
<dt><a href="#Plurals">Plurals</a></dt>
|
|
<dd>XML resource that carries different strings for different pluralizations
|
|
of the same word or phrase.</dd>
|
|
</dl>
|
|
|
|
<p>All strings are capable of applying some styling markup and formatting arguments. For
|
|
information about styling and formatting strings, see the section about <a
|
|
href="#FormattingAndStyling">Formatting and Styling</a>.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="String">String</h2>
|
|
|
|
<p>A single string that can be referenced from the application or from other resource files (such
|
|
as an XML layout).</p>
|
|
|
|
<p class="note"><strong>Note:</strong> A string is a simple resource that is referenced
|
|
using the value provided in the {@code 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 {@code <resources>} element.</p>
|
|
|
|
<dl class="xml">
|
|
|
|
<dt>file location:</dt>
|
|
<dd><code>res/values/<em>filename</em>.xml</code><br/>
|
|
The filename is arbitrary. The {@code <string>} element's {@code name} will be used as the
|
|
resource ID.</dd>
|
|
|
|
<dt>compiled resource datatype:</dt>
|
|
<dd>Resource pointer to a {@link java.lang.String}.</dd>
|
|
|
|
<dt>resource reference:</dt>
|
|
<dd>
|
|
In Java: <code>R.string.<em>string_name</em></code><br/>
|
|
In XML:<code>@string/<em>string_name</em></code>
|
|
</dd>
|
|
|
|
<dt>syntax:</dt>
|
|
<dd>
|
|
<pre class="stx">
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<<a href="#string-resources-element">resources</a>>
|
|
<<a href="#string-element">string</a>
|
|
name="<em>string_name</em>"
|
|
><em>text_string</em></string>
|
|
</resources>
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>elements:</dt>
|
|
<dd>
|
|
<dl class="tag-list">
|
|
|
|
<dt id="string-resources-element"><code><resources></code></dt>
|
|
<dd><strong>Required.</strong> This must be the root node.
|
|
<p>No attributes.</p>
|
|
</dd>
|
|
<dt id="string-element"><code><string></code></dt>
|
|
<dd>A string, which can include styling tags. Beware that you must escape apostrophes and
|
|
quotation marks. For more information about how to properly style and format your strings see <a
|
|
href="#FormattingAndStyling">Formatting and Styling</a>, below.
|
|
<p class="caps">attributes:</p>
|
|
<dl class="atn-list">
|
|
<dt><code>name</code></dt>
|
|
<dd><em>String</em>. A name for the string. This name will be used as the resource
|
|
ID.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
</dl>
|
|
</dd> <!-- end elements and attributes -->
|
|
|
|
<dt>example:</dt>
|
|
<dd>XML file saved at <code>res/values/strings.xml</code>:
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<resources>
|
|
<string name="hello">Hello!</string>
|
|
</resources>
|
|
</pre>
|
|
|
|
<p>This layout XML applies a string to a View:</p>
|
|
<pre>
|
|
<TextView
|
|
android:layout_width="fill_parent"
|
|
android:layout_height="wrap_content"
|
|
<strong>android:text="@string/hello"</strong> />
|
|
</pre>
|
|
|
|
<p>This application code retrieves a string:</p>
|
|
<pre>
|
|
String string = {@link android.content.Context#getString(int) getString}(R.string.hello);
|
|
</pre>
|
|
<p>You can use either {@link android.content.Context#getString(int)} or
|
|
{@link android.content.Context#getText(int)} to retieve a string. {@link
|
|
android.content.Context#getText(int)} will retain any rich text styling applied to the string.</p>
|
|
|
|
</dd> <!-- end example -->
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="StringArray">String Array</h2>
|
|
|
|
<p>An array of strings that can be referenced from the application.</p>
|
|
|
|
<p class="note"><strong>Note:</strong> A string array is a simple resource that is referenced
|
|
using the value provided in the {@code 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 {@code <resources>} element.</p>
|
|
|
|
<dl class="xml">
|
|
|
|
<dt>file location:</dt>
|
|
<dd><code>res/values/<em>filename</em>.xml</code><br/>
|
|
The filename is arbitrary. The {@code <string-array>} element's {@code name} will be used as the
|
|
resource ID.</dd>
|
|
|
|
<dt>compiled resource datatype:</dt>
|
|
<dd>Resource pointer to an array of {@link java.lang.String}s.</dd>
|
|
|
|
<dt>resource reference:</dt>
|
|
<dd>
|
|
In Java: <code>R.array.<em>string_array_name</em></code>
|
|
</dd>
|
|
|
|
<dt>syntax:</dt>
|
|
<dd>
|
|
<pre class="stx">
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<<a href="#string-array-resources-element">resources</a>>
|
|
<<a href="#string-array-element">string-array</a>
|
|
name="<em>string_array_name</em>">
|
|
<<a href="#string-array-item-element">item</a>
|
|
><em>text_string</em></item>
|
|
</string-array>
|
|
</resources>
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>elements:</dt>
|
|
<dd>
|
|
<dl class="tag-list">
|
|
<dt id="string-array-resources-element"><code><resources></code></dt>
|
|
<dd><strong>Required.</strong> This must be the root node.
|
|
<p>No attributes.</p>
|
|
</dd>
|
|
<dt id="string-array-element"><code><string-array></code></dt>
|
|
<dd>Defines an array of strings. Contains one or more {@code <item>} elements.
|
|
<p class="caps">attributes:</p>
|
|
<dl class="atn-list">
|
|
<dt><code>name</code></dt>
|
|
<dd><em>String</em>. A name for the array. This name will be used as the resource
|
|
ID to reference the array.</dd>
|
|
</dl>
|
|
|
|
</dd>
|
|
<dt id="string-array-item-element"><code><item></code></dt>
|
|
<dd>A string, which can include styling tags. The value can be a referenced to another
|
|
string resource. Must be a child of a {@code <string-array>} element. Beware that you
|
|
must escape apostrophes and
|
|
quotation marks. See <a href="#FormattingAndStyling">Formatting and Styling</a>, below, for
|
|
information about to properly style and format your strings.
|
|
<p>No attributes.</p>
|
|
</dd>
|
|
</dl>
|
|
</dd> <!-- end elements -->
|
|
|
|
<dt>example:</dt>
|
|
<dd>XML file saved at <code>res/values/strings.xml</code>:
|
|
<pre>
|
|
<?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>
|
|
</pre>
|
|
|
|
<p>This application code retrieves a string array:</p>
|
|
<pre>
|
|
Resources res = {@link android.content.Context#getResources()};
|
|
String[] planets = res.{@link android.content.res.Resources#getStringArray(int)
|
|
getStringArray}(R.array.planets_array);
|
|
</pre>
|
|
</dd> <!-- end example -->
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="Plurals">Plurals</h2>
|
|
|
|
<p>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 {@link android.content.res.Resources#getQuantityString(int,int)
|
|
getQuantityString()}, you must pass a "count", which will determine the plural form you
|
|
require and return that string to you.</p>
|
|
|
|
<p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is
|
|
referenced using the value provided in the {@code 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 {@code <resources>} element.</p>
|
|
|
|
<dl class="xml">
|
|
|
|
<dt>file location:</dt>
|
|
<dd><code>res/values/<em>filename</em>.xml</code><br/>
|
|
The filename is arbitrary. The {@code <plurals>} element's {@code name} will be used as the
|
|
resource ID.</dd>
|
|
|
|
<dt>resource reference:</dt>
|
|
<dd>
|
|
In Java: <code>R.plurals.<em>plural_name</em></code>
|
|
</dd>
|
|
|
|
<dt>syntax:</dt>
|
|
<dd>
|
|
<pre class="stx">
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<<a href="#plurals-resources-element">resources</a>>
|
|
<<a href="#plurals-element">plurals</a>
|
|
name="<em>plural_name</em>">
|
|
<<a href="#plurals-item-element">item</a>
|
|
quantity=["one" | "other"]
|
|
><em>text_string</em></item>
|
|
</plurals>
|
|
</resources>
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>elements:</dt>
|
|
<dd>
|
|
<dl class="tag-list">
|
|
|
|
<dt id="plurals-resources-element"><code><resources></code></dt>
|
|
<dd><strong>Required.</strong> This must be the root node.
|
|
<p>No attributes.</p>
|
|
</dd>
|
|
<dt id="plurals-element"><code><plurals></code></dt>
|
|
<dd>A collection of strings, of which, one string is provided depending on the amount of
|
|
something. Contains one or more {@code <item>} elements.
|
|
<p class="caps">attributes:</p>
|
|
<dl class="atn-list">
|
|
<dt><code>name</code></dt>
|
|
<dd><em>String</em>. A name for the pair of strings. This name will be used as the
|
|
resource ID.</dd>
|
|
</dl>
|
|
|
|
</dd>
|
|
<dt id="plurals-item-element"><code><item></code></dt>
|
|
<dd>A plural or singular string. The value can be a referenced to another
|
|
string resource. Must be a child of a {@code <plurals>} element. Beware that you must
|
|
escape apostrophes and quotation marks. See <a href="#FormattingAndStyling">Formatting and
|
|
Styling</a>, below, for information about to properly style and format your strings.
|
|
<p class="caps">attributes:</p>
|
|
<dl class="atn-list">
|
|
<dt><code>quantity</code></dt>
|
|
<dd><em>Keyword</em>. A value indicating the case in which this string should be used. Valid
|
|
values:
|
|
<table>
|
|
<tr><th>Value</th><th>Description</th></tr>
|
|
<tr>
|
|
<td>{@code one}</td><td>When there is one (a singular string).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>{@code other}</td><td>When the quantity is anything other than one (a plural
|
|
string, but also used when the count is zero).</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
</dl>
|
|
</dd> <!-- end elements -->
|
|
|
|
<dt>example:</dt>
|
|
<dd>XML file saved at {@code res/values/strings.xml}:</p>
|
|
<pre>
|
|
<?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>
|
|
</pre>
|
|
<p>Java code:</p>
|
|
<pre>
|
|
int count = getNumberOfsongsAvailable();
|
|
Resources res = {@link android.content.Context#getResources()};
|
|
String songsFound = res.{@link android.content.res.Resources#getQuantityString(int,int)
|
|
getQuantityString}(R.plurals.numberOfSongsAvailable, count);
|
|
</pre>
|
|
</dd> <!-- end example -->
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="FormattingAndStyling">Formatting and Styling</h2>
|
|
|
|
<p>Here are a few important things you should know about how to properly
|
|
format and style your string resources.</p>
|
|
|
|
|
|
<h3>Escaping apostrophes and quotes</h3>
|
|
|
|
<p>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:</p>
|
|
|
|
<pre>
|
|
<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&apos;t work</string>
|
|
</pre>
|
|
|
|
|
|
<h3>Formatting strings</h3>
|
|
|
|
<p>If you need to format your strings using <a
|
|
href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
|
|
java.lang.Object...)">{@code String.format(String, Object...)}</a>,
|
|
then you can do so by putting
|
|
your format arguments in the string resource. For example, with the following resource:</p>
|
|
|
|
<pre>
|
|
<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>
|
|
</pre>
|
|
|
|
<p>In this example, the format string has two arguments: {@code %1$s} is a string and {@code %2$d}
|
|
is a decimal number. You can format the string with arguements from your application like this:</p>
|
|
|
|
<pre>
|
|
Resources res = {@link android.content.Context#getResources()};
|
|
String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
|
|
java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount);
|
|
</pre>
|
|
|
|
|
|
|
|
<h3>Styling with HTML markup</h3>
|
|
|
|
<p>You can add styling to your strings with HTML markup. For example:</p>
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<resources>
|
|
<string name="welcome">Welcome to <b>Android</b>!</string>
|
|
</resources>
|
|
</pre>
|
|
<p>Supported HTML elements include:</p>
|
|
<ul>
|
|
<li>{@code <b>} for <b>bold</b> text.</li>
|
|
<li>{@code <i>} for <i>italic</i> text.</li>
|
|
<li>{@code <u>} for <u>underline</u> text.</li>
|
|
</ul>
|
|
|
|
<p>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 <a
|
|
href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
|
|
java.lang.Object...)">{@code String.format(String, Object...)}</a>
|
|
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 {@link android.text.Html#fromHtml(String)},
|
|
after the formatting takes place. For example:</p>
|
|
|
|
<ol>
|
|
<li>Store your styled text resource as an HTML-escaped string:
|
|
<pre>
|
|
<resources>
|
|
<string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string>
|
|
</resources>
|
|
</pre>
|
|
<p>In this formatted string, a {@code <b>} element is added. Notice that the opening bracket is
|
|
HTML-escaped, using the {@code &lt;} notation.</p>
|
|
</li>
|
|
<li>Then format the string as usual, but also call {@link android.text.Html#fromHtml} to
|
|
convert the HTML text into styled text:
|
|
<pre>
|
|
Resources res = {@link android.content.Context#getResources()};
|
|
String text = String.<a
|
|
href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
|
|
java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount);
|
|
CharSequence styledText = Html.fromHtml(text);
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>Because the {@link android.text.Html#fromHtml} method will format all HTML entities, be sure to
|
|
escape any possible HTML characters in the strings you use with the formatted text, using
|
|
{@link android.text.TextUtils#htmlEncode}. For instance, if you'll be passing a string argument to
|
|
<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
|
|
java.lang.Object...)">{@code String.format()}</a> that may contain characters such as
|
|
"<" or "&", then they must be escaped before formatting, so that when the formatted string
|
|
is passed through {@link android.text.Html#fromHtml}, the characters come out the way they were
|
|
originally written. For example:</p>
|
|
<pre>
|
|
String escapedUsername = TextUtil.{@link android.text.TextUtils#htmlEncode htmlEncode}(username);
|
|
|
|
Resources res = {@link android.content.Context#getResources()};
|
|
String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
|
|
java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), escapedUsername, mailCount);
|
|
CharSequence styledText = Html.fromHtml(text);
|
|
</pre>
|
|
|
|
|
|
|