diff options
Diffstat (limited to 'docs/html/training/basics')
| -rw-r--r-- | docs/html/training/basics/firstapp/building-ui.jd | 363 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/creating-project.jd | 142 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/index.jd | 64 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/running-app.jd | 178 | ||||
| -rw-r--r-- | docs/html/training/basics/firstapp/starting-activity.jd | 308 | ||||
| -rw-r--r-- | docs/html/training/basics/intents/filters.jd | 244 | ||||
| -rw-r--r-- | docs/html/training/basics/intents/index.jd | 64 | ||||
| -rw-r--r-- | docs/html/training/basics/intents/result.jd | 182 | ||||
| -rw-r--r-- | docs/html/training/basics/intents/sending.jd | 211 | ||||
| -rw-r--r-- | docs/html/training/basics/supporting-devices/index.jd | 49 | ||||
| -rw-r--r-- | docs/html/training/basics/supporting-devices/languages.jd | 134 | ||||
| -rw-r--r-- | docs/html/training/basics/supporting-devices/platforms.jd | 138 | ||||
| -rw-r--r-- | docs/html/training/basics/supporting-devices/screens.jd | 180 |
13 files changed, 2257 insertions, 0 deletions
diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd new file mode 100644 index 0000000..847163a --- /dev/null +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -0,0 +1,363 @@ +page.title=Building a Simple User Interface +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Running Your App +previous.link=running-app.html +next.title=Starting Another Activity +next.link=starting-activity.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#LinearLayout">Use a Linear Layout</a></li> + <li><a href="#TextInput">Add a Text Input Box</a></li> + <li><a href="#Strings">Add String Resources</a></li> + <li><a href="#Button">Add a Button</a></li> + <li><a href="#Weight">Make the Input Box Fill in the Screen Width</a></li> +</ol> + + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a></li> +</ul> + + +</div> +</div> + + + +<p>The graphical user interface for an Android app is built using a hierarchy of {@link +android.view.View} and {@link android.view.ViewGroup} objects. {@link android.view.View} objects are +usually UI widgets such as a button or text field and {@link android.view.ViewGroup} objects are +invisible view containers that define how the child views are laid out, such as in a +grid or a vertical list.</p> + +<p>Android provides an XML vocabulary that corresponds to the subclasses of {@link +android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML with a +hierarchy of view elements.</p> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h2>Alternative Layouts</h2> + <p>Separating the UI layout into XML files is important for several reasons, +but it's especially important on Android because it allows you to define alternative layouts for +different screen sizes. For example, you can create two versions of a layout and tell +the system to use one on "small" screens and the other on "large" screens. For more information, +see the class about <a +href="{@docRoot}training/supporting-hardware/index.html">Supporting Various Hardware</a>.</p> +</div> +</div> + +<img src="{@docRoot}images/viewgroup.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> Illustration of how {@link +android.view.ViewGroup} objects form branches in the layout and contain {@link +android.view.View} objects.</p> + +<p>In this lesson, you'll create a layout in XML that includes a text input field and a +button. In the following lesson, you'll respond when the button is pressed by sending the +content of the text field to another activity.</p> + + + +<h2 id="LinearLayout">Use a Linear Layout</h2> + +<p>Open the <code>main.xml</code> file from the <code>res/layout/</code> +directory (every new Android project includes this file by default).</p> + +<p class="note"><strong>Note:</strong> In Eclipse, when you open a layout file, you’re first shown +the ADT Layout Editor. This is an editor that helps you build layouts using WYSIWYG tools. For this +lesson, you’re going to work directly with the XML, so click the <em>main.xml</em> tab at +the bottom of the screen to open the XML editor.</p> + +<p>By default, the <code>main.xml</code> file includes a layout with a {@link +android.widget.LinearLayout} root view group and a {@link android.widget.TextView} child view. +You’re going to re-use the {@link android.widget.LinearLayout} in this lesson, but change its +contents and layout orientation.</p> + +<p>First, delete the {@link android.widget.TextView} element and change the value +<a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code +android:orientation}</a> to be <code>"horizontal"</code>. The result looks like this:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="horizontal" > +</LinearLayout> +</pre> + +<p>{@link android.widget.LinearLayout} is a view group (a subclass of {@link +android.view.ViewGroup}) that lays out child views in either a vertical or horizontal orientation, +as specified by the <a +href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code +android:orientation}</a> attribute. Each child of a {@link android.widget.LinearLayout} appears on +the screen in the order in which it appears in the XML.</p> + +<p>The other two attributes, <a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code +android:layout_width}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code +android:layout_height}</a>, are required for all views in order to specify their size.</p> + +<p>Because the {@link android.widget.LinearLayout} is the root view in the layout, it should fill +the entire screen area that's +available to the app by setting the width and height to +<code>"fill_parent"</code>.</p> + +<p class="note"><strong>Note:</strong> Beginning with Android 2.2 (API level 8), +<code>"fill_parent"</code> has been renamed <code>"match_parent"</code> to better reflect the +behavior. The reason is that if you set a view to <code>"fill_parent"</code> it does not expand to +fill the remaining space after sibling views are considered, but instead expands to +<em>match</em> the size of the parent view no matter what—it will overlap any sibling +views.</p> + +<p>For more information about layout properties, see the <a +href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layout</a> guide.</p> + + + +<h2 id="TextInput">Add a Text Input Box</h2> + +<p>To create a user-editable text box, add an {@link android.widget.EditText +<EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}. The {@link +android.widget.EditText} class is a subclass of {@link android.view.View} that displays an editable +text box.</p> + +<p>Like every {@link android.view.View} object, you must define certain XML attributes to specify +the {@link android.widget.EditText} object's properties. Here’s how you should declare it +inside the {@link android.widget.LinearLayout <LinearLayout>} element:</p> + +<pre> + <EditText android:id="@+id/edit_message" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> +</pre> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>About resource objects</h3> + <p>A resource object is simply a unique integer name that's associated with an app resource, +such as a bitmap, layout file, or string.</p> + <p>Every resource has a +corresponding resource object defined in your project's {@code gen/R.java} file. You can use the +object names in the {@code R} class to refer to your resources, such as when you need to specify a +string value for the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code android:hint}</a> +attribute. You can also create arbitrary resource IDs that you associate with a view using the <a +href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> attribute, +which allows you to reference that view from other code.</p> + <p>The SDK tools generate the {@code R.java} each time you compile your app. You should never +modify this file by hand.</p> +</div> +</div> + +<p>About these attributes:</p> + +<dl> +<dt><a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a></dt> +<dd>This provides a unique identifier for the view, which you can use to reference the object +from your app code, such as to read and manipulate the object (you'll see this in the next +lesson). + +<p>The at-symbol (<code>@</code>) is required when you want to refer to a resource object from +XML, followed by the resource type ({@code id} in this case), then the resource name ({@code +edit_message}). (Other resources can use the same name as long as they are not the same +resource type—for example, the string resource uses the same name.)</p> + +<p>The plus-symbol (<code>+</code>) is needed only when you're defining a resource ID for the +first time. It tells the SDK tools that the resource ID needs to be created. Thus, when the app is +compiled, the SDK tools use the ID value, <code>edit_message</code>, to create a new identifier in +your project's {@code gen/R.java} file that is now assiciated with the {@link +android.widget.EditText} element. Once the resource ID is created, other references to the ID do not +need the plus symbol. See the sidebox for more information about resource objects.</p></dd> + +<dt><a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code +android:layout_width}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code +android:layout_height}</a></dt> +<dd>Instead of using specific sizes for the width and height, the <code>"wrap_content"</code> value +specifies that the view should be only as big as needed to fit the contents of the view. If you +were to instead use <code>"fill_parent"</code>, then the {@link android.widget.EditText} +element would fill the screen, because it'd match the size of the parent {@link +android.widget.LinearLayout}. For more information, see the <a +href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a> guide.</dd> + +<dt><a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code +android:hint}</a></dt> +<dd>This is a default string to display when the text box is empty. Instead of using a hard-coded +string as the value, the value given in this example refers to a string resource. When you add the +{@code +"@string/edit_message"} value, you’ll see a compiler error because there’s no matching string +resource by that name. You'll fix this in the next section by defining the string +resource.</dd> +</dl> + + + +<h2 id="Strings">Add String Resources</h2> + +<p>When you need to add text in the user interface, you should always specify each string of text in +a resource file. String resources allow you to maintain a single location for all string +values, which makes it easier to find and update text. Externalizing the strings also allows you to +localize your app to different languages by providing alternative definitions for each +string.</p> + +<p>By default, your Android project includes a string resource file at +<code>res/values/strings.xml</code>. Open this file, delete the existing <code>"hello"</code> +string, and add one for the +<code>"edit_message"</code> string used by the {@link android.widget.EditText <EditText>} +element.</p> + +<p>While you’re in this file, also add a string for the button you’ll soon add, called +<code>"button_send"</code>.</p> + +<p>The result for <code>strings.xml</code> looks like this:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="app_name">My First App</string> + <string name="edit_message">Enter a message</string> + <string name="button_send">Send</string> +</resources> +</pre> + +<p>For more information about using string resources to localize your app for several languages, +see the <a +href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Various Devices</a> +class.</p> + + + + +<h2 id="Button">Add a Button</h2> + +<p>Now add a {@link android.widget.Button <Button>} to the layout, immediately following the +{@link android.widget.EditText <EditText>} element:</p> + +<pre> + <Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" /> +</pre> + +<p>The height and width are set to <code>"wrap_content"</code> so the button is only as big as +necessary to fit the button's text.</p> + + + +<h2 id="Weight">Make the Input Box Fill in the Screen Width</h2> + +<p>The layout is currently designed so that both the {@link android.widget.EditText} and {@link +android.widget.Button} widgets are only as big as necessary to fit their content, as shown in +figure 2.</p> + +<img src="{@docRoot}images/training/firstapp/edittext_wrap.png" /> +<p class="img-caption"><strong>Figure 2.</strong> The {@link android.widget.EditText} and {@link +android.widget.Button} widgets have their widths set to +<code>"wrap_content"</code>.</p> + +<p>This works fine for the button, but not as well for the text box, because the user might type +something longer and there's extra space left on the screen. So, it'd be nice to fill that width +using the text box. +{@link android.widget.LinearLayout} enables such a design with the <em>weight</em> property, which +you can specify using the <a +href="{@docRoot}reference/android/widget/LinearLayout.LayoutParams.html#weight">{@code +android:layout_weight}</a> attribute.</p> + +<p>The weight value allows you to specify the amount of remaining space each view should consume, +relative to the amount consumed by sibling views, just like the ingredients in a drink recipe: "2 +parts vodka, 1 part coffee liquer" means two-thirds of the drink is vodka. For example, if you give +one view a weight of 2 and another one a weight of 1, the sum is 3, so the first view gets 2/3 of +the remaining space and the second view gets the rest. If you give a third view a weight of 1, +then the first view now gets 1/2 the remaining space, while the remaining two each get 1/4.</p> + +<p>The default weight for all views is 0, so if you specify any weight value +greater than 0 to only one view, then that view fills whatever space remains after each view is +given the space it requires. So, to fill the remaining space with the {@link +android.widget.EditText} element, give it a weight of 1 and leave the button with no weight.</p> + +<pre> + <EditText + android:layout_weight="1" + ... /> +</pre> + +<p>In order to improve the layout efficiency when you specify the weight, you should change the +width of the {@link android.widget.EditText} to be +zero (0dp). Setting the width to zero improves layout performance because using +<code>"wrap_content"</code> as the width requires the system to calculate a width that is +ultimately irrelevant because the weight value requires another width calculation to fill the +remaining space.</p> +<pre> + <EditText + android:layout_weight="1" + android:layout_width="0dp" + ... /> +</pre> + +<p>Figure 3 +shows the result when you assign all weight to the {@link android.widget.EditText} element.</p> + +<img src="{@docRoot}images/training/firstapp/edittext_gravity.png" /> +<p class="img-caption"><strong>Figure 3.</strong> The {@link android.widget.EditText} widget is +given all the layout weight, so fills the remaining space in the {@link +android.widget.LinearLayout}.</p> + +<p>Here’s how your complete layout file should now look:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="horizontal"> + <EditText android:id="@+id/edit_message" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> + <Button android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" /> +</LinearLayout> +</pre> + +<p>This layout is applied by the default {@link android.app.Activity} class +that the SDK tools generated when you created the project, so you can now run the app to see the +results:</p> + +<ul> + <li>In Eclipse, click <strong>Run</strong> from the toolbar.</li> + <li>Or from a command line, change directories to the root of your Android project and +execute: +<pre> +ant debug +adb install bin/MyFirstApp-debug.apk +</pre></li> +</ul> + +<p>Continue to the next lesson to learn how you can respond to button presses, read content +from the text field, start another activity, and more.</p> + + + diff --git a/docs/html/training/basics/firstapp/creating-project.jd b/docs/html/training/basics/firstapp/creating-project.jd new file mode 100644 index 0000000..5a89f2e --- /dev/null +++ b/docs/html/training/basics/firstapp/creating-project.jd @@ -0,0 +1,142 @@ +page.title=Creating an Android Project +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +next.title=Running Your App +next.link=running-app.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#Eclipse">Create a Project with Eclipse</a></li> + <li><a href="#CommandLine">Create a Project with Command Line Tools</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}sdk/installing.html">Installing the +SDK</a></li> + <li><a href="{@docRoot}guide/developing/projects/index.html">Managing Projects</a></li> +</ul> + + +</div> +</div> + +<p>An Android project contains all the files that comprise the source code for your Android +app. The Android SDK tools make it easy to start a new Android project with a set of +default project directories and files.</p> + +<p>This lesson +shows how to create a new project either using Eclipse (with the ADT plugin) or using the +SDK tools from a command line.</p> + +<p class="note"><strong>Note:</strong> You should already have the Android SDK installed, and if +you're using Eclipse, you should have installed the <a +href="{@docRoot}sdk/eclipse-adt.html">ADT plugin</a> as well. If you have not installed +these, see <a href="{@docRoot}sdk/installing.html">Installing the Android SDK</a> and return here +when you've completed the installation.</p> + + +<h2 id="Eclipse">Create a Project with Eclipse</h2> + +<div class="figure" style="width:416px"> +<img src="{@docRoot}images/training/firstapp/adt-firstapp-setup.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The new project wizard in Eclipse.</p> +</div> + +<ol> + <li>In Eclipse, select <strong>File > New > Project</strong>. +The resulting dialog should have a folder labeled <em>Android</em>. (If you don’t see the +<em>Android</em> folder, +then you have not installed the ADT plugin—see <a +href="{@docRoot}sdk/eclipse-adt.html#installing">Installing the ADT Plugin</a>).</li> + <li>Open the <em>Android</em> folder, select <em>Android Project</em> and click +<strong>Next</strong>.</li> + <li>Enter a project name (such as "MyFirstApp") and click <strong>Next</strong>.</li> + <li>Select a build target. This is the platform version against which you will compile your app. +<p>We recommend that you select the latest version possible. You can still build your app to +support older versions, but setting the build target to the latest version allows you to +easily optimize your app for a great user experience on the latest Android-powered devices.</p> +<p>If you don't see any built targets listed, you need to install some using the Android SDK +Manager tool. See <a href="{@docRoot}sdk/installing.html#AddingComponents">step 4 in the +installing guide</a>.</p> +<p>Click <strong>Next</strong>.</p></li> + <li>Specify other app details, such as the: + <ul> + <li><em>Application Name</em>: The app name that appears to the user. Enter "My First +App".</li> + <li><em>Package Name</em>: The package namespace for your app (following the same +rules as packages in the Java programming language). Your package name +must be unique across all packages installed on the Android system. For this reason, it's important +that you use a standard domain-style package name that’s appropriate to your company or +publisher entity. For +your first app, you can use something like "com.example.myapp." However, you cannot publish your +app using the "com.example" namespace.</li> + <li><em>Create Activity</em>: This is the class name for the primary user activity in your +app (an activity represents a single screen in your app). Enter "MyFirstActivity".</li> + <li><em>Minimum SDK</em>: Select <em>4 (Android 1.6)</em>. + <p>Because this version is lower than the build target selected for the app, a warning +appears, but that's alright. You simply need to be sure that you don't use any APIs that require an +<a href="{@docRoot}guide/appendix/api-levels.html">API level</a> greater than the minimum SDK +version without first using some code to verify the device's system version (you'll see this in some +other classes).</p> + </li> + </ul> + <p>Click <strong>Finish</strong>.</p> + </li> +</ol> + +<p>Your Android project is now set up with some default files and you’re ready to begin +building the app. Continue to the <a href="running-app.html">next lesson</a>.</p> + + + +<h2 id="CommandLine">Create a Project with Command Line Tools</h2> + +<p>If you're not using the Eclipse IDE with the ADT plugin, you can instead create your project +using the SDK tools in a command line:</p> + +<ol> + <li>Change directories into the Android SDK’s <code>tools/</code> path.</li> + <li>Execute: +<pre class="no-pretty-print">android list targets</pre> +<p>This prints a list of the available Android platforms that you’ve downloaded for your SDK. Find +the platform against which you want to compile your app. Make a note of the target id. We +recommend that you select the highest version possible. You can still build your app to +support older versions, but setting the build target to the latest version allows you to optimize +your app for the latest devices.</p> +<p>If you don't see any targets listed, you need to +install some using the Android SDK +Manager tool. See <a href="{@docRoot}sdk/installing.html#AddingComponents">step 4 in the +installing guide</a>.</p></li> + <li>Execute: +<pre class="no-pretty-print"> +android create project --target <target-id> --name MyFirstApp \ +--path <path-to-workspace>/MyFirstApp --activity MyFirstActivity \ +--package com.example.myapp +</pre> +<p>Replace <code><target-id></code> with an id from the list of targets (from the previous step) +and replace +<code><path-to-workspace></code> with the location in which you want to save your Android +projects.</p></li> +</ol> + +<p>Your Android project is now set up with several default configurations and you’re ready to begin +building the app. Continue to the <a href="running-app.html">next lesson</a>.</p> + +<p class="note"><strong>Tip:</strong> Add the <code>platform-tools/</code> as well as the +<code>tools/</code> directory to your <code>PATH</code> environment variable.</p> + + + + diff --git a/docs/html/training/basics/firstapp/index.jd b/docs/html/training/basics/firstapp/index.jd new file mode 100644 index 0000000..a95ed8e --- /dev/null +++ b/docs/html/training/basics/firstapp/index.jd @@ -0,0 +1,64 @@ +page.title=Building Your First App + +trainingnavtop=true +startpage=true +next.title=Creating an Android Project +next.link=creating-project.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> + +<ul> + <li>Android 1.6 or higher</li> + <li><a href="http://developer.android.com/sdk/index.html">Android SDK</a></li> +</ul> + +</div> +</div> + +<p>Welcome to Android application development!</p> + +<p>This class teaches you how to build your first Android app. You’ll learn how to create an Android +project and run a debuggable version of the app. You'll also learn some fundamentals of Android app +design, including how to build a simple user interface and handle user input.</p> + +<p>Before you start this class, be sure that you have your development environment set up. You need +to:</p> +<ol> + <li>Download the Android SDK Starter Package.</li> + <li>Install the ADT plugin for Eclipse (if you’ll use the Eclipse IDE).</li> + <li>Download the latest SDK tools and platforms using the SDK Manager.</li> +</ol> + +<p>If you haven't already done this setup, read <a href="{@docRoot}sdk/installing.html">Installing +the SDK</a>. Once you've finished the setup, you're ready to begin this class.</p> + +<p>This class uses a tutorial format that incrementally builds a small Android app in order to teach +you some fundamental concepts about Android development, so it's important that you follow each +step.</p> + +<p><strong><a href="creating-project.html">Start the first lesson ›</a></strong></p> + + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="creating-project.html">Creating an Android Project</a></b></dt> + <dd>Shows how to create a project for an Android app, which includes a set of default +app files.</dd> + + <dt><b><a href="running-app.html">Running Your Application</a></b></dt> + <dd>Shows how to run your app on an Android-powered device or the Android +emulator.</dd> + + <dt><b><a href="building-ui.html">Building a Simple User Interface</a></b></dt> + <dd>Shows how to create a new user interface using an XML file.</dd> + + <dt><b><a href="starting-activity.html">Starting Another Activity</a></b></dt> + <dd>Shows how to respond to a button press, start another activity, send it some +data, then receive the data in the subsequent activity.</dd> +</dl> diff --git a/docs/html/training/basics/firstapp/running-app.jd b/docs/html/training/basics/firstapp/running-app.jd new file mode 100644 index 0000000..2398fa0 --- /dev/null +++ b/docs/html/training/basics/firstapp/running-app.jd @@ -0,0 +1,178 @@ +page.title=Running Your App +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Creating a Project +previous.link=creating-project.html +next.title=Building a Simple User Interface +next.link=building-ui.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#RealDevice">Run on a Real Device</a></li> + <li><a href="#Emulator">Run on the Emulator</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a></li> + <li><a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a></li> + <li><a href="{@docRoot}guide/developing/projects/index.html">Managing Projects</a></li> +</ul> + + +</div> +</div> + + +<p>If you followed the <a href="{@docRoot}creating-project.html">previous lesson</a> to create an +Android project, it includes a default set of "Hello World" source files that allow you to +run the app right away.</p> + +<p>How you run your app depends on two things: whether you have a real Android-powered device and +whether you’re using Eclipse. This lesson shows you how to install and run your app on a +real device and on the Android emulator, and in both cases with either Eclipse or the command line +tools.</p> + +<p>Before you run your app, you should be aware of a few directories and files in the Android +project:</p> + +<dl> + <dt><code>AndroidManifest.xml</code></dt> + <dd>This manifest file describes the fundamental characteristics of the app and defines each of +its components. You'll learn about various declarations in this file as you read more training +classes.</dd> + <dt><code>src/</code></dt> + <dd>Directory for your app's main source files. By default, it includes an {@link +android.app.Activity} class that runs when your app is launched using the app icon.</dd> + <dt><code>res/</code></dt> + <dd>Contains several sub-directories for app resources. Here are just a few: + <dl style="margin-top:1em"> + <dt><code>drawable-hdpi/</code></dt> + <dd>Directory for drawable objects (such as bitmaps) that are designed for high-density +(hdpi) screens. Other drawable directories contain assets designed for other screen densities.</dd> + <dt><code>layout/</code></dt> + <dd>Directory for files that define your app's user interface.</dd> + <dt><code>values/</code></dt> + <dd>Directory for other various XML files that contain a collection of resources, such as +string and color definitions.</dd> + </dl> + </dd> +</dl> + +<p>When you build and run the default Android project, the default {@link android.app.Activity} +class in the <code>src/</code> directory starts and loads a layout file from the +<code>layout/</code> directory, which includes a "Hello World" message. Not real exciting, but it's +important that you understand how to build and run your app before adding real functionality to +the app.</p> + + + +<h2 id="RealDevice">Run on a Real Device</h2> + +<p>Whether you’re using Eclipse or the command line, you need to:</p> + +<ol> + <li>Plug in your Android-powered device to your machine with a USB cable. +If you’re developing on Windows, you might need to install the appropriate USB driver for your +device. For help installing drivers, see the <a href=”{@docRoot}sdk/oem-usb.html”>OEM USB +Drivers</a> document.</li> + <li>Ensure that <strong>USB debugging</strong> is enabled in the device Settings (open Settings +and navitage to <strong>Applications > Development</strong> on most devices, or select +<strong>Developer options</strong> on Android 4.0 and higher).</li> +</ol> + +<p>To run the app from Eclipse, open one of your project's files and click +<strong>Run</strong> from the toolbar. Eclipse installs the app on your connected device and starts +it.</p> + + +<p>Or to run your app from a command line:</p> + +<ol> + <li>Change directories to the root of your Android project and execute: +<pre class="no-pretty-print">ant debug</pre></li> + <li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your +<code>PATH</code> environment variable, then execute: +<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li> + <li>On your device, locate <em>MyFirstActivity</em> and open it.</li> +</ol> + +<p>To start adding stuff to the app, continue to the <a href="building-ui.html">next +lesson</a>.</p> + + + +<h2 id="Emulator">Run on the Emulator</h2> + +<p>Whether you’re using Eclipse or the command line, you need to first create an <a +href="{@docRoot}guide/developing/devices/index.html">Android Virtual +Device</a> (AVD). An AVD is a +device configuration for the Android emulator that allows you to model +different device configurations.</p> + +<div class="figure" style="width:457px"> + <img src="{@docRoot}images/screens_support/avds-config.png" alt="" /> + <p class="img-caption"><strong>Figure 1.</strong> The AVD Manager showing a few virtual +devices.</p> +</div> + +<p>To create an AVD:</p> +<ol> + <li>Launch the Android Virtual Device Manager: + <ol type="a"> + <li>In Eclipse, select <strong>Window > AVD Manager</strong>, or click the <em>AVD +Manager</em> icon in the Eclipse toolbar.</li> + <li>From the command line, change directories to <code><sdk>/tools/</code> and execute: +<pre class="no-pretty-print">./android avd</pre></li> + </ol> + </li> + <li>In the <em>Android Virtual Device Device Manager</em> panel, click <strong>New</strong>.</li> + <li>Fill in the details for the AVD. +Give it a name, a platform target, an SD card size, and a skin (HVGA is default).</li> + <li>Click <strong>Create AVD</strong>.</li> + <li>Select the new AVD from the <em>Android Virtual Device Manager</em> and click +<strong>Start</strong>.</li> + <li>After the emulator boots up, unlock the emulator screen.</li> +</ol> + +<p>To run the app from Eclipse, open one of your project's files and click +<strong>Run</strong> from the toolbar. Eclipse installs the app on your AVD and starts it.</p> + + +<p>Or to run your app from the command line:</p> + +<ol> + <li>Change directories to the root of your Android project and execute: +<pre class="no-pretty-print">ant debug</pre></li> + <li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your +<code>PATH</code> environment +variable, then execute: +<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li> + <li>On the emulator, locate <em>MyFirstActivity</em> and open it.</li> +</ol> + + +<p>To start adding stuff to the app, continue to the <a href="building-ui.html">next +lesson</a>.</p> + + + + + + + + + + + diff --git a/docs/html/training/basics/firstapp/starting-activity.jd b/docs/html/training/basics/firstapp/starting-activity.jd new file mode 100644 index 0000000..16a6fd8 --- /dev/null +++ b/docs/html/training/basics/firstapp/starting-activity.jd @@ -0,0 +1,308 @@ +page.title=Starting Another Activity +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Building a Simpler User Interface +previous.link=building-ui.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> + +<ol> + <li><a href="#RespondToButton">Respond to the Send Button</a></li> + <li><a href="#BuildIntent">Build an Intent</a></li> + <li><a href="#StartActivity">Start the Second Activity</a></li> + <li><a href="#CreateActivity">Create the Second Activity</a> + <ol> + <li><a href="#AddToManifest">Add it to the manifest</a></li> + </ol> + </li> + <li><a href="#ReceiveIntent">Receive the Intent</a></li> + <li><a href="#DisplayMessage">Display the Message</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}sdk/installing.html">Installing the +SDK</a></li> +</ul> + + +</div> +</div> + + + +<p>After completing the <a href="building-ui.html">previous lesson</a>, you have an app that +shows an activity (a single screen) with a text box and a button. In this lesson, you’ll add some +code to <code>MyFirstActivity</code> that +starts a new activity when the user selects the Send button.</p> + + +<h2 id="RespondToButton">Respond to the Send Button</h2> + +<p>To respond to the button's on-click event, open the <code>main.xml</code> layout file and add the +<a +href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code android:onClick}</a> +attribute to the {@link android.widget.Button <Button>} element:</p> + +<pre> +<Button android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" /> +</pre> + +<p>The <a +href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code +android:onClick}</a> attribute’s value, <code>sendMessage</code>, is the name of a method in your +activity that you want to call when the user selects the button.</p> + +<p>Add the corresponding method inside the <code>MyFirstActivity</code> class:</p> + +<pre> +/** Called when the user selects the Send button */ +public void sendMessage(View view) { + // Do something in response to button +} +</pre> + +<p class="note"><strong>Tip:</strong> In Eclipse, press Ctrl + Shift + O to import missing classes +(Cmd + Shift + O on Mac).</p> + +<p>Note that, in order for the system to match this method to the method name given to <a +href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code android:onClick}</a>, +the signature must be exactly as shown. Specifically, the method must:</p> + +<ul> +<li>Be public</li> +<li>Have a void return value</li> +<li>Have a {@link android.view.View} as the only parameter (this will be the {@link +android.view.View} that was clicked)</li> +</ul> + +<p>Next, you’ll fill in this method to read the contents of the text box and deliver that text to +another activity.</p> + + + +<h2 id="BuildIntent">Build an Intent</h2> + +<p>An {@link android.content.Intent} is an object that provides runtime binding between separate +components (such as two activities). The {@link android.content.Intent} represents an +app’s "intent to do something." You can use an {@link android.content.Intent} for a wide +variety of tasks, but most often they’re used to start another activity.</p> + +<p>Inside the {@code sendMessage()} method, create an {@link android.content.Intent} to start +an activity called {@code DisplayMessageActvity}:</p> + +<pre> +Intent intent = new Intent(this, DisplayMessageActivity.class); +</pre> + +<p>The constructor used here takes two parameters:</p> +<ul> + <li>A {@link +android.content.Context} as its first parameter ({@code this} is used because the {@link +android.app.Activity} class is a subclass of {@link android.content.Context}) + <li>The {@link java.lang.Class} of the app component to which the system should deliver +the {@link android.content.Intent} (in this case, the activity that should be started) +</ul> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Sending an intent to other apps</h3> + <p>The intent created in this lesson is what's considered an <em>explicit intent</em>, because the +{@link android.content.Intent} +specifies the exact app component to which the intent should be given. However, intents +can also be <em>implicit</em>, in which case the {@link android.content.Intent} does not specify +the desired component, but allows any app installed on the device to respond to the intent +as long as it satisfies the meta-data specifications for the action that's specified in various +{@link android.content.Intent} parameters. For more informations, see the class about <a +href="{@docRoot}training/intents/index.html">Interacting with Other Apps</a>.</p> +</div> +</div> + +<p class="note"><strong>Note:</strong> The reference to {@code DisplayMessageActivity} +will raise an error if you’re using an IDE such as Eclipse because the class doesn’t exist yet. +Ignore the error for now; you’ll create the class soon.</p> + +<p>An intent not only allows you to start another activity, but can carry a bundle of data to the +activity as well. So, use {@link android.app.Activity#findViewById findViewById()} to get the +{@link android.widget.EditText} element and add its message to the intent:</p> + +<pre> +Intent intent = new Intent(this, DisplayMessageActivity.class); +EditText editText = (EditText) findViewById(R.id.edit_message); +String message = editText.getText().toString(); +intent.putExtra(EXTRA_MESSAGE, message); +</pre> + +<p>An {@link android.content.Intent} can carry a collection of various data types as key-value +pairs called <em>extras</em>. The {@link android.content.Intent#putExtra putExtra()} method takes a +string as the key and the value in the second parameter.</p> + +<p>In order for the next activity to query the extra data, you should define your keys using a +public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code +MyFirstActivity} class:</p> + +<pre> +public class MyFirstActivity extends Activity { + public final static String EXTRA_MESSAGE = "com.example.myapp.MESSAGE"; + ... +} +</pre> + +<p>It's generally a good practice to define keys for extras with your app's package name as a prefix +to ensure it's unique, in case your app interacts with other apps.</p> + + +<h2 id="StartActivity">Start the Second Activity</h2> + +<p>To start an activity, you simply need to call {@link android.app.Activity#startActivity +startActivity()} and pass it your {@link android.content.Intent}.</p> + +<p>The system receives this call and starts an instance of the {@link android.app.Activity} +specified by the {@link android.content.Intent}.</p> + +<p>With this method included, the complete {@code sendMessage()} method that's invoked by the Send +button now looks like this:</p> + +<pre> +/** Called when the user selects the Send button */ +public void sendMessage(View view) { + Intent intent = new Intent(this, DisplayMessageActivity.class); + EditText editText = (EditText) findViewById(R.id.edit_message); + String message = editText.getText().toString(); + intent.putExtra(EXTRA_MESSAGE, message); + startActivity(intent); +} +</pre> + +<p>Now you need to create the {@code DisplayMessageActivity} class in order for this to +work.</p> + + + +<h2 id="CreateActivity">Create the Second Activity</h2> + +<p>In your project, create a new class file under the <code>src/<package-name>/</code> +directory called <code>DisplayMessageActivity.java</code>.</p> + +<p class="note"><strong>Tip:</strong> In Eclipse, right-click the package name under the +<code>src/</code> directory and select <strong>New > Class</strong>. +Enter "DisplayMessageActivity" for the name and {@code android.app.Activity} for the superclass.</p> + +<p>Inside the class, add the {@link android.app.Activity#onCreate onCreate()} callback method:</p> + +<pre> +public class DisplayMessageActivity extends Activity { + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + } +} +</pre> + +<p>All subclasses of {@link android.app.Activity} must implement the {@link +android.app.Activity#onCreate onCreate()} method. The system calls this when creating a new +instance of the activity. It is where you must define the activity layout and where you should +initialize essential activity components.</p> + + + +<h3 id="AddToManifest">Add it to the manifest</h3> + +<p>You must declare all activities in your manifest file, <code>AndroidManifest.xml</code>, using an +<a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element.</p> + +<p>Because {@code DisplayMessageActivity} is invoked using an explicit intent, it does not require +any intent filters (such as those you can see in the manifest for <code>MyFirstActivity</code>). So +the declaration for <code>DisplayMessageActivity</code> can be simply one line of code inside the <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +element:</p> + +<pre> +<application ... > + <activity android:name="com.example.myapp.DisplayMessageActivity" /> + ... +</application> +</pre> + +<p>The app is now runnable because the {@link android.content.Intent} in the +first activity now resolves to the {@code DisplayMessageActivity} class. If you run the app now, +pressing the Send button starts the +second activity, but it doesn't show anything yet.</p> + + +<h2 id="ReceiveIntent">Receive the Intent</h2> + +<p>Every {@link android.app.Activity} is invoked by an {@link android.content.Intent}, regardless of +how the user navigated there. You can get the {@link android.content.Intent} that started your +activity by calling {@link android.app.Activity#getIntent()} and the retrieve data contained +within it.</p> + +<p>In the {@code DisplayMessageActivity} class’s {@link android.app.Activity#onCreate onCreate()} +method, get the intent and extract the message delivered by {@code MyFirstActivity}:</p> + +<pre> +Intent intent = getIntent(); +String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE); +</pre> + + + +<h2 id="DisplayMessage">Display the Message</h2> + +<p>To show the message on the screen, create a {@link android.widget.TextView} widget and set the +text using {@link android.widget.TextView#setText setText()}. Then add the {@link +android.widget.TextView} as the root view of the activity’s layout by passing it to {@link +android.app.Activity#setContentView setContentView()}.</p> + +<p>The complete {@link android.app.Activity#onCreate onCreate()} method for {@code +DisplayMessageActivity} now looks like this:</p> + +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + // Get the message from the intent + Intent intent = getIntent(); + String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE); + + // Create the text view + TextView textView = new TextView(this); + textView.setTextSize(40); + textView.setText(message); + + setContentView(textView); +} +</pre> + +<p>You can now run the app, type a message in the text box, press Send, and view the message on the +second activity.</p> + +<img src="{@docRoot}images/training/firstapp/firstapp.png" /> +<p class="img-caption"><strong>Figure 1.</strong> Both activities in the final app, running +on Android 4.0. + +<p>That's it, you've built your first Android app!</p> + +<p>To learn more about building Android apps, continue to follow the +basic training classes. The next class is <a +href="{@docRoot}training/activity-lifecycle/index.html">Managing the Activity Lifecycle</a>.</p> + + + + diff --git a/docs/html/training/basics/intents/filters.jd b/docs/html/training/basics/intents/filters.jd new file mode 100644 index 0000000..0090c98 --- /dev/null +++ b/docs/html/training/basics/intents/filters.jd @@ -0,0 +1,244 @@ +page.title=Allowing Other Apps to Start Your Activity +parent.title=Interacting with Other Apps +parent.link=index.html + +trainingnavtop=true +previous.title=Getting a Result from an Activity +previous.link=result.html + +@jd:body + +<div id="tb-wrapper"> + <div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#AddIntentFilter">Add an Intent Filter</a></li> + <li><a href="#HandleIntent">Handle the Intent in Your Activity</a></li> + <li><a href="#ReturnResult">Return a Result</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/sharing/index.html">Sharing Content</a></li> +</ul> + </div> +</div> + +<p>The previous two lessons focused on one side of the story: starting another app's activity from +your app. But if your app can perform an action that might be useful to another app, +your app should be prepared to respond to action requests from other apps. For instance, if you +build a social app that can share messages or photos with the user's friends, it's in your best +interest to support the {@link android.content.Intent#ACTION_SEND} intent so users can initiate a +"share" action from another app and launch your app to perform the action.</p> + +<p>To allow other apps to start your activity, you need to add an <a +href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a> +element in your manifest file for the corresponding <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element.</p> + +<p>When your app is installed on a device, the system identifies your intent +filters and adds the information to an internal catalog of intents supported by all installed apps. +When an app calls {@link android.app.Activity#startActivity +startActivity()} or {@link android.app.Activity#startActivityForResult startActivityForResult()}, +with an implicit intent, the system finds which activity (or activities) can respond to the +intent.</p> + + + +<h2 id="AddIntentFilter">Add an Intent Filter</h2> + +<p>In order to properly define which intents your activity can handle, each intent filter you add +should be as specific as possible in terms of the type of action and data the activity +accepts.</p> + +<p>The system may send a given {@link android.content.Intent} to an activity if that activity has +an intent filter fulfills the following criteria of the {@link android.content.Intent} object:</p> + +<dl> + <dt>Action</dt> + <dd>A string naming the action to perform. Usually one of the platform-defined values such +as {@link android.content.Intent#ACTION_SEND} or {@link android.content.Intent#ACTION_VIEW}. + <p>Specify this in your intent filter with the <a +href="{@docRoot}guide/topics/manifest/action-element.html">{@code <action>}</a> element. +The value you specify in this element must be the full string name for the action, instead of the +API constant (see the examples below).</p></dd> + + <dt>Data</dt> + <dd>A description of the data associated with the intent. + <p>Specify this in your intent filter with the <a +href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> element. Using one +or more attributes in this element, you can specify just the MIME type, just a URI prefix, +just a URI scheme, or a combination of these and others that indicate the data type +accepted.</p> + <p class="note"><strong>Note:</strong> If you don't need to declare specifics about the data +{@link android.net.Uri} (such as when your activity handles to other kind of "extra" data, instead +of a URI), you should specify only the {@code android:mimeType} attribute to declare the type of +data your activity handles, such as {@code text/plain} or {@code image/jpeg}.</p> +</dd> + <dt>Category</dt> + <dd>Provides an additional way to characterize the activity handling the intent, usually related +to the user gesture or location from which it's started. There are several different categories +supported by the system, but most are rarely used. However, all implicit intents are defined with +{@link android.content.Intent#CATEGORY_DEFAULT} by default. + <p>Specify this in your intent filter with the <a +href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a> +element.</p></dd> +</dl> + +<p>In your intent filter, you can declare which criteria your activity accepts +by declaring each of them with corresponding XML elements nested in the <a +href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a> +element.</p> + +<p>For example, here's an activity with an intent filter that handles the {@link +android.content.Intent#ACTION_SEND} intent when the data type is either text or an image:</p> + +<pre> +<activity android:name="ShareActivity"> + <intent-filter> + <action android:name="android.intent.action.SEND"/> + <category android:name="android.intent.category.DEFAULT"/> + <data android:mimeType="text/plain"/> + <data android:mimeType="image/*"/> + </intent-filter> +</activity> +</pre> + +<p>Each incoming intent specifies only one action and one data type, but it's OK to declare multiple +instances of the <a href="{@docRoot}guide/topics/manifest/action-element.html">{@code +<action>}</a>, <a href="{@docRoot}guide/topics/manifest/category-element.html">{@code +<category>}</a>, and <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code +<data>}</a> elements in each +<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a>.</p> + +<p>If any two pairs of action and data are mutually exclusive in +their behaviors, you should create separate intent filters to specify which actions are acceptable +when paired with which data types.</p> + +<p>For example, suppose your activity handles both text and images for both the {@link +android.content.Intent#ACTION_SEND} and {@link +android.content.Intent#ACTION_SENDTO} intents. In this case, you must define two separate +intent filters for the two actions because a {@link +android.content.Intent#ACTION_SENDTO} intent must use the data {@link android.net.Uri} to specify +the recipient's address using the {@code send} or {@code sendto} URI scheme. For example:</p> + +<pre> +<activity android:name="ShareActivity"> + <!-- filter for sending text; accepts SENDTO action with sms URI schemes --> + <intent-filter> + <action android:name="android.intent.action.SENDTO"/> + <category android:name="android.intent.category.DEFAULT"/> + <data android:scheme="sms" /> + <data android:scheme="smsto" /> + </intent-filter> + <!-- filter for sending text or images; accepts SEND action and text or image data --> + <intent-filter> + <action android:name="android.intent.action.SEND"/> + <category android:name="android.intent.category.DEFAULT"/> + <data android:mimeType="image/*"/> + <data android:mimeType="text/plain"/> + </intent-filter> +</activity> +</pre> + +<p class="note"><strong>Note:</strong> In order to receive implicit intents, you must include the +{@link android.content.Intent#CATEGORY_DEFAULT} category in the intent filter. The methods {@link +android.app.Activity#startActivity startActivity()} and {@link +android.app.Activity#startActivityForResult startActivityForResult()} treat all intents as if they +contained the {@link android.content.Intent#CATEGORY_DEFAULT} category. If you do not declare it, no +implicit intents will resolve to your activity.</p> + +<p>For more information about sending and receiving {@link android.content.Intent#ACTION_SEND} +intents that perform social sharing behaviors, see the lesson about <a +href="{@docRoot}training/sharing/receive.html">Receiving Content from Other Apps</a>.</p> + + +<h2 id="HandleIntent">Handle the Intent in Your Activity</h2> + +<p>In order to decide what action to take in your activity, you can read the {@link +android.content.Intent} that was used to start it.</p> + +<p>As your activity starts, call {@link android.app.Activity#getIntent()} to retrieve the +{@link android.content.Intent} that started the activity. You can do so at any time during the +lifecycle of the activity, but you should generally do so during early callbacks such as +{@link android.app.Activity#onCreate onCreate()} or {@link android.app.Activity#onStart()}.</p> + +<p>For example:</p> + +<pre> +@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + setContentView(R.layout.main); + + // Get the intent that started this activity + Intent intent = getIntent(); + Uri data = intent.getData(); + + // Figure out what to do based on the intent type + if (intent.getType().indexOf("image/") != -1) { + // Handle intents with image data ... + } else if (intent.getType().equals("text/plain")) { + // Handle intents with text ... + } +} +</pre> + + +<h2 id="ReturnResult">Return a Result</h2> + +<p>If you want to return a result to the activity that invoked yours, simply call {@link +android.app.Activity#setResult(int,Intent) setResult()} to specify the result code and result {@link +android.content.Intent}. When your operation is done and the user should return to the original +activity, call {@link android.app.Activity#finish()} to close (and destroy) your activity. For +example:</p> + +<pre> +// Create intent to deliver some kind of result data +Intent result = new Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri"); +setResult(Activity.RESULT_OK, result); +finish(); +</pre> + +<p>You must always specify a result code with the result. Generally, it's either {@link +android.app.Activity#RESULT_OK} or {@link android.app.Activity#RESULT_CANCELED}. You can then +provide additional data with an {@link android.content.Intent}, as necessary.</p> + +<p class="note"><strong>Note:</strong> The result is set to {@link +android.app.Activity#RESULT_CANCELED} by default. So, if the user presses the <em>Back</em> +button before completing the action and before you set the result, the original activity receives +the "canceled" result.</p> + +<p>If you simply need to return an integer that indicates one of several result options, you can set +the result code to any value higher than 0. If you use the result code to deliver an integer and you +have no need to include the {@link android.content.Intent}, you can call {@link +android.app.Activity#setResult(int) setResult()} and pass only a result code. For example:</p> + +<pre> +setResult(RESULT_COLOR_RED); +finish(); +</pre> + +<p>In this case, there might be only a handful of possible results, so the result code is a locally +defined integer (greater than 0). This works well when you're returning a result to an activity +in your own app, because the activity that receives the result can reference the public +constant to determine the value of the result code.</p> + +<p class="note"><strong>Note:</strong> There's no need to check whether your activity was started +with {@link +android.app.Activity#startActivity startActivity()} or {@link +android.app.Activity#startActivityForResult startActivityForResult()}. Simply call {@link +android.app.Activity#setResult(int,Intent) setResult()} if the intent that started your activity +might expect a result. If the originating activity had called {@link +android.app.Activity#startActivityForResult startActivityForResult()}, then the system delivers it +the result you supply to {@link android.app.Activity#setResult(int,Intent) setResult()}; otherwise, +the result is ignored.</p> + + + + + + diff --git a/docs/html/training/basics/intents/index.jd b/docs/html/training/basics/intents/index.jd new file mode 100644 index 0000000..c661d98 --- /dev/null +++ b/docs/html/training/basics/intents/index.jd @@ -0,0 +1,64 @@ +page.title=Interacting with Other Apps + +trainingnavtop=true +startpage=true +next.title=Sending the User to Another App +next.link=sending.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Basic understanding of the Activity lifecycle (see <a +href="{@docRoot}training/basics/activity-lifecycle/index.html">Managing the Activity +Lifecycle</a>)</li> +</ul> + + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/sharing/index.html">Sharing Content</a></li> + <li><a +href="http://android-developers.blogspot.com/2009/11/integrating-application-with-intents.html"> +Integrating Application with Intents (blog post)</a></li> + <li><a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent +Filters</a></li> +</ul> + +</div> +</div> + +<p>An Android app typically has several <a +href="{@docRoot}guide/topics/fundamentals/activities.html">activities</a>. Each activity displays a +user interface that allows the user to perform a specific task (such as view a map or take a photo). +To take the user from one activity to another, your app must use an {@link +android.content.Intent} to define your app's "intent" to do something. When you pass an +{@link android.content.Intent} to the system with a method such as {@link +android.app.Activity#startActivity startActivity()}, the system uses the {@link +android.content.Intent} to identify and start the appropriate app component. Using intents even +allows your app to start an activity that is contained in a separate app.</p> + +<p>An {@link android.content.Intent} can be <em>explicit</em> in order to start a specific component +(a specific {@link android.app.Activity} instance) or <em>implicit</em> in order to start any +component that can handle the intended action (such as "capture a photo").</p> + +<p>This class shows you how to use an {@link android.content.Intent} to perform some basic +interactions with other apps, such as start another app, receive a result from that app, and +make your app able to respond to intents from other apps.</p> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="sending.html">Sending the User to Another App</a></b></dt> + <dd>Shows how you can create implicit intents to launch other apps that can perform an +action.</dd> + <dt><b><a href="result.html">Getting a Result from an Activity</a></b></dt> + <dd>Shows how to start another activity and receive a result from the activity.</dd> + <dt><b><a href="filters.html">Allowing Other Apps to Start Your Activity</a></b></dt> + <dd>Shows how to make activities in your app open for use by other apps by defining +intent filters that declare the implicit intents your app accepts.</dd> +</dl> + diff --git a/docs/html/training/basics/intents/result.jd b/docs/html/training/basics/intents/result.jd new file mode 100644 index 0000000..0086913 --- /dev/null +++ b/docs/html/training/basics/intents/result.jd @@ -0,0 +1,182 @@ +page.title=Getting a Result from an Activity +parent.title=Interacting with Other Apps +parent.link=index.html + +trainingnavtop=true +previous.title=Sending the User to Another App +previous.link=sending.html +next.title=Allowing Other Apps to Start Your Activity +next.link=filters.html + +@jd:body + +<div id="tb-wrapper"> + <div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#StartActivity">Start the Activity</a></li> + <li><a href="#ReceiveResult">Receive the Result</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/sharing/index.html">Sharing Content</a></li> +</ul> + + </div> +</div> + +<p>Starting another activity doesn't have to be one-way. You can also start another activity and +receive a result back. To receive a result, call {@link android.app.Activity#startActivityForResult +startActivityForResult()} (instead of {@link android.app.Activity#startActivity +startActivity()}).</p> + +<p>For example, your app can start a camera app and receive the captured photo as a result. Or, you +might start the People app in order for the user to select a +contact and you'll receive the contact details as a result.</p> + +<p>Of course, the activity that responds must be designed to return a result. When it does, it +sends the result as another {@link android.content.Intent} object. Your activity receives it in +the {@link android.app.Activity#onActivityResult onActivityResult()} callback.</p> + +<p class="note"><strong>Note:</strong> You can use explicit or implicit intents when you call +{@link android.app.Activity#startActivityForResult startActivityForResult()}. When starting one of +your own activities to receive a result, you should use an explicit intent to ensure that you +receive the expected result.</p> + + +<h2 id="StartActivity">Start the Activity</h2> + +<p>There's nothing special about the {@link android.content.Intent} object you use when starting +an activity for a result, but you do need to pass an additional integer argument to the {@link +android.app.Activity#startActivityForResult startActivityForResult()} method.</p> + +<p>The integer argument is a "request code" that identifies your request. When you receive the +result {@link android.content.Intent}, the callback provides the same request code so that your +app can properly identify the result and determine how to handle it.</p> + +<p>For example, here's how to start an activity that allows the user to pick a contact:</p> + +<pre> +static final int PICK_CONTACT_REQUEST = 1; // The request code +... +private void pickContact() { + Intent pickContactIntent = new Intent(Intent.ACTION_PICK, new Uri("content://contacts")); + pickContactIntent.setType(Phone.CONTENT_TYPE); // Show user only contacts w/ phone numbers + startActivityForResult(pickContactIntent, PICK_CONTACT_REQUEST); +} +</pre> + + +<h2 id="ReceiveResult">Receive the Result</h2> + +<p>When the user is done with the subsequent activity and returns, the system calls your activity's +{@link android.app.Activity#onActivityResult onActivityResult()} method. This method includes three +arguments:</p> + +<ul> + <li>The request code you passed to {@link +android.app.Activity#startActivityForResult startActivityForResult()}.</li> + <li>A result code specified by the second activity. This is either {@link +android.app.Activity#RESULT_OK} if the operation was successful or {@link +android.app.Activity#RESULT_CANCELED} if the user backed out or the operation failed for some +reason.</li> + <li>An {@link android.content.Intent} that carries the result data.</li> +</ul> + +<p>For example, here's how you can handle the result for the "pick a contact" intent:</p> + +<pre> +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + // Check which request we're responding to + if (requestCode == PICK_CONTACT_REQUEST) { + // Make sure the request was successful + if (resultCode == RESULT_OK) { + // The user picked a contact. + // The Intent's data Uri identifies which contact was selected. + + // Do something with the contact here (bigger example below) + } + } +} +</pre> + +<p>In this example, the result {@link android.content.Intent} returned by +Android's Contacts or People app provides a content {@link android.net.Uri} that identifies the +contact the user selected.</p> + +<p>In order to successfully handle the result, you must understand what the format of the result +{@link android.content.Intent} will be. Doing so is easy when the activity returning a result is +one of your own activities. Apps included with the Android platform offer their own APIs that +you can count on for specific result data. For instance, the People app (Contacts app on some older +versions) always returns a result with the content URI that identifies the selected contact, and the +Camera app returns a {@link android.graphics.Bitmap} in the {@code "data"} extra (see the class +about <a href="{@docRoot}training/camera/index.html">Capturing Photos</a>).</p> + + +<h4>Bonus: Read the contact data</h4> + +<p>The code above showing how to get a result from the People app doesn't go into +details about how to actually read the data from the result, because it requires more advanced +discussion about <a href="{@docRoot}guide/topics/providers/content-providers.html">content +providers</a>. However, if you're curious, here's some more code that shows how to query the +result data to get the phone number from the selected contact:</p> + +<pre> +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + // Check which request it is that we're responding to + if (requestCode == PICK_CONTACT_REQUEST) { + // Make sure the request was successful + if (resultCode == RESULT_OK) { + // Get the URI that points to the selected contact + Uri contactUri = data.getData(); + // We only need the NUMBER column, because there will be only one row in the result + String[] projection = {Phone.NUMBER}; + + // Perform the query on the contact to get the NUMBER column + // We don't need a selection or sort order (there's only one result for the given URI) + // CAUTION: The query() method should be called from a separate thread to avoid blocking + // your app's UI thread. (For simplicity of the sample, this code doesn't do that.) + // Consider using {@link android.content.CursorLoader} to perform the query. + Cursor cursor = getContentResolver() + .query(contactUri, projection, null, null, null); + cursor.moveToFirst(); + + // Retrieve the phone number from the NUMBER column + int column = cursor.getColumnIndex(Phone.NUMBER); + String number = cursor.getString(column); + + // Do something with the phone number... + } + } +} +</pre> + +<p class="note"><strong>Note:</strong> Before Android 2.3 (API level 9), performing a query +on the {@link android.provider.ContactsContract.Contacts Contacts Provider} (like the one shown +above) requires that your app declare the {@link +android.Manifest.permission#READ_CONTACTS} permission (see <a +href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>). However, +beginning with Android 2.3, the Contacts/People app grants your app a temporary +permission to read from the Contacts Provider when it returns you a result. The temporary permission +applies only to the specific contact requested, so you cannot query a contact other than the one +specified by the intent's {@link android.net.Uri}, unless you do declare the {@link +android.Manifest.permission#READ_CONTACTS} permission.</p> + + + + + + + + + + + + + + + diff --git a/docs/html/training/basics/intents/sending.jd b/docs/html/training/basics/intents/sending.jd new file mode 100644 index 0000000..a71c8f9 --- /dev/null +++ b/docs/html/training/basics/intents/sending.jd @@ -0,0 +1,211 @@ +page.title=Sending the User to Another App +parent.title=Interacting with Other Apps +parent.link=index.html + +trainingnavtop=true +next.title=Getting a Result from an Activity +next.link=result.html + +@jd:body + + +<div id="tb-wrapper"> + <div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#Build">Build an Implicit Intent</a></li> + <li><a href="#Verify">Verify There is an App to Receive the Intent</a></li> + <li><a href="#StartActivity">Start an Activity with the Intent</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/sharing/index.html">Sharing Content</a></li> +</ul> + + </div> +</div> + +<p>One of Android's most important features is an app's ability to send the user to another app +based on an "action" it would like to perform. For example, if +your app has the address of a business that you'd like to show on a map, you don't have to build +an activity in your app that shows a map. Instead, you can send a out a request to view the address +using an {@link android.content.Intent}. The Android system then starts an app that's able to view +the address on a map.</p> + +<p>As shown in the first class, <a href="{@docRoot}training/basics/firstapp/index.html">Building +Your First App</a>, you must use intents to navigate between activities in your own app. You +generally do so with an <em>explicit intent</em>, which defines the exact class name of the +component you want to start. However, when you want to have a separate app perform an action, such +as "view a map," you must use an <em>implicit intent</em>.</p> + +<p>This lesson shows you how to create an implicit intent for a particular action, and how to use it +to start an activity that performs the action in another app.</p> + + + +<h2 id="Build">Build an Implicit Intent</h2> + +<p>Implicit intents do not declare the class name of the component to start, but instead declare an +action to perform. The action specifies the thing you want to do, such as <em>view</em>, +<em>edit</em>, <em>send</em>, or <em>get</em> something. Intents often also include data associated +with the action, such as the address you want to view, or the email message you want to send. +Depending on the intent you want to create, the data might be a {@link android.net.Uri}, +one of several other data types, or the intent might not need data at all.</p> + +<p>If your data is a {@link android.net.Uri}, there's a simple {@link +android.content.Intent#Intent(String,Uri) Intent()} constructor you can use define the action and +data.</p> + +<p>For example, here's how to create an intent to initiate a phone call using the {@link +android.net.Uri} data to specify the telephone number:</p> + +<pre> +Uri number = Uri.parse("tel:5551234"); +Intent callIntent = new Intent(Intent.ACTION_DIAL, number); +</pre> + +<p>When your app invokes this intent by calling {@link android.app.Activity#startActivity +startActivity()}, the Phone app initiates a call to the given phone number.</p> + +<p>Here are a couple other intents and their action and {@link android.net.Uri} data +pairs:</p> + +<ul> + <li>View a map: +<pre> +// Map point based on address +Uri location = Uri.parse("geo:0,0?q=1600+Amphitheatre+Parkway,+Mountain+View,+California"); +// Or map point based on latitude/longitude +// Uri location = Uri.parse("geo:37.422219,-122.08364?z=14"); // z param is zoom level +Intent mapIntent = new Intent(Intent.ACTION_VIEW, location); +</pre> + </li> + <li>View a web page: +<pre> +Uri webpage = Uri.parse("http://www.android.com"); +Intent webIntent = new Intent(Intent.ACTION_VIEW, webpage); +</pre> + </li> +</ul> + +<p>Other kinds of implicit intents require "extra" data that provide different data types, +such as a string. You can add one or more pieces of extra data using the various {@link +android.content.Intent#putExtra(String,String) putExtra()} methods.</p> + +<p>By default, the system determines the appropriate MIME type required by an intent based on the +{@link android.net.Uri} data that's included. If you don't include a {@link android.net.Uri} in the +intent, you should usually use {@link android.content.Intent#setType setType()} to specify the type +of data associated with the intent. Setting the MIME type further specifies which kinds of +activities should receive the intent.</p> + +<p>Here are some more intents that add extra data to specify the desired action:</p> + +<ul> + <li>Send an email with an attachment: +<pre> +Intent emailIntent = new Intent(Intent.ACTION_SEND); +// The intent does not have a URI, so declare the "text/plain" MIME type +emailIntent.setType(HTTP.PLAIN_TEXT_TYPE); +emailIntent.putExtra(Intent.EXTRA_EMAIL, new String[] {"jon@example.com"}); // recipients +emailIntent.putExtra(Intent.EXTRA_SUBJECT, "Email subject"); +emailIntent.putExtra(Intent.EXTRA_TEXT, "Email message text"); +emailIntent.putExtra(Intent.EXTRA_STREAM, Uri.parse("content://path/to/email/attachment"); +// You can also attach multiple items by passing an ArrayList of Uris +</pre> + </li> + <li>Create a calendar event: +<pre> +Intent calendarIntent = new Intent(Intent.ACTION_INSERT, Events.CONTENT_URI); +Calendar beginTime = Calendar.getInstance().set(2012, 0, 19, 7, 30); +Calendar endTime = Calendar.getInstance().set(2012, 0, 19, 10, 30); +calendarIntent.putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, beginTime.getTimeInMillis()); +calendarIntent.putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endTime.getTimeInMillis()); +calendarIntent.putExtra(Events.TITLE, "Ninja class"); +calendarIntent.putExtra(Events.EVENT_LOCATION, "Secret dojo"); +</pre> +<p class="note"><strong>Note:</strong> This intent for a calendar event is supported only with API +level 14 and higher.</p> + </li> +</ul> + +<p class="note"><strong>Note:</strong> It's important that you define your {@link +android.content.Intent} to be as specific as possible. For example, if you want to display an image +using the {@link android.content.Intent#ACTION_VIEW} intent, you should specify a MIME type of +{@code image/*}. This prevents apps that can "view" other types of data (like a map app) from being +triggered by the intent.</p> + + + +<h2 id="Verify">Verify There is an App to Receive the Intent</h2> + +<p>Although the Android platform guarantees that certain intents will resolve to one of the +built-in apps (such as the Phone, Email, or Calendar app), you should always include a +verification step before invoking an intent.</p> + +<p class="caution"><strong>Caution:</strong> If you invoke an intent and there is no app +available on the device that can handle the intent, your app will crash.</p> + +<p>To verify there is an activity available that can respond to the intent, call {@link +android.content.pm.PackageManager#queryIntentActivities queryIntentActivities()} to get a list +of activities capable of handling your {@link android.content.Intent}. If the returned {@link +java.util.List} is not empty, you can safely use the intent. For example:</p> + +<pre> +PackageManager packageManager = {@link android.content.Context#getPackageManager()}; +List<ResolveInfo> activities = packageManager.queryIntentActivities(intent, 0); +boolean isIntentSafe = activities.size() > 0; +</pre> + +<p>If <code>isIntentSafe</code> is <code>true</code>, then at least one app will respond to +the intent. If it is <code>false</code>, then there aren't any apps to handle the intent.</p> + +<p class="note"><strong>Note:</strong> You should perform this check when your activity first +starts in case you need to disable the feature that uses the intent before the user attempts to use +it. If you know of a specific app that can handle the intent, you can also provide a link for the +user to download the app (see how to <a +href="{@docRoot}guide/publishing/publishing.html#marketintent">link to an app on Google +Play</a>).</p> + + +<h2 id="StartActivity">Start an Activity with the Intent</h2> + +<div class="figure" style="width:200px"> + <img src="{@docRoot}images/training/basics/intents-choice.png" alt="" /> + <p class="img-caption"><strong>Figure 1.</strong> Example of the selection dialog that appears +when more than one app can handle an intent.</p> +</div> + +<p>Once you have created your {@link android.content.Intent} and set the extra info, call {@link +android.app.Activity#startActivity startActivity()} to send it to the system. If the system +identifies more than one activity that can handle the intent, it displays a dialog for the user to +select which app to use, as shown in figure 1. If there is only one activity that handles the +intent, the system immediately starts it.</p> + +<pre> +startActivity(intent); +</pre> + +<p>Here's a complete example that shows how to create an intent to view a map, verify that an +app exists to handle the intent, then start it:</p> + +<pre> +// Build the intent +Uri location = Uri.parse("geo:0,0?q=1600+Amphitheatre+Parkway,+Mountain+View,+California"); +Intent mapIntent = new Intent(Intent.ACTION_VIEW, location); + +// Verify it resolves +PackageManager packageManager = {@link android.content.Context#getPackageManager()}; +List<ResolveInfo> activities = packageManager.queryIntentActivities(mapIntent, 0); +boolean isIntentSafe = activities.size() > 0; + +// Start an activity if it's safe +if (isIntentSafe) { + startActivity(mapIntent); +} +</pre> + + + + diff --git a/docs/html/training/basics/supporting-devices/index.jd b/docs/html/training/basics/supporting-devices/index.jd new file mode 100644 index 0000000..49ea81d --- /dev/null +++ b/docs/html/training/basics/supporting-devices/index.jd @@ -0,0 +1,49 @@ +page.title=Supporting Different Devices + +trainingnavtop=true +startpage=true +next.title=Supporting Multiple Languages +next.link=languages.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 1.6 or higher</li> +</ul> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a></li> + <li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a></li> +</ul> + + +</div> +</div> + +<p>Android devices come in many shapes and sizes all around the world. With a wide range of device +types, you have an opportunity to reach a huge audience with your app. In order to be as successful +as possible on Android, your app needs to adapt to various device configurations. Some of the +important variations that you should consider include different languages, screen sizes, and +versions of the Android platform.</p> + +<p>This class teaches you how to use basic platform features that leverage alternative +resources and other features so your app can provide an optimized user experience on a +variety of Android-compatible devices, using a single application package (APK).</p> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="languages.html">Supporting Different Languages</a></b></dt> + <dd>Learn how to support multiple languages with alternative string resources.</dd> + <dt><b><a href="screens.html">Supporting Different Screens</a></b></dt> + <dd>Learn how to optimize the user experience for different screen sizes and densities.</dd> + <dt><b><a href="platforms.html">Supporting Different Platform Versions</a></b></dt> + <dd>Learn how to use APIs available in new versions of Android while continuing to support +older versions of Android.</dd> +</dl> + diff --git a/docs/html/training/basics/supporting-devices/languages.jd b/docs/html/training/basics/supporting-devices/languages.jd new file mode 100644 index 0000000..fcc95c2 --- /dev/null +++ b/docs/html/training/basics/supporting-devices/languages.jd @@ -0,0 +1,134 @@ +page.title=Supporting Different Languages +parent.title=Supporting Different Devices +parent.link=index.html + +trainingnavtop=true +next.title=Supporting Different Screens +next.link=screens.html + +@jd:body + + +<div id="tb-wrapper"> + <div id="tb"> + <h2>This class teaches you to</h2> + <ol> + <li><a href="#CreateDirs">Create Locale Directories and String Files</a></li> + <li><a href="#UseString">Use the String Resources</a></li> + </ol> + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/topics/resources/localization.html">Localization</a></li> + </ul> + </div> +</div> + +<p>It’s always a good practice to extract UI strings from your app code and keep them +in an external file. Android makes this easy with a resources directory in each Android +project.</p> + +<p>If you created your project using the Android SDK +Tools (read <a href="{@docRoot}training/basics/firstapp/creating-project.html">Creating an +Android Project</a>), the tools create a <code>res/</code> directory in the top level of +the project. Within this <code>res/</code> directory are subdirectories for various resource +types. There are also a few default files such as <code>res/values/strings.xml</code>, which holds +your string values.</p> + + +<h2 id="CreateDirs">Create Locale Directories and String Files</h2> + +<p>To add support for more languages, create additional <code>values</code> directories inside +<code>res/</code> that include a hyphen and the ISO country code at the end of the +directory name. For example, <code>values-es/</code> is the directory containing simple +resourcess for the Locales with the language code "es". Android loads the appropriate resources +according to the locale settings of the device at run time.</p> + +<p>Once you’ve decided on the languages you will support, create the resource subdirectories and +string resource files. For example:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + values/ + strings.xml + values-es/ + strings.xml + values-fr/ + strings.xml +</pre> + +<p>Add the string values for each locale into the appropriate file.</p> + +<p>At runtime, the Android system uses the appropriate set of string resources based on the +locale currently set for the user's device.</p> + +<p>For example, the following are some different string resource files for different languages.</p> + + +<p>English (default locale), <code>/values/strings.xml</code>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="title">My Application</string> + <string name="hello_world">Hello World!</string> +</resources> +</pre> + + +<p>Spanish, <code>/values-es/strings.xml</code>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="title">Mi Aplicación</string> + <string name="hello_world">Hola Mundo!</string> +</resources> +</pre> + + +<p>French, <code>/values-fr/strings.xml</code>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="title">Ma Application</string> + <string name="hello_world">Bonjour tout le Monde!</string> +</resources> +</pre> + + +<h2 id="UseString">Use the String Resources</h2> + +<p>You can reference your string resources in your source code and other XML files using the +resource name defined by the {@code <string>} element's {@code name} attribute.</p> + +<p>In your source code, you can refer to a string resource with the syntax {@code +R.string.<string_name>}. There are a variety of methods that accept a string resource this +way.</p> + +<p>For example:</p> + +<pre> +// Get a string resource from your app's {@link android.content.res.Resources} +String hello = {@link android.content.Context#getResources()}.getString(R.string.hello_world); + +// Or supply a string resource to a method that requires a string +TextView textView = new TextView(this); +textView.setText(R.string.hello_world); +</pre> + +<p>In other XML files, you can refer to a string resource with the syntax {@code +@string/<string_name>} whenever the XML attribute accepts a string value.</p> + +<p>For example:</p> + +<pre> +<TextView + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/hello_world" /> +</pre> + + + diff --git a/docs/html/training/basics/supporting-devices/platforms.jd b/docs/html/training/basics/supporting-devices/platforms.jd new file mode 100644 index 0000000..0d4e7d9 --- /dev/null +++ b/docs/html/training/basics/supporting-devices/platforms.jd @@ -0,0 +1,138 @@ +page.title=Supporting Different Platform Versions +parent.title=Supporting Different Devices +parent.link=index.html + +trainingnavtop=true +previous.title=Supporting Different Screens +previous.link=screens.html + +@jd:body + + +<div id="tb-wrapper"> + <div id="tb"> + + <h2>This lesson teaches you to</h2> + <ol> + <li><a href="#sdk-versions">Specify Minimum and Target API Levels</a></li> + <li><a href="#version-codes">Check System Version at Runtime</a></li> + <li><a href="#style-themes">Use Platform Styles and Themes</a></li> + </ol> + + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a></li> + <li><a +href="{@docRoot}sdk/compatibility-library.html">Android Support Library</a></li> + </ul> + </div> +</div> + +<p>While the latest versions of Android often provide great APIs for your app, you should continue +to support older versions of Android until more devices get updated. This +lesson shows you how to take advantage of the latest APIs while continuing to support older +versions as well.</p> + +<p>The dashboard for <a +href="http://developer.android.com/resources/dashboard/platform-versions.html">Platform Versions</a> +is updated regularly to show the distribution of active +devices running each version of Android, based on the number of devices that visit the Google Play +Store. Generally, it’s a good practice to support about 90% of the active devices, while +targeting your app to the latest version.</p> + +<p class="note"><strong>Tip:</strong> In order to provide the best features and +functionality across several Android versions, you should use the <a +href="{@docRoot}sdk/compatibility-library.html">Android Support Library</a> in your app, +which allows you to use several recent platform APIs on older versions.</p> + + + +<h2 id="sdk-versions">Specify Minimum and Target API Levels</h2> + +<p>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file +describes details about your app and +identifies which versions of Android it supports. Specifically, the <code>minSdkVersion</code> +and <code>targetSdkVersion</code> attributes for the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk}</a> element +identify the lowest API level with which your app is compatible and the highest API level against +which you’ve designed and tested your app.</p> + +<p>For example:</p> + +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... > + <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="15" /> + ... +</manifest> +</pre> + +<p>As new versions of Android are released, some style and behaviors may change. +To allow your app to take advantage of these changes and ensure that your app fits the style of +each user's device, you should set the +<a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> +value to match the latest Android version +available.</p> + + + +<h2 id="version-codes">Check System Version at Runtime</h2> + +<p>Android provides a unique code for each platform version in the {@link android.os.Build} +constants class. Use these codes within your app to build conditions that ensure the code that +depends on higher API levels is executed only when those APIs are available on the system.</p> + +<pre> +private void setUpActionBar() { + // Make sure we're running on Honeycomb or higher to use ActionBar APIs + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { + ActionBar actionBar = getActionBar(); + actionBar.setDisplayHomeAsUpEnabled(true); + } +} +</pre> + + + +<p class="note"><strong>Note:</strong> When parsing XML resources, Android ignores XML +attributes that aren’t supported by the current device. So you can safely use XML attributes that +are only supported by newer versions without worrying about older versions breaking when they +encounter that code. For example, if you set the +<code>targetSdkVersion="11"</code>, your app includes the {@link android.app.ActionBar} by default +on Android 3.0 and higher. To then add menu items to the action bar, you need to set +<code>android:showAsAction="ifRoom"</code> in your menu resource XML. It's safe to do this +in a cross-version XML file, because the older versions of Android simply ignore the +<code>showAsAction</code> attribute (that is, you <em>do not</em> need a separate +version in <code>res/menu-v11/</code>).</p> + + + +<h2 id="style-themes">Use Platform Styles and Themes</h2> + +<p>Android provides user experience themes that give apps the look and feel of the +underlying operating system. These themes can be applied to your app within the +manifest file. By using these built in styles and themes, your app will +naturally follow the latest look and feel of Android with each new release.</p> + +<p>To make your activity look like a dialog box:</p> + +<pre><activity android:theme="@android:style/Theme.Dialog"></pre> + +<p>To make your activity have a transparent background:</p> + +<pre><activity android:theme="@android:style/Theme.Translucent"></pre> + +<p>To apply your own custom theme defined in <code>/res/values/styles.xml</code>:</p> + +<pre><activity android:theme="@style/CustomTheme"></pre> + +<p>To apply a theme to your entire app (all activities), add the <code>android:theme</code> +attribute +to the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code +<application>}</a> element:</p> + +<pre><application android:theme="@style/CustomTheme"></pre> + +<p>For more about creating and using themes, read the <a +href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> guide.</p> + diff --git a/docs/html/training/basics/supporting-devices/screens.jd b/docs/html/training/basics/supporting-devices/screens.jd new file mode 100644 index 0000000..8697cd5 --- /dev/null +++ b/docs/html/training/basics/supporting-devices/screens.jd @@ -0,0 +1,180 @@ +page.title=Supporting Different Screens +parent.title=Supporting Different Devices +parent.link=index.html + +trainingnavtop=true +previous.title=Supporting Different Languages +previous.link=languages.html +next.title=Supporting Different Platform Versions +next.link=platforms.html + +@jd:body + +<div id="tb-wrapper"> + <div id="tb"> + + <h2>This lesson teaches you to</h2> + <ol> + <li><a href="#create-layouts">Create Different Layouts</a></li> + <li><a href="#create-bitmaps">Create Different Bitmaps</a></li> + </ol> + + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple +Screens</a></li> + <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple +Screens</a></li> + <li><a href="{@docRoot}design/style/iconography.html">Iconography design guide</a></li> + </ul> + </div> +</div> + +<p>Android categorizes device screens using two general properties: size and density. You should +expect that your app will be installed on devices with screens that range in both size +and density. As such, you should include some alternative resources that optimize your app’s +appearance for different screen sizes and densities.</p> + +<ul> + <li>There are four generalized sizes: small, normal, large, xlarge</li> + <li>And four generalized densities: low (ldpi), medium (mdpi), high (hdpi), extra high +(xhdpi)</li> +</ul> + +<p>To declare different layouts and bitmaps you'd like to use for different screens, you must place +these alternative resources in separate directories, similar to how you do for different language +strings.</p> + +<p>Also be aware that the screens orientation (landscape or portrait) is considered a variation of +screen size, so many apps should revise the layout to optimize the user experience in each +orientation.</p> + + +<h2 id="create-layouts">Create Different Layouts</h2> + +<p>To optimize your user experience on different screen sizes, you should create a unique layout XML +file for each screen size you want to support. Each layout should be +saved into the appropriate resources directory, named with a <code>-<screen_size></code> +suffix. For example, a unique layout for large screens should be saved under +<code>res/layout-large/</code>.</p> + +<p class="note"><strong>Note:</strong> Android automatically scales your layout in order to +properly fit the screen. Thus, your layouts for different screen sizes don't +need to worry about the absolute size of UI elements but instead focus on the layout structure that +affects the user experience (such as the size or position of important views relative to sibling +views).</p> + +<p>For example, this project includes a default layout and an alternative layout for <em>large</em> +screens:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + layout/ + main.xml + layout-large/ + main.xml +</pre> + +<p>The file names must be exactly the same, but their contents are different in order to provide +an optimized UI for the corresponding screen size.</p> + +<p>Simply reference the layout file in your app as usual:</p> + +<pre> +@Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); +} +</pre> + +<p>The system loads the layout file from the appropriate layout directory based on screen size of +the device on which your app is running. More information about how Android selects the +appropriate resource is available in the <a +href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">Providing Resources</a> +guide.</p> + +<p>As another example, here's a project with an alternative layout for landscape orientation:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + layout/ + main.xml + layout-land/ + main.xml +</pre> + +<p>By default, the <code>layout/main.xml</code> file is used for portrait orientation.</p> + +<p>If you want a provide a special layout for landscape, including while on large screens, then +you need to use both the <code>large</code> and <code>land</code> qualifier:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + layout/ # default (portrait) + main.xml + layout-land/ # landscape + main.xml + layout-large/ # large (portrait) + main.xml + layout-large-land/ # large landscape + main.xml +</pre> + +<p class="note"><strong>Note:</strong> Android 3.2 and above supports an advanced method of +defining screen sizes that allows you to specify resources for screen sizes based on +the minimum width and height in terms of density-independent pixels. This lesson does not cover +this new technique. For more information, read <a +href="{@docRoot}training/multiscreen/index.html">Designing for Multiple +Screens</a>.</p> + + + +<h2 id="create-bitmaps">Create Different Bitmaps</h2> + +<p>You should always provide bitmap resources that are properly scaled to each of the generalized +density buckets: low, medium, high and extra-high density. This helps you achieve good graphical +quality and performance on all screen densities.</p> + +<p>To generate these images, you should start with your raw resource in vector format and generate +the images for each density using the following size scale:</p> +<ul> +<li>xhdpi: 2.0</li> +<li>hdpi: 1.5</li> +<li>mdpi: 1.0 (baseline)</li> +<li>ldpi: 0.75</li> +</ul> + +<p>This means that if you generate a 200x200 image for xhdpi devices, you should generate the same +resource in 150x150 for hdpi, 100x100 for mdpi, and 75x75 for ldpi devices.</p> + +<p>Then, place the files in the appropriate drawable resource directory:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + res/ + drawable-xhdpi/ + awesomeimage.png + drawable-hdpi/ + awesomeimage.png + drawable-mdpi/ + awesomeimage.png + drawable-ldpi/ + awesomeimage.png +</pre> + +<p>Any time you reference <code>@drawable/awesomeimage</code>, the system selects the +appropriate bitmap based on the screen's density.</p> + +<p class="note"><strong>Note:</strong> Low-density (ldpi) resources aren’t always necessary. When +you provide hdpi assets, the system scales them down by one half to properly fit ldpi +screens.</p> + +<p>For more tips and guidelines about creating icon assets for your app, see the +<a href="{@docRoot}design/style/iconography.html">Iconography design guide</a>.</p> + + + |