From 025ec882be3de274ddc935c7d669c4e86a74e0eb Mon Sep 17 00:00:00 2001
From: Joe Fernandez <joefernandez@google.com>
Date: Fri, 16 Nov 2012 16:10:52 -0800
Subject: docs: App Template Tool documentation

Change-Id: I75b8956b808ab21cb744f67c2ce69405dc0a0de4
---
 docs/html/tools/projects/projects-eclipse.jd | 156 +++++++-----
 docs/html/tools/projects/templates.jd        | 347 +++++++++++++++++++++++++++
 2 files changed, 443 insertions(+), 60 deletions(-)
 create mode 100644 docs/html/tools/projects/templates.jd

(limited to 'docs/html/tools/projects')

diff --git a/docs/html/tools/projects/projects-eclipse.jd b/docs/html/tools/projects/projects-eclipse.jd
index f1972bc..af85015 100644
--- a/docs/html/tools/projects/projects-eclipse.jd
+++ b/docs/html/tools/projects/projects-eclipse.jd
@@ -27,7 +27,7 @@ parent.link=index.html
 
   <p>Eclipse and the ADT plugin provide GUIs and wizards to create all three types of projects
   (Android project, Library project, and Test project):
-  
+
   <ul>
     <li>An Android project contains all of the files and resources that are needed to build a project into
   an .apk file for installation. You need to create an Android project for any application that you
@@ -44,99 +44,132 @@ parent.link=index.html
 
   <h2 id="CreatingAProject">Creating an Android Project</h2>
 
-  <p>The ADT plugin provides a <em>New Project Wizard</em> that you can use to quickly create a new Android
-  project (or a project from existing code). To create a new project:</p>
+  <p>The ADT plugin provides a <em>New Project Wizard</em> that you can use to quickly create a new
+  Android project (or a project from existing code). To create a new project:</p>
 
   <ol>
     <li>Select <strong>File</strong> &gt; <strong>New</strong> &gt; <strong>Project</strong>.</li>
 
-    <li>Select <strong>Android</strong> &gt; <strong>Android Project</strong>, and click
+    <li>Select <strong>Android</strong> &gt; <strong>Android Application Project</strong>, and click
     <strong>Next</strong>.</li>
 
-    <li>Select the contents for the project:
+    <li>Enter the basic settings for the project:
 
       <ul>
-        <li>Enter a <em>Project Name</em>. This will be the name of the folder where your project
-        is created.</li>
-
-        <li>Under Contents, select <strong>Create new project in workspace</strong>. Select your
-        project workspace location.</li>
-
-        <li>Under Target, select an Android target to be used as the project's Build Target. The
-        Build Target specifies which Android platform you'd like your application built against.
-
-          <p>Select the lowest platform with which your application is compatible.</p>
-
-          <p class="note"><strong>Note:</strong> You can change your the Build Target for your
+        <li>Enter an <strong>Application Name</strong>. This name is used as the title of your
+        application launcher icon when it is installed on a device.</li>
+
+        <li>Enter a <strong>Project Name</strong>. This text is used as the name of the folder where
+        your project is created.</li>
+
+        <li>Enter a <strong>Package Name</strong>. This class package namespace creates the initial
+        package structure for your applications code files and is added as the
+        <a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">{@code package}</a>
+        attribute in your application's
+        <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android manifest file</a>.
+        This manifest value serves as the unique identifier for your application app when you
+        distribute it to users. The package name must follow the same rules as packages in the Java
+        programming language.</li>
+
+        <li>Select a <strong>Minimum Required SDK</strong>. This setting indicates the lowest
+        version of the Android platform that your application supports. This value sets the
+        <code>minSdkVersion</code> attribute in the
+        <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a>
+        element of your manifest file.</li>
+
+        <li>Select a <strong>Target SDK</strong>. This setting indicates the highest version of
+        Android with which you have tested with your application and sets the
+        <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+        targetSdkVersion}</a> attribute in your application's' manifest file.
+
+          <p class="note"><strong>Note:</strong> You can change the target SDK for your
           project at any time: Right-click the project in the Package Explorer, select
           <strong>Properties</strong>, select <strong>Android</strong> and then check the desired
-          Project Target.</p>
+          <strong>Project Build Target</strong>.</p>
         </li>
 
