Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* commit 'fc815c328bea63c2dee7e67b81c95d7c4d5696bb':
  docs: update Building Your First App class to reflect changes to New Project setup in eclipse
This commit is contained in:
Scott Main
2012-07-23 18:49:50 -07:00
committed by Android Git Automerger
parent 0275552bba fc815c328b
commit 26db8b9594
13 changed files with 295 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/tools/avd_manager.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 269 B

BIN
docs/html/images/tools/eclipse-new.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

BIN
docs/html/images/tools/eclipse-run.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 638 B

BIN
docs/html/images/tools/new_adt_project.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 664 B

BIN
docs/html/images/tools/sdk_manager.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 219 B

BIN
docs/html/images/training/firstapp/adt-firstapp-setup.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 42 KiB

BIN
docs/html/images/training/firstapp/adt-new-activity.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

35
docs/html/sdk/installing/adding-packages.jd
View File

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

169
docs/html/training/basics/firstapp/building-ui.jd
View File

@@ -18,7 +18,7 @@ next.link=starting-activity.html
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#LinearLayout">Use a Linear Layout</a></li>
<li><a href="#LinearLayout">Create a Linear Layout</a></li>
<li><a href="#TextInput">Add a Text Field</a></li>
<li><a href="#Strings">Add String Resources</a></li>
<li><a href="#Button">Add a Button</a></li>
@@ -28,10 +28,9 @@ next.link=starting-activity.html
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a></li>
<li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li>
</ul>
</div>
</div>
@@ -39,63 +38,68 @@ next.link=starting-activity.html
<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
usually UI widgets such as <a href="{@docRoot}guide/topics/ui/controls/button.html">buttons</a> or
<a href="{@docRoot}guide/topics/ui/controls/text.html">text fields</a> 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>
android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML using
a hierarchy of UI 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
<p>Declaring your UI layout in XML rather than runtime code is useful for several reasons,
but it's especially important so you can create different 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/basics/supporting-devices/index.html">Supporting Different
Hardware</a>.</p>
Devices</a>.</p>
</div>
</div>
<img src="{@docRoot}images/viewgroup.png" alt="" width="440" />
<img src="{@docRoot}images/viewgroup.png" alt="" width="400" />
<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.ViewGroup} objects form branches in the layout and contain other {@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
<p>In this lesson, you'll create a layout in XML that includes a text 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>
<h2 id="LinearLayout">Create 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>Open the <code>activity_main.xml</code> file from the <code>res/layout/</code>
directory.</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 Graphical 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>activity_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>The BlankActivity template you used to start this project creates the
<code>activity_main.xml</code> file with a {@link
android.widget.RelativeLayout} root view and a {@link android.widget.TextView} child view.</p>
<p>First, delete the {@link android.widget.TextView} element and change the value
<p>First, delete the {@link android.widget.TextView &lt;TextView>} element and change the {@link
android.widget.RelativeLayout &lt;RelativeLayout>} element to {@link
android.widget.LinearLayout &lt;LinearLayout>}. Then add the
<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>
android:orientation}</a> attribute and set it to <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"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="horizontal" >
&lt;/LinearLayout>
</pre>
@@ -116,26 +120,18 @@ android:layout_height}</a>, are required for all views in order to specify their
<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>
<code>"match_parent"</code>. This value declares that the view should expand its width
or height to <em>match</em> the width or height of the parent view.</p>
<p>For more information about layout properties, see the <a
href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layout</a> guide.</p>
href="{@docRoot}guide/topics/ui/declaring-layout.html">Layout</a> guide.</p>
<h2 id="TextInput">Add a Text Field</h2>
<p>To create a user-editable text field, 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 field.</p>
&lt;EditText>} element inside the {@link android.widget.LinearLayout &lt;LinearLayout>}.</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
@@ -164,6 +160,8 @@ href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android
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>
<p>For more information, read the guide to <a
href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</p>
</div>
</div>
@@ -175,17 +173,18 @@ modify this file by hand.</p>
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 at sign (<code>&#64;</code>) is required when you're referring to any resource object from
XML. It is followed by the resource type ({@code id} in this case), a slash, then the resource name
({@code edit_message}).</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 associated with the {@link
android.widget.EditText} element. Once the resource ID is created, other references to the ID do not
need the plus symbol. This is the only attribute that may need the plus-symbol. See the sidebox for
<p>The plus sign (<code>+</code>) before the resource type is needed only when you're defining a
resource ID for the first time. When you compile the app,
the SDK tools use the ID name to create a new resource ID in
your project's {@code gen/R.java} file that refers to the {@link
android.widget.EditText} element. Once the resource ID is declared once this way,
other references to the ID do not
need the plus sign. Using the plus sign is necessary only when specifying a new resource ID and not
needed for concrete resources such as strings or layouts. See the sidebox for
more information about resource objects.</p></dd>
<dt><a
@@ -195,39 +194,42 @@ href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@c
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
were to instead use <code>"match_parent"</code>, then the {@link android.widget.EditText}
element would fill the screen, because it would 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>
href="{@docRoot}guide/topics/ui/declaring-layout.html">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 field is empty. Instead of using a hard-coded
string as the value, the {@code "@string/edit_message"} value refers to a string resource defined
in a separate file. Because this value refers to an existing resource, it does not need the
plus-symbol. However, because you haven't defined the string resource yet, you’ll see a compiler
error when you add the {@code "@string/edit_message"} value. You'll fix this in the next section by
defining the string resource.</dd>
string as the value, the {@code "@string/edit_message"} value refers to a string resource defined in
a separate file. Because this refers to a concrete resource (not just an identifier), it does not
need the plus sign. However, because you haven't defined the string resource yet, you’ll see a
compiler error at first. You'll fix this in the next section by defining the string.
<p class="note"><strong>Note:</strong> This string resource has the same name as the element ID:
{@code edit_message}. However, references
to resources are always scoped by the resource type (such as {@code id} or {@code string}), so using
the same name does not cause collisions.</p>
</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
<p>When you need to add text in the user interface, you should always specify each string as
a resource. String resources allow you to manage all UI text in a single location,
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>
string resource.</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>
<code>res/values/strings.xml</code>. Open this file and delete the {@code &lt;string>} element
named <code>"hello_world"</code>. Then add a new one named
<code>"edit_message"</code> and set the value to "Enter a message."</p>
<p>While you’re in this file, also add a string for the button you’ll soon add, called
<p>While you’re in this file, also add a "Send" 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>
@@ -238,12 +240,14 @@ element.</p>
&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;string name="menu_settings">Settings&lt;/string>
&lt;string name="title_activity_main">MainActivity&lt;/string>
&lt;/resources>
</pre>
<p>For more information about using string resources to localize your app for several languages,
<p>For more information about using string resources to localize your app for other languages,
see the <a
href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Various Devices</a>
href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Different Devices</a>
class.</p>
@@ -280,23 +284,26 @@ 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 field, 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 field.
{@link android.widget.LinearLayout} enables such a design with the <em>weight</em> property, which
something longer. So, it would be nice to fill the unused screen width
with the text field. You can do this inside a
{@link android.widget.LinearLayout} 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
<p>The weight value is a number that specifies the amount of remaining space each view should
consume,
relative to the amount consumed by sibling views. This works kind of like the
amount of ingredients in a drink recipe: "2
parts vodka, 1 part coffee liqueur" 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>
one view a weight of 2 and another one a weight of 1, the sum is 3, so the first view fills 2/3 of
the remaining space and the second view fills the rest. If you add a third view and give it a weight
of 1, then the first view (with weight of 2) 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
greater than 0 to only one view, then that view fills whatever space remains after all views are
given the space they require. So, to fill the remaining space in your layout with the {@link
android.widget.EditText} element, give it a weight of 1 and leave the button with no weight.</p>
<pre>
@@ -331,8 +338,9 @@ android.widget.LinearLayout}.</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"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="horizontal">
&lt;EditText android:id="@+id/edit_message"
android:layout_weight="1"
@@ -351,7 +359,8 @@ that the SDK tools generated when you created the project, so you can now run th
results:</p>
<ul>
<li>In Eclipse, click <strong>Run</strong> from the toolbar.</li>
<li>In Eclipse, click Run <img src="{@docRoot}images/tools/eclipse-run.png"
style="vertical-align:baseline;margin:0" /> from the toolbar.</li>
<li>Or from a command line, change directories to the root of your Android project and
execute:
<pre>

