docs: add 101 Training class "Building Your First App"

Change-Id: I9a1f27dc2b44fac8b0e9fbeb9326b5c62a93bc41

5 files changed, 1055 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>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent"
+    android:orientation="horizontal" >
+&lt;/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&mdash;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
+&lt;EditText>} element inside the {@link android.widget.LinearLayout &lt;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 &lt;LinearLayout>} element:</p>
+
+<pre>
+    &lt;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>&#64;</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&mdash;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 &lt;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>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;string name="app_name">My First App&lt;/string>
+    &lt;string name="edit_message">Enter a message&lt;/string>
+    &lt;string name="button_send">Send&lt;/string>
+&lt;/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 &lt;Button>} to the layout, immediately following the
+{@link android.widget.EditText &lt;EditText>} element:</p>
+
+<pre>
+    &lt;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>
+    &lt;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>
+    &lt;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>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent"
+    android:orientation="horizontal">
+    &lt;EditText android:id="@+id/edit_message"
+        android:layout_weight="1"
+        android:layout_width="0dp"
+        android:layout_height="wrap_content"
+        android:hint="@string/edit_message" />
+    &lt;Button android:id="@+id/button_send"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/button_send" />
+&lt;/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 &gt; New &gt; 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&mdash;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 &lt;target-id> --name MyFirstApp \
+--path &lt;path-to-workspace>/MyFirstApp --activity MyFirstActivity \
+--package com.example.myapp
+</pre>
+<p>Replace <code>&lt;target-id></code> with an id from the list of targets (from the previous step)
+and replace
+<code>&lt;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 &rsaquo;</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>&lt;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 &lt;Button>} element:</p>
+
+<pre>
+&lt;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/&lt;package-name&gt;/</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 {
+    &#64;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 &lt;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 &lt;application>}</a>
+element:</p>
+
+<pre>
+&lt;application ... >
+    &lt;activity android:name="com.example.myapp.DisplayMessageActivity" />
+    ...
+&lt;/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>
+&#64;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>
+
+
+
+