-        <li>Under Properties, fill in all necessary fields.
+        <li>Select a <strong>Compile With</strong> API version. This setting specifies what version
+        of the SDK to compile your project against. We strongly recommend using the most recent
+        version of the API.</li>
 
-          <ul>
-            <li>Enter an <em>Application name</em>. This is the human-readable title for your
-            application &mdash; the name that will appear on the Android device.</li>
+        <li>Select a <strong>Theme</strong>. This setting specifies which standard Android
+        <a href="{@docRoot}design/style/themes.html">visual style</a> is applied to your
+        application.</li>
 
-            <li>Enter a <em>Package name</em>. This is the package namespace (following the same
-            rules as for packages in the Java programming language) where all your source code will
-            reside.</li>
-
-            <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name
-            for your main Activity class.</li>
-
-            <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates the minimum API
-            Level required to properly run your application. Entering this here automatically sets
-            the <code>minSdkVersion</code> attribute in the <a href=
-            "{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a> of your
-            Android Manifest file. If you're unsure of the appropriate <a href=
-            "{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Level</a> to use, copy the API Level
-            listed for the Build Target you selected in the Target tab.</li>
-          </ul>
-        </li>
+        <li>Click <strong>Next</strong>.</li>
       </ul>
     </li>
 
-    <li>Click <strong>Finish</strong>.</li>
+    <li>In the <strong>Configure Project</strong> page, select the desired settings and click
+      <strong>Next</strong>. Leave the <strong>Create activity</strong> option checked so you can
+      start your application with some essential components.</li>
+
+    <li>In the <strong>Configure Launcher Icon</strong> page, create an icon and click
+      <strong>Next</strong>.</li>
+
+    <li>In the <strong>Create Activity</strong> page, select activity template and click
+      <strong>Next</strong>. For more information about Android code templates, see
+      <a href="{@docRoot}tools/projects/templates.html">Using Code Templates</a>.
+      </li>
+
+    <li>Click <strong>Finish</strong> and the wizard creates a new project according to the options
+      you have chosen.</li>
   </ol>
 
-  <p class="note"><strong>Tip:</strong> You can also start the New Project Wizard from the
-  <em>New</em> icon in the toolbar.</p>
+  <p class="note"><strong>Tip:</strong> You can also start the New Project Wizard by clicking the
+  <strong>New</strong> <img src="/images/tools/eclipse-new.png"
+  style="vertical-align:baseline;margin:0"> icon in the toolbar.</p>
+
 
   <h2 id="SettingUpLibraryProject">Setting up a Library Project</h2>
 
   <p>A library project is a standard Android project, so you can create a new one in the same way
   as you would a new application project.</p>
 
-  <p>When you are creating the library project, you can select any application name, package, and
-  set other fields as needed, as shown in figure 1.</p>
+  <p>To create a new library project:</p>
+
+  <ol>
+    <li>Select <strong>File</strong> &gt; <strong>New</strong> &gt; <strong>Project</strong>.</li>
+
+    <li>Select <strong>Android</strong> &gt; <strong>Android Application Project</strong>, and click
+    <strong>Next</strong>.</li>
 
-  <p>Next, set the project's properties to indicate that it is a library project:</p>
+    <li>Enter the basic settings for the project, including <strong>Application Name</strong>,
+    <strong>Project Name</strong>, <strong>Package Name</strong>, and SDK settings.</li>
+
+    <li>In the <strong>Configure Project</strong> page, select the <strong>Mark this project as a
+    library</strong> option to flag the project as a library.</li>
+
+    <li>Set the other options as desired and click <strong>Next</strong>.</li>
+
+    <li>Follow the instructions to complete the wizard and create a new library project.</li>
+  </ol>
+
+  <p>You can also convert an existing application project into a library. To do so, simply open the
+    Properties for the project and select the <strong>is Library</strong> checkbox, as shown in
+    the figure below.</p>
+
+  <img src= "{@docRoot}images/developing/adt-props-isLib.png">
+  <p class="img-caption"><strong>Figure 1.</strong> Marking a project as an Android library.</p>
+
+  <p>To set the a project's properties to indicate that it is a library project:</p>
 
   <ol>
     <li>In the <strong>Package Explorer</strong>, right-click the library project and select
     <strong>Properties</strong>.</li>
 
-    <li>In the <strong>Properties</strong> window, select the "Android" properties group at left
-    and locate the <strong>Library</strong> properties at right.</li>
+    <li>In the <strong>Properties</strong> window, select the <strong>Android</strong> properties
+    group in the left pane and locate the <strong>Library</strong> properties in the right pane.</li>
 
