am 90172e0f: Merge "docs: App Template Tool documentation" into jb-mr1-dev

* commit '90172e0f0cb0abfbaa3f1ea0e5251913bd30d828':
  docs: App Template Tool documentation
This commit is contained in:
Joe Fernandez
2012-12-17 15:47:56 -08:00
committed by Android Git Automerger
11 changed files with 446 additions and 62 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

View File

@@ -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>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>Under Contents, select <strong>Create new project in workspace</strong>. Select your
project workspace location.</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>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.
<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>
<p>Select the lowest platform with which your application is compatible.</p>
<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>
<p class="note"><strong>Note:</strong> You can change your the Build Target for your
<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>
<p>Next, set the project's properties to indicate that it is a 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>
<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;
...

View File

@@ -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>

View File

@@ -10,8 +10,8 @@
<div class="nav-section-header"><a href="<?cs var:toroot
?>sdk/index.html"><span class="en">Download</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/installing/bundle.html">
<span class="en">Setting Up the ADT Bundle</span></a></li>
<li><a href="<?cs var:toroot ?>sdk/installing/bundle.html">
<span class="en">Setting Up the ADT Bundle</span></a></li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>sdk/installing/index.html"><span class="en">Setting Up
@@ -19,12 +19,12 @@
<ul>
<li><a href="<?cs var:toroot ?>sdk/installing/installing-adt.html">
<span class="en">Installing the Eclipse Plugin</span></a></li>
<li><a href="<?cs var:toroot ?>sdk/installing/adding-packages.html">
<span class="en">Adding Platforms and Packages</span></a></li>
<li><a href="<?cs var:toroot ?>sdk/installing/adding-packages.html">
<span class="en">Adding Platforms and Packages</span></a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>sdk/exploring.html">
<span class="en">Exploring the SDK</span></a></li>
<li><a href="<?cs var:toroot ?>sdk/exploring.html">
<span class="en">Exploring the SDK</span></a></li>
<li><a href="<?cs var:toroot ?>tools/sdk/ndk/index.html">Download the NDK</a>
</li>
</ul>
@@ -49,6 +49,7 @@
<ul>
<li><a href="/tools/projects/projects-eclipse.html"><span class="en">From Eclipse with ADT</span></a></li>
<li><a href="/tools/projects/projects-cmdline.html"><span class="en">From the Command Line</span></a></li>
<li><a href="/tools/projects/templates.html"><span class="en">Using Code Templates</span></a></li>
</ul>
</li>