107
docs/html/training/basics/firstapp/creating-project.jd
View File

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

30
docs/html/training/basics/firstapp/index.jd
View File

@@ -27,39 +27,21 @@ next.link=creating-project.html
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
<p>Before you start this class, be sure you have your development environment set up. You need
to:</p>
<ol>
<li>Download the Android SDK Starter Package.</li>
<li>Download the Android SDK.</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/index.html">Installing
the SDK</a>. Once you've finished the setup, you're ready to begin this class.</p>
<p>If you haven't already done these tasks, start by downloading the
<a href="{@docRoot}sdk/index.html">Android SDK</a> and following the install steps.
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
<p>This class uses a tutorial format that incrementally builds a small Android app that teaches
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>

55
docs/html/training/basics/firstapp/running-app.jd
View File

@@ -37,7 +37,7 @@ next.link=building-ui.html
<p>If you followed the <a href="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>
immediately run the app.</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
@@ -49,14 +49,16 @@ project:</p>
<dl>
<dt><code>AndroidManifest.xml</code></dt>
<dd>This manifest file describes the fundamental characteristics of the app and defines each of
<dd>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest file</a> 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:
<dd>Contains several sub-directories for <a
href="{@docRoot}guide/topics/resources/overview.html">app resources</a>. 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
@@ -70,30 +72,30 @@ string and color definitions.</dd>
</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>
<p>When you build and run the default Android app, the default {@link android.app.Activity}
class starts and loads a layout file
that says "Hello World." The result is nothing exciting, but it's
important that you understand how to run your app before you start developing.</p>
<h2 id="RealDevice">Run on a Real Device</h2>
<p>Whether you’re using Eclipse or the command line, you need to:</p>
<p>If you have a real Android-powered device, here's how you can install and run your app:</p>
<ol>
<li>Plug in your Android-powered device to your machine with a USB cable.
<li>Plug in your device to your development 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}tools/extras/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
and navitage to <strong>Applications > Development</strong> on most devices, or click
<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
Run <img src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" />
from the toolbar. Eclipse installs the app on your connected device and starts
it.</p>
@@ -108,18 +110,18 @@ it.</p>
<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
<p>That's how you build and run your Android app on a device!
To start developing, 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}tools/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>
<p>Whether you’re using Eclipse or the command line, to run your app on the emulator you need to
first create an <a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a> (AVD). An
AVD is a device configuration for the Android emulator that allows you to model different
devices.</p>
<div class="figure" style="width:457px">
<img src="{@docRoot}images/screens_support/avds-config.png" alt="" />
@@ -131,13 +133,14 @@ devices.</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>
<li>In Eclipse, AVD Manager <img src="{@docRoot}images/tools/avd_manager.png"
style="vertical-align:baseline;margin:0" /> in the 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>In the <em>Android Virtual 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>
@@ -147,7 +150,8 @@ Give it a name, a platform target, an SD card size, and a skin (HVGA is default)
</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>
Run <img src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" />
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>
@@ -163,7 +167,8 @@ variable, then execute:
</ol>
<p>To start adding stuff to the app, continue to the <a href="building-ui.html">next
<p>That's how you build and run your Android app on the emulator!
To start developing, continue to the <a href="building-ui.html">next
lesson</a>.</p>

