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">Plurals</a></dt> 16 <dd>XML resource that carries different strings for different pluralizations 17 of the same word or phrase.</dd> 18 </dl> 19 20 <p>All strings are capable of applying some styling markup and formatting arguments. For 21 information about styling and formatting strings, see the section about <a 22 href="#FormattingAndStyling">Formatting and Styling</a>.</p> 23 24 25 26 27 <h2 id="String">String</h2> 28 29 <p>A single string that can be referenced from the application or from other resource files (such 30 as an XML layout).</p> 31 32 <p class="note"><strong>Note:</strong> A string is a simple resource that is referenced 33 using the value provided in the {@code name} attribute (not the name of the XML file). So, you can 34 combine string resources with other simple resources in the one XML file, 35 under one {@code <resources>} element.</p> 36 37 <dl class="xml"> 38 39 <dt>file location:</dt> 40 <dd><code>res/values/<em>filename</em>.xml</code><br/> 41 The filename is arbitrary. The {@code <string>} element's {@code name} will be used as the 42 resource ID.</dd> 43 44 <dt>compiled resource datatype:</dt> 45 <dd>Resource pointer to a {@link java.lang.String}.</dd> 46 47 <dt>resource reference:</dt> 48 <dd> 49 In Java: <code>R.string.<em>string_name</em></code><br/> 50 In XML:<code>@string/<em>string_name</em></code> 51 </dd> 52 53 <dt>syntax:</dt> 54 <dd> 55 <pre class="stx"> 56 <?xml version="1.0" encoding="utf-8"?> 57 <<a href="#string-resources-element">resources</a>> 58 <<a href="#string-element">string</a> 59 name="<em>string_name</em>" 60 ><em>text_string</em></string> 61 </resources> 62 </pre> 63 </dd> 64 65 <dt>elements:</dt> 66 <dd> 67 <dl class="tag-list"> 68 69 <dt id="string-resources-element"><code><resources></code></dt> 70 <dd><strong>Required.</strong> This must be the root node. 71 <p>No attributes.</p> 72 </dd> 73 <dt id="string-element"><code><string></code></dt> 74 <dd>A string, which can include styling tags. Beware that you must escape apostrophes and 75 quotation marks. For more information about how to properly style and format your strings see <a 76 href="#FormattingAndStyling">Formatting and Styling</a>, below. 77 <p class="caps">attributes:</p> 78 <dl class="atn-list"> 79 <dt><code>name</code></dt> 80 <dd><em>String</em>. A name for the string. This name will be used as the resource 81 ID.</dd> 82 </dl> 83 </dd> 84 85 </dl> 86 </dd> <!-- end elements and attributes --> 87 88 <dt>example:</dt> 89 <dd>XML file saved at <code>res/values/strings.xml</code>: 90 <pre> 91 <?xml version="1.0" encoding="utf-8"?> 92 <resources> 93 <string name="hello">Hello!</string> 94 </resources> 95 </pre> 96 97 <p>This layout XML applies a string to a View:</p> 98 <pre> 99 <TextView 100 android:layout_width="fill_parent" 101 android:layout_height="wrap_content" 102 <strong>android:text="@string/hello"</strong> /> 103 </pre> 104 105 <p>This application code retrieves a string:</p> 106 <pre> 107 String string = {@link android.content.Context#getString(int) getString}(R.string.hello); 108 </pre> 109 <p>You can use either {@link android.content.Context#getString(int)} or 110 {@link android.content.Context#getText(int)} to retieve a string. {@link 111 android.content.Context#getText(int)} will retain any rich text styling applied to the string.</p> 112 113 </dd> <!-- end example --> 114 115 </dl> 116 117 118 119 120 121 122 123 124 125 <h2 id="StringArray">String Array</h2> 126 127 <p>An array of strings that can be referenced from the application.</p> 128 129 <p class="note"><strong>Note:</strong> A string array is a simple resource that is referenced 130 using the value provided in the {@code name} attribute (not the name of the XML file). As 131 such, you can combine string array resources with other simple resources in the one XML file, 132 under one {@code <resources>} element.</p> 133 134 <dl class="xml"> 135 136 <dt>file location:</dt> 137 <dd><code>res/values/<em>filename</em>.xml</code><br/> 138 The filename is arbitrary. The {@code <string-array>} element's {@code name} will be used as the 139 resource ID.</dd> 140 141 <dt>compiled resource datatype:</dt> 142 <dd>Resource pointer to an array of {@link java.lang.String}s.</dd> 143 144 <dt>resource reference:</dt> 145 <dd> 146 In Java: <code>R.array.<em>string_array_name</em></code> 147 </dd> 148 149 <dt>syntax:</dt> 150 <dd> 151 <pre class="stx"> 152 <?xml version="1.0" encoding="utf-8"?> 153 <<a href="#string-array-resources-element">resources</a>> 154 <<a href="#string-array-element">string-array</a> 155 name="<em>string_array_name</em>"> 156 <<a href="#string-array-item-element">item</a> 157 ><em>text_string</em></item> 158 </string-array> 159 </resources> 160 </pre> 161 </dd> 162 163 <dt>elements:</dt> 164 <dd> 165 <dl class="tag-list"> 166 <dt id="string-array-resources-element"><code><resources></code></dt> 167 <dd><strong>Required.</strong> This must be the root node. 168 <p>No attributes.</p> 169 </dd> 170 <dt id="string-array-element"><code><string-array></code></dt> 171 <dd>Defines an array of strings. Contains one or more {@code <item>} elements. 172 <p class="caps">attributes:</p> 173 <dl class="atn-list"> 174 <dt><code>name</code></dt> 175 <dd><em>String</em>. A name for the array. This name will be used as the resource 176 ID to reference the array.</dd> 177 </dl> 178 179 </dd> 180 <dt id="string-array-item-element"><code><item></code></dt> 181 <dd>A string, which can include styling tags. The value can be a referenced to another 182 string resource. Must be a child of a {@code <string-array>} element. Beware that you 183 must escape apostrophes and 184 quotation marks. See <a href="#FormattingAndStyling">Formatting and Styling</a>, below, for 185 information about to properly style and format your strings. 186 <p>No attributes.</p> 187 </dd> 188 </dl> 189 </dd> <!-- end elements --> 190 191 <dt>example:</dt> 192 <dd>XML file saved at <code>res/values/strings.xml</code>: 193 <pre> 194 <?xml version="1.0" encoding="utf-8"?> 195 <resources> 196 <string-array name="planets_array"> 197 <item>Mercury</item> 198 <item>Venus</item> 199 <item>Earth</item> 200 <item>Mars</item> 201 </string-array> 202 </resources> 203 </pre> 204 205 <p>This application code retrieves a string array:</p> 206 <pre> 207 Resources res = {@link android.content.Context#getResources()}; 208 String[] planets = res.{@link android.content.res.Resources#getStringArray(int) 209 getStringArray}(R.array.planets_array); 210 </pre> 211 </dd> <!-- end example --> 212 213 </dl> 214 215 216 217 218 219 220 221 <h2 id="Plurals">Plurals</h2> 222 223 <p>A pair of strings that each provide a different plural form of the same word or phrase, 224 which you can collectively reference from the application. When you request the plurals 225 resource using a method such as {@link android.content.res.Resources#getQuantityString(int,int) 226 getQuantityString()}, you must pass a "count", which will determine the plural form you 227 require and return that string to you.</p> 228 229 <p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is 230 referenced using the value provided in the {@code name} attribute (not the name of the XML 231 file). As such, you can combine plurals resources with other simple resources in the one 232 XML file, under one {@code <resources>} element.</p> 233 234 <dl class="xml"> 235 236 <dt>file location:</dt> 237 <dd><code>res/values/<em>filename</em>.xml</code><br/> 238 The filename is arbitrary. The {@code <plurals>} element's {@code name} will be used as the 239 resource ID.</dd> 240 241 <dt>resource reference:</dt> 242 <dd> 243 In Java: <code>R.plurals.<em>plural_name</em></code> 244 </dd> 245 246 <dt>syntax:</dt> 247 <dd> 248 <pre class="stx"> 249 <?xml version="1.0" encoding="utf-8"?> 250 <<a href="#plurals-resources-element">resources</a>> 251 <<a href="#plurals-element">plurals</a> 252 name="<em>plural_name</em>"> 253 <<a href="#plurals-item-element">item</a> 254 quantity=["one" | "other"] 255 ><em>text_string</em></item> 256 </plurals> 257 </resources> 258 </pre> 259 </dd> 260 261 <dt>elements:</dt> 262 <dd> 263 <dl class="tag-list"> 264 265 <dt id="plurals-resources-element"><code><resources></code></dt> 266 <dd><strong>Required.</strong> This must be the root node. 267 <p>No attributes.</p> 268 </dd> 269 <dt id="plurals-element"><code><plurals></code></dt> 270 <dd>A collection of strings, of which, one string is provided depending on the amount of 271 something. Contains one or more {@code <item>} elements. 272 <p class="caps">attributes:</p> 273 <dl class="atn-list"> 274 <dt><code>name</code></dt> 275 <dd><em>String</em>. A name for the pair of strings. This name will be used as the 276 resource ID.</dd> 277 </dl> 278 279 </dd> 280 <dt id="plurals-item-element"><code><item></code></dt> 281 <dd>A plural or singular string. The value can be a referenced to another 282 string resource. Must be a child of a {@code <plurals>} element. Beware that you must 283 escape apostrophes and quotation marks. See <a href="#FormattingAndStyling">Formatting and 284 Styling</a>, below, for information about to properly style and format your strings. 285 <p class="caps">attributes:</p> 286 <dl class="atn-list"> 287 <dt><code>quantity</code></dt> 288 <dd><em>Keyword</em>. A value indicating the case in which this string should be used. Valid 289 values: 290 <table> 291 <tr><th>Value</th><th>Description</th></tr> 292 <tr> 293 <td>{@code one}</td><td>When there is one (a singular string).</td> 294 </tr> 295 <tr> 296 <td>{@code other}</td><td>When the quantity is anything other than one (a plural 297 string, but also used when the count is zero).</td> 298 </tr> 299 </table> 300 </dd> 301 </dl> 302 </dd> 303 304 </dl> 305 </dd> <!-- end elements --> 306 307 <dt>example:</dt> 308 <dd>XML file saved at {@code res/values/strings.xml}:</p> 309 <pre> 310 <?xml version="1.0" encoding="utf-8"?> 311 <resources> 312 <plurals name="numberOfSongsAvailable"> 313 <item quantity="one">One song found.</item> 314 <item quantity="other">%d songs found.</item> 315 </plurals> 316 </resources> 317 </pre> 318 <p>Java code:</p> 319 <pre> 320 int count = getNumberOfsongsAvailable(); 321 Resources res = {@link android.content.Context#getResources()}; 322 String songsFound = res.{@link android.content.res.Resources#getQuantityString(int,int) 323 getQuantityString}(R.plurals.numberOfSongsAvailable, count); 324 </pre> 325 </dd> <!-- end example --> 326 327 </dl> 328 329 330 331 332 333 334 335 336 <h2 id="FormattingAndStyling">Formatting and Styling</h2> 337 338 <p>Here are a few important things you should know about how to properly 339 format and style your string resources.</p> 340 341 342 <h3>Escaping apostrophes and quotes</h3> 343 344 <p>If you have an apostrophe or a quote in your string, you must either escape it or enclose the 345 whole string in the other type of enclosing quotes. For example, here are some stings that 346 do and don't work:</p> 347 348 <pre> 349 <string name="good_example">"This'll work"</string> 350 <string name="good_example_2">This\'ll also work</string> 351 <string name="bad_example">This doesn't work</string> 352 <string name="bad_example_2">XML encodings don&apos;t work</string> 353 </pre> 354 355 356 <h3>Formatting strings</h3> 357 358 <p>If you need to format your strings using <a 359 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 360 java.lang.Object...)">{@code String.format(String, Object...)}</a>, 361 then you can do so by putting 362 your format arguments in the string resource. For example, with the following resource:</p> 363 364 <pre> 365 <string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string> 366 </pre> 367 368 <p>In this example, the format string has two arguments: {@code %1$s} is a string and {@code %2$d} 369 is a decimal number. You can format the string with arguements from your application like this:</p> 370 371 <pre> 372 Resources res = {@link android.content.Context#getResources()}; 373 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 374 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount); 375 </pre> 376 377 378 379 <h3>Styling with HTML markup</h3> 380 381 <p>You can add styling to your strings with HTML markup. For example:</p> 382 <pre> 383 <?xml version="1.0" encoding="utf-8"?> 384 <resources> 385 <string name="welcome">Welcome to <b>Android</b>!</string> 386 </resources> 387 </pre> 388 <p>Supported HTML elements include:</p> 389 <ul> 390 <li>{@code <b>} for <b>bold</b> text.</li> 391 <li>{@code <i>} for <i>italic</i> text.</li> 392 <li>{@code <u>} for <u>underline</u> text.</li> 393 </ul> 394 395 <p>Sometimes you may want to create a styled text resource that is also used as a format 396 string. Normally, this won't work because the <a 397 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 398 java.lang.Object...)">{@code String.format(String, Object...)}</a> 399 method will strip all the style 400 information from the string. The work-around to this is to write the HTML tags with escaped 401 entities, which are then recovered with {@link android.text.Html#fromHtml(String)}, 402 after the formatting takes place. For example:</p> 403 404 <ol> 405 <li>Store your styled text resource as an HTML-escaped string: 406 <pre> 407 <resources> 408 <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string> 409 </resources> 410 </pre> 411 <p>In this formatted string, a {@code <b>} element is added. Notice that the opening bracket is 412 HTML-escaped, using the {@code &lt;} notation.</p> 413 </li> 414 <li>Then format the string as usual, but also call {@link android.text.Html#fromHtml} to 415 convert the HTML text into styled text: 416 <pre> 417 Resources res = {@link android.content.Context#getResources()}; 418 String text = String.<a 419 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 420 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount); 421 CharSequence styledText = Html.fromHtml(text); 422 </pre> 423 </li> 424 </ol> 425 426 <p>Because the {@link android.text.Html#fromHtml} method will format all HTML entities, be sure to 427 escape any possible HTML characters in the strings you use with the formatted text, using 428 {@link android.text.TextUtils#htmlEncode}. For instance, if you'll be passing a string argument to 429 <a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 430 java.lang.Object...)">{@code String.format()}</a> that may contain characters such as 431 "<" or "&", then they must be escaped before formatting, so that when the formatted string 432 is passed through {@link android.text.Html#fromHtml}, the characters come out the way they were 433 originally written. For example:</p> 434 <pre> 435 String escapedUsername = TextUtil.{@link android.text.TextUtils#htmlEncode htmlEncode}(username); 436 437 Resources res = {@link android.content.Context#getResources()}; 438 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 439 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), escapedUsername, mailCount); 440 CharSequence styledText = Html.fromHtml(text); 441 </pre> 442 443 444 445
