diff options
Diffstat (limited to 'docs/html/guide/topics/resources/string-resource.jd')
| -rw-r--r-- | docs/html/guide/topics/resources/string-resource.jd | 444 |
1 files changed, 444 insertions, 0 deletions
diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd new file mode 100644 index 0000000..81c5d55 --- /dev/null +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -0,0 +1,444 @@ +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> + + + |