Figure 1. Two device configurations, both using default resources.
Figure 2. Two device configurations, one using alternative
diff --git a/docs/html/guide/topics/resources/layout-resource.jd b/docs/html/guide/topics/resources/layout-resource.jd
index a6b177f01fc6b..2c51d54f41e0b 100644
--- a/docs/html/guide/topics/resources/layout-resource.jd
+++ b/docs/html/guide/topics/resources/layout-resource.jd
@@ -36,14 +36,14 @@ In XML: @[package:]layout/filename
<?xml version="1.0" encoding="utf-8"?>
<ViewGroup xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/name"
- android:layout_height="@+id/string_name"
- android:layout_width="@+id/string_name"
- [other attributes] >
+ android:layout_height=["dimension" | "fill_parent" | "wrap_content"]
+ android:layout_width=["dimension" | "fill_parent" | "wrap_content"]
+ [ViewGroup-specific attributes] >
<View
android:id="@+id/name"
- android:layout_height="@+id/string_name"
- android:layout_width="@+id/string_name"
- [other attributes] >
+ android:layout_height=["dimension" | "fill_parent" | "wrap_content"]
+ android:layout_width=["dimension" | "fill_parent" | "wrap_content"]
+ [View-specific attributes] >
<requestFocus/>
</View>
<ViewGroup >
diff --git a/docs/html/guide/topics/resources/menu-resource.jd b/docs/html/guide/topics/resources/menu-resource.jd
index c9f27fa71d250..badc40328a542 100644
--- a/docs/html/guide/topics/resources/menu-resource.jd
+++ b/docs/html/guide/topics/resources/menu-resource.jd
@@ -35,12 +35,12 @@ In XML: @[package:]menu.filename
<?xml version="1.0" encoding="utf-8"?> <menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="resource ID" + <item android:id="@+id/id_name" android:menuCategory=["container" | "system" | "secondary" | "alternative"] android:orderInCategory="integer" android:title="string" android:titleCondensed="string" - android:icon="drawable resource" + android:icon="@[package:]drawable/drawable_resource_name" android:alphabeticShortcut="string" android:numericShortcut="string" android:checkable=["true" | "false"] @@ -172,22 +172,22 @@ too long.
res/menu/example_menu.xml:
<menu xmlns:android="http://schemas.android.com/apk/res/android">
- <item android:id="@+id/example_item"
- android:title="Example Item"
- android:icon="@drawable/example_item_icon" />
- <group android:id="@+id/example_group">
+ <item android:id="@+id/item1"
+ android:title="@string/item1"
+ android:icon="@drawable/group_item1_icon" />
+ <group android:id="@+id/group">
<item android:id="@+id/group_item1"
- android:title="Group Item 1"
- android:icon="@drawable/example_item1_icon" />
+ android:title="@string/group_item1"
+ android:icon="@drawable/group_item1_icon" />
<item android:id="@+id/group_item2"
- android:title="Group Item 2"
- android:icon="@drawable/example_item2_icon" />
+ android:title="G@string/group_item2"
+ android:icon="@drawable/group_item2_icon" />
</group>
<item android:id="@+id/submenu"
- android:title="Sub Menu" >
+ android:title="@string/submenu_title" >
<menu>
- <item android:id="@+id/submenu_item"
- android:title="Sub Menu Item" />
+ <item android:id="@+id/submenu_item1"
+ android:title="@string/submenu_item1" />
</menu>
</item>
</menu>
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd
index b495eb8a1b22c..0f3d389939589 100644
--- a/docs/html/guide/topics/resources/providing-resources.jd
+++ b/docs/html/guide/topics/resources/providing-resources.jd
@@ -7,13 +7,15 @@ parent.link=index.html
Quickview
- - Different types of resources belong in different sub-directories of {@code res/}
+ - Different types of resources belong in different subdirectories of {@code res/}
- Alternative resources provide configuration-specific resource files
In this document
+ - Grouping Resource Types
- Providing Alternative Resources
@@ -24,17 +26,30 @@ parent.link=index.html
There are several types of resource files you can -include in your application and each type belongs in a specific sub-directory of your project's -{@code res/} directory. Absolutely no files should be saved directly inside {@code res/}.
+You should always externalize application resources such as images and strings from your +code, so that you can maintain them independently. You can also provide alternative resources for +specific device configurations, by grouping them in specially-named resource directories. Android +will then automatically apply the appropriate resource based on the current configuration. For +instance, you might want to provide a different UI layout depending on the screen size.
-For example, here's the file hierarchy for a simple project:
+Once you save your resources external to your application code, you can access them +using resource IDs that are generated in your project's {@code R} class. How to use +resources in your application is discussed in Accessing +Resources.
-+ +Grouping Resource Types
+ +You should place each type of resource in a specific subdirectory of your project's +{@code res/} directory. For example, here's the file hierarchy for a simple project:
+ +MyProject/ src/ MyActivity.java @@ -42,23 +57,23 @@ MyProject/ drawable/ icon.png layout/ - main_layout.xml + main.xml + info.xml values/ strings.xml-This project includes an image resource, a layout resource, and string resource file.
+The {@code res/} directory contains all the resources (in subdirectories): an image resource, two +layout resources, and a string resource file. The resource directory names are important and are +described in table 1.
-Table 1 lists the different {@code res/} sub-directories supported -and describes the types of resource files that belong in each one.
- -Table 1. Resource directories. Each directory -belongs inside the project {@code res/} directory.
+Table 1. Resource directories +supported inside project {@code res/} directory.
| Directory | -Resource Types | +Resource Type |
|---|---|---|
color/ |
XML files that define a state list of colors. See Color -State List Resources | +State List Resource|
drawable/ |
Bitmap files ({@code .png}, {@code .9.png}, {@code .jpg}, {@code .gif}) or XML files that -are compiled into the following Drawable resource subtypes: +are compiled into the following drawable resource subtypes:
|
system. To open these resources with a raw {@link java.io.InputStream}, call {@link
android.content.res.Resources#openRawResource(int)
Resources.openRawResource()} with the resource ID, which is {@code R.raw.filename}.
- |
values/ |
XML files that contain simple values, such as strings, integers, and colors. -Unlike the other {@code res/} subdirectories, this one - can hold files that contain descriptions of more than one resource, rather than -just one resource for the file. The XML element types of an XML file in {@code values/} control -how these resources are defined in the {@code R} class. For example, a {@code <string>} -element will create an -{@code R.string} resource, and a {@code <color>} element will create an {@code R.color} + Whereas XML resource files in other {@code res/} subdirectories define a single resource +based on the XML filename, files in the {@code values/} directory describe multiple resources. +For a file in this directory, each child of the {@code <resources>} element defines a single +resource. For example, a {@code <string>} element creates an +{@code R.string} resource and a {@code <color>} element creates an {@code R.color} resource. -While the name of a file in this directory is arbitrary and not related to the name given -to a resource produced, you might want to separate different types of resources into different -files for easier maintenance. Here are some filename conventions for some of the different types -of resources you can save here: +Because each resource is defined with its own XML element, you can name the file +whatever you want and place different resource types in one file. However, for clarity, you might +want to place unique resource types in different files. For example, here are some filename +conventions for resources you can create in this directory:
See String Resources, Style Resource, and @@ -147,38 +160,42 @@ values. | |
xml/ |
- Arbitrary XML files that are compiled and can be read at runtime by calling {@link + | Arbitrary XML files that can be read at runtime by calling {@link android.content.res.Resources#getXml(int) Resources.getXML()}. Various XML configuration files -must also be saved here, such as a searchable configuration. |
Note: You should never save resource files directly inside the +{@code res/} directory.
+For more information about certain types of resources, see the Resource Types documentation.
- - +How to access resources in the {@code res/} subdirectories is discussed in Accessing Resources. +
Providing Alternative Resources
-
Figure 1. Two device configurations, one using alternative resources.
Almost every application should provide alternative resources to support specific device -configurations. For instance, you should include different drawable resources for different -screen densities and different string resources for different languages. At runtime, Android -will automatically detect the current device configuration and then load the appropriate +configurations. For instance, you should include alternative drawable resources for different +screen densities and alternative string resources for different languages. At runtime, Android +automatically detects the current device configuration and loads the appropriate resources.
-For each set of resources for which you want to provide configuration-specific alternatives:
+To specify configuration-specific alternatives for a set of resources:
- Create a new directory in {@code res/} named in the form {@code <resources_name>-<config_qualifier>}. @@ -191,13 +208,13 @@ for which these resources are to be used.
- Save your alternative resources in this directory, named exactly the same as the default -resource files. +
- Save your alternative resources in this new directory. The resource files must be named +exactly the same as the default resource files.
You can append more than one {@code <config_qualifier>}. Separate each one with a dash.
-For example, here are some default and alternative resources:
-+res/ drawable/ icon.png @@ -207,22 +224,23 @@ res/ background.png-The {@code hdpi} qualifier indicates that the resources are for devices with a high-density -screen. While the images in each directory are different, the filenames are -identical. This way, the resource ID that you use to reference the {@code icon.png} image is -always the same. When you request the {@code icon} drawable, Android will select the +
The {@code hdpi} qualifier indicates that the resources in that directory are for devices with a +high-density screen. While the images in each drawable directory are sized for a specific screen +density, the filenames are +the same. This way, the resource ID that you use to reference the {@code icon.png} or {@code +background.png} image is always the same, but Android selects the version of that drawable that best matches the current device configuration.
Android supports several configuration qualifiers and you can -add multiple qualifiers to one directory name in order to further specify the configuration, by -separating the qualifiers with dashes. Table 2 lists the valid configuration qualifiers, in order -of precedence—they must be specified in the directory name in the order that they are listed -in the table.
+add multiple qualifiers to one directory name, by separating each qualifier with a dash. Table 2 +lists the valid configuration qualifiers, in order of precedence—if you use multiple +qualifiers, they must be added to the directory name in the order they are listed in the +table.Table 2. Alternative resource qualifier names.
-
| Qualifier | Values | @@ -237,18 +255,22 @@ names. etc.
- Specifies resources based on the mobile country code (MCC), optionally followed by mobile
-network code (MNC)
- from the SIM in the device. For example, The mobile country code (MCC), optionally followed by mobile network code (MNC)
+ from the SIM card in the device. For example, If the device uses a radio connection (GSM phone), the MCC will come - from the SIM, and the MNC will come from the network to which the - device is attached. -You might sometimes use the MCC alone, for example to include country-specific legal -resources in your application, but if you only need to specify based on language, then use the -language and region qualifier below. If you decide to use the MCC and MNC qualifier, you -should do so with great care and completely test that it works as expected. |
+
|---|---|---|
| Language and region | @@ -260,22 +282,24 @@ should do so with great care and completely test that it works as expected.<This is defined by a two-letter The language is defined by a two-letter ISO
639-1 language code, optionally followed by a two letter
ISO
- 3166-1-alpha-2 region code (preceded by lowercase "r").
+ 3166-1-alpha-2 The codes are not case-sensitive; the {@code r} prefix is used to distinguish the region portion. You cannot specify a region alone. This can change during the life -of your application if the user changes their language in the system settings. See Handling Runtime Changes for information about how this can affect your application during runtime. See Localization for a complete guide to localizing your application for other langauges. +Also see the {@link android.content.res.Configuration#locale} configuration field, which +indicates the current locale. |
|
-
|
||
|
- This is based purely on the aspect ratio of the screen (a "long" screen is wider): -
This is not related to the screen orientation. +This is based purely on the aspect ratio of the screen (a "long" screen is wider). This +is not related to the screen orientation. +Also see the {@link android.content.res.Configuration#screenLayout} configuration field, +which indicates whether the screen is long. |
||
|
- Portrait orientation ({@code port}) is vertical and landscape orientation -({@code land}) is horizontal. +
This can change during the life of your application if the user rotates the screen. See Handling Runtime Changes for information about how this affects your application during runtime. +Also see the {@link android.content.res.Configuration#orientation} configuration field, +which indicates the current device orientation. |
||
|
- These configurations can be initiated when the device is placed in a dock. +
Added in API Level 8. This can change during the life of your application if the user places the device in a -dock. See Handling Runtime Changes for -information about how this affects your application during runtime. Also see {@link -android.app.UiModeManager}. +dock. You can eneable or disable this mode using {@link +android.app.UiModeManager}. See Handling Runtime Changes for +information about how this affects your application during runtime. |
||
|
- - These configurations can be initiated by the device light sensor (if available). +
Added in API Level 8. -This can change during the life of your application if the device determines that the -user environment is a "night" (dark) setting. See Handling Runtime -Changes for information about how this affects your application during runtime. You can -also explicitly set this mode using {@link android.app.UiModeManager}. +This can change during the life of your application if night mode is left in +auto mode (default), in which case the mode changes based on the time of day. You can eneable +or disable this mode using {@link android.app.UiModeManager}. See Handling Runtime Changes for information about how this affects your +application during runtime. |
||
|
- The medium
- density of traditional HVGA screens (mdpi) is defined to be approximately
- 160dpi; low density (ldpi) is 120, and high density (hdpi) is 240. There
- is thus a 4:3 scaling factor between each density, so a 9x9 bitmap
- in ldpi would be 12x12 in mdpi and 16x16 in hdpi. The special
- - When Android selects which resource files to use, - it handles screen density differently than the other qualifiers. +
There is thus a 4:3 scaling factor between each density, so a 9x9 bitmap + in ldpi is 12x12 in mdpi and 16x16 in hdpi. +When Android selects which resource files to use, + it handles screen density differently than the other qualifiers. In step 1 of How Android finds the best matching directory (below), screen density is always considered to be a match. In step 4, if the qualifier being considered is screen - density, Android will select the best final match at that point, + density, Android selects the best final match at that point, without any need to move on to step 5. See Supporting Multiple -Screens for more information. +Screens for more information about how to handle screen sizes and how Android might scale +your bitmaps. |
||
If the device has a resistive touch screen that's suited for use with a stylus, -then it may use the {@code stylus} resources. + |
+
Also see the {@link android.content.res.Configuration#touchscreen} configuration field, +which indicates the type of touchscreen on the device. |
|
| Keyboard availability |
keysexposed- keyshiddenkeyssoft
|
- If your application has specific resources that should only be used with a soft keyboard,
-use the This can change during the life of your application if the user opens a keyboard. See Handling Runtime Changes for information about how this affects your -application during runtime. +
If you provide This can change during the life of your application if the user opens a hardware +keyboard. See Handling Runtime Changes for information about how +this affects your application during runtime. +Also see the configuration fields {@link +android.content.res.Configuration#hardKeyboardHidden} and {@link +android.content.res.Configuration#keyboardHidden}, which indicate the visibility of a hardware +keyboard and and the visibility of any kind of keyboard (including software), respectively. |
If the device has no hardware keys for text input, then it may use the {@code -nokeys} resources. Even if the device has a QWERTY keyboard but it is currently hidden, it may use -the {@code qwerty} resources. |
+
+
Also see the {@link android.content.res.Configuration#keyboard} configuration field, +which indicates the primary text input method available. + |
|
| Navigation key availability | @@ -442,13 +513,16 @@ the {@code qwerty} resources.
- - If the device's navigation keys are currently available to - the user, it may use the {@code navexposed} resources; if they are not - available (such as behind a closed lid), it may use the {@code navhidden} resources. +
This can change during the life of your application if the user reveals the navigation keys. See Handling Runtime Changes for information about how this affects your application during runtime. +Also see the {@link android.content.res.Configuration#navigationHidden} configuration +field, which indicates whether navigation keys are hidden. |
|
If the device has no navigation facility other than using the touchscreen, then it -may use the {@code nonav} resources. + |
+
Also see the {@link android.content.res.Configuration#navigation} configuration field, +which indicates the type of navigation method available. |