-    <li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li>
+    <li>Select the <strong>is Library</strong> check box and click <strong>Apply</strong>.</li>
 
-    <li>Click <strong>OK</strong> to close the <em>Properties</em> window.</li>
+    <li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
   </ol>
 
-  <p>The new project is now marked as a library project. You can begin moving source code and
-  resources into it, as described in the sections below.</p>
+  <p>Once you create a library project or mark an existing project as a library, you can reference
+  the library project in other Android application projects. For more information, see the
+  <a href="#ReferencingLibraryProject">Referencing a library project</a> section.
 
-  <p>You can also convert an existing application project into a library. To do so, simply open the
-  Properties for the project and select the "is Library" checkbox. Other application projects can
-  now reference the existing project as a library project.</p>
-  
-  <img src= "{@docRoot}images/developing/adt-props-isLib.png">
-
-  <p class="img-caption"><strong>Figure 1.</strong> Marking a project as an
-     Android library project.</p>
 
   <h3>Creating the manifest file</h3>
 
@@ -146,7 +179,7 @@ parent.link=index.html
 
   <p>For example, the <a href=
   "{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library
-  project declares the Activity <code>GameActivity</code>:</p>
+  project declares the activity <code>GameActivity</code>:</p>
   <pre>
 &lt;manifest&gt;
   ...
@@ -167,6 +200,9 @@ parent.link=index.html
   <p>To add a reference to a library project, follow these steps:</p>
 
   <ol>
+    <li>Make sure that both the project library and the application project that depends on it are
+      in your workspace. If one of the projects is missing, import it into your workspace.</li>
+
     <li>In the <strong>Package Explorer</strong>, right-click the dependent project and select
     <strong>Properties</strong>.</li>
 
@@ -214,7 +250,7 @@ parent.link=index.html
 
   <p>For example, the <a href=
   "{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example
-  application declares the library Activity <code>GameActivity</code> like this:</p>
+  application declares the library activity <code>GameActivity</code> like this:</p>
   <pre>
 &lt;manifest&gt;
   ...
