| 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> |
| |
| |
| |