CHAPTER 20: Working with Resources 208 <color name="yellow_orange">#FFD555</color> <color name="forest_green">#005500</color> <color name="burnt_umber">#8A3324</color> </resources> In a layout, you can reference colors as @color/ , replacing the ellipsis with your unique name for the color (e.g., burnt_umber). In Java, you reference color resources by the unique name prefixed with R.color. (e.g., Resources.getColor(R.color.forest_green)). Arrays Array resources are designed to hold lists of simple strings, such as a list of honorifics (Mr., Mrs., Ms., Dr., etc.). In the resource file, you need one string-array element per array, with a name attribute for the unique name you are giving the array. Then add one or more child item elements, each with a single text element containing the value for that entry in the array: <?xml version="1.0" encoding="utf-8"?> <resources> <string-array name="cities"> <item>Philadelphia</item> <item>Pittsburgh</item> <item>Allentown/Bethlehem</item> <item>Erie</item> <item>Reading</item> <item>Scranton</item> <item>Lancaster</item> <item>Altoona</item> <item>Harrisburg</item> </string-array> <string-array name="airport_codes"> <item>PHL</item> <item>PIT</item> <item>ABE</item> <item>ERI</item> <item>RDG</item> <item>AVP</item> <item>LNS</item> <item>AOO</item> <item>MDT</item> </string-array> </resources> From your Java code, you can then use Resources.getStringArray() to get a String[] of the items in the list. The parameter to getStringArray() is your unique name for the array, prefixed with R.array. (e.g., Resources.getStringArray(R.array.honorifics)). Different Strokes for Different Folks One set of resources may not fit all situations where your application may be used. One obvious area comes with string resources and dealing with internationalization (I18N) CHAPTER 20: Working with Resources 209 and localization (L10N). Putting strings all in one language works fine—at least, for the developer—but covers only one language. That is not the only scenario where resources might need to differ, though. Here are others: Screen orientation: Is the screen in a portrait or landscape orientation? Or is the screen square and, therefore, without an orientation? Screen size: How many pixels does the screen have, so you can size your resources accordingly (e.g., large versus small icons)? Touchscreen: does the device have a touchscreen? If so, is the touchscreen set up to be used with a stylus or a finger? Keyboard: Which keyboard does the user have (QWERTY, numeric, neither), either now or as an option? Other input: Does the device have some other form of input, like a D- pad or click-wheel? The way Android currently handles this is by having multiple resource directories, with the criteria for each embedded in their names. Suppose, for example, you want to support strings in both English and Spanish. Normally, for a single-language setup, you would put your strings in a file named res/values/strings.xml. To support both English and Spanish, you would create two folders, named res/values-en/ and res/values-es/, where the value after the hyphen is the ISO 639-1 two-letter code for the language. Your English strings would go in res/values-en/strings.xml, and the Spanish ones would go in res/values- es/strings.xml. Android will choose the proper file based on the user’s device settings. An even better approach is for you to consider some language to be your default, and put those strings in res/values/strings.xml. Then create other resource directories for your translations (e.g., res/values-es/strings.xml for Spanish). Android will try to match a specific language set of resources; failing that, it will fall back to the default of res/values/strings.xml. Seems easy, right? Where things start to get complicated is when you need to use multiple disparate criteria for your resources. For example, suppose you want to develop both for the T-Mobile G1 and two currently fictitious devices. One device (Fictional One) has a VGA (“large”) screen normally in a landscape orientation, an always-open QWERTY keyboard, a D- pad, but no touchscreen. The other device (Fictional Two) has a G1-sized screen (normal), a numeric keyboard but no QWERTY, a D-pad, and no touchscreen. You may want to have somewhat different layouts for these devices, to take advantage of different screen real estate and different input options, as follows: For each combination of resolution and orientation For touchscreen devices versus ones without touchscreens For QWERTY versus non-QWERTY devices CHAPTER 20: Working with Resources 210 Once you get into these sorts of situations, all sorts of rules come into play, such as these: The configuration options (e.g., -en) have a particular order of precedence, and they must appear in the directory name in that order. The Android documentation outlines the specific order in which these options can appear. For the purposes of this example, screen orientation must precede touchscreen type, which must precede screen size. There can be only one value of each configuration option category per directory. Options are case-sensitive. So, for the sample scenario, in theory, we would need the following directories: res/layout-large-port-notouch-qwerty res/layout-normal-port-notouch-qwerty res/layout-large-port-notouch-12key res/layout-normal-port-notouch-12key res/layout-large-port-notouch-nokeys res/layout-normal-port-notouch-nokeys res/layout-large-port-stylus-qwerty res/layout-normal-port-stylus-qwerty res/layout-large-port-stylus-12key res/layout-normal-port-stylus-12key res/layout-large-port-stylus-nokeys res/layout-normal-port-stylus-nokeys res/layout-large-port-finger-qwerty res/layout-normal-port-finger-qwerty res/layout-large-port-finger-12key res/layout-normal-port-finger-12key res/layout-large-port-finger-nokeys res/layout-normal-port-finger-nokeys res/layout-large-land-notouch-qwerty res/layout-normal-land-notouch-qwerty res/layout-large-land-notouch-12key res/layout-normal-land-notouch-12key res/layout-large-land-notouch-nokeys CHAPTER 20: Working with Resources 211 res/layout-normal-land-notouch-nokeys res/layout-large-land-stylus-qwerty res/layout-normal-land-stylus-qwerty res/layout-large-land-stylus-12key res/layout-normal-land-stylus-12key res/layout-large-land-stylus-nokeys res/layout-normal-land-stylus-nokeys res/layout-large-land-finger-qwerty res/layout-normal-land-finger-qwerty res/layout-large-land-finger-12key res/layout-normal-land-finger-12key res/layout-large-land-finger-nokeys res/layout-normal-land-finger-nokeys Don’t panic! We will shorten this list in just a moment. Note that for many of these, the actual layout files will be identical. For example, we only care about touchscreen layouts being different from the other two layouts, but since we cannot combine those two, we would theoretically need separate directories with identical contents for finger and stylus. Also note that there is nothing preventing you from having another directory with the unadorned base name (res/layout). In fact, this is probably a good idea, in case future editions of the Android runtime introduce other configuration options you did not consider. Having a default layout might make the difference between your application working or failing on that new device. Now, we can cheat a bit, by decoding the rules Android uses for determining which, among a set of candidates, is the correct resource directory to use: First up, Android tosses out ones that are specifically invalid. So, for example, if the screen size of the device is normal, the -large directories would be dropped as candidates, since they call for some other size. Next, Android counts the number of matches for each folder, and pays attention to only those with the most matches. Finally, Android goes in the order of precedence of the options; in other words, it goes from left to right in the directory name. So, we could skate by with only the following configurations: res/layout-large-port-notouch-qwerty res/layout-port-notouch-qwerty CHAPTER 20: Working with Resources 212 res/layout-large-port-notouch res/layout-port-notouch res/layout-large-port-qwerty res/layout-port-qwerty res/layout-large-port res/layout-port res/layout-large-land-notouch-qwerty res/layout-land-notouch-qwerty res/layout-large-land-notouch res/layout-land-notouch res/layout-large-land-qwerty res/layout-land-qwerty res/layout-large-land res/layout-land Here, we take advantage of the fact that specific matches take precedence over unspecified values. So, a device with a QWERTY keyboard will choose a resource with qwerty in the directory over a resource that does not specify its keyboard type. Combining that with the “most matches wins” rule, we see that res/layout-port will match only devices with normal-sized screens, no QWERTY keyboard, and a touchscreen in portrait orientation. We could refine this even further, to cover only the specific devices we are targeting (T- Mobile G1, Fictional One, and Fictional Two), plus take advantage of res/layout being the overall default: res/layout-large-port-notouch res/layout-port-notouch res/layout-large-land-notouch res/layout-land-notouch res/layout-large-land res/layout Here, -large differentiates Fictional One from the other two devices, while notouch differentiates Fictional Two from the T-Mobile G1. You will see these resource sets again in Chapter 36, which describes how to support multiple screen sizes. . The configuration options (e.g., -en) have a particular order of precedence, and they must appear in the directory name in that order. The Android documentation outlines the specific order. can cheat a bit, by decoding the rules Android uses for determining which, among a set of candidates, is the correct resource directory to use: First up, Android tosses out ones that are specifically. call for some other size. Next, Android counts the number of matches for each folder, and pays attention to only those with the most matches. Finally, Android goes in the order of precedence