Merge "docs: update Building Your First App class to reflect changes to New Project setup in eclipse" into jb-dev

Author: scottamain

docs/html/images/tools/avd_manager.png

@@ -4,8 +4,9 @@ walkthru=1
 @jd:body
 
 
-<p>The Android SDK separates different parts of the SDK into separately downloadable packages. The
-SDK starter package that you've installed includes only the SDK Tools. To develop an Android app,
+<p>The Android SDK separates tools, platforms, and other components into packages you can
+  download using the Android SDK Manager. The original
+SDK package you've downloaded includes only the SDK Tools. To develop an Android app,
 you also need to download at least one Android platform and the latest SDK Platform-tools.</p>
 
 <p>You can update and install SDK packages at any time using the Android SDK Manager.</p>
@@ -48,28 +49,32 @@ you keep this up to date.</dd>
   <dd><strong>Required.</strong> You must install this package when you install the SDK for
 the first time.</dd>
   <dt>SDK Platform</dt>
-  <dd><strong>Required.</strong>You need to download <strong
-style="color:red">at least one platform</strong> into your environment so you're
-able to compile your application. In order to provide the best user experience on the latest
-devices, we recommend that you use the latest platform version as your build target. You'll
-still be able to run your app on older versions, but you must build against the latest version
-in order to use new features when running on devices with the latest version of Android.</dd>
+  <dd><strong>Required.</strong>You must download <em>at least one platform</em> into your
+environment so you're able to compile your application. In order to provide the best user experience
+on the latest devices, we recommend that you use the latest platform version as your build target.
+You'll still be able to run your app on older versions, but you must build against the latest
+version in order to use new features when running on devices with the latest version of Android.
+  <p>To get started, download the latest Android version, plus the lowest version you plan
+  to support (we recommend Android 2.2 for your lowest version).</p></dd>
   <dt>System Image</dt>
   <dd>Recommended. Although you might have one or more Android-powered devices on which to test
  your app, it's unlikely you have a device for every version of Android your app supports. It's
-a good practice to download a system image for each version of Android you support and use them
-to test your app on the Android emulator.</dd>
+a good practice to download system images for all versions of Android your app supports and test
+your app running on them with the <a href="{@docRoot}tools/devices/emulator.html">Android emulator</a>.</dd>
+  <dt>Android Support</dt>
+  <dd>Recommended. Includes a static library that allows you to use some of the latest
+Android APIs (such as <a href="{@docRoot}guide/components/fragments.html">fragments</a>,
+plus others not included in the framework at all) on devices running
+a platform version as old as Android 1.6. All of the activity templates available when creating
+a new project with the <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin</a>
+require this. For more information, read <a
+href="{@docRoot}tools/extras/support-library.html">Support Library</a>.</dd>
   <dt>SDK Samples</dt>
   <dd>Recommended. The samples give you source code that you can use to learn about
 Android, load as a project and run, or reuse in your own app. Note that multiple
 samples packages are available &mdash; one for each Android platform version. When
 you are choosing a samples package to download, select the one whose API Level
 matches the API Level of the Android platform that you plan to use.</dd>
-  <dt>Android Support</dt>
-  <dd>Recommended. The APIs available in this static library allow you to use a variety of new
-framework features (including some not available in even the latest version) on devices running
-a platform version as old as Android 1.6. For more information, read <a
-href="{@docRoot}tools/extras/support-library.html">Support Library</a>.</dd>
 </dl>
 
 

docs/html/images/tools/eclipse-new.png

@@ -34,66 +34,77 @@ SDK</a></li>
 
 <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> 
+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}tools/sdk/eclipse-adt.html">ADT plugin</a> as well. If you have not installed
-these, see <a href="{@docRoot}sdk/installing/index.html">Installing the Android SDK</a> and return here
-when you've completed the installation.</p>
+you're using Eclipse, you should also have the <a
+href="{@docRoot}tools/sdk/eclipse-adt.html">ADT plugin</a> installed. If you don't have
+these, follow the guide to <a href="{@docRoot}sdk/installing/index.html">Installing the Android SDK</a>
+before you start this lesson.</p>
 
 
 <h2 id="Eclipse">Create a Project with Eclipse</h2>
 