137
docs/html/training/basics/firstapp/starting-activity.jd
View File

@@ -43,8 +43,8 @@ SDK</a></li>
<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 field 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>
code to <code>MainActivity</code> that
starts a new activity when the user clicks the Send button.</p>
<h2 id="RespondToButton">Respond to the Send Button</h2>
@@ -64,13 +64,13 @@ attribute to the {@link android.widget.Button &lt;Button>} element:</p>
<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>
android:onClick}</a> attribute’s value, <code>"sendMessage"</code>, is the name of a method in your
activity that the system calls when the user clicks the button.</p>
<p>Add the corresponding method inside the <code>MyFirstActivity</code> class:</p>
<p>Open the <code>MainActivity</code> class and add the corresponding method:</p>
<pre>
/** Called when the user selects the Send button */
/** Called when the user clicks the Send button */
public void sendMessage(View view) {
// Do something in response to button
}
@@ -79,7 +79,7 @@ public void sendMessage(View view) {
<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
<p>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>
@@ -99,11 +99,11 @@ another activity.</p>
<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
app’s "intent to do something." You can use intents 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>
an activity called {@code DisplayMessageActivity}:</p>
<pre>
Intent intent = new Intent(this, DisplayMessageActivity.class);
@@ -127,7 +127,7 @@ specifies the exact app component to which the intent should be given. However,
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
{@link android.content.Intent} parameters. For more information, see the class about <a
href="{@docRoot}training/basics/intents/index.html">Interacting with Other Apps</a>.</p>
</div>
</div>
@@ -136,9 +136,9 @@ href="{@docRoot}training/basics/intents/index.html">Interacting with Other Apps<
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
<p>An intent not only allows you to start another activity, but it 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>
{@link android.widget.EditText} element and add its text value to the intent:</p>
<pre>
Intent intent = new Intent(this, DisplayMessageActivity.class);
@@ -148,37 +148,36 @@ 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>
pairs called <em>extras</em>. The {@link android.content.Intent#putExtra putExtra()} method takes the
key name in the first parameter 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
<p>In order for the next activity to query the extra data, you should define your key using a
public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code
MyFirstActivity} class:</p>
MainActivity} class:</p>
<pre>
public class MyFirstActivity extends Activity {
public final static String EXTRA_MESSAGE = "com.example.myapp.MESSAGE";
public class MainActivity extends Activity {
public final static String EXTRA_MESSAGE = "com.example.myfirstapp.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>
<p>It's generally a good practice to define keys for intent extras using your app's package name
as a prefix. This ensures they are 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}
startActivity()} and pass it your {@link android.content.Intent}. 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
<p>With this new code, 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 */
/** Called when the user clicks the Send button */
public void sendMessage(View view) {
Intent intent = new Intent(this, DisplayMessageActivity.class);
EditText editText = (EditText) findViewById(R.id.edit_message);
@@ -195,20 +194,48 @@ 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>
<div class="figure" style="width:400px">
<img src="{@docRoot}images/training/firstapp/adt-new-activity.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The new activity wizard in Eclipse.</p>
</div>
<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>To create a new activity using Eclipse:</p>
<p>Inside the class, add the {@link android.app.Activity#onCreate onCreate()} callback method:</p>
<ol>
<li>Click New <img src="{@docRoot}images/tools/eclipse-new.png"
style="vertical-align:baseline;margin:0" /> in the toolbar.</li>
<li>In the window that appears, open the <strong>Android</strong> folder
and select <strong>Android Activity</strong>. Click <strong>Next</strong>.</li>
<li>Select <strong>BlankActivity</strong> and click <strong>Next</strong>.</li>
<li>Fill in the activity details:
<ul>
<li><em>Project</em>: MyFirstApp</li>
<li><em>Activity Name</em>: DisplayMessageActivity</li>
<li><em>Layout Name</em>: activity_display_message</li>
<li><em>Navigation Type</em>: None</li>
<li><em>Hierarchial Parent</em>: com.example.myfirstapp.MainActivity</li>
<li><em>Title</em>: My Message</li>
</ul>
<p>Click <strong>Finish</strong>.</p>
</li>
</ol>
<p>If you're using a different IDE or the command line tools, create a new file named
{@code DisplayMessageActivity.java} in the project's <code>src/</code> directory, next to
the original {@code MainActivity.java} file.</p>
<p>Open the {@code DisplayMessageActivity.java} file. If you used Eclipse to create it, the class
already includes an implementation of the required {@link android.app.Activity#onCreate onCreate()}
method. There's also an implemtation of the {@link android.app.Activity#onCreateOptionsMenu
onCreateOptionsMenu()} method, but
you won't need it for this app so you can remove it. The class should look like this:</p>
<pre>
public class DisplayMessageActivity extends Activity {
&#64;Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_display_message);
}
}
</pre>
@@ -216,7 +243,7 @@ public class DisplayMessageActivity extends Activity {
<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>
perform initial setup for the activity components.</p>
@@ -226,22 +253,39 @@ initialize essential activity components.</p>
<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>
<p>When you use the Eclipse tools to create the activity, it creates a default entry. It should
look like this:</p>
<pre>
&lt;application ... >
&lt;activity android:name="com.example.myapp.DisplayMessageActivity" />
...
&lt;activity
android:name=".DisplayMessageActivity"
android:label="@string/title_activity_display_message" >
&lt;meta-data
android:name="android.support.PARENT_ACTIVITY"
android:value="com.example.myfirstapp.MainActivity" />
&lt;/activity>
&lt;/application>
</pre>
<p>The <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code
&lt;meta-data>}</a> element declares the name of this activity's parent activity
within the app's logical hierarchy. The Android <a
href="{@docRoot}tools/extras/support-library.html">Support Library</a> uses this information
to implement default navigation behaviors, such as <a
href="{@docRoot}design/patterns/navigation.html">Up navigation</a>.</p>
<p class="note"><strong>Note:</strong> During <a
href="{@docRoot}sdk/installing/adding-packages.html">installation</a>, you should have downloaded
the latest Support Library. Eclipse automatically includes this library in your app project (you
can see the library's JAR file listed under <em>Android Dependencies</em>). If you're not using
Eclipse, you may need to manually add the library to your project&mdash;follow this guide for <a
href="{@docRoot}tools/extras/support-library.html#SettingUp">setting up the Support Library</a>.</p>
<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
clicking the Send button starts the
second activity, but it doesn't show anything yet.</p>
@@ -249,15 +293,15 @@ second activity, but it doesn't show anything yet.</p>
<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
activity by calling {@link android.app.Activity#getIntent()} and retrieve the 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>
method, get the intent and extract the message delivered by {@code MainActivity}:</p>
<pre>
Intent intent = getIntent();
String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE);
String message = intent.getStringExtra(MainActivity.EXTRA_MESSAGE);
</pre>
@@ -279,22 +323,23 @@ public void onCreate(Bundle savedInstanceState) {
// Get the message from the intent
Intent intent = getIntent();
String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE);
String message = intent.getStringExtra(MainActivity.EXTRA_MESSAGE);
// Create the text view
TextView textView = new TextView(this);
textView.setTextSize(40);
textView.setText(message);
// Set the text view as the activity layout
setContentView(textView);
}
</pre>
<p>You can now run the app, type a message in the text field, press Send, and view the message on
the second activity.</p>
<p>You can now run the app. When it opens, type a message in the text field, click Send,
and the message appears 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
<p class="img-caption"><strong>Figure 2.</strong> Both activities in the final app, running
on Android 4.0.
<p>That's it, you've built your first Android app!</p>