diff --git a/docs/html/tools/projects/templates.jd b/docs/html/tools/projects/templates.jd
new file mode 100644
index 0000000..fce24fd
--- /dev/null
+++ b/docs/html/tools/projects/templates.jd
@@ -0,0 +1,347 @@
+page.title=Using Code Templates
+@jd:body
+
+  <div id="qv-wrapper">
+    <div id="qv">
+      <h2>In this document</h2>
+
+      <ol>
+        <li><a href="#app-templates">Application Templates</a>
+          <ol>
+            <li><a href="#blank-activity">BlankActivity Template</a></li>
+            <li><a href="#full-screen-activity">Full Screen Activity Template</a></li>
+            <li><a href="#master-detail-activity">Master Detail Flow Template</a></li>
+          </ol>
+        </li>
+
+        <li><a href="#activity-templates">Activity Templates</a>
+          <ol>
+            <li><a href="#login-activity">Login Activity Template</a></li>
+            <li><a href="#settings-activity">Settings Activity Template</a></li>
+          </ol>
+        </li>
+        <li><a href="#object-templates">Other Templates</a></li>
+      </ol>
+
+    </div>
+  </div>
+
+
+<p>The SDK tools provide templates for quickly creating Android application projects with the basic
+  structure or for adding components to your existing projects. The code templates
+  provided by the Android SDK follow the Android design and development guidelines to get you on the
+  right track to creating a beautiful, functional application.</p>
+
+<p>There are several types of Android code templates, which can create anything from an entire
+  application down to specific application components. The main categories of code templates are as
+  follows:</p>
+
+<ul>
+  <li><a href="#app-templates">Application Templates</a></li>
+  <li><a href="#activity-templates">Activity Templates</a></li>
+  <li><a href="#object-templates">Other Templates</a></li>
+</ul>
+
+
+<h2 id="app-templates">Application Templates</h2>
+
+<p>Application templates create basic Android applications that you can immediately run and test
+  on your Android device. These templates are available when you create a new Android project,
+  though you can also use these templates to <a href="#activity-templates">add new activities</a>
+  to an existing project.</p>
+
+<p>To use Android application templates:</p>
+
+<ol>
+  <li>In Eclipse, with the Android Development Tools (ADT) plugin installed, select <strong>File
+    &gt; New &gt; Android</strong>.</li>
+  <li>Select <strong>Android &gt; Android Application Project</strong>, and click
+    <strong>Next</strong>.</li>
+  <li>Enter the settings for your application, including <strong>Application Name</strong>,
+    <strong>Project Name</strong>, <strong>Package Name</strong>, API level settings and
+    presentation <strong>Theme</strong>, and click <strong>Next</strong>.</li>
+  <li>Enter the project configuration options, and click <strong>Next</strong>.</li>
+  <li>Optionally enter launcher icon settings, and click <strong>Next</strong>.</li>
+  <li>In the <strong>Create Activity</strong> page, select an application template to use.
+    <ul>
+      <li><a href="#blank-activity">BlankActivity</a></li>
+      <li><a href="#full-screen-activity">FullScreenActivity</a></li>
+      <li><a href="#master-detail-activity">MasterDetailFlow</a></li>
+    </ul>
+  </li>
+</ol>
+
+<p class="note">
+  <strong>Note:</strong> The other activity template options also create applications, however these
+  applications require further modification before they can be launched on an Android device.
+</p>
+
+
+<h3 id="blank-activity">Blank Activity Template</h3>
+
+<table>
+  <tr>
+    <th width="206px">Example</th>
+
+    <th>Description</th>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/ba-no-navigation.png" alt="" />
+    </td>
+
+    <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+      None</strong> option creates a simple application that follows the
+      <a href="{@docRoot}design/index.html">Android Design</a> guidelines. Use this template to
+      create a basic, minimal app as a starting point for your project.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>Title bar ({@link android.app.ActionBar} on Android 3.0 and later)</li>
+        <li>Options menu (action overflow on Android 3.0 and later) </li>
+        <li>Basic layout</li>
+      </ul>
+    </td>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/ba-tabs.png" alt="" />
+    </td>
+
+    <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+      Tabs</strong> or <strong>Tabs + Swipe</strong> option creates an application with
+      three sections based on the {@link android.app.Fragment} class and a tabbed user
+      interface.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>{@link android.app.ActionBar} for tab controls</li>
+        <li>{@link android.app.Fragment} objects for section content</li>
+        <li>Optional swipe gesture support based on the
+          <a href="{@docRoot}design/patterns/swipe-views.html">swipe view</a> design pattern,
+          which extends {@link android.support.v4.app.FragmentPagerAdapter} to manage section
+          fragments</li>
+      </ul>
+    </td>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/ba-title-strip.png" alt="" />
+    </td>
+
+    <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+      Swipe Views + Title Strip</strong> option creates an application with three
+      {@link android.app.Fragment} sections, a compact title strip header (known as
+      <a href="{@docRoot}design/building-blocks/tabs.html#scrollable">Scrollable Tabs</a> in the
+      <a href="{@docRoot}design/index.html">Android Design</a> guide) and swipe navigation between
+      the sections, based on the <a href="{@docRoot}design/patterns/swipe-views.html">swipe
+      view</a> design pattern.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>{@link android.support.v4.view.PagerTitleStrip} for section titles</li>
+        <li>{@link android.app.Fragment} objects for section content</li>
+        <li>{@link android.support.v4.app.FragmentPagerAdapter} to manage section fragments</li>
+      </ul>
+    </td>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/ba-dropdown.png" alt="" />
+    </td>
+
+    <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+      Dropdown</strong> option creates an application that extends
+      {@link android.support.v4.app.FragmentActivity}, containing three
+      {@link android.app.Fragment} sections, with an {@link android.app.ActionBar} using list mode
+      navigation.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>{@link android.app.ActionBar} for list mode navigation</li>
+        <li>{@link android.app.Fragment} objects for section content</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+<h3 id="full-screen-activity">Full Screen Activity Template</h3>
+
+<table>
+  <tr>
+    <th width="240px">Example</th>
+
+    <th>Description</th>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/full-screen-activity.png" alt="" />
+    </td>
+
+    <td><p>This template provides an implementation of an activity which alternates between a
+      primary, full screen view and a view with standard user interface controls, including the
+      notification bar and application title bar. The full screen view is the default and a user
+      can activate the standard view by touching the device screen.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>{@code SystemUiHider} implementation that manages hiding of the system user interface
+          using a version-compatible approach</li>
+        <li>Basic layout</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+<h3 id="master-detail-activity">Master Detail Flow Template</h3>
+
+<table>
+  <tr>
+    <th width="350px">Example</th>
+
+    <th>Description</th>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/master-detail-flow.png" alt=""/>
+    </td>
+
+    <td><p>This template creates an adaptive layout for a set of items and associated details. On a
+      tablet device, the item list and item details are displayed on the same screen. On a smaller
+      device, the list and details are displayed on separate screens.</p>
+
+      <p class="note">
+        <strong>Note:</strong> This template follows the recommendations of the
+        <a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a>
+        Android training.
+      </p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>Adaptive layout using
+          <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"
+          >alternative resource</a> XML files</li>
+        <li>{@link android.support.v4.app.FragmentActivity}, {@link android.app.Fragment} and
+          {@link android.support.v4.app.ListFragment} implementations</li>
+      </ul></td>
+  </tr>
+</table>
+
+
+<h2 id="activity-templates">Activity Templates</h2>
+
+<p>Android activity templates provide options to add new activities to your existing
+  application.</p>
+
+<p>To use Android activity templates:</p>
+
+<ol>
+  <li>Right click the project folder of the Android application where you want to add an
+    activity.</li>
+  <li>Select <strong>New &gt; Other...</strong></li>
+  <li>Select <strong>Android &gt; Android Activity</strong>, and click <strong>Next</strong>.</li>
+  <li>Select an activity template, then follow the instructions to add it to your existing
+    application.
+    <ul>
+      <li><a href="#login-activity">LoginActivity</a></li>
+      <li><a href="#settings-activity">SettingsActivity</a></li>
+      <li><a href="#blank-activity">BlankActivity</a></li>
+      <li><a href="#full-screen-activity">FullScreenActivity</a></li>
+      <li><a href="#master-detail-activity">MasterDetailFlow</a></li>
+    </ul>
+  </li>
+</ol>
+
+<p>These templates create the same type of activity as they do when used as an application template,
+however the following templates create activities which are specifically intended to be used as part
+of an existing application.</p>
+
+
+<h3 id="login-activity">Login Activity Template</h3>
+
+<table>
+  <tr>
+    <th width="206px">Example</th>
+
+    <th>Description</th>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/login-activity.png" alt="" />
+    </td>
+
+    <td><p>This activity template provides input fields and a sample implementation of
+      an {@link android.os.AsyncTask} that asks users to login or register with their credentials.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>Recommended user interface for requesting login information</li>
+        <li>{@link android.os.AsyncTask} implementation for handing network operations separately
+          from the main user interface thread</li>
+        <li>Progress indicator during network operations</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+<h3 id="settings-activity">Settings Activity Template</h3>
+
+<table>
+  <tr>
+    <th width="206px">Example</th>
+
+    <th>Description</th>
+  </tr>
+
+  <tr>
+    <td><img src="{@docRoot}images/code_templates/settings-activity.png" alt="" />
+    </td>
+
+    <td><p>This template extends the {@link android.preference.PreferenceActivity} class and uses an
+      XML file to create preference settings. This template also demonstrates how to implement
+      several data types for settings.</p>
+
+      <p>This template includes:</p>
+
+      <ul>
+        <li>Activity extending {@link android.preference.PreferenceActivity}</li>
+        <li>Preference values defined using XML files added to the {@code res/xml/} directory of
+          your project.</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+<h2 id="object-templates">Other Templates</h2>
+
+<p>Android object templates provide options to add new components to your existing application,
+including the previously mentioned activities as well as the following additional items:</p>
+
+<p>To use Android object templates:</p>
+
+<ol>
+  <li>Right click the project folder of the Android application where you want to add a code
+    component.</li>
+  <li>Select <strong>New &gt; Other...</strong></li>
+  <li>Select <strong>Android &gt; Android Object</strong>, and click <strong>Next</strong>.</li>
+  <li>Select an object template, then follow the instructions to add it to your existing
+    application.
+    <ul>
+      <li>{@link android.content.BroadcastReceiver}</li>
+      <li>{@link android.content.ContentProvider}</li>
+      <li><a href="{@docRoot}guide/topics/ui/custom-components.html">Custom View</a></li>
+      <li>{@link android.app.Service}</li>
+    </ul>
+  </li>
+</ol>
-- 
cgit v1.1