diff options
Diffstat (limited to 'docs/html/guide/topics')
| -rw-r--r-- | docs/html/guide/topics/intents/intents-filters.jd | 418 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/manifest-element.jd | 7 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/provider-element.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/supports-screens-element.jd | 37 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/uses-sdk-element.jd | 33 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/available-resources.jd | 346 | ||||
| -rwxr-xr-x | docs/html/guide/topics/resources/localization.jd | 644 | ||||
| -rwxr-xr-x | docs/html/guide/topics/resources/res-selection-flowchart.png | bin | 23228 -> 0 bytes | |||
| -rwxr-xr-x | docs/html/guide/topics/resources/resources-i18n.jd | 12 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/declaring-layout.jd | 14 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/dialogs.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/ui-events.jd | 8 |
12 files changed, 1413 insertions, 110 deletions
diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd index fd20ca1..962a001 100644 --- a/docs/html/guide/topics/intents/intents-filters.jd +++ b/docs/html/guide/topics/intents/intents-filters.jd @@ -16,10 +16,11 @@ page.title=Intents and Intent Filters <h2>In this document</h2> <ol> <li><a href="#iobjs">Intent Objects</a></li> -<li><a href="#ires">Intent Resolution</a>, including:</li> +<li><a href="#ires">Intent Resolution</a></li> <li style="margin-left: 2em"><a href="#ifs">Intent filters</a></li> <li style="margin-left: 2em"><a href="#ccases">Common cases</a></li> <li style="margin-left: 2em"><a href="#imatch">Using intent matching</a></li> +<li><a href="#npex">Note Pad Example</a></li> </ol> </div> </div> @@ -31,7 +32,7 @@ broadcast receivers — are activated through messages, called <i>intents</i Intent messaging is a facility for late run-time binding between components in the same or different applications. The intent itself, an {@link android.content.Intent} object, is a passive data structure holding an abstract description of an operation -to be performed — or, in the case of broadcasts, a description of something +to be performed — or, often in the case of broadcasts, a description of something that has happened and is being announced. There are separate mechanisms for delivering intents to each type of component: </p> @@ -40,7 +41,9 @@ delivering intents to each type of component: <li>An Intent object is passed to <code>{@link android.content.Context#startActivity Context.startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}</code> to launch an activity or get an existing -activity to do something new.</li> +activity to do something new. (It can also be passed to +<code>{@link android.app.Activity#setResult(int, Intent) Activity.setResult()}</code> +to return information to the activity that called {@code startActivityForResult()}.)</li> <li><p>An Intent object is passed to <code>{@link android.content.Context#startService Context.startService()}</code> to initiate a service or deliver new instructions to an @@ -380,22 +383,12 @@ component's filters. <p> A component has separate filters for each job it can do, each face it can -present to the user. For example, the principal activity of the sample -NotePad application has three filters — one for starting up with a -blank slate, another for starting with an assigned directory of notes -that the user can view, edit, or select from, and a third for finding a -particular note without an initial specification of its directory. -</p> - -<p> -An intent filter is an instance of the {@link android.content.IntentFilter} class. -However, since the Android system must know about the capabilities of a component -before it can launch that component, intent filters are generally not set up in -Java code, but in the application's manifest file (AndroidManifest.xml) as -{@code <intent-filter>} elements. (The one exception would be filters for -broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, -Handler) Context.registerReceiver()}</code>; they are directly created as -IntentFilter objects.) +present to the user. For example, the NoteEditor activity of the sample +Note Pad application has two filters — one for starting up with a +specific note that the user can view or edit, and another for starting +with a new, blank note that the user can fill in and save. (All of Note +Pad's filters are described in the <a href="#npex">Note Pad Example</a> +section, later.) </p> <div class="sidebox-wrapper"> @@ -413,6 +406,18 @@ name the component as the target. </div> <p> +An intent filter is an instance of the {@link android.content.IntentFilter} class. +However, since the Android system must know about the capabilities of a component +before it can launch that component, intent filters are generally not set up in +Java code, but in the application's manifest file (AndroidManifest.xml) as +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +elements. (The one exception would be filters for +broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, +Handler) Context.registerReceiver()}</code>; they are directly created as +IntentFilter objects.) +</p> + +<p> A filter has fields that parallel the action, data, and category fields of an Intent object. An implicit intent is tested against the filter in all three areas. To be delivered to the component that owns the filter, it must pass all three tests. @@ -429,8 +434,11 @@ Each of the three tests is described in detail below: <dl> <dt><b>Action test</b></dt> -<dd>An {@code <intent-filter>} element in the manifest file lists actions -as {@code <action>} subelements. For example: +<dd>An +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +element in the manifest file lists actions as +<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> +subelements. For example: <pre><intent-filter . . . > <action android:name="com.example.project.SHOW_CURRENT" /> @@ -464,8 +472,9 @@ contains at least one action.</p></li> </dd> <dt><b>Category test</b></dt> -<dd>An {@code <intent-filter>} element also lists categories as subelements. -For example: +<dd>An +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +element also lists categories as subelements. For example: <pre><intent-filter . . . > <category android:name="android.intent.category.DEFAULT" /> @@ -512,14 +521,16 @@ is contained in a subelement. And, as in those cases, the subelement can appear multiple times, or not at all. For example: <pre><intent-filter . . . > - <data android:type="video/mpeg" android:scheme="http" . . . /> - <data android:type="audio/mpeg" android:scheme="http" . . . /> + <data android:mimeType="video/mpeg" android:scheme="http" . . . /> + <data android:mimeType="audio/mpeg" android:scheme="http" . . . /> . . . </intent-filter></pre> <p> -Each {@code <data>} element can specify a URI and a data type (MIME media type). -There are separate attributes — {@code scheme}, {@code host}, {@code port}, +Each +<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> +element can specify a URI and a data type (MIME media type). There are separate +attributes — {@code scheme}, {@code host}, {@code port}, and {@code path} — for each part of the URI: </p> @@ -607,7 +618,7 @@ for example, tells Android that the component can get image data from a content provider and display it: </p> -<pre><data android:type="image/*" /></pre> +<pre><data android:mimeType="image/*" /></pre> <p> Since most available data is dispensed by content providers, filters that @@ -681,6 +692,357 @@ can respond. There's a similar method, queryBroadcastReceivers()}, for broadcast receivers. </p> +<h2 id="npex">Note Pad Example</h2> + +<p> +The Note Pad sample application enables users to browse through a list +of notes, view details about individual items in the list, edit the items, +and add a new item to the list. This section looks at the intent filters +declared in its manifest file. (If you're working offline in the SDK, you +can find all the source files for this sample application, including its +manifest file, at {@code <sdk>/samples/NotePad/index.html}. +If you're viewing the documentation online, the source files are in the +<a href="{@docRoot}guide/samples/index.html">Tutorials and Sample Code</a> +section <a href="{@docRoot}guide/samples/NotePad/index.html">here</a>.) +</p> + +<p> +In its manifest file, the Note Pad application declares three activities, +each with at least one intent filter. It also declares a content provider +that manages the note data. Here is the manifest file in its entirety: +</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.android.notepad"> + <application android:icon="@drawable/app_notes" + android:label="@string/app_name" > + + <provider android:name="NotePadProvider" + android:authorities="com.google.provider.NotePad" /> + + <activity android:name="NotesList" android:label="@string/title_notes_list"> + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="android.intent.action.PICK" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.GET_CONTENT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> + </intent-filter> + </activity> + + <activity android:name="NoteEditor" + android:theme="@android:style/Theme.Light" + android:label="@string/title_note" > + <intent-filter android:label="@string/resolve_edit"> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="com.android.notepad.action.EDIT_NOTE" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.INSERT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> + </intent-filter> + </activity> + + <activity android:name="TitleEditor" + android:label="@string/title_edit_title" + android:theme="@android:style/Theme.Dialog"> + <intent-filter android:label="@string/resolve_title"> + <action android:name="com.android.notepad.action.EDIT_TITLE" /> + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.ALTERNATIVE" /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> + </intent-filter> + </activity> + + </application> +</manifest></pre> + +<p> +The first activity, NotesList, is +distinguished from the other activities by the fact that it operates +on a directory of notes (the note list) rather than on a single note. +It would generally serve as the initial user interface into the +application. It can do three things as described by its three intent +filters: +</p> + +<ol> +<li><pre><intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> +</intent-filter></pre> + +<p> +This filter declares the main entry point into the Note Pad application. +The standard {@code MAIN} action is an entry point that does not require +any other information in the Intent (no data specification, for example), +and the {@code LAUNCHER} category says that this entry point should be +listed in the application launcher. +</p></li> + +<li><pre><intent-filter> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="android.intent.action.PICK" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> +</intent-filter></pre> + +<p> +This filter declares the things that the activity can do on a directory +of notes. It can allow the user to view or edit the directory (via +the {@code VIEW} and {@code EDIT} actions), or to pick a particular note +from the directory (via the {@code PICK} action). +</p> + +<p> +The {@code mimeType} attribute of the +<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> +element specifies the kind of data that these actions operate on. It +indicates that the activity can get a Cursor over zero or more items +({@code vnd.android.cursor.dir}) from a content provider that holds +Note Pad data ({@code vnd.google.note}). The Intent object that launches +the activity would include a {@code content:} URI specifying the exact +data of this type that the activity should open. +</p> + +<p> +Note also the {@code DEFAULT} category supplied in this filter. It's +there because the <code>{@link android.content.Context#startActivity +Context.startActivity()}</code> and +<code>{@link android.app.Activity#startActivityForResult +Activity.startActivityForResult()}</code> methods treat all intents +as if they contained the {@code DEFAULT} category — with just +two exceptions: +</p> + +<ul> +<li>Intents that explicitly name the target activity</li> +<li>Intents consisting of the {@code MAIN} action and {@code LAUNCHER} +category</li> +</ul> + +<p> +Therefore, the {@code DEFAULT} category is <em>required</em> for all +filters — except for those with the {@code MAIN} action and +{@code LAUNCHER} category. (Intent filters are not consulted for +explicit intents.) +</p></li> + +<li><pre><intent-filter> + <action android:name="android.intent.action.GET_CONTENT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> +</intent-filter></pre> + +<p> +This filter describes the activity's ability to return a note selected by +the user without requiring any specification of the directory the user should +choose from. The {@code GET_CONTENT} action is similar to the {@code PICK} +action. In both cases, the activity returns the URI for a note selected by +the user. (In each case, it's returned to the activity that called +<code>{@link android.app.Activity#startActivityForResult +startActivityForResult()}</code> to start the NoteList activity.) Here, +however, the caller specifies the type of data desired instead of the +directory of data the user will be picking from. +</p> + +<p> +The data type, <code>vnd.android.cursor.item/vnd.google.note</code>, +indicates the type of data the activity can return — a URI for +a single note. From the returned URI, the caller can get a Cursor for +exactly one item ({@code vnd.android.cursor.item}) from the content +provider that holds Note Pad data ({@code vnd.google.note}). +</p> + +<p> +In other words, for the {@code PICK} action in the previous filter, +the data type indicates the type of data the activity could display to the +user. For the {@code GET_CONTENT} filter, it indicates the type of data +the activity can return to the caller. +</p></li> +</ol> + +<p> +Given these capabilities, the following intents will resolve to the +NotesList activity: +</p> + +<dl style="margin-left: 2em"> +<dt>action: <code>android.intent.action.MAIN</code></dt> +<dd>Launches the activity with no data specified.</dd> + +<dt>action: <code>android.intent.action.MAIN</code> +<br/>category: <code>android.intent.category.LAUNCHER</code></dt> +<dd> Launches the activity with no data selected specified. +This is the actual intent used by the Launcher to populate its top-level +list. All activities with filters that match this action and category +are added to the list.</dd> + +<dt>action: <code>android.intent.action.VIEW</code> +<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> +<dd>Asks the activity to display a list of all the notes under +<code>content://com.google.provider.NotePad/notes</code>. The user can then +browse through the list and get information about the items in it.</dd> + +<dt>action: <code>android.intent.action.PICK</code> +<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> +<dd>Asks the activity to display a list of the notes under +<code>content://com.google.provider.NotePad/notes</code>. +The user can then pick a note from the list, and the activity will return +the URI for that item back to the activity that started the NoteList activity.</dd> + +<dt>action: <code>android.intent.action.GET_CONTENT</code> +<br/>data type: <code>vnd.android.cursor.item/vnd.google.note</code></dt> +<dd>Asks the activity to supply a single item of Note Pad data.</dd> +</dl> + +<p> +The second activity, NoteEditor, shows +users a single note entry and allows them to edit it. It can do two things +as described by its two intent filters: + +<ol> +<li><pre><intent-filter android:label="@string/resolve_edit"> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="com.android.notepad.action.EDIT_NOTE" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> +</intent-filter></pre> + +<p> +The first, primary, purpose of this activity is to enable the user to +interact with a single note &mdash to either {@code VIEW} the note or +{@code EDIT} it. (The {@code EDIT_NOTE} category is a synonym for +{@code EDIT}.) The intent would contain the URI for data matching the +MIME type <code>vnd.android.cursor.item/vnd.google.note</code> — +that is, the URI for a single, specific note. It would typically be a +URI that was returned by the {@code PICK} or {@code GET_CONTENT} +actions of the NoteList activity. +</p> + +<p> +As before, this filter lists the {@code DEFAULT} category so that the +activity can be launched by intents that don't explicitly specify the +NoteEditor class. +</p></li> + +<li><pre><intent-filter> + <action android:name="android.intent.action.INSERT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> +</intent-filter></pre> + +<p> +The secondary purpose of this activity is to enable the user to create a new +note, which it will {@code INSERT} into an existing directory of notes. The +intent would contain the URI for data matching the MIME type +<code>vnd.android.cursor.dir/vnd.google.note</code> — that +is, the URI for the directory where the note should be placed. +</p></li> +</ol> + +<p> +Given these capabilities, the following intents will resolve to the +NoteEditor activity: +</p> + +<dl style:"margin-left: 2em"> +<dt>action: <code>android.intent.action.VIEW</code> +<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> +<dd>Asks the activity to display the content of the note identified +by {@code <var>ID</var>}. (For details on how {@code content:} URIs +specify individual members of a group, see +<a href="{@docRoot}guide/topics/provider/content-providers.html">Content Providers</a>.) + +<dt>action: <code>android.intent.action.EDIT</code> +<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> +<dd>Asks the activity to display the content of the note identified +by {@code <var>ID</var>}, and to let the user edit it. If the user +saves the changes, the activity updates the data for the note in the +content provider.</dd> + +<dt>action: <code>android.intent.action.INSERT</code> +<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> +<dd>Asks the activity to create a new, empty note in the notes list at +<code>content://com.google.provider.NotePad/notes</code> +and allow the user to edit it. If the user saves the note, its URI +is returned to the caller. +</dd> +</dl> + +<p>The last activity, TitleEditor, +enables the user to edit the title of a note. This could be implemented +by directly invoking the activity (by explicitly setting its component +name in the Intent), without using an intent filter. But here we take +the opportunity to show how to publish alternative operations on existing +data: +</p> + +<pre><intent-filter android:label="@string/resolve_title"> + <action android:name="com.android.notepad.action.EDIT_TITLE" /> + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.ALTERNATIVE" /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> +</intent-filter></pre> + +<p> +The single intent filter for this activity uses a custom action called +"<code>com.android.notepad.action.EDIT_TITLE</code>". It must be invoked on +a specific note (data type <code>vnd.android.cursor.item/vnd.google.note</code>), +like the previous {@code VIEW} and {@code EDIT} actions. However, here the +activity displays the title contained in the note data, not the content of +the note itself. +</p> + +<p> +In addition to supporting the usual {@code DEFAULT} category, the title +editor also supports two other standard categories: +<code>{@link android.content.Intent#CATEGORY_ALTERNATIVE ALTERNATIVE}</code> +and <code>{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE +SELECTED_ALTERNATIVE}</code>. +These categories identify activities that can be presented to users in +a menu of options (much as the {@code LAUNCHER} category identifies +activities that should be presented to user in the application launcher). +Note that the filter also supplies an explicit label (via +<code>android:label="@string/resolve_title"</code>) to better control +what users see when presented with this activity as an alternative +action to the data they are currently viewing. (For more information +on these categories and building options menus, see the +<code>{@link android.content.pm.PackageManager#queryIntentActivityOptions +PackageManager.queryIntentActivityOptions()}</code> and +<code>{@link android.view.Menu#addIntentOptions Menu.addIntentOptions()}</code> +methods.) +</p> + +<p> +Given these capabilities, the following intent will resolve to the +TitleEditor activity: +</p> + +<dl style="margin-left: 2em"> +<dt>action: <code>com.android.notepad.action.EDIT_TITLE</code> +<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> +<dd>Asks the activity to display the title associated with note <var>ID</var>, and +allow the user to edit the title.</dd> +</dl> + diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd index a9d1090..48e598a 100644 --- a/docs/html/guide/topics/manifest/manifest-element.jd +++ b/docs/html/guide/topics/manifest/manifest-element.jd @@ -44,8 +44,11 @@ to "{@code http://schemas.android.com/apk/res/android}".</dd> <dt><a name="package"></a>{@code package}</dt> <dd>A full Java package name for the application. The name should -be unique. For example, applications published by Google could have -names in the form <code>com.google.app.<i>application_name</i></code>. +be unique. The name may contain uppercase or lowercase letters ('A' +through 'Z'), numbers, and underscores ('_'). However, individual +package name parts may only start with letters. For example, applications +published by Google could have names in the form +<code>com.google.app.<i>application_name</i></code>. <p> The package name serves as a unique identifier for the application. diff --git a/docs/html/guide/topics/manifest/provider-element.jd b/docs/html/guide/topics/manifest/provider-element.jd index 3942f95..98892f1 100644 --- a/docs/html/guide/topics/manifest/provider-element.jd +++ b/docs/html/guide/topics/manifest/provider-element.jd @@ -111,7 +111,7 @@ temporarily overcoming the restriction imposed by the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attributes — -"{@code true}" if permission can be granted, and "{@ code false}" if not. +"{@code true}" if permission can be granted, and "{@code false}" if not. If "{@code true}", permission can be granted to any of the content provider's data. If "{@code false}", permission can be granted only to the data subsets listed in diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index 00797ed..3fb0172 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -30,40 +30,8 @@ framework will scale down assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5 (high dpi screens). The screen density is expressed as dots-per-inch (dpi).</p> -<p>Currently supported densities:</p> -<ul> - <li>Low density: 120 dpi</li> - <li>Medium density: 160 dpi</li> - <li>High density: 240 dpi</li> -</ul> - -<p>Table of display types:</p> - -<table> -<tr> - <th></th><th>Low Density</th><th>Medium Density</th><th>High Density</th> -</tr> -<tr> - <th>Small Screen</th> - <td>QVGA</td> - <td>n/a</td> - <td>VGA</td> -</tr> -<tr> - <th>Normal Screen</th> - <td>WQVGA</td> - <td>HVGA</td> - <td>WVGA, FWVGA</td> -</tr> -<tr> - <th>Large Screen</th> - <td>n/a</td> - <td>VGA, WVGA, FWVGA</td> - <td>n/a</td> -</tr> -</table> - -</dd> +<p>For more information, see +<a href="{@docRoot}guide/practices/screens_suppport.html">Multiple Screens Support</a>.</p> <dt>attributes:</dt> @@ -116,6 +84,7 @@ The screen density is expressed as dots-per-inch (dpi).</p> <dt>see also:</dt> <dd> <ul> + <li><a href="{@docRoot}guide/practices/screens_suppport.html">Multiple Screens Support</a></li> <li>{@link android.util.DisplayMetrics}</li> </ul> </dd> diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index ee8d03d..aa1e8ae 100644 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd @@ -36,30 +36,27 @@ and minor versions).</p> <dd> <dl class="attr"> <dt><a name="min"></a>{@code android:minSdkVersion}</dt> - <dd>An integer designating the minimum level of the Android API that's required - for the application to run. + <dd>An integer designating the minimum API Level required + for the application to run. The Android system will prevent the user from installing + the application if the system's API Level is lower than the value specified in + this attribute. You should always declare this attribute. - <p>Prior to installing an application, the Android system checks the value of this - attribute and allows the installation only if it - is less than or equal to the API Level used by the system itself.</p> - - <p>If you do not declare this attribute, then a value of "1" is assumed, which + <p class="caution"><strong>Caution:</strong> + If you do not declare this attribute, then a value of "1" is assumed, which indicates that your application is compatible with all versions of Android. If your - application is <em>not</em> universally compatible (for instance if it uses APIs - introduced in Android 1.5) and you have not declared the proper <code>minSdkVersion</code>, - then when installed on a system with a lower API Level, the application - will crash during runtime. For this reason, be certain to declare the appropriate API Level + application is <em>not</em> compatible with all versions (for instance, it uses APIs + introduced in API Level 3) and you have not declared the proper <code>minSdkVersion</code>, + then when installed on a system with an API Level less than 3, the application will crash + during runtime when attempting to access the unavailable APIs. For this reason, + be certain to declare the appropriate API Level in the <code>minSdkVersion</code> attribute.</p> </dd> <dt><a name="max"></a>{@code android:maxSdkVersion}</dt> - <dd>An integer designating the maximum level of the Android API that the application is - compatible with. You can use this to ensure your application is filtered out - of later versions of the platform when you know you have incompatibility with them.</p> - - <p>Prior to installing an application, the Android system checks the value of this - attribute and allows the installation only it - is greater than or equal to the API Level used by the system itself.</p> + <dd>An integer designating the maximum API Level on which the application is + designed to run. The Android system will prevent the user from installing the + application if the system's API Level is higher than the value specified + in this attribute. <p>Introduced in: API Level 4</p> </dd> diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd index 2a6a6ac..f5f1475 100644 --- a/docs/html/guide/topics/resources/available-resources.jd +++ b/docs/html/guide/topics/resources/available-resources.jd @@ -36,6 +36,7 @@ parent.link=index.html </ol> </li> <li><a href="#stylesandthemes">Styles and Themes</a></li> + <li><a href="#Searchable">Searchable</a></li> </ol> </div> @@ -86,7 +87,7 @@ XML files such as <a href="#layoutresources">layouts</a>.</p> <code><color></code> tags. </p> <p> - <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary) + <strong>Resource source file location</strong>: {@code res/values/<em>colors</em>.xml} (File name is arbitrary.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a Java int. @@ -183,7 +184,7 @@ tags. <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><string></code> tags. </p> <p> - <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary) + <strong>Resource source file location</strong>: {@code res/values/<em>strings</em>.xml} (File name is arbitrary.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. @@ -338,8 +339,8 @@ version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><dimen></code> tags.</p> -<p><strong>Resource source file location</strong>: res/values/dimens.xml (File -name is arbitrary; standard practice is to put all dimensions in one file +<p><strong>Resource source file location</strong>: {@code res/values/dimens.xml} (File +name is arbitrary, but standard practice is to put all dimensions in one file devoted to dimensions.)</p> <p><strong>Compiled resource datatype:</strong> Resource pointer to a dimension.</p> @@ -424,7 +425,7 @@ res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file. </p> <p> - <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif. + <strong>Resource file location</strong>: {@code res/drawable/<em>some_file</em>.png} </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}. @@ -453,7 +454,8 @@ version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><drawable></code> tags.</p> <p> - <strong>Resource source file location</strong>: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.) + <strong>Resource source file location</strong>: {@code res/values/colors.xml} (File name is arbitrary, but standard practice is to put the PaintDrawable + items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}. @@ -540,7 +542,7 @@ tv.setBackground(redDrawable); <strong>Source file format:</strong> PNG — one resource per file </p> <p> - <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png) + <strong>Resource source file location</strong>: {@code res/drawable/<em>some_name</em>.9.png} (Filename must end in {@code .9.png}) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}. @@ -573,7 +575,7 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration </p> <p> - <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml + <strong>Resource file location</strong>: {@code res/anim/<em>some_file</em>.xml} </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}. @@ -906,7 +908,7 @@ res/layout/<em>some_file</em>.xml.</p> </p> <pre> <<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android" - id="@+id/<em>string_name</em>" (attributes)> + android:id="@+id/<em>string_name</em>" (attributes)> <<em>widget</em> or other nested <em>ViewGroupClass</em>>+ <requestFocus/>(0 or 1 per layout file, assigned to any element) </<em>ViewGroupClass</em>> @@ -917,7 +919,7 @@ res/layout/<em>some_file</em>.xml.</p> </dt> <dd> <p>The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android {@link android.widget widget} or {@link android.view.ViewGroup ViewGroup} class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <code><TextView></code> elements inside a <code><ListLayout></code>).</p> - <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <code><TextView id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> + <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <code><TextView android:id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> <ul> <li> <em>id</em> - An ID value used to access this element in Java. Typically you will use the syntax @+id/<em>string_name</em> to generate an ID for you in the id.xml file if you haven't created one yourself. @@ -1005,7 +1007,7 @@ res/layout/<em>some_file</em>.xml.</p> android:paddingBottom="4" // TextView.paddingBottom android:text="@string/redirect_getter"/> // TextView.text - <EditText id="@+id/text" + <EditText android:id="@+id/text" android:layout_width="fill_parent" // EditText.LayoutParams.width android:layout_height="wrap_content" // EditText.LayoutParams.height android:layout_weight="0" // EditText.LinearLayoutParams.weight @@ -1013,7 +1015,7 @@ res/layout/<em>some_file</em>.xml.</p> <requestFocus /> </EditText> - <Button id="@+id/apply" + <Button android:id="@+id/apply" android:layout_width="wrap_content" // Button.LayoutParams.width android:layout_height="wrap_content" // Button.LayoutParams.height android:text="@string/apply" /> // TextView.text @@ -1045,7 +1047,7 @@ setContentView(R.layout.main_screen); <strong>Java implementation file</strong> - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos. </li> <li> - <strong>res/values/attrs.xml</strong> - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <code><declare-styleable id=<em>your_java_class_name</em>></code>. See res/layout/attrs.xml in ApiDemos. + <strong>res/values/attrs.xml</strong> - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <code><declare-styleable name=<em>your_java_class_name</em>></code>. See res/values/attrs.xml in ApiDemos. </li> <li> <strong>res/layout/<em>your_class</em>.xml</strong> [<em>optional</em>] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos. @@ -1055,7 +1057,7 @@ setContentView(R.layout.main_screen); <strong>Source file format:</strong> XML file without an <code><?xml></code> declaration, and a <code><resources></code> root element containing one or more custom element tags. </p> <p> - <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary). + <strong>Resource file location</strong>: {@code res/values/<em>attrs</em>.xml} (File name is arbitrary.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. @@ -1084,7 +1086,7 @@ setContentView(R.layout.main_screen); <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><style></code> tags. </p> <p> - <strong>Resource source file location</strong>: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard practice is to put all styles into a file named styles.xml. + <strong>Resource source file location</strong>: {@code res/values/styles.xml} (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. @@ -1133,3 +1135,317 @@ setContentView(R.layout.main_screen); <p>For examples of how to declare and apply styles and themes, read <a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> + + + +<h2 id="Searchable">Searchable</h2> + +<p>To make search appear to the user as a seamless system-wide feature, the Android framework +offers APIs that let applications control how they are searched. +Applications can customize how search is invoked, how the search dialog looks, and what type of +search results are available, including suggestions that are shown as the user types.</p> + +<p>In order to utilize the Android search framework, an application must provide a search configuration +in the form of an XML resource. +This section describes the search configuration XML in terms of its syntax and usage. For a more +complete discussion about how to implement search features for your application, see +<!-- <a href="{@docRoot}guide/topics/search/index.html">Search</a> --> +{@link android.app.SearchManager}.</p> + +<p> + <strong>Source file format:</strong> + XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> + declaration, and a root <code><searchable></code> element. +</p> + +<p> + <strong>Resource source file location</strong>: {@code res/xml/searchable.xml} + (The file name is arbitrary, but standard practice is to use searchable.xml.) +</p> + +<p> + <strong>Compiled resource datatype:</strong> + Resource pointer to an xml object. +</p> + +<p> + <strong>Resource reference name:</strong> +</p> + +<ul> + <li> + <strong>Java:</strong> + <code>R.xml.<em>filename</em></code>. + </li> + <li> + <strong>XML:</strong> + <code>@[<em>package</em>:]xml/<em>filename</em></code> (e.g., <code>@xml/searchable</code>). + </li> +</ul> + +<p> + <strong>Syntax</strong> +</p> + +<pre> +<searchable xmlns:android="http://schemas.android.com/apk/res/android + android:label="@string/search_label" + ... > + <em><actionkey + android:keycode="KEYCODE_CALL" + ... ></em> +</searchable> +</pre> + +<dl> + <dt> + <searchable> + </dt> + <dd> + Defines all application search configurations, including settings for text and voice searches + performed within the application. It accepts the following attributes: + <ul> + <li> + <em>label</em> - <strong>Required</strong>. This is the name for your application, as it + will appear to the user. This will be visible only if <em>searchMode</em> is set to + "showSearchLabelAsBadge" (see below). + </li> + <li> + <em>hint</em> - This is the text to display in the search text field when no text has + been entered. This is recommended in order to provide context to the search about to be + performed (e.g., "Search the Dictionary"). + </li> + <li> + <em>searchMode</em> - If provided and non-zero, this sets additional modes for control + of the search presentation. The following mode values are accepted: + <ul> + <li> + <em>showSearchLabelAsBadge</em> - If set, this enables the display of the + search target (label) within the search bar. + </li> + <li> + <em>queryRewriteFromData</em> - If set, this causes the suggestion column + SUGGEST_COLUMN_INTENT_DATA to be considered as the text for suggestion query + rewriting. This should only be used when the values in + SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing - + typically, HTTP/HTTPS Uri's. + </li> + <li> + <em>queryRewriteFromText</em> - If set, this causes the suggestion + column SUGGEST_COLUMN_TEXT_1 to be considered as the text for suggestion query + rewriting. This should be used for suggestions in which no query + text is provided and the SUGGEST_COLUMN_INTENT_DATA values are not suitable + for user inspection and editing. + </li> + </ul> + <p>More than one of the above values for <em>searchMode</em> can be used at once. For + example, you can declare two modes at once, like this: + <code>searchMode="queryRewriteFromData|queryRewriteFromText"</code> + </li> + <li> + <em>inputType</em> - If provided, supplies a hint about the type of search text + the user will be entering. For most searches, in which free form text is expected, + this attribute is not needed. See + {@link android.R.attr#inputType} for a list of suitable values for this attribute. + </li> + <li> + <em>imeOptions</em> - If provided, supplies additional options for the input method. + For most searches, in which free form text is expected, this attribute is not needed, + and will default to "actionSearch". See + {@link android.R.attr#imeOptions} for a list of suitable values for this attribute. + </li> + </ul> + + <p>If you have defined a content provider to generate search suggestions, you need to + provide some more searchable metadata in order to configure communications with the content + provider. The following are additional {@code <searchable>} attributes for use when + providing search suggestions:</p> + + <ul> + <li> + <em>searchSuggestAuthority</em> - <strong>Required to provide search suggestions</strong>. + This value must match the authority string provided in the provider section of your manifest. + </li> + <li> + <em>searchSuggestPath</em> - If provided, this path will be inserted in the suggestions + query Uri, after the authority you have provide but before the standard suggestions path. + This is only required if you have a single content provider issuing different types + of suggestions (e.g. for different data types) and you need + a way to disambiguate the suggestions queries when they are received. + </li> + <li> + <em>searchSuggestSelection</em> - If provided, this value will be passed into your + query function as the selection parameter. Typically this will be a WHERE clause for + your database, and will contain a single question mark, which represents the actual query + string that has been typed by the user. However, you can also use any non-null value to simply + trigger the delivery of the query text (via selection arguments), and then use the query + text in any way appropriate for your provider (ignoring the actual text of the selection parameter.) + </li> + <li> + <em>searchSuggestIntentAction</em> - The default Intent action to be used when a user + clicks on a search suggestion. + If provided, and not overridden by the selected suggestion, this value will + be placed in the action field of the {@link android.content.Intent} when the + user clicks a suggestion. + </li> + <li> + <em>searchSuggestIntentData</em> - The default Intent data to be used when a user + clicks on a search suggestion. + If provided, and not overridden by the selected suggestion, this value will be + placed in the data field of the {@link android.content.Intent} when the user clicks + a suggestion. + </li> + </ul> + + <p>Beyond providing search suggestions while using your application's local search, you + can also configure your search suggestions to be made available to Quick Search Box, + which will allow users so receive search suggestions from your application content from outside + your application. The following are additional {@code <searchable>} attributes for use when + providing search suggestions to Quick Search Box:</p> + + <ul> + <li> + <em>includeInGlobalSearch</em> - <strong>Required to provide search suggestions in + Quick Search Box</strong>. If true, this indicates the search suggestions provided by your + application should be included in the globally accessible Quick Search Box. The user must + still enable your application as a searchable item in the system search settings in order + for your suggestions to appear in Quick Search Box. + </li> + <li> + <em>searchSettingsDescription</em> - If provided, this provides a brief description + of the search suggestions that you provide to Quick Search Box, + and will be displayed in the search settings entry for your application. + </li> + <li> + <em>queryAfterZeroResults</em> - Indicates whether a source should be invoked for + supersets of queries it has returned zero results for in the past. For example, if a + source returned zero results for "bo", it would be ignored for "bob". If set to false, + this source will only be ignored for a single session; the next time the search dialog + is invoked, all sources will be queried. The default value is false. + </li> + <li> + <em>searchSuggestThreshold</em> - Indicates the minimum number of characters needed to + trigger a source lookup from Quick Search Box. Only guarantees that a source will not be + queried for anything shorter than the threshold. The default value is 0. + </li> + </ul> + + <p>To enable voice search for your Activity, you can add fields to the searchable metadata + that enable and configure voice search. The following are additional {@code <searchable>} + attributes for use when implementing voice search:</p> + + <ul> + <li> + <em>voiceSearchMode</em> - <strong>Required to provide voice search + capabilities</strong>. + If provided and non-zero, enables voice search. + (Voice search may not be provided by the device, in which case these flags will + have no effect.) The following mode values are accepted: + <ul> + <li> + <em>showVoiceSearchButton</em> - If set, display a voice search button. This only + takes effect if voice search is available on the device. If set, then "launchWebSearch" + or "launchRecognizer" must also be set. + </li> + <li> + <em>launchWebSearch</em> - If set, the voice search button will take the user directly + to a built-in voice web search activity. Most applications will not use this flag, as + it will take the user away from the activity in which search was invoked. + </li> + <li> + <em>launchRecognizer</em> - If set, the voice search button will take + the user directly to a built-in voice recording activity. This activity + will prompt the user to speak, transcribe the spoken text, and forward the resulting + query text to the searchable activity, just as if the user had typed it into the + search UI and clicked the search button. + </li> + </ul> + </li> + <li> + <em>voiceLanguageModel</em> - A string constant from + {@link android.speech.RecognizerIntent}. + If provided, this specifies the language model that + should be used by the voice recognition system. See + {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL } for more + information. If not provided, the default value + {@link android.speech.RecognizerIntent#LANGUAGE_MODEL_FREE_FORM } will be used. + </li> + <li> + <em>voicePromptText</em> - A string. If provided, this specifies a prompt + that will be displayed during voice input. If not provided, a default prompt + will be displayed. + </li> + <li> + <em>voiceLanguage</em> - A string constant from {@link java.util.Locale}. + If provided, this specifies the spoken language to be expected. + This is only needed if it is different from the current value of + {@link java.util.Locale#getDefault()}. + </li> + <li> + <em>voiceMaxResults</em> - If provided, enforces the maximum number of results to return, + including the "best" result which will always be provided as the SEARCH intent's primary + query. Must be one or greater. Use EXTRA_RESULTS to get the results from the intent. + If not provided, the recognizer will choose how many results to return. + </li> + </ul> + </dd> + + <dt> + <actionkey> + </dt> + <dd> + Defines a shortcut key for a search action. + <ul> + <li> + <em>keycode</em> - <strong>Required</strong>. This attribute denotes the action key + you wish to respond to. Note that not all action keys are actually supported using + this mechanism, as many of them are used for typing, + navigation, or system functions. This will be added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your + searchable Activity. To examine the key code, use + {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}. + Note that, in addition to the keycode, you must also provide one or more of + the action specifier attributes below. + </li> + <li> + <em>queryActionMsg</em> - If you wish to handle an action key during normal + search query entry, you must define an action string here. This will be added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is + passed to your searchable Activity. To examine the string, use + {@link android.content.Intent#getStringExtra + getStringExtra(SearchManager.ACTION_MSG)}. + </li> + <li> + <em>suggestActionMsg</em> - If you wish to handle an action key while a + suggestion is being displayed and selected, there are two ways to handle this. + If all of your suggestions can handle the action key, you can simply define + the action message using this attribute. This will be added to the + {@link android.content.Intent#ACTION_SEARCH} Intent that is passed to your + searchable Activity. To examine the string, + use {@link android.content.Intent#getStringExtra + getStringExtra(SearchManager.ACTION_MSG)}. + </li> + <li> + <em>suggestActionMsgColumn</em> - If you wish to handle an action key while + a suggestion is being displayed and selected, but you do not wish to enable + this action key for every suggestion, then you can use this attribute to control + it on a suggestion-by-suggestion basis. First, you must define a column + (and name it here) where your suggestions will include the action string. Then, + in your content provider, you must provide this column, and when desired, + provide data in this column. The search manager will look at your suggestion cursor, + using the string provided here in order to select a column, and will use + that to select a string from the cursor. That string will be added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} + Intent that is passed to your searchable Activity. To examine + the string, use {@link android.content.Intent#getStringExtra + getStringExtra(SearchManager.ACTION_MSG)}. If the data does not exist for the + selection suggestion, the action key will be ignored. + </li> + </ul> + </dd> +</dl> + + + + + diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd new file mode 100755 index 0000000..f32f1ac --- /dev/null +++ b/docs/html/guide/topics/resources/localization.jd @@ -0,0 +1,644 @@ +page.title=Localization
+parent.title=Resources and Assets
+parent.link=index.html
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+
+<h2>Localization quickview</h2>
+
+<ul>
+ <li>Android lets you create different resource sets for different locales.</li>
+ <li>When your application runs, Android will load the resource set
+that match the device's locale.</li>
+ <li>If locale-specific resources are not available, Android falls back to
+defaults.</li>
+ <li>The emulator has features for testing localized apps. </li>
+</ul>
+
+<h2>In this document</h2>
+<ol>
+ <li><a href="#resource-switching">Overview: Resource-Switching in Android</a>
+
+</li>
+<ol><li><a href="#defaults-r-important">Why Default Resources Are Important</a></li></ol>
+<li><a href="#using-framework">Using Resources for Localization</a>
+ <ol>
+ <li><a href="#creating-defaults">How to Create Default Resources</a></li><li>
+ <a href="#creating-alternates">How to Create Alternate Resources</a></li>
+ <li><a href="#resource-precedence">Which Resources Take Precedence?</a></li>
+ <li><a href="#referring-to-resources">Referring to Resources in Java</a></li>
+
+ </ol>
+</li>
+<li><a href="#strategies">Localization Strategies</a></li>
+<li><a href="#testing">Testing Localized Applications</a></li>
+ <ol>
+ <li><a href="#device">Testing on a Device</a></li>
+ <li><a href="#emulator">Testing on an Emulator</a></li>
+ <li><a href="#test-for-default">Testing for Default Resources</a></li>
+ </ol>
+<li><a href="#publishing">Publishing</a></li>
+<li><a href="#checklist">Localization Checklists</a></li>
+ <ol>
+ <li><a href="#planning-checklist">Planning and Design Checklist</a></li>
+ <li><a href="#content-checklist">Content Checklist</a></li>
+ <li><a href="#testing-checklist">Testing and Publishing Checklist</a></li>
+ </ol>
+</ol>
+
+<h2>See also</h2>
+ <ol>
+ <li><a
+href="{@docRoot}guide/tutorials/localization/index.html">Hello, L10N Tutorial</a></li>
+ <li><a href="resources-i18n.html">Resources</a></li>
+ <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>
+ <li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">Activity Lifecycle</a></li>
+</ol>
+</div>
+</div>
+
+<p>Android will run on many devices in many regions. To reach the most users,
+your application should handle text, audio files, numbers, currency, and
+graphics in ways appropriate to the locales where your application will be used.
+</p>
+
+<p>This document describes best practices for localizing Android
+applications. The principles apply whether you are developing your application
+using ADT with Eclipse, Ant-based tools, or any other IDE. </p>
+
+<p>You should already have a working knowledge of Java and be familiar with
+Android resource loading, the declaration of user interface elements in XML,
+development considerations such as Activity lifecycle, and general principles of
+internationalization and localization. </p>
+
+<p>It is good practice to use the Android resource framework to separate the
+localized aspects of your application as much as possible from the core Java
+functionality:</p>
+
+<ul>
+ <li>You can put most or all of the <em>contents</em> of your application's
+user interface into resource files, as described in this document and in <a
+href="index.html">Resources</a>. </li>
+ <li>The <em>behavior</em> of the user interface, on the other hand, is driven
+by your Java code.
+ For example, if users input data that needs to be formatted or sorted
+differently depending on locale, then you would use Java to handle the data
+programmatically. This document does not cover how to localize your Java code.
+</li>
+</ul>
+
+<p>The <a
+href="{@docRoot}guide/tutorials/localization/index.html">Hello, L10N
+</a> tutorial takes you through the steps of creating a simple localized
+application that uses locale-specific resources in the way described in this
+document. </p>
+
+
+<h2 id="resource-switching">Overview: Resource-Switching in Android</h2>
+
+<p>Resources are text strings, layouts, sounds, graphics, and any other static
+data that your Android application needs. An application can include multiple
+sets of resources, each customized for a different device configuration. When a
+user runs the application, Android automatically selects and loads the
+resources that best match the device.</p>
+
+<p>(This document focuses on localization and locale. For a complete description
+of resource-switching and all the types of configurations that you can
+specify — screen orientation, touchscreen type, and so on — see <a
+href="resources-i18n.html#AlternateResources">Alternate Resources</a>.)</p>
+
+<table border="0" cellspacing="0" cellpadding="0">
+ <tr border="0">
+ <td width="180" style="border: 0pt none ;"><p class="special-note">
+ <strong>When you write your application:</strong>
+ <br><br>
+ You create a set of default resources, plus alternates to be used in
+ different locales.</p></td>
+ <td style="border: 0pt none; padding:0">
+ <p style="border:0; padding:0"><img src="../../../images/resources/right-arrow.png" alt="right-arrow"
+ width="51" height="17"></p></td>
+ <td width="180" style="border: 0pt none ;"><p class="special-note">
+ <strong>When a user runs your application:</strong>
+ <br><br>The Android system selects which resources to load, based on the
+ device's locale.</p></td>
+ </tr>
+</table>
+
+<p>When you write your application, you create default and alternate resources
+for your application to use. To create resources, you place files within
+specially named subdirectories of the project's <code>res/</code> directory.
+</p>
+
+
+
+<h3 id="defaults-r-important">Why Default Resources Are Important</h3>
+
+<p>Whenever the application runs in a locale for which you have not provided
+locale-specific text, Android will load the default strings from
+<code>res/values/strings.xml</code>. If this default file is absent, or if it
+is missing a string that your application needs, then your application will not run
+and will show an error.
+The example below illustrates what can happen when the default text file is incomplete. </p>
+
+<p><em>Example:</em>
+<p>An application's Java code refers to just two strings, <code>text_a</code> and
+ <code>text_b</code>. This application includes a localized resource file
+ (<code>res/values-en/strings.xml</code>) that defines <code>text_a</code> and
+ <code>text_b</code> in English. This application also includes a default
+ resource file (<code>res/values/strings.xml</code>) that includes a
+definition for <code>text_a</code>, but not for <code>text_b</code>:
+<ul>
+ <li>This application might compile without a problem. An IDE such as Eclipse
+ will not highlight any errors if a resource is missing.</li>
+ <li>When this application is launched on a device with locale set to English,
+ the application might run without a problem, because
+ <code>res/values-en/strings.xml</code> contains both of the needed text
+ strings.</li>
+ <li>However, <strong>the user will see an error message and a Force Close
+ button</strong> when this application is launched on a device set to a
+ language other than English. The application will not load.</li>
+</ul>
+
+
+<p>To prevent this situation, make sure that a <code>res/values/strings.xml</code>
+ file exists and that it defines every needed string. The situation applies to
+ all types of resources, not just strings: You
+ need to create a set of default resource files containing all
+ the resources that your application calls upon — layouts, drawables,
+ animations, etc. For information about testing, see <a href="#test-for-default">
+ Testing for Default Resources</a>.</p>
+
+<h2 id="using-framework">Using Resources for Localization</h2>
+
+<h3 id="creating-defaults">How to Create Default Resources</h3>
+
+<p>Put the application's default text in
+a file with the following location and name:</p>
+<p><code> res/values/strings.xml</code> (required directory)</p>
+
+<p>The text strings in <code>res/values/strings.xml</code> should use the
+default language, which is the language that you expect most of your application's users to
+speak. </p>
+
+<p>The default resource set must also include any default drawables and layouts,
+ and can include other types of resources such as animations.
+<br>
+ <code> res/drawable/</code>(required directory holding at least
+ one graphic file, for the application's icon in the Market)<br>
+ <code> res/layout/</code> (required directory holding an XML
+ file that defines the default layout)<br>
+ <code> res/anim/</code> (required if you have any
+ <code>res/anim-<em><qualifiers></em></code> folders)<br>
+ <code> res/xml/</code> (required if you have any
+ <code>res/xml-<em><qualifiers></em></code> folders)<br>
+ <code> res/raw/</code> (required if you have any
+ <code>res/raw-<em><qualifiers></em></code> folders)
+</p>
+
+<p class="note"><strong>Tip:</strong> In your code, examine each reference to
+ an Android resource. Make sure that a default resource is defined for each
+ one. Also make sure that the default string file is complete: A <em>
+ localized</em> string file can contain a subset of the strings, but the
+ <em>default</em> string file must contain them all.
+</p>
+
+<h3 id="creating-alternates">How to Create Alternate Resources</h3>
+
+<p>A large part of localizing an application is providing alternate text for
+different languages. In some cases you will also provide alternate graphics,
+sounds, layouts, and other locale-specific resources. </p>
+
+<p>An application can specify many <code>res/<em><qualifiers></em>/</code>
+directories, each with different qualifiers. To create an alternate resource for
+a different locale, you use a qualifier that specifies a language or a
+language-region combination. (The name of a resource directory must conform
+to the naming scheme described in
+<a href="resources-i18n.html#AlternateResources">Alternate Resources</a>,
+or else it will not compile.)</p>
+
+<p><em>Example:</em></p>
+
+<p>Suppose that your application's default language is English. Suppose also
+that you want to localize all the text in your application to French, and most
+of the text in your application (everything except the application's title) to
+Japanese. In this case, you could create three alternate <code>strings.xml</code>
+files, each stored in a locale-specific resource directory:</p>
+
+<ol>
+ <li><code>res/values/strings.xml</code><br>
+ Contains English text for all the strings that the application uses,
+including text for a string named <code>title</code>.</li>
+ <li><code>res/values-fr/strings.xml</code><br>
+ Contain French text for all the strings, including <code>title</code>.</li>
+ <li><code>res/values-ja/strings.xml</code><br>
+ Contain Japanese text for all the strings <em>except</em>
+<code>title</code>.<br>
+ <code></code></li>
+</ol>
+
+<p>If your Java code refers to <code>R.string.title</code>, here is what will
+happen at runtime:</p>
+
+<ul>
+ <li>If the device is set to any language other than French, Android will load
+<code>title</code> from the <code>res/values/strings.xml</code> file.</li>
+ <li>If the device is set to French, Android will load <code>title</code> from
+the <code>res/values-fr/strings.xml</code> file.</li>
+</ul>
+
+<p>Notice that if the device is set to Japanese, Android will look for
+<code>title</code> in the <code>res/values-ja/strings.xml</code> file. But
+because no such string is included in that file, Android will fall back to the
+default, and will load <code>title</code> in English from the
+<code>res/values/strings.xml</code> file. </p>
+
+<h3 id="resource-precedence">Which Resources Take Precedence?</h3>
+
+<p> If multiple resource files match a device's configuration, Android follows a
+set of rules in deciding which file to use. Among the qualifiers that can be
+specified in a resource directory name, <strong>locale almost always takes
+precedence</strong>. </p>
+<p><em>Example:</em></p>
+
+<p>Assume that an application includes a default set of graphics and two other
+sets of graphics, each optimized for a different device setup:</p>
+
+<ul>
+ <li><code>res/drawable/</code><br>
+ Contains
+ default graphics.</li>
+ <li><code>res/drawable-small-land-stylus/</code><br>
+ Contains graphics optimized for use with a device that expects input from a
+ stylus and has a QVGA low-density screen in landscape orientation.</li>
+ <li><code>res/drawable-ja/</code> <br>
+ Contains graphics optimized for use with Japanese.</li>
+</ul>
+
+<p>If the application runs on a device that is configured to use Japanese,
+Android will load graphics from <code>res/drawable-ja/</code>, even if the
+device happens to be one that expects input from a stylus and has a QVGA
+low-density screen in landscape orientation.</p>
+
+<p class="note"><strong>Exception:</strong> The only qualifiers that take
+precedence over locale in the selection process are MCC and MNC (mobile country
+code and mobile network code). </p>
+
+<p><em>Example:</em></p>
+
+<p>Assume that you have the following situation:</p>
+
+<ul>
+ <li>The application code calls for <code>R.string.text_a</code></li>
+ <li>Two relevant resource files are available:
+ <ul>
+ <li><code>res/values-mcc404/strings.xml</code>, which includes
+<code>text_a</code> in the application's default language, in this case
+English.</li>
+ <li><code>res/values-hi/strings.xml</code>, which includes
+<code>text_a</code> in Hindi.</li>
+ </ul>
+ </li>
+ <li>The application is running on a device that has the following
+configuration:
+ <ul>
+ <li>The SIM card is connected to a mobile network in India (MCC 404).</li>
+ <li>The language is set to Hindi (<code>hi</code>).</li>
+ </ul>
+ </li>
+</ul>
+
+<p>Android will load <code>text_a</code> from
+<code>res/values-mcc404/strings.xml</code> (in English), even if the device is
+configured for Hindi. That is because in the resource-selection process, Android
+will prefer an MCC match over a language match. </p>
+
+<p>The selection process is not always as straightforward as these examples
+suggest. Please read <a href="resources-i18n.html#best-match">How Android finds
+the best matching directory</a> for a more nuanced description of the
+process. All the qualifiers are described and listed in order of
+precedence in <a href="resources-i18n.html#table2">Table 2 in the Resources
+document</a>.</p>
+
+<h3 id="referring-to-resources">Referring to Resources in Java</h3>
+
+<p>In your application's Java code, you refer to resources using the syntax
+<code>R.<em>resource_type</em>.<em>resource_name</em></code> or
+<code>android.R.<em>resource_type</em>.<em>resource_name</em></code><em>.</em>
+For more about this, see <a href="resources-i18n.html#ResourcesInCode">Using
+Resources in Code</a>.</p>
+
+<h2 id="strategies">Localization Strategies</h2>
+
+<h4 id="failing2">Design your application to work in any locale</h4>
+
+<p>You cannot assume anything about the device on which a user will
+run your application. The device might have hardware that you were not
+anticipating, or it might be set to a locale that you did not plan for or that
+you cannot test. Design your application so that it will function normally or fail gracefully no
+matter what device it runs on.</p>
+
+<p class="note"><strong>Important:</strong> Make sure that your application
+includes a full set of default resources.</p> <p>Make sure to include
+<code>res/drawable/</code> and a <code>res/values/</code> folders (without any
+additional modifiers in the folder names) that contain all the images and text
+that your application will need. </p>
+
+<p>If an application is missing even one default resource, it will not run on a
+ device that is set to an unsupported locale. For example, the
+ <code>res/values/strings.xml</code> default file might lack one string that
+ the application needs: When the application runs in an unsupported locale and
+ attempts to load <code>res/values/strings.xml</code>, the user will see an
+ error message and a Force Close button. An IDE such as Eclipse will not
+ highlight this kind of error, and you will not see the problem when you
+ test the application on a device or emulator that is set to a supported locale.</p>
+
+<p>For more information, see <a href="#test-for-default">Testing for Default Resources</a>.</p>
+
+<h4>Design a flexible layout</h4>
+
+<p> If you need to rearrange your layout to fit a certain language (for example
+German with its long words), you can create an alternate layout for that
+language (for example <code>res/layout-de/main.xml</code>). However, doing this
+can make your application harder to maintain. It is better to create a single
+layout that is more flexible.</p>
+
+<p>Another typical situation is a language that requires something different in
+its layout. For example, you might have a contact form that should include two
+name fields when the application runs in Japanese, but three name fields when
+the application runs in some other language. You could handle this in either of
+two ways:</p>
+
+<ul>
+ <li>Create one layout with a field that you can programmatically enable or
+disable, based on the language, or</li>
+ <li>Have the main layout include another layout that includes the changeable
+field. The second layout can have different configurations for different
+languages.</li>
+</ul>
+
+<h4>Avoid creating more resource files and text strings than you need</h4>
+
+<p>You probably do not need to create a locale-specific
+alternative for every resource in your application. For example, the layout
+defined in the <code>res/layout/main.xml</code> file might work in any locale,
+in which case there would be no need to create any alternate layout files.
+</p>
+
+<p>Also, you might not need to create alternate text for every
+string. For example, assume the following:</p>
+
+<ul>
+ <li>Your application's default language is American
+English. Every string that the application uses is defined, using American
+English spellings, in <code>res/values/strings.xml</code>. </li>
+
+ <li>For a few important phrases, you want to provide
+British English spelling. You want these alternate strings to be used when your
+application runs on a device in the United Kingdom. </li>
+</ul>
+
+<p>To do this, you could create a small file called
+<code>res/values-en-rGB/strings.xml</code> that includes only the strings that
+should be different when the application runs in the U.K. For all the rest of
+the strings, the application will fall back to the defaults and use what is
+defined in <code>res/values/strings.xml</code>.</p>
+
+<h4>Use the Android Context object for manual locale lookup</h4>
+
+<p>You can look up the locale using the {@link android.content.Context} object
+that Android makes available:</p>
+
+<pre>String locale = context.getResources().getConfiguration().locale.getDisplayName();</pre>
+
+<h2 id="testing">Testing Localized Applications</h2>
+
+<h3 id="device">Testing on a Device</h3>
+<p>Keep in mind that the device you are testing may be significantly different from
+ the devices available to consumers in other geographies. The locales available
+ on your device may differ from those available on other devices. Also, the
+ resolution and density of the device screen may differ, which could affect
+ the display of strings and drawables in your UI.</p>
+
+<p>To change the locale on a device, use the Settings application (Home >
+Menu > Settings > Locale & text > Select locale). </p>
+
+<h3 id="emulator">Testing on an Emulator</h3>
+
+<p>For details about using the emulator, see See <a
+href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
+<h4>Creating and using a custom locale</h4>
+
+<p>A "custom" locale is a language/region combination that the
+Android system image does not explicitly support. (For a list of supported
+locales, see the <a href="{@docRoot}sdk/android-{@sdkCurrentVersion}.html">Android
+Version Notes</a>.) You can test how your application will run in a custom
+locale by creating a custom locale in the emulator. There are two ways to do
+this:</p>
+
+<ul>
+ <li>Use the Custom Locale application, which is accessible from the
+Application tab. (After you create a custom locale, switch to it by
+pressing and holding the locale name.)</li>
+ <li>Change to a custom locale from the adb shell, as described below.</li>
+</ul>
+
+<p>When you set the emulator to a locale that is not available in the Android
+system image, the system itself will display in its default language. Your
+application, however, should localize properly.</p>
+
+<h4>Changing the emulator locale from the adb shell</h4>
+
+<p>To change the locale in the emulator by using the adb shell. </p>
+
+<ol>
+ <li>Pick the locale you want to test and determine its language and region codes, for
+example <code>fr</code> for French and <code>CA</code> for Canada.<br>
+ </li>
+ <li>Launch an emulator.</li>
+ <li>From a command-line shell on the host computer, run the following
+command:<br>
+ <code>adb shell</code><br>
+ or if you have a device attached, specify that you want the emulator by adding
+the <code>-e</code> option:<br>
+ <code>adb -e shell</code></li>
+ <li>At the adb shell prompt (<code>#</code>), run this command: <br>
+ <code>setprop persist.sys.language [<em>language code</em>];setprop
+persist.sys.country [<em>country code</em>];stop;sleep 5;start <br>
+ </code>Replace bracketed sections with the appropriate codes from Step
+1.</li>
+</ol>
+
+<p>For instance, to test in Canadian French:</p>
+
+<p><code>setprop persist.sys.language fr;setprop persist.sys.country
+CA;stop;sleep 5;start </code></p>
+
+<p>This will cause the emulator to restart. (It will look like a full reboot,
+but it is not.) Once the Home screen appears again, re-launch your application (for
+example, click the Run icon in Eclipse), and the application will launch with
+the new locale. </p>
+
+<h3 id="test-for-default">Testing for Default Resources</h3>
+<p>Here's how to test whether an application includes every string resource that it needs: </p>
+<ol><li>Set the emulator or device to a language that your application does not
+ support. For example, if the application has French strings in
+ <code>res/values-fr/</code> but does not have any Spanish strings in
+ <code>res/values-es/</code>, then set the emulator's locale to Spanish.
+ (You can use the Custom Locale application to set the emulator to an
+ unsupported locale.)</li>
+ <li>Run the application.</li>
+<li>If the application shows an error message and a Force Close button, it might
+ be looking for a string that is not available. Make sure that your
+ <code>res/values/strings.xml</code> file includes a definition for
+ every string that the application uses.</li>
+</ol>
+</p>
+
+<p>If the test is successful, repeat it for other types of
+ configurations. For example, if the application has a layout file called
+ <code>res/layout-land/main.xml</code> but does not contain a file called
+ <code>res/layout-port/main.xml</code>, then set the emulator or device to
+ portrait orientation and see if the application will run.
+
+<h2 id="publishing">Publishing Localized Applications</h2>
+
+<p>The Android Market is
+ the main application distribution system for Android devices. To publish a
+ localized application, you need to sign your application, version it, and go
+through all the other steps described in <a
+href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a>. </p>
+
+<p>If you split your application in several .apk files, each targeted to a
+different locale, follow these guidelines:</p>
+
+<ul>
+ <li>Sign each .apk file with the same certificate. For more about this, see <a
+href="{@docRoot}guide/publishing/app-signing.html#strategies">Signing
+Strategies</a>. </li>
+ <li>Give each .apk file a different application name. Currently it is
+impossible to put two applications into the Android Market that have exactly the
+same name.</li>
+<li>Include a complete set of default resources in each .apk file.</li>
+</ul>
+
+<h2 id="checklist">Localization Checklists</h2>
+
+<p>These checklists summarize the process of localizing an Android application.
+Not everything on these lists will apply to every application.</p>
+
+<h3 id="planning-checklist">Planning and Design Checklist</h3>
+
+<table width="100%" border="0" cellpadding="5" cellspacing="0">
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Choose a localization strategy. Which countries and which languages will
+your application support? What is your application's default country and
+language? How will your application behave when it does not have specific
+resources available for a given locale?</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td><p>Identify everything in your application that will need to be
+localized: </p>
+ <ul>
+ <li>Consider specific details of your application — text, images,
+sounds, music, numbers, money, dates and times. You might not need to localize
+everything. For example, you don't need to localize text that the user never
+sees, or images that are culturally neutral, or icons that convey the same
+meaning in every locale. </li>
+ <li>Consider broad themes. For example, if you hope to sell your
+application in two very culturally different markets, you might want to design
+your UI and present your application in an entirely different way for each
+locale.</li>
+ </ul></td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td><p>Design your Java code to externalize resources wherever possible:</p>
+ <ul>
+ <li>Use <code>R.string</code> and <code>strings.xml</code> files instead
+of hard-coded strings or string constants. </li>
+ <li>Use <code>R.drawable</code> and <code>R.layout</code> instead of
+hard-coded drawables or layouts. </li>
+ </ul></td>
+ </tr>
+</table>
+<h3 id="content-checklist">Content Checklist</h3>
+<table border="0" cellspacing="0" cellpadding="5" width="100%">
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Create a full set of default resources in <code>res/values/</code> and
+other <code>res/</code> folders, as described in <a
+href="#creating-defaults">Creating Default Resources</a>.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Obtain reliable translations of the static text, including menu text,
+button names, error messages, and help text. Place the translated strings in
+<code>res/values-<em><qualifiers></em>/strings.xml</code> files. </td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Make sure that your application correctly formats dynamic text (for
+example numbers and dates) for each supported locale. Make sure that your
+application handles word breaks, punctuation, and alphabetical sorting correctly
+for each supported language.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>If necessary, create locale-specific versions of your graphics and
+layout, and place them in <code>res/drawable-<em><qualifiers></em>/</code> and
+<code>res/layout-<em><qualifiers></em>/</code> folders.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Create any other localized content that your application requires; for
+example, create recordings of sound files for each language, as needed.</td>
+ </tr>
+</table>
+<h3 id="testing-checklist">Testing and Publishing Checklist</h3>
+ <table border="0" cellspacing="0" cellpadding="5" width="100%">
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Test your application for each supported locale. If possible, have a
+person who is native to each locale test your application and give you
+feedback.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Test the default resources by loading a locale that is not available on
+ the device or emulator. For instructions, see <a href="#test-for-default">
+ Testing for Default Resources</a>. </td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Test the localized strings in both landscape and portrait display modes.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Sign your application and create your final build or builds.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Upload your .apk file or files to Market, selecting the appropriate
+languages as
+ you upload. (For more details, see <a
+href="{@docRoot}guide/publishing/publishing.html">Publishing Your
+Applications</a>.)</td>
+ </tr>
+</table>
\ No newline at end of file diff --git a/docs/html/guide/topics/resources/res-selection-flowchart.png b/docs/html/guide/topics/resources/res-selection-flowchart.png Binary files differdeleted file mode 100755 index d738b3f..0000000 --- a/docs/html/guide/topics/resources/res-selection-flowchart.png +++ /dev/null diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd index 85b89d1..091bc62 100755 --- a/docs/html/guide/topics/resources/resources-i18n.jd +++ b/docs/html/guide/topics/resources/resources-i18n.jd @@ -441,7 +441,7 @@ resources for a fully specified configuration would look like this:</p> <pre> MyApp/ res/ - drawable-en-rUS-large-long-port-mdpi-finger-keysexposed-qwerty-dpad-480x320/ + drawable-en-rUS-large-long-port-mdpi-finger-keysexposed-qwerty-navexposed-dpad-480x320/ </pre> <p>More typically, you will only specify a few specific configuration options. You may drop any of the values from the @@ -575,6 +575,14 @@ MyApp/ <td><code>nokeys</code>, <code>qwerty</code>, <code>12key</code> </td> </tr> <tr> + <td>Whether the navigation keys are available to the user</td> + <td><p><code>navexposed</code>, <code>navhidden</code> + </p><p> + If the hardware's navigation keys are currently available to + the user, the navexposed resources will be used; if they are not + available (such as behind a closed lid), navhidden will be used.</p></td> + </tr> + <tr> <td>Primary non-touchscreen<br /> navigation method</td> <td><code>nonav</code>, <code>dpad</code>, <code>trackball</code>, <code>wheel</code> </td> @@ -685,7 +693,7 @@ MyApp/res/drawable-en-port/ </ol> <p class="note"><strong>Tip:</strong> The <em>precedence</em> of the qualifiers is more important than the number of qualifiers that exactly match the device. For example, in step 4 above, the last choice on the list includes three qualifiers that exactly match the device (orientation, touchscreen type, and input method), while <code>drawable-en</code> has only one parameter that matches (language). However, language has a higher precedence, so <code>drawable-port-notouch-12key</code> is out.</p> <p>This flowchart summarizes how Android selects resource directories to load.</p> -<p><img src="res-selection-flowchart.png" alt="resource-selection" width="461" height="471" style="margin:15px"></p> +<p><img src="../../../images/resources/res-selection-flowchart.png" alt="resource-selection" width="461" height="471" style="margin:15px"></p> <h3>Terminology</h3> <p>The resource system brings a number of different pieces together to form the final complete resource functionality. To help understand the diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 7ef22a6..80ad7b8 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -25,6 +25,7 @@ parent.link=index.html <li><a href="#SizePaddingMargin">Size, Padding and Margins</a></li> <li><a href="#example">Example Layout</a></li> </ol> + </div> </div> @@ -41,14 +42,17 @@ application can create View and ViewGroup objects (and manipulate their properti <p>The Android framework gives you the flexibility to use either or both of these methods for declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time. </p> <div class="sidebox"> - <p>The <a href="{@docRoot}guide/developing/tools/adt.html">Android Development Tools</a> - (ADT) plugin for Eclipse offers a layout preview of your XML — - with the XML file opened, select the <strong>Layout</strong> tab.</p> - <p>You should also try the + <ul> + <li>The <a href="{@docRoot}sdk/eclipse-adt.html">ADT + Plugin for Eclipse</a> offers a layout preview of your XML — + with the XML file opened, select the <strong>Layout</strong> tab.</li> + <li>You should also try the <a href="{@docRoot}guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a> tool, for debugging layouts — it reveals layout property values, draws wireframes with padding/margin indicators, and full rendered views while - you debug on the emulator or device.</p> + you debug on the emulator or device.</li> + <li>The <a href="{@docRoot}guide/developing/tools/layoutopt.html">layoutopt</a> tool lets + you quickly analyze your layouts and hierarchies for inefficiencies or other problems.</li> </div> <p>The advantage to declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls its behavior. Your UI descriptions are external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations, different device screen sizes, and different languages. Additionally, declaring the layout in XML makes it easier to visualize the structure of your UI, so it's easier to debug problems. As such, this document focuses on teaching you how to declare your layout in XML. If you're diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index c0c0b1b..4e4ca14 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -624,7 +624,7 @@ AlertDialog.Builder builder; AlertDialog alertDialog; Context mContext = getApplicationContext(); -LayoutInflater inflater = (LayoutInflater) mContext.getSystemService(LAYOUT_INFLATER); +LayoutInflater inflater = (LayoutInflater) mContext.getSystemService(LAYOUT_INFLATER_SERVICE); View layout = inflater.inflate(R.layout.custom_dialog, (ViewGroup) findViewById(R.id.layout_root)); diff --git a/docs/html/guide/topics/ui/ui-events.jd b/docs/html/guide/topics/ui/ui-events.jd index f4d114a..5628d46 100644 --- a/docs/html/guide/topics/ui/ui-events.jd +++ b/docs/html/guide/topics/ui/ui-events.jd @@ -28,8 +28,8 @@ the specific View object that the user interacts with. The View class provides t methods that look useful for UI events. These methods are called by the Android framework when the respective action occurs on that object. For instance, when a View (such as a Button) is touched, the <code>onTouchEvent()</code> method is called on that object. However, in order to intercept this, you must extend -the class and override the method. Obviously, extending every View object -you want to use (just to handle an event) would be obsurd. This is why the View class also contains +the class and override the method. However, extending every View object +in order to handle such an event would not be practical. This is why the View class also contains a collection of nested interfaces with callbacks that you can much more easily define. These interfaces, called <a href="#EventListeners">event listeners</a>, are your ticket to capturing the user interaction with your UI.</p> @@ -102,7 +102,7 @@ protected void onCreate(Bundle savedValues) { } </pre> -<p>You may also find it more conventient to implement OnClickListener as a part of your Activity. +<p>You may also find it more convenient to implement OnClickListener as a part of your Activity. This will avoid the extra class load and object allocation. For example:</p> <pre> public class ExampleActivity extends Activity implements OnClickListener { @@ -168,7 +168,7 @@ you'll learn see some of the common callbacks used for event handling, including <li><code>{@link android.view.View#onTouchEvent}</code> - Called when a touch screen motion event occurs.</li> <li><code>{@link android.view.View#onFocusChanged}</code> - Called when the view gains or loses focus.</li> </ul> -<p>There are some other methods that you should be awere of, which are not part of the View class, +<p>There are some other methods that you should be aware of, which are not part of the View class, but can directly impact the way you're able to handle events. So, when managing more complex events inside a layout, consider these other methods:</p> <ul> |
