| 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">Quantity Strings (Plurals)</a></dt> |
| <dd>XML resource that carries different strings for pluralization.</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 retrieve 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 reference 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">Quantity Strings (Plurals)</h2> |
| |
| <p>Different languages have different rules for grammatical agreement with quantity. In English, |
| for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd |
| write "<i>n</i> books". This distinction between singular and plural is very common, but other |
| languages make finer distinctions. The full set supported by Android is <code>zero</code>, |
| <code>one</code>, <code>two</code>, <code>few</code>, <code>many</code>, and <code>other</code>. |
| |
| <p>The rules for deciding which case to use for a given language and quantity can be very complex, |
| so Android provides you with methods such as |
| {@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select |
| the appropriate resource for you. |
| |
| <p>Although historically called "quantity strings" (and still called that in API), quantity |
| strings should <i>only</i> be used for plurals. It would be a mistake to use quantity strings to |
| implement something like Gmail's "Inbox" versus "Inbox (12)" when there are unread messages, for |
| example. It might seem convenient to use quantity strings instead of an {@code if} statement, |
| but it's important to note that some languages (such as Chinese) don't make these grammatical |
| distinctions at all, so you'll always get the <code>other</code> string. |
| |
| <p>The selection of which string to use is made solely based on grammatical <i>necessity</i>. |
| In English, a string for <code>zero</code> will be ignored even if the quantity is 0, because 0 |
| isn't grammatically different from 2, or any other number except 1 ("zero books", "one book", |
| "two books", and so on). Conversely, in Korean <i>only</i> the <code>other</code> string will |
| ever be used. |
| |
| <p>Don't be misled either by the fact that, say, <code>two</code> sounds like it could only apply to |
| the quantity 2: a language may require that 2, 12, 102 (and so on) are all treated like one |
| another but differently to other quantities. Rely on your translator to know what distinctions |
| their language actually insists upon. |
| |
| <p>It's often possible to avoid quantity strings by using quantity-neutral formulations such as |
| "Books: 1". This will make your life and your translators' lives easier, if it's a style that's |
| in keeping with your application. |
| |
| <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=["zero" | "one" | "two" | "few" | "many" | "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 reference 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 when this string should be used. Valid |
| values, with non-exhaustive examples in parentheses: |
| <table> |
| <tr><th>Value</th><th>Description</th></tr> |
| <tr> |
| <td>{@code zero}</td><td>When the language requires special treatment of the number 0 (as in Arabic).</td> |
| </tr> |
| <tr> |
| <td>{@code one}</td><td>When the language requires special treatment of numbers like one (as with the number 1 in English and most other languages; in Russian, any number ending in 1 but not ending in 11 is in this class).</td> |
| </tr> |
| <tr> |
| <td>{@code two}</td><td>When the language requires special treatment of numbers like two (as with 2 in Welsh, or 102 in Slovenian).</td> |
| </tr> |
| <tr> |
| <td>{@code few}</td><td>When the language requires special treatment of "small" numbers (as with 2, 3, and 4 in Czech; or numbers ending 2, 3, or 4 but not 12, 13, or 14 in Polish).</td> |
| </tr> |
| <tr> |
| <td>{@code many}</td><td>When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).</td> |
| </tr> |
| <tr> |
| <td>{@code other}</td><td>When the language does not require special treatment of the given quantity (as with all numbers in Chinese, or 42 in English).</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"> |
| <!-- |
| As a developer, you should always supply "one" and "other" |
| strings. Your translators will know which strings are actually |
| needed for their language. Always include %d in "one" because |
| translators will need to use %d for languages where "one" |
| doesn't mean 1 (as explained above). |
| --> |
| <item quantity="one">%d song found.</item> |
| <item quantity="other">%d songs found.</item> |
| </plurals> |
| </resources> |
| </pre> |
| <p>XML file saved at {@code res/values-pl/strings.xml}:</p> |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <plurals name="numberOfSongsAvailable"> |
| <item quantity="one">Znaleziono %d piosenkę.</item> |
| <item quantity="few">Znaleziono %d piosenki.</item> |
| <item quantity="other">Znaleziono %d piosenek.</item> |
| </plurals> |
| </resources> |
| </pre> |
| <p>Java code:</p> |
| <pre> |
| int count = getNumberOfsongsAvailable(); |
| Resources res = {@link android.content.Context#getResources()}; |
| String songsFound = res.<a |
| href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)" |
| >getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count); |
| </pre> |
| |
| <p>When using the <a |
| href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code |
| getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes |
| <a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string |
| {@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and |
| the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural |
| strings do not include string formatting, you don't need to pass the third parameter to {@link |
| android.content.res.Resources#getQuantityString(int,int) getQuantityString}.</p> |
| </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 id="escaping_quotes">Escaping apostrophes and quotes</h3> |
| |
| <p> |
| If you have an apostrophe (<code>'</code>) in your string, you must either |
| escape it with a backslash (<code>\'</code>) or enclose the string in |
| double-quotes (<code>""</code>). For example, here are some strings 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> |
| <!-- Causes a compile error --> |
| </pre> |
| |
| <p> |
| If you have a double-quote in your string, you must escape it |
| (<code>\"</code>). Surrounding the string with single-quotes does |
| <em>not</em> work. |
| </p> |
| |
| <pre> |
| <string name="good_example">This is a \"good string\".</string> |
| <string name="bad_example">This is a "bad string".</string> |
| <!-- Quotes are stripped; displays as: This is a bad string. --> |
| <string name="bad_example_2">'This is another "bad string".'</string> |
| <!-- Causes a compile error --> |
| </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 arguments 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 id="StylingWithHTML">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> |
| |
| <h2 id="StylingWithSpannables">Styling with Spannables</h2> |
| <p> |
| A {@link android.text.Spannable} is a text object that you can style with |
| typeface properties such as color and font weight. You use |
| {@link android.text.SpannableStringBuilder} to build |
| your text and then apply styles defined in the {@link android.text.style} |
| package to the text. |
| </p> |
| |
| <p>You can use the following helper methods to set up much of the work |
| of creating spannable text:</p> |
| |
| <pre style="pretty-print"> |
| /** |
| * Returns a CharSequence that concatenates the specified array of CharSequence |
| * objects and then applies a list of zero or more tags to the entire range. |
| * |
| * @param content an array of character sequences to apply a style to |
| * @param tags the styled span objects to apply to the content |
| * such as android.text.style.StyleSpan |
| * |
| */ |
| private static CharSequence apply(CharSequence[] content, Object... tags) { |
| SpannableStringBuilder text = new SpannableStringBuilder(); |
| openTags(text, tags); |
| for (CharSequence item : content) { |
| text.append(item); |
| } |
| closeTags(text, tags); |
| return text; |
| } |
| |
| /** |
| * Iterates over an array of tags and applies them to the beginning of the specified |
| * Spannable object so that future text appended to the text will have the styling |
| * applied to it. Do not call this method directly. |
| */ |
| private static void openTags(Spannable text, Object[] tags) { |
| for (Object tag : tags) { |
| text.setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK); |
| } |
| } |
| |
| /** |
| * "Closes" the specified tags on a Spannable by updating the spans to be |
| * endpoint-exclusive so that future text appended to the end will not take |
| * on the same styling. Do not call this method directly. |
| */ |
| private static void closeTags(Spannable text, Object[] tags) { |
| int len = text.length(); |
| for (Object tag : tags) { |
| if (len > 0) { |
| text.setSpan(tag, 0, len, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); |
| } else { |
| text.removeSpan(tag); |
| } |
| } |
| } |
| </pre> |
| |
| <p> |
| The following <code>bold</code>, <code>italic</code>, and <code>color</code> |
| methods show you how to call the helper methods to apply |
| styles defined in the {@link android.text.style} package. You |
| can create similar methods to do other types of text styling. |
| </p> |
| |
| <pre style="pretty-print"> |
| /** |
| * Returns a CharSequence that applies boldface to the concatenation |
| * of the specified CharSequence objects. |
| */ |
| public static CharSequence bold(CharSequence... content) { |
| return apply(content, new StyleSpan(Typeface.BOLD)); |
| } |
| |
| /** |
| * Returns a CharSequence that applies italics to the concatenation |
| * of the specified CharSequence objects. |
| */ |
| public static CharSequence italic(CharSequence... content) { |
| return apply(content, new StyleSpan(Typeface.ITALIC)); |
| } |
| |
| /** |
| * Returns a CharSequence that applies a foreground color to the |
| * concatenation of the specified CharSequence objects. |
| */ |
| public static CharSequence color(int color, CharSequence... content) { |
| return apply(content, new ForegroundColorSpan(color)); |
| } |
| </pre> |
| |
| <p> |
| Here's an example of how to chain these methods to create a character sequence |
| with different types of styling applied to individual words: |
| </p> |
| |
| <pre style="pretty-print"> |
| // Create an italic "hello, " a red "world", |
| // and bold the entire sequence. |
| CharSequence text = bold(italic(res.getString(R.string.hello)), |
| color(Color.RED, res.getString(R.string.world))); |
| </pre> |