-<div class="figure" style="width:416px">
+<ol>
+  <li>In Eclipse, click New Android
+    App Project <img src="{@docRoot}images/tools/new_adt_project.png" 
+             style="vertical-align:baseline;margin:0" />
+    in the toolbar.  (If you don’t see this button,
+then you have not installed the ADT plugin&mdash;see <a
+href="{@docRoot}sdk/installing/installing-adt.html">Installing the Eclipse Plugin</a>.)
+  </li>
+
+<div class="figure" style="width:420px">
 <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>
+<p class="img-caption"><strong>Figure 1.</strong> The New Android App 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}tools/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/index.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:
+  <li>Fill in the form that appears:
     <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
+      <li><em>Application Name</em> is the app name that appears to users.
+          For this project, use "My First App."</p></li>
+      <li><em>Project Name</em> is the name of your project directory and the name visible in Eclipse.</li>
+      <li><em>Package Name</em> is 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/topics/manifest/uses-sdk-element.html#ApiLevels">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>
+must be unique across all packages installed on the Android system. For this reason, it's generally
+best if you use a name that begins with the reverse domain name of your organization or
+publisher entity. For this project, you can use something like "com.example.myfirstapp."
+However, you cannot publish your app on Google Play using the "com.example" namespace.</li>
+      <li><em>Build SDK</em> is the platform version against which you will compile your app.
+        By default, this is set to the latest version of Android available in your SDK. (It should
+        be Android 4.1 or greater; if you don't have such a version available, you must install one
+        using the <a href="{@docRoot}sdk/installing/adding-packages.html">SDK Manager</a>).
+        You can still build your app to
+support older versions, but setting the build target to the latest version allows you to
+enable new features and optimize your app for a great user experience on the latest
+devices.</li>
+      <li><em>Minimum Required SDK</em> is the lowest version of Android that your app supports.
+        To support as many devices as possible, you should set this to the lowest version available
+        that allows your app to provide its core feature set. If any feature of your app is possible
+        only on newer versions of Android and it's not critical to the app's core feature set, you
+        can enable the feature only when running on the versions that support it.
+        <p>Leave this set to the default value for this project.</p>
     </ul>
-    <p>Click <strong>Finish</strong>.</p>
+    <p>Click <strong>Next</strong>.</p>
+  </li>
+  
+  <li>The following screen provides tools to help you create a launcher icon for your app.
+    <p>You can customize an icon in several ways and the tool generates an icon for all
+    screen densities. Before you publish your app, you should be sure your icon meets
+    the specifications defined in the <a
+    href="{@docRoot}design/style/iconography.html">Iconography</a>
+    design guide.</p>
+    <p>Click <strong>Next</strong>.</p>
+  </li>
+  <li>Now you can select an activity template from which to begin building your app.
+    <p>For this project, select <strong>BlankActivity</strong> and click <strong>Next</strong>.</p>
   </li>
+  <li>Leave all the details for the activity in their default state and click 
+    <strong>Finish</strong>.</li>
 </ol>
 
 <p>Your Android project is now set up with some default files and you’re ready to begin
@@ -104,7 +115,7 @@ 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>
+using the SDK tools from a command line:</p>
 
 <ol>
   <li>Change directories into the Android SDK’s <code>tools/</code> path.</li>
@@ -117,13 +128,13 @@ support older versions, but setting the build target to the latest version allow
 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/index.html#AddingComponents">step 4 in the
-installing guide</a>.</p></li>
+Manager tool. See <a href="{@docRoot}sdk/installing/adding-packages.html">Adding Platforms
+  and Packages</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
+--path &lt;path-to-workspace>/MyFirstApp --activity MainActivity \
+--package com.example.myfirstapp
 </pre>
 <p>Replace <code>&lt;target-id></code> with an id from the list of targets (from the previous step)
 and replace