1 page.title=String Resources 2 parent.title=Resource Types 3 parent.link=available-resources.html 4 @jd:body 5 6 <p>A string resource provides text strings for your application 7 with optional text styling and formatting. There are three types of resources that can provide 8 your application with strings:</p> 9 10 <dl> 11 <dt><a href="#String">String</a></dt> 12 <dd>XML resource that provides a single string.</dd> 13 <dt><a href="#StringArray">String Array</a></dt> 14 <dd>XML resource that provides an array of strings.</dd> 15 <dt><a href="#Plurals">Quantity Strings (Plurals)</a></dt> 16 <dd>XML resource that carries different strings for pluralization.</dd> 17 </dl> 18 19 <p>All strings are capable of applying some styling markup and formatting arguments. For 20 information about styling and formatting strings, see the section about <a 21 href="#FormattingAndStyling">Formatting and Styling</a>.</p> 22 23 <h2 id="String">String</h2> 24 25 <p>A single string that can be referenced from the application or from other resource files (such 26 as an XML layout).</p> 27 28 <p class="note"><strong>Note:</strong> A string is a simple resource that is referenced 29 using the value provided in the {@code name} attribute (not the name of the XML file). So, you can 30 combine string resources with other simple resources in the one XML file, 31 under one {@code <resources>} element.</p> 32 33 <dl class="xml"> 34 35 <dt>file location:</dt> 36 <dd><code>res/values/<em>filename</em>.xml</code><br/> 37 The filename is arbitrary. The {@code <string>} element's {@code name} will be used as the 38 resource ID.</dd> 39 40 <dt>compiled resource datatype:</dt> 41 <dd>Resource pointer to a {@link java.lang.String}.</dd> 42 43 <dt>resource reference:</dt> 44 <dd> 45 In Java: <code>R.string.<em>string_name</em></code><br/> 46 In XML:<code>@string/<em>string_name</em></code> 47 </dd> 48 49 <dt>syntax:</dt> 50 <dd> 51 <pre class="stx"> 52 <?xml version="1.0" encoding="utf-8"?> 53 <<a href="#string-resources-element">resources</a>> 54 <<a href="#string-element">string</a> 55 name="<em>string_name</em>" 56 ><em>text_string</em></string> 57 </resources> 58 </pre> 59 </dd> 60 61 <dt>elements:</dt> 62 <dd> 63 <dl class="tag-list"> 64 65 <dt id="string-resources-element"><code><resources></code></dt> 66 <dd><strong>Required.</strong> This must be the root node. 67 <p>No attributes.</p> 68 </dd> 69 <dt id="string-element"><code><string></code></dt> 70 <dd>A string, which can include styling tags. Beware that you must escape apostrophes and 71 quotation marks. For more information about how to properly style and format your strings see <a 72 href="#FormattingAndStyling">Formatting and Styling</a>, below. 73 <p class="caps">attributes:</p> 74 <dl class="atn-list"> 75 <dt><code>name</code></dt> 76 <dd><em>String</em>. A name for the string. This name will be used as the resource 77 ID.</dd> 78 </dl> 79 </dd> 80 81 </dl> 82 </dd> <!-- end elements and attributes --> 83 84 <dt>example:</dt> 85 <dd>XML file saved at <code>res/values/strings.xml</code>: 86 <pre> 87 <?xml version="1.0" encoding="utf-8"?> 88 <resources> 89 <string name="hello">Hello!</string> 90 </resources> 91 </pre> 92 93 <p>This layout XML applies a string to a View:</p> 94 <pre> 95 <TextView 96 android:layout_width="fill_parent" 97 android:layout_height="wrap_content" 98 <strong>android:text="@string/hello"</strong> /> 99 </pre> 100 101 <p>This application code retrieves a string:</p> 102 <pre> 103 String string = {@link android.content.Context#getString(int) getString}(R.string.hello); 104 </pre> 105 <p>You can use either {@link android.content.Context#getString(int)} or 106 {@link android.content.Context#getText(int)} to retrieve a string. {@link 107 android.content.Context#getText(int)} will retain any rich text styling applied to the string.</p> 108 109 </dd> <!-- end example --> 110 111 </dl> 112 113 114 115 116 117 118 119 120 121 <h2 id="StringArray">String Array</h2> 122 123 <p>An array of strings that can be referenced from the application.</p> 124 125 <p class="note"><strong>Note:</strong> A string array is a simple resource that is referenced 126 using the value provided in the {@code name} attribute (not the name of the XML file). As 127 such, you can combine string array resources with other simple resources in the one XML file, 128 under one {@code <resources>} element.</p> 129 130 <dl class="xml"> 131 132 <dt>file location:</dt> 133 <dd><code>res/values/<em>filename</em>.xml</code><br/> 134 The filename is arbitrary. The {@code <string-array>} element's {@code name} will be used as the 135 resource ID.</dd> 136 137 <dt>compiled resource datatype:</dt> 138 <dd>Resource pointer to an array of {@link java.lang.String}s.</dd> 139 140 <dt>resource reference:</dt> 141 <dd> 142 In Java: <code>R.array.<em>string_array_name</em></code> 143 </dd> 144 145 <dt>syntax:</dt> 146 <dd> 147 <pre class="stx"> 148 <?xml version="1.0" encoding="utf-8"?> 149 <<a href="#string-array-resources-element">resources</a>> 150 <<a href="#string-array-element">string-array</a> 151 name="<em>string_array_name</em>"> 152 <<a href="#string-array-item-element">item</a> 153 ><em>text_string</em></item> 154 </string-array> 155 </resources> 156 </pre> 157 </dd> 158 159 <dt>elements:</dt> 160 <dd> 161 <dl class="tag-list"> 162 <dt id="string-array-resources-element"><code><resources></code></dt> 163 <dd><strong>Required.</strong> This must be the root node. 164 <p>No attributes.</p> 165 </dd> 166 <dt id="string-array-element"><code><string-array></code></dt> 167 <dd>Defines an array of strings. Contains one or more {@code <item>} elements. 168 <p class="caps">attributes:</p> 169 <dl class="atn-list"> 170 <dt><code>name</code></dt> 171 <dd><em>String</em>. A name for the array. This name will be used as the resource 172 ID to reference the array.</dd> 173 </dl> 174 175 </dd> 176 <dt id="string-array-item-element"><code><item></code></dt> 177 <dd>A string, which can include styling tags. The value can be a reference to another 178 string resource. Must be a child of a {@code <string-array>} element. Beware that you 179 must escape apostrophes and 180 quotation marks. See <a href="#FormattingAndStyling">Formatting and Styling</a>, below, for 181 information about to properly style and format your strings. 182 <p>No attributes.</p> 183 </dd> 184 </dl> 185 </dd> <!-- end elements --> 186 187 <dt>example:</dt> 188 <dd>XML file saved at <code>res/values/strings.xml</code>: 189 <pre> 190 <?xml version="1.0" encoding="utf-8"?> 191 <resources> 192 <string-array name="planets_array"> 193 <item>Mercury</item> 194 <item>Venus</item> 195 <item>Earth</item> 196 <item>Mars</item> 197 </string-array> 198 </resources> 199 </pre> 200 201 <p>This application code retrieves a string array:</p> 202 <pre> 203 Resources res = {@link android.content.Context#getResources()}; 204 String[] planets = res.{@link android.content.res.Resources#getStringArray(int) 205 getStringArray}(R.array.planets_array); 206 </pre> 207 </dd> <!-- end example --> 208 209 </dl> 210 211 212 213 214 215 216 217 <h2 id="Plurals">Quantity Strings (Plurals)</h2> 218 219 <p>Different languages have different rules for grammatical agreement with quantity. In English, 220 for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd 221 write "<i>n</i> books". This distinction between singular and plural is very common, but other 222 languages make finer distinctions. The full set supported by Android is <code>zero</code>, 223 <code>one</code>, <code>two</code>, <code>few</code>, <code>many</code>, and <code>other</code>. 224 225 <p>The rules for deciding which case to use for a given language and quantity can be very complex, 226 so Android provides you with methods such as 227 {@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select 228 the appropriate resource for you. 229 230 <p>Although historically called "quantity strings" (and still called that in API), quantity 231 strings should <i>only</i> be used for plurals. It would be a mistake to use quantity strings to 232 implement something like Gmail's "Inbox" versus "Inbox (12)" when there are unread messages, for 233 example. It might seem convenient to use quantity strings instead of an {@code if} statement, 234 but it's important to note that some languages (such as Chinese) don't make these grammatical 235 distinctions at all, so you'll always get the <code>other</code> string. 236 237 <p>The selection of which string to use is made solely based on grammatical <i>necessity</i>. 238 In English, a string for <code>zero</code> will be ignored even if the quantity is 0, because 0 239 isn't grammatically different from 2, or any other number except 1 ("zero books", "one book", 240 "two books", and so on). Conversely, in Korean <i>only</i> the <code>other</code> string will 241 ever be used. 242 243 <p>Don't be misled either by the fact that, say, <code>two</code> sounds like it could only apply to 244 the quantity 2: a language may require that 2, 12, 102 (and so on) are all treated like one 245 another but differently to other quantities. Rely on your translator to know what distinctions 246 their language actually insists upon. 247 248 <p>It's often possible to avoid quantity strings by using quantity-neutral formulations such as 249 "Books: 1". This will make your life and your translators' lives easier, if it's a style that's 250 in keeping with your application. 251 252 <p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is 253 referenced using the value provided in the {@code name} attribute (not the name of the XML 254 file). As such, you can combine plurals resources with other simple resources in the one 255 XML file, under one {@code <resources>} element.</p> 256 257 <dl class="xml"> 258 259 <dt>file location:</dt> 260 <dd><code>res/values/<em>filename</em>.xml</code><br/> 261 The filename is arbitrary. The {@code <plurals>} element's {@code name} will be used as the 262 resource ID.</dd> 263 264 <dt>resource reference:</dt> 265 <dd> 266 In Java: <code>R.plurals.<em>plural_name</em></code> 267 </dd> 268 269 <dt>syntax:</dt> 270 <dd> 271 <pre class="stx"> 272 <?xml version="1.0" encoding="utf-8"?> 273 <<a href="#plurals-resources-element">resources</a>> 274 <<a href="#plurals-element">plurals</a> 275 name="<em>plural_name</em>"> 276 <<a href="#plurals-item-element">item</a> 277 quantity=["zero" | "one" | "two" | "few" | "many" | "other"] 278 ><em>text_string</em></item> 279 </plurals> 280 </resources> 281 </pre> 282 </dd> 283 284 <dt>elements:</dt> 285 <dd> 286 <dl class="tag-list"> 287 288 <dt id="plurals-resources-element"><code><resources></code></dt> 289 <dd><strong>Required.</strong> This must be the root node. 290 <p>No attributes.</p> 291 </dd> 292 <dt id="plurals-element"><code><plurals></code></dt> 293 <dd>A collection of strings, of which, one string is provided depending on the amount of 294 something. Contains one or more {@code <item>} elements. 295 <p class="caps">attributes:</p> 296 <dl class="atn-list"> 297 <dt><code>name</code></dt> 298 <dd><em>String</em>. A name for the pair of strings. This name will be used as the 299 resource ID.</dd> 300 </dl> 301 302 </dd> 303 <dt id="plurals-item-element"><code><item></code></dt> 304 <dd>A plural or singular string. The value can be a reference to another 305 string resource. Must be a child of a {@code <plurals>} element. Beware that you must 306 escape apostrophes and quotation marks. See <a href="#FormattingAndStyling">Formatting and 307 Styling</a>, below, for information about to properly style and format your strings. 308 <p class="caps">attributes:</p> 309 <dl class="atn-list"> 310 <dt><code>quantity</code></dt> 311 <dd><em>Keyword</em>. A value indicating when this string should be used. Valid 312 values, with non-exhaustive examples in parentheses: 313 <table> 314 <tr><th>Value</th><th>Description</th></tr> 315 <tr> 316 <td>{@code zero}</td><td>When the language requires special treatment of the number 0 (as in Arabic).</td> 317 </tr> 318 <tr> 319 <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> 320 </tr> 321 <tr> 322 <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> 323 </tr> 324 <tr> 325 <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> 326 </tr> 327 <tr> 328 <td>{@code many}</td><td>When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).</td> 329 </tr> 330 <tr> 331 <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> 332 </tr> 333 </table> 334 </dd> 335 </dl> 336 </dd> 337 338 </dl> 339 </dd> <!-- end elements --> 340 341 <dt>example:</dt> 342 <dd>XML file saved at {@code res/values/strings.xml}:</p> 343 <pre> 344 <?xml version="1.0" encoding="utf-8"?> 345 <resources> 346 <plurals name="numberOfSongsAvailable"> 347 <!-- 348 As a developer, you should always supply "one" and "other" 349 strings. Your translators will know which strings are actually 350 needed for their language. Always include %d in "one" because 351 translators will need to use %d for languages where "one" 352 doesn't mean 1 (as explained above). 353 --> 354 <item quantity="one">%d song found.</item> 355 <item quantity="other">%d songs found.</item> 356 </plurals> 357 </resources> 358 </pre> 359 <p>XML file saved at {@code res/values-pl/strings.xml}:</p> 360 <pre> 361 <?xml version="1.0" encoding="utf-8"?> 362 <resources> 363 <plurals name="numberOfSongsAvailable"> 364 <item quantity="one">Znaleziono %d piosenkę.</item> 365 <item quantity="few">Znaleziono %d piosenki.</item> 366 <item quantity="other">Znaleziono %d piosenek.</item> 367 </plurals> 368 </resources> 369 </pre> 370 <p>Java code:</p> 371 <pre> 372 int count = getNumberOfsongsAvailable(); 373 Resources res = {@link android.content.Context#getResources()}; 374 String songsFound = res.<a 375 href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)" 376 >getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count); 377 </pre> 378 379 <p>When using the <a 380 href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code 381 getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes 382 <a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string 383 {@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and 384 the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural 385 strings do not include string formatting, you don't need to pass the third parameter to {@link 386 android.content.res.Resources#getQuantityString(int,int) getQuantityString}.</p> 387 </dd> <!-- end example --> 388 389 </dl> 390 391 392 393 394 395 396 397 398 <h2 id="FormattingAndStyling">Formatting and Styling</h2> 399 400 <p>Here are a few important things you should know about how to properly 401 format and style your string resources.</p> 402 403 404 <h3 id="escaping_quotes">Escaping apostrophes and quotes</h3> 405 406 <p> 407 If you have an apostrophe (<code>'</code>) in your string, you must either 408 escape it with a backslash (<code>\'</code>) or enclose the string in 409 double-quotes (<code>""</code>). For example, here are some strings that do 410 and don't work: 411 </p> 412 413 <pre> 414 <string name="good_example">This\'ll work</string> 415 <string name="good_example_2">"This'll also work"</string> 416 <string name="bad_example">This doesn't work</string> 417 <!-- Causes a compile error --> 418 </pre> 419 420 <p> 421 If you have a double-quote in your string, you must escape it 422 (<code>\"</code>). Surrounding the string with single-quotes does 423 <em>not</em> work. 424 </p> 425 426 <pre> 427 <string name="good_example">This is a \"good string\".</string> 428 <string name="bad_example">This is a "bad string".</string> 429 <!-- Quotes are stripped; displays as: This is a bad string. --> 430 <string name="bad_example_2">'This is another "bad string".'</string> 431 <!-- Causes a compile error --> 432 </pre> 433 434 <h3>Formatting strings</h3> 435 436 <p>If you need to format your strings using <a 437 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 438 java.lang.Object...)">{@code String.format(String, Object...)}</a>, 439 then you can do so by putting 440 your format arguments in the string resource. For example, with the following resource:</p> 441 442 <pre> 443 <string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string> 444 </pre> 445 446 <p>In this example, the format string has two arguments: {@code %1$s} is a string and {@code %2$d} 447 is a decimal number. You can format the string with arguments from your application like this:</p> 448 449 <pre> 450 Resources res = {@link android.content.Context#getResources()}; 451 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 452 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount); 453 </pre> 454 455 456 457 <h3 id="StylingWithHTML">Styling with HTML markup</h3> 458 459 <p>You can add styling to your strings with HTML markup. For example:</p> 460 <pre> 461 <?xml version="1.0" encoding="utf-8"?> 462 <resources> 463 <string name="welcome">Welcome to <b>Android</b>!</string> 464 </resources> 465 </pre> 466 <p>Supported HTML elements include:</p> 467 <ul> 468 <li>{@code <b>} for <b>bold</b> text.</li> 469 <li>{@code <i>} for <i>italic</i> text.</li> 470 <li>{@code <u>} for <u>underline</u> text.</li> 471 </ul> 472 473 <p>Sometimes you may want to create a styled text resource that is also used as a format 474 string. Normally, this won't work because the <a 475 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 476 java.lang.Object...)">{@code String.format(String, Object...)}</a> 477 method will strip all the style 478 information from the string. The work-around to this is to write the HTML tags with escaped 479 entities, which are then recovered with {@link android.text.Html#fromHtml(String)}, 480 after the formatting takes place. For example:</p> 481 482 <ol> 483 <li>Store your styled text resource as an HTML-escaped string: 484 <pre> 485 <resources> 486 <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string> 487 </resources> 488 </pre> 489 <p>In this formatted string, a {@code <b>} element is added. Notice that the opening bracket is 490 HTML-escaped, using the {@code &lt;} notation.</p> 491 </li> 492 <li>Then format the string as usual, but also call {@link android.text.Html#fromHtml} to 493 convert the HTML text into styled text: 494 <pre> 495 Resources res = {@link android.content.Context#getResources()}; 496 String text = String.<a 497 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 498 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount); 499 CharSequence styledText = Html.fromHtml(text); 500 </pre> 501 </li> 502 </ol> 503 504 <p>Because the {@link android.text.Html#fromHtml} method will format all HTML entities, be sure to 505 escape any possible HTML characters in the strings you use with the formatted text, using 506 {@link android.text.TextUtils#htmlEncode}. For instance, if you'll be passing a string argument to 507 <a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 508 java.lang.Object...)">{@code String.format()}</a> that may contain characters such as 509 "<" or "&", then they must be escaped before formatting, so that when the formatted string 510 is passed through {@link android.text.Html#fromHtml}, the characters come out the way they were 511 originally written. For example:</p> 512 <pre> 513 String escapedUsername = TextUtil.{@link android.text.TextUtils#htmlEncode htmlEncode}(username); 514 515 Resources res = {@link android.content.Context#getResources()}; 516 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 517 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), escapedUsername, mailCount); 518 CharSequence styledText = Html.fromHtml(text); 519 </pre> 520 521 <h2 id="StylingWithSpannables">Styling with Spannables</h2> 522 <p> 523 A {@link android.text.Spannable} is a text object that you can style with 524 typeface properties such as color and font weight. You use 525 {@link android.text.SpannableStringBuilder} to build 526 your text and then apply styles defined in the {@link android.text.style} 527 package to the text. 528 </p> 529 530 <p>You can use the following helper methods to set up much of the work 531 of creating spannable text:</p> 532 533 <pre style="pretty-print"> 534 /** 535 * Returns a CharSequence that concatenates the specified array of CharSequence 536 * objects and then applies a list of zero or more tags to the entire range. 537 * 538 * @param content an array of character sequences to apply a style to 539 * @param tags the styled span objects to apply to the content 540 * such as android.text.style.StyleSpan 541 * 542 */ 543 private static CharSequence apply(CharSequence[] content, Object... tags) { 544 SpannableStringBuilder text = new SpannableStringBuilder(); 545 openTags(text, tags); 546 for (CharSequence item : content) { 547 text.append(item); 548 } 549 closeTags(text, tags); 550 return text; 551 } 552 553 /** 554 * Iterates over an array of tags and applies them to the beginning of the specified 555 * Spannable object so that future text appended to the text will have the styling 556 * applied to it. Do not call this method directly. 557 */ 558 private static void openTags(Spannable text, Object[] tags) { 559 for (Object tag : tags) { 560 text.setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK); 561 } 562 } 563 564 /** 565 * "Closes" the specified tags on a Spannable by updating the spans to be 566 * endpoint-exclusive so that future text appended to the end will not take 567 * on the same styling. Do not call this method directly. 568 */ 569 private static void closeTags(Spannable text, Object[] tags) { 570 int len = text.length(); 571 for (Object tag : tags) { 572 if (len > 0) { 573 text.setSpan(tag, 0, len, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); 574 } else { 575 text.removeSpan(tag); 576 } 577 } 578 } 579 </pre> 580 581 <p> 582 The following <code>bold</code>, <code>italic</code>, and <code>color</code> 583 methods show you how to call the helper methods to apply 584 styles defined in the {@link android.text.style} package. You 585 can create similar methods to do other types of text styling. 586 </p> 587 588 <pre style="pretty-print"> 589 /** 590 * Returns a CharSequence that applies boldface to the concatenation 591 * of the specified CharSequence objects. 592 */ 593 public static CharSequence bold(CharSequence... content) { 594 return apply(content, new StyleSpan(Typeface.BOLD)); 595 } 596 597 /** 598 * Returns a CharSequence that applies italics to the concatenation 599 * of the specified CharSequence objects. 600 */ 601 public static CharSequence italic(CharSequence... content) { 602 return apply(content, new StyleSpan(Typeface.ITALIC)); 603 } 604 605 /** 606 * Returns a CharSequence that applies a foreground color to the 607 * concatenation of the specified CharSequence objects. 608 */ 609 public static CharSequence color(int color, CharSequence... content) { 610 return apply(content, new ForegroundColorSpan(color)); 611 } 612 </pre> 613 614 <p> 615 Here's an example of how to chain these methods to create a character sequence 616 with different types of styling applied to individual words: 617 </p> 618 619 <pre style="pretty-print"> 620 // Create an italic "hello, " a red "world", 621 // and bold the entire sequence. 622 CharSequence text = bold(italic(res.getString(R.string.hello)), 623 color(Color.RED, res.getString(R.string.world))); 624 </pre> 625