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

docs: Training refactor for Android Studio [CP]

Browse Source 
Cherrypick from lmp-docs hange-Id: I4c396b1a6b689a32b5a3328e9948f363ebb1e37d, from lmp-dev Change-Id: I830da649d9fac2b87eff5ee5cfc3422d5ab65ffc, Cherrypick from klp-modular-docs Change-Id: Ifaae51e4fa3afbef3d81d260135fd348a6ccb612

Change-Id: I09a9473d73eb9c27ee6966b2a0e1cd736575db06
(cherry picked from commit 8c068aeee0)
This commit is contained in:
Scott Rowe
2014-05-19 16:50:47 -07:00
committed by Joe Fernandez
parent caacc895d7
commit e829d8fca6
10 changed files with 582 additions and 467 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/screens_support/as-mac-avds-config.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

BIN
docs/html/images/tools/as-hide-side.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.5 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/html/images/training/firstapp/studio-setup-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

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

@@ -8,9 +8,9 @@ helpoutsWidget=true
<!-- This is the training bar -->
<div id="tb-wrapper">
<div id="tb">
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
@@ -27,16 +27,18 @@ helpoutsWidget=true
<li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li>
</ul>
</div>
</div>
</div>
</div>
<p>In this lesson, you create a layout in XML that includes a text field and a
button. In the next lesson, your app responds when the button is pressed by sending the
content of the text field to another activity.</p>
<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 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
<a href="{@docRoot}guide/topics/ui/controls/text.html">text fields</a>.
{@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>
@@ -44,6 +46,8 @@ grid or a vertical list.</p>
android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML using
a hierarchy of UI elements.</p>
<p>Layouts are subclasses of the {@link android.view.ViewGroup}. In this exercise, you'll work with
a {@link android.widget.LinearLayout}.</p>
<div class="sidebox-wrapper">
<div class="sidebox">
@@ -63,33 +67,32 @@ Devices</a>.</p>
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 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">Create a Linear Layout</h2>
<p>Open the <code>fragment_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 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>fragment_main.xml</em> tab at
the bottom of the screen to open the XML editor.</p>
<ol>
<li>In Android Studio, from the <code>res/layout</code> directory, open the <code>activity_my.xml</code>
file.
<p>The BlankActivity template you chose when you created this project includes the
<code>fragment_main.xml</code> file with a {@link
android.widget.RelativeLayout} root view and a {@link android.widget.TextView} child view.</p>
<code>activity_my.xml</code> file with a {@link android.widget.RelativeLayout} root view and a
{@link android.widget.TextView} child view.</p>
</li>
<li>In the <strong>Preview</strong> pane, click the Hide icon <img src="{@docRoot}images/tools/as-hide-side.png"
style="vertical-align:baseline;margin:0; max-height:1.5em" /> to close the Preview pane.
<p> In Android Studio, when you open a layout file, you’re first shown
the Preview pane. Clicking elements in this pane opens the WYSIWYG tools in the Design pane. For
this lesson, you’re going to work directly with the XML.</p></li>
<li>Delete the {@link android.widget.TextView &lt;TextView>} element.</li>
<li>Change the {@link android.widget.RelativeLayout &lt;RelativeLayout>} element to
{@link android.widget.LinearLayout &lt;LinearLayout>}.</li>
<li>Add the <a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">
{@code android:orientation}</a> attribute and set it to <code>"horizontal"</code>.</li>
<li>Remove the {@code android:padding} attributes and the {@code tools:context} attribute.
</ol>
<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> attribute and set it to <code>"horizontal"</code>.
The result looks like this:</p>
</p>The result looks like this:</p>
<p class="code-caption">res/layout/activity_my.xml</p>
<pre>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
@@ -104,9 +107,9 @@ android.view.ViewGroup}) that lays out child views in either a vertical or horiz
as specified by the <a
href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code
android:orientation}</a> attribute. Each child of a {@link android.widget.LinearLayout} appears on
the screen in the order in which it appears in the XML.</p>
the screen in the order in which it appears in the XML.</p>
<p>The other two attributes, <a
<p>Two other attributes, <a
href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code
android:layout_width}</a> and <a
href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code
@@ -122,45 +125,32 @@ or height to <em>match</em> the width or height of the parent view.</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>}.</p>
<p>As with every {@link android.view.View} object, you must define certain XML attributes to specify
the {@link android.widget.EditText} object's properties.</p>
<p>Like every {@link android.view.View} object, you must define certain XML attributes to specify
the {@link android.widget.EditText} object's properties. Here’s how you should declare it
inside the {@link android.widget.LinearLayout &lt;LinearLayout>} element:</p>
<ol>
<li>In the <code>activity_my.xml</code> file, within the
{@link android.widget.LinearLayout &lt;LinearLayout>} element, define an
{@link android.widget.EditText &lt;EditText>} element with the <code>id</code> attribute
set to <code>@+id/edit_message</code>.</li>
<li>Define the <code>layout_width</code> and <code>layout_height</code> attributes as
<code>wrap_content</code>.</li>
<li>Define a <code>hint</code> attribute as a string object named <code>edit_message</code>.</li>
</ol>
<p>The {@link android.widget.EditText &lt;EditText>} element should read as follows:</p>
<p class="code-caption">res/layout/activity_my.xml</p>
<pre>
&lt;EditText android:id="@+id/edit_message"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:hint="@string/edit_message" />
&lt;EditText android:id="@+id/edit_message"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:hint="@string/edit_message" />
</pre>
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>About resource objects</h3>
<p>A resource object is simply a unique integer name that's associated with an app resource,
such as a bitmap, layout file, or string.</p>
<p>Every resource has a
corresponding resource object defined in your project's {@code gen/R.java} file. You can use the
object names in the {@code R} class to refer to your resources, such as when you need to specify a
string value for the <a
href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code android:hint}</a>
attribute. You can also create arbitrary resource IDs that you associate with a view using the <a
href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> attribute,
which allows you to reference that view from other code.</p>
<p>The SDK tools generate the {@code R.java} each time you compile your app. You should never
modify this file by hand.</p>
<p>For more information, read the guide to <a
href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</p>
</div>
</div>
<p>About these attributes:</p>
<p>Here are the {@link android.widget.EditText &lt;EditText>} attributes you added:</p>
<dl>
<dt><a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a></dt>
@@ -172,11 +162,31 @@ lesson).
XML. It is followed by the resource type ({@code id} in this case), a slash, then the resource name
({@code edit_message}).</p>
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Resource Objects</h3>
<p>A resource object is a unique integer name that's associated with an app resource,
such as a bitmap, layout file, or string.</p>
<p>Every resource has a
corresponding resource object defined in your project's {@code gen/R.java} file. You can use the
object names in the {@code R} class to refer to your resources, such as when you need to specify a
string value for the <a
href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code android:hint}</a>
attribute. You can also create arbitrary resource IDs that you associate with a view using the <a
href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> attribute,
which allows you to reference that view from other code.</p>
<p>The SDK tools generate the {@code R.java} file 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>
<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,
android.widget.EditText} element. With the resource ID 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
@@ -209,26 +219,25 @@ 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 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 resource.</p>
<p>By default, your Android project includes a string resource file at
<code>res/values/strings.xml</code>. Add a new string named
<code>"edit_message"</code> and set the value to "Enter a message." (You can delete
the "hello_world" string.)</p>
<code>res/values/strings.xml</code>. Here, you'll add a new string named
<code>"edit_message"</code> and set the value to "Enter a message."</p>
<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>
<ol>
<li>In Android Studio, from the <code>res/values</code> directory, open <code>strings.xml</code>.</li>
<li>Add a line for a string named <code>"edit_message"</code> with the value, "Enter a message".
</li>
<li>Add a line for a string named <code>"button_send"</code> with the value, "Send".
<p>You'll create the button that uses this string in the next section.</p>
</li>
<li>Remove the line for the <code>"hello world"</code> string.</li>
</ol>
<p>The result for <code>strings.xml</code> looks like this:</p>
<p class="code-caption">res/values/strings.xml</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
@@ -240,35 +249,59 @@ the "hello_world" string.)</p>
&lt;/resources>
</pre>
<p>For text in the user interface, always specify each string as
a resource. String resources allow you to manage all UI text in a single location,
which makes the text easier to find and update. Externalizing the strings also allows you to
localize your app to different languages by providing alternative definitions for each
string resource.</p>
<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 Different Devices</a>
class.</p>
<h2 id="Button">Add a Button</h2>
<p>Now add a {@link android.widget.Button &lt;Button>} to the layout, immediately following the
{@link android.widget.EditText &lt;EditText>} element:</p>
<ol>
<li>In Android Studio, from the <code>res/layout</code> directory, edit the <code>activity_my.xml</code>
file.</li>
<li>Within the
{@link android.widget.LinearLayout &lt;LinearLayout>} element, define a
{@link android.widget.Button &lt;Button>} element immediately following the
{@link android.widget.EditText &lt;EditText>} element.</li>
<li>Set the button's width and height attributes to <code>"wrap_content"</code> so
the button is only as big as necessary to fit the button's text label.</li>
<li>Define the button's text label with the <a
href="{@docRoot}reference/android/widget/TextView.html#attr_android:text">{@code
android:text}</a> attribute; set its value to the <code>button_send</code> string
resource you defined in the previous section.</li>
</ol>
<p>Your {@link android.widget.LinearLayout &lt;LinearLayout>} should look like this:</p>
<p class="code-caption">res/layout/activity_my.xml</p>
<pre>
&lt;Button
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="horizontal" &gt;
&lt;EditText android:id="@+id/edit_message"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/button_send" />
android:hint="@string/edit_message" /&gt;
&lt;Button
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/button_send" /&gt;
&lt;/LinearLayout&gt;
</pre>
<p>The height and width are set to <code>"wrap_content"</code> so the button is only as big as
necessary to fit the button's text. This button doesn't need the
<p class="note"><strong>Note:</strong> This button doesn't need the
<a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a>
attribute, because it won't be referenced from the activity code.</p>
<h2 id="Weight">Make the Input Box Fill in the Screen Width</h2>
<p>The layout is currently designed so that both the {@link android.widget.EditText} and {@link
android.widget.Button} widgets are only as big as necessary to fit their content, as shown in
figure 2.</p>
@@ -279,7 +312,7 @@ 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. So, it would be nice to fill the unused screen width
something longer. 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
@@ -288,9 +321,9 @@ android:layout_weight}</a> attribute.</p>
<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
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
parts soda, 1 part syrup" means two-thirds of the drink is soda. 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 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
@@ -298,38 +331,49 @@ 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 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>
given the space they require.</p>
<h2 id="Weight">Make the Input Box Fill in the Screen Width</h2>
<p>To fill the remaining space in your layout with the {@link android.widget.EditText} element, do
the following:</p>
<ol>
<li>In the <code>activity_my.xml</code> file, assign the
{@link android.widget.EditText &lt;EditText>} element's <code>layout_weight</code> attribute a value
of <code>1</code>.</li>
<li>Also, assign {@link android.widget.EditText &lt;EditText>} element's <code>layout_width</code>
attribute a value of <code>0dp</code>.
<p class="code-caption">res/layout/activity_my.xml</p>
<pre>
&lt;EditText
android:layout_weight="1"
... />
&lt;EditText
android:layout_weight="1"
android:layout_width="0dp"
... /&gt;
</pre>
<p>In order to improve the layout efficiency when you specify the weight, you should change the
<p>To improve the layout efficiency when you specify the weight, you should change the
width of the {@link android.widget.EditText} to be
zero (0dp). Setting the width to zero improves layout performance because using
<code>"wrap_content"</code> as the width requires the system to calculate a width that is
ultimately irrelevant because the weight value requires another width calculation to fill the
remaining space.</p>
<pre>
&lt;EditText
android:layout_weight="1"
android:layout_width="0dp"
... />
</pre>
<p>Figure 3
shows the result when you assign all weight to the {@link android.widget.EditText} element.</p>
<img src="{@docRoot}images/training/firstapp/edittext_gravity.png" />
<p class="img-caption"><strong>Figure 3.</strong> The {@link android.widget.EditText} widget is
given all the layout weight, so fills the remaining space in the {@link
given all the layout weight, so it fills the remaining space in the {@link
android.widget.LinearLayout}.</p>
<p>Here’s how your complete layout file should now look:</p>
</li>
</ol>
<p>Here’s how your complete <code>activity_my.xml</code>layout file should now look:</p>
<p class="code-caption">res/layout/activity_my.xml</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
@@ -349,13 +393,16 @@ android.widget.LinearLayout}.</p>
&lt;/LinearLayout>
</pre>
<h2>Run Your App</h2>
<p>This layout is applied by the default {@link android.app.Activity} class
that the SDK tools generated when you created the project, so you can now run the app to see the
that the SDK tools generated when you created the project. Run the app to see the
results:</p>
<ul>
<li>In Eclipse, click Run <img src="{@docRoot}images/tools/eclipse-run.png"
style="vertical-align:baseline;margin:0" /> from the toolbar.</li>
<li>In Android Studio, from the toolbar, click <strong>Run</strong>
<img src="{@docRoot}images/tools/as-run.png"
style="vertical-align:baseline;margin:0; max-height:1em" />.</li>
<li>Or from a command line, change directories to the root of your Android project and
execute:
<pre>
@@ -364,7 +411,8 @@ adb install bin/MyFirstApp-debug.apk
</pre></li>
</ul>
<p>Continue to the next lesson to learn how you can respond to button presses, read content
<p>Continue to the <a href="starting-activity.html">next
lesson</a> to learn how to respond to button presses, read content
from the text field, start another activity, and more.</p>

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

@@ -17,7 +17,7 @@ next.link=running-app.html
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#Eclipse">Create a Project with Eclipse</a></li>
<li><a href="#Studio">Create a Project with Android Studio</a></li>
<li><a href="#CommandLine">Create a Project with Command Line Tools</a></li>
</ol>
@@ -38,97 +38,145 @@ app. The Android SDK tools make it easy to start a new Android project with a se
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
shows how to create a new project either using Android Studio 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 also have the <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT
plugin</a> installed (version 22.6.2 or higher). If you don't have these, follow the guide to <a
you're using Android Studio, you should also have <a href="{@docRoot}sdk/installing/studio.html">
Android Studio</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>
<h2 id="Studio">Create a Project with Android Studio</h2>
<ol>
<li>Click <strong>New</strong> <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,
select <strong>Android Application Project</strong>, and click <strong>Next</strong>.</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 Android App Project wizard in Eclipse.</p>
</div>
<li>Fill in the form that appears:
<li>In Android Studio, create a new project:
<ul>
<li>If you don't have a project opened, in the <strong>Welcome</strong> screen, click <strong>
New Project</strong>.</li>
<li>If you have a project opened, from the <strong>File</strong> menu, select <strong>New
Project</strong>.</li>
</ul>
</li>
<div class="figure" style="width:420px">
<img src="{@docRoot}images/training/firstapp/studio-setup-1.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> Configuring a new project in Android Studio.</p>
</div>
<li>Under <strong>Configure your new project</strong>, fill in the fields as shown in figure 1
and click <strong>Next</strong>.
<p>It will probably be easier to follow these lessons if you use the same values as shown.</p>
<ul>
<li><strong>Application Name</strong> is the app name that appears to users.
For this project, use "My First App."</p></li>
<li><strong>Project Name</strong> is the name of your project directory and the name visible in Eclipse.</li>
<li><strong>Package Name</strong> 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 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><strong>Minimum Required SDK</strong> is the lowest version of Android that your app supports,
indicated using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels"
>API level</a>.
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 (as
discussed in <a href="{@docRoot}training/basics/supporting-devices/platforms.html"
>Supporting Different Platform Versions</a>).
Leave this set to the default value for this project.
</li>
<li><strong>Target SDK</strong> indicates the highest version of Android (also using the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels"
>API level</a>) with which you
have tested with your application.
<p>As new versions of Android become available, you should
test your app on the new version and update this value to match the latest API level
in order to take advantage of new platform features.</p>
</li>
<li><strong>Compile With</strong> 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><strong>Theme</strong> specifies the Android UI style to apply for your app. You can leave
this alone.</li>
For this project, use "My First App."</li>
<li><strong>Company domain</strong> provides a qualifier that will be appended to the package
name; Android Studio will remember this qualifier for each new project you create.</li>
<li><strong>Package name</strong> is the fully qualified name for the project (following the
same rules as those for naming packages in the Java programming language). Your package name
must be unique across all packages installed on the Android system. You can <strong>
Edit</strong> this value independently from the application name or the company
domain.</li>
<li><strong>Project location</strong> is the directory on your system that holds the project
files.</li>
</ul>
<p>Click <strong>Next</strong>.</p>
</li>
<li>On the next screen to configure the project, leave the default selections and click
<strong>Next</strong>.</li>
<li>The next screen can 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>
<li>Under <strong>Select the form factors your app will run on</strong>, check the box for <strong>
Phone and Tablet</strong>.</li>
<li>For <strong>Minimum SDK</strong>, select <strong>API 8: Android 2.2 (Froyo)</strong>.
<p>The Minimum Required SDK is the earliest version of Android that your app supports,
indicated using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">
API level</a>. 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 (as
discussed in <a href="{@docRoot}training/basics/supporting-devices/platforms.html">
Supporting Different Platform Versions</a>).</p></li>
<li>Leave all of the other options (TV, Wear, and Glass) unchecked and click <strong>Next.</strong></li>
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Activities</h3>
<p>An activity is one of the distinguishing features of the Android framework. Activities
provide the user with access to your app, and there may be many activities. An application
will usually have a main activity for when the user launches the application, another
activity for when she selects some content to view, for example, and other activities for
when she performs other tasks within the app. See <a href="{@docRoot}guide/components/activities.html">
Activities</a> for more information.</p>
</div>
</div>
<li>Under <strong>Add an activity to your project</strong>, select <strong>Blank Activity</strong>
and click <strong>Next</strong>.</li>
<li>Under <strong>Describe the new activity for your project</strong>, leave the fields as they
are and click <strong>Finish</strong>.</li>
</ol>
<p>Your Android project is now a basic "Hello World" app that contains some default files.
To run the app, continue to the <a href="running-app.html">next lesson</a>.</p>
<p>Your Android project is now a basic "Hello World" app that contains some default files. Take a
moment to review the most important of these:</p>
<dl>
<dt><code>app/src/main/res/layout/activity_my.xml</code></dt>
<dd>This is the XML layout file for the activity you added when you created the project with Android
Studio. Following the New Project workflow, Android Studio presents this file with both a text
view and a preview of the screen UI. The file includes some default settings and a <code>TextView</code>
element that displays the message, "Hello world!"</dd>
<dt><code>app/src/main/java/com.mycompany.myfirstapp/MyActivity.java</code></dt>
<dd>A tab for this file appears in Android Studio when the New Project workflow finishes. When you
select the file you see the class definition for the activity you created. When you build and
run the app, the {@link android.app.Activity} class starts the activity and loads the layout file
that says "Hello World!"</dd>
<dt><code>app/src/res/AndroidManifest.xml</code></dt>
<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 revisit
this file as you follow these lessons and add more components to your app.</dd>
<dt><code>app/build.gradle</code></dt>
<dd>Android Studio uses Gradle to compile and build your app. There is a <code>build.gradle</code>
file for each module of your project, as well as a <code>build.gradle</code> file for the entire
project. Usually, you're only interested in the <code>build.gradle</code> file for the module,
in this case the <code>app</code> or application module. This is where your app's build dependencies
are set, including the <code>defaultConfig</code> settings:
<ul>
<li><code>compiledSdkVersion</code> 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 this 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><code>applicationId</code> is the fully qualified package name for your application that
you specified during the New Project workflow.</li>
<li><code>minSdkVersion</code> is the Minimum SDK version you specified during the New Project
workflow. This is the earliest version of the Android SDK that your app supports.</li>
<li><code>targetSdkVersion</code> indicates the highest version of Android with which you have
tested your application. As new versions of Android become available, you should
test your app on the new version and update this value to match the latest API level and
thereby take advantage of new platform features. For more information, read
<a href="{@docRoot}training/basics/supporting-devices/platforms.html">Supporting Different
Platform Versions</a>.</li>
</ul>
<p>See <a href="{@docRoot}sdk/installing/studio-build.html">Building Your Project with Gradle</a>
for more information about Gradle.</p></dd>
</dl>
<p>Note also the <code>/res</code> subdirectories that contain the
<a href="{@docRoot}guide/topics/resources/overview.html">resources</a> for your application:</p>
<dl>
<dt><code>drawable-hdpi/</code></dt>
<dd>Directory for drawable objects (such as bitmaps) that are designed for high-density
(hdpi) screens. Other drawable directories contain assets designed for other screen densities.
Here you'll find the ic_launcher.png that appears when you run the default app.</dd>
<dt><code>layout/</code></dt>
<dd>Directory for files that define your app's user interface like activity_my.xml,
discussed above, which describes a basic layout for the MyActivity class.</dd>
<dt><code>values/</code></dt>
<dd>Directory for other XML files that contain a collection of resources, such as
string and color definitions. The strings.xml file defines the "Hello world!" string that
displays when you run the default app.</dd>
</dl>
<p>To run 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
<p>If you're not using the Android Studio IDE, you can instead create your project
using the SDK tools from a command line:</p>
<ol>
@@ -136,32 +184,32 @@ using the SDK tools from a command line:</p>
<li>Execute:
<pre class="no-pretty-print">android list targets</pre>
<p>This prints a list of the available Android platforms that you’ve downloaded for your SDK. Find
the platform against which you want to compile your app. Make a note of the target id. We
the platform against which you want to compile your app. Make a note of the target ID. We
recommend that you select the highest version possible. You can still build your app to
support older versions, but setting the build target to the latest version allows you to optimize
your app for the latest devices.</p>
<p>If you don't see any targets listed, you need to
install some using the Android SDK
Manager tool. See <a href="{@docRoot}sdk/installing/adding-packages.html">Adding Platforms
and Packages</a>.</p></li>
Manager tool. See <a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK
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 MainActivity \
--path &lt;path-to-workspace>/MyFirstApp --activity MyActivity \
--package com.example.myfirstapp
</pre>
<p>Replace <code>&lt;target-id></code> with an id from the list of targets (from the previous step)
<p>Replace <code>&lt;target-id></code> with an ID from the list of targets (from the previous step)
and replace
<code>&lt;path-to-workspace></code> with the location in which you want to save your Android
projects.</p></li>
</ol>
<p>Your Android project is now a basic "Hello World" app that contains some default files.
To run the app, continue to the <a href="running-app.html">next lesson</a>.</p>
<p class="note"><strong>Tip:</strong> Add the <code>platform-tools/</code> as well as the
<code>tools/</code> directory to your <code>PATH</code> environment variable.</p>
<p>Your Android project is now a basic "Hello World" app that contains some default files.
To run the app, continue to the <a href="running-app.html">next lesson</a>.</p>

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

@@ -15,9 +15,8 @@ helpoutsWidget=true
<h2>Dependencies and prerequisites</h2>
<ul>
<li><a href="http://developer.android.com/sdk/index.html">Android SDK</a></li>
<li><a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin</a> 22.6.2 or higher
(if you're using Eclipse)</li>
<li><a href="{@docRoot}sdk/index.html">Android SDK</a></li>
<li><a href="{@docRoot}sdk/installing/studio.html">Android Studio</a></li>
</ul>
</div>
@@ -29,16 +28,19 @@ helpoutsWidget=true
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>
<h2>Set Up Your Environment</h2>
<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.</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>
<li>Download the <a href="{@docRoot}sdk/index.html">Android SDK</a>.</li>
<li>Install <a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>.</li>
<li>Download the latest SDK tools and platforms using the <a href="{@docRoot}tools/help/sdk-manager.html">
SDK Manager</a>.</li>
</ol>
<p class="note"><strong>Note:</strong> Make sure you install the most recent versions of the ADT
plugin and the Android SDK before you start this class. The procedures described in this class may
<p class="note"><strong>Note:</strong> Make sure you install the most recent versions of Android
Studio and the Android SDK before you start this class. The procedures described in this class may
not apply to earlier versions.</p>
<p>If you haven't already done these tasks, start by downloading the

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

@@ -11,9 +11,9 @@ helpoutsWidget=true
<!-- This is the training bar -->
<div id="tb-wrapper">
<div id="tb">
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
@@ -28,85 +28,32 @@ helpoutsWidget=true
<li><a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a></li>
<li><a href="{@docRoot}tools/projects/index.html">Managing Projects</a></li>
</ul>
</div>
</div>
</div>
</div>
<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
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
real device and on the Android emulator, and in both cases with either Eclipse or the command line
tools.</p>
<p>Before you run your app, you should be aware of a few directories and files in the Android
project:</p>
<dl>
<dt><code>AndroidManifest.xml</code></dt>
<dd>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.
<p>One of the most important elements your manifest should include is the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk>}</a>
element. This declares your app's compatibility with different Android versions using the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
and <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a>
attributes. For your first app, it should look like this:</p>
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
&lt;uses-sdk android:minSdkVersion="8" android:targetSdkVersion="19" />
...
&lt;/manifest>
</pre>
<p>You should always set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a>
as high as possible and test your app on the corresponding platform version. For more information,
read <a href="{@docRoot}training/basics/supporting-devices/platforms.html">Supporting Different
Platform Versions</a>.</p>
</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 <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
(hdpi) screens. Other drawable directories contain assets designed for other screen densities.</dd>
<dt><code>layout/</code></dt>
<dd>Directory for files that define your app's user interface.</dd>
<dt><code>values/</code></dt>
<dd>Directory for other various XML files that contain a collection of resources, such as
string and color definitions.</dd>
</dl>
</dd>
</dl>
<p>When you build and run the default Android 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>
<p>How you run your app depends on two things: whether you have a real device running Android and
whether you're using Android Studio. This lesson shows you how to install and run your app on a
real device and on the Android emulator, and in both cases with either Android Studio or the command
line tools.</p>
<h2 id="RealDevice">Run on a Real Device</h2>
<p>If you have a real Android-powered device, here's how you can install and run your app:</p>
<p>If you have a device running Android, here's how to install and run your app.</p>
<h3>Set up your device</h3>
<ol>
<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>
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>Enable <strong>USB debugging</strong> on your device.
<ul>
<li>On most devices running Android 3.2 or older, you can find the option under
@@ -121,19 +68,20 @@ Drivers</a> document.</li>
</li>
</ol>
<p>To run the app from Eclipse:</p>
<h3>Run the app from Android Studio</h3>
<ol>
<li>Open one of your project's files and click
<strong>Run</strong> <img
src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" />
src="{@docRoot}images/tools/as-run.png" style="vertical-align:baseline;margin:0; max-height:1em" />
from the toolbar.</li>
<li>In the <strong>Run as</strong> window that appears, select
<strong>Android Application</strong> and click <strong>OK</strong>.</li>
<li>In the <strong>Choose Device</strong> window that appears, select the
<strong>Choose a running device</strong> radio button, select your device, and click <strong>OK
</strong>.</li>
</ol>
<p>Eclipse installs the app on your connected device and starts it.</p>
<p>Android Studio installs the app on your connected device and starts it.</p>
<p>Or to run your app from a command line:</p>
<h3>Run the app from a command line</h3>
<ol>
<li>Change directories to the root of your Android project and execute:
@@ -141,7 +89,7 @@ from the toolbar.</li>
<li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your
<code>PATH</code> environment variable, then execute:
<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li>
<li>On your device, locate <em>MyFirstActivity</em> and open it.</li>
<li>On your device, locate <em>MyFirstApp</em> and open it.</li>
</ol>
<p>That's how you build and run your Android app on a device!
@@ -152,64 +100,67 @@ lesson</a>.</p>
<h2 id="Emulator">Run on the Emulator</h2>
<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>
<p>Whether you're using Android Studio 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 a specific
device.</p>
<div class="figure" style="width:457px">
<img src="{@docRoot}images/screens_support/avds-config.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The AVD Manager showing a few virtual
devices.</p>
<img src="{@docRoot}images/screens_support/as-mac-avds-config.png" />
<p class="img-caption"><strong>Figure 1.</strong> The AVD Manager showing a virtual device.</p>
</div>
<p>To create an AVD:</p>
<h3>Create an AVD</h3>
<ol>
<li>Launch the Android Virtual Device Manager:
<ol type="a">
<li>In Eclipse, click Android Virtual Device Manager
<img src="{@docRoot}images/tools/avd_manager.png"
style="vertical-align:baseline;margin:0" /> from 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>
<ul>
<li>In the Android Studio tool bar, click the Android Virtual Device Manager icon
<img src="{@docRoot}images/tools/avd-manager-studio.png"
style="vertical-align:baseline;margin:0; max-height:1em" />.</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>
</ul>
</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>
<li>Select the new AVD from the <em>Android Virtual Device Manager</em> and click
<strong>Start</strong>.</li>
<li>After the emulator boots up, unlock the emulator screen.</li>
<li>In the <strong>Android Virtual Device Manager</strong> window, click <strong>Create</strong>.</li>
<li>Enter an <strong>AVD Name</strong>.</li>
<li>Select a <strong>Device</strong> type.
<p>When you select a device type, most of the fields auto-populate.</p>
<li>For <strong>Skin</strong> select <strong>HVGA</strong>.</li>
<li>For <strong>SD Card</strong>, enter something small, like 10 MiB.
<p>It really doesn't matter what you enter here since you're not using any storage. But if you
reuse this AVD, you might have to adjust this setting.</p></li>
<li>Ignore the <strong>Emulation Options</strong> and click <strong>OK</strong>.</li>
<li>In the <strong>Result</strong> screen, click <strong>OK</strong>.</li>
<li>Close the <strong>Android Virtual Device Manager</strong> window.</li>
</ol>
<p>To run the app from Eclipse:</p>
<h3>Run the app from Android Studio</h3>
<ol>
<li>Open one of your project's files and click
<strong>Run</strong> <img
src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" />
from the toolbar.</li>
<li>In the <strong>Run as</strong> window that appears, select
<strong>Android Application</strong> and click <strong>OK</strong>.</li>
<li>In <strong>Android Studio</strong>, select your project and click <strong>Run</strong>
<img src="{@docRoot}images/tools/as-run.png" style="vertical-align:baseline;margin:0; max-height:1em" />
from the toolbar.</li>
<li>In the <strong>Choose Device</strong> window, click the <strong>Launch emulator</strong> radio
button.</li>
<li>From the <strong>Android virtual device</strong> pull-down menu, select the emulator
you created, and click <strong>OK</strong>.</li>
</ol>
<p>Eclipse installs the app on your AVD and starts it.</p>
<p>It can take a few minutes for the emulator to load itself. You may have to unlock the screen.
When you do, My First App appears on the emulator screen.</p>
<p>Or to run your app from the command line:</p>
<h3>Run your app from the command line</h3>
<ol>
<li>Change directories to the root of your Android project and execute:
<pre class="no-pretty-print">ant debug</pre></li>
<pre class="no-pretty-print">ant debug</pre></li>
<li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your
<code>PATH</code> environment
variable, then execute:
<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li>
<li>On the emulator, locate <em>MyFirstActivity</em> and open it.</li>
<code>PATH</code> environment variable, then execute:
<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li>
<li>On the emulator, locate <em>MyFirstApp</em> and open it.</li>
</ol>
<p>That's how you build and run your Android app on the emulator!
<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>

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

@@ -19,7 +19,7 @@ helpoutsWidget=true
<ol>
<li><a href="#RespondToButton">Respond to the Send Button</a></li>
<li><a href="#BuildIntent">Build an Intent</a></li>
<li><a href="#StartActivity">Start the Second Activity</a></li>
<!-- <li><a href="#StartActivity">Start the Second Activity</a></li> -->
<li><a href="#CreateActivity">Create the Second Activity</a></li>
<li><a href="#ReceiveIntent">Receive the Intent</a></li>
<li><a href="#DisplayMessage">Display the Message</a></li>
@@ -40,17 +40,20 @@ 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>MainActivity</code> that
code to <code>MyActivity</code> that
starts a new activity when the user clicks the Send button.</p>
<h2 id="RespondToButton">Respond to the Send Button</h2>
<p>To respond to the button's on-click event, open the <code>fragment_main.xml</code>
layout file and add the <a
<ol>
<li>In Android Studio, from the <code>res/layout</code> directory, edit the <code>activity_my.xml</code>
file.</li>
<li>To the {@link android.widget.Button &lt;Button>} element, add the <a
href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code android:onClick}</a>
attribute to the {@link android.widget.Button &lt;Button>} element:</p>
attribute.
<p class="code-caption">res/layout/activity_my.xml</p>
<pre>
&lt;Button
android:layout_width="wrap_content"
@@ -63,10 +66,12 @@ attribute to the {@link android.widget.Button &lt;Button>} element:</p>
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 the system calls when the user clicks the button.</p>
</li>
<li>In the <code>java/com.mycompany.myfirstapp</code> directory, open the <code>MyActivity.java</code> file.</li>
<li>Within the <code>MyActivity</code> class, add the {@code sendMessage()} method stub shown
below.
<p>Open the <code>MainActivity</code> class (located in the project's
<code>src/</code> directory) and add the corresponding method:</p>
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
/** Called when the user clicks the Send button */
public void sendMessage(View view) {
@@ -85,32 +90,40 @@ the signature must be exactly as shown. Specifically, the method must:</p>
android.view.View} that was clicked)</li>
</ul>
</li>
</ol>
<p>Next, you’ll fill in this method to read the contents of the text field and deliver that text to
another activity.</p>
<h2 id="BuildIntent">Build an Intent</h2>
<ol>
<li>In <code>MyActivity.java</code>, inside the {@code sendMessage()} method, create an
{@link android.content.Intent} to start an activity called {@code DisplayMessageActivity} with the
following code:
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
public void sendMessage(View view) {
Intent intent = new Intent(this, DisplayMessageActivity.class);
}
</pre>
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Intents</h3>
<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 intents for a wide
variety of tasks, but most often they’re used to start another activity.</p>
variety of tasks, but most often they’re used to start another activity. For more information, see
<a href="{@docRoot}guide/components/intents-filters.html ">Intents and Intent Filters</a>.</p>
</div>
</div>
<p>Inside the {@code sendMessage()} method, create an {@link android.content.Intent} to start
an activity called {@code DisplayMessageActivity}:</p>
<pre>
Intent intent = new Intent(this, DisplayMessageActivity.class);
</pre>
<p>This requires that you import the {@link android.content.Intent} class:</p>
<pre>
import android.content.Intent;
</pre>
<p class="note"><strong>Tip:</strong> In Eclipse, press Ctrl + Shift + O to import missing classes
(Cmd + Shift + O on Mac).</p>
<p class="note"><strong>Note:</strong> The reference to {@code DisplayMessageActivity}
will raise an error if you’re using an IDE such as Android Studio because the class doesn’t exist yet.
Ignore the error for now; you’ll create the class soon.</p>
<p>The constructor used here takes two parameters:</p>
<ul>
@@ -121,6 +134,19 @@ android.app.Activity} class is a subclass of {@link android.content.Context})
the {@link android.content.Intent} (in this case, the activity that should be started)
</ul>
<p>Android Studio indicates that you must import the {@link android.content.Intent} class.</p>
</li>
<li>At the top of the file, import the {@link android.content.Intent} class:
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
import android.content.Intent;
</pre>
<p class="note"><strong>Tip:</strong> In Android Studio, press Alt + Enter (option + return on Mac)
to import missing classes.</p>
</li>
<!-- I didn't think this was necessary
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Sending an intent to other apps</h3>
@@ -134,59 +160,69 @@ as long as it satisfies the meta-data specifications for the action that's speci
href="{@docRoot}training/basics/intents/index.html">Interacting with Other Apps</a>.</p>
</div>
</div>
-->
<p class="note"><strong>Note:</strong> The reference to {@code DisplayMessageActivity}
will raise an error if you’re using an IDE such as Eclipse because the class doesn’t exist yet.
Ignore the error for now; you’ll create the class soon.</p>
<p>An intent not only allows you to start another activity, but it can carry a bundle of data to the
activity as well. Inside the {@code sendMessage()} method,
<li>Inside the {@code sendMessage()} method,
use {@link android.app.Activity#findViewById findViewById()} to get the
{@link android.widget.EditText} element and add its text value to the intent:</p>
{@link android.widget.EditText} element.
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
Intent intent = new Intent(this, DisplayMessageActivity.class);
EditText editText = (EditText) findViewById(R.id.edit_message);
String message = editText.getText().toString();
intent.putExtra(EXTRA_MESSAGE, message);
public void sendMessage(View view) {
Intent intent = new Intent(this, DisplayMessageActivity.class);
EditText editText = (EditText) findViewById(R.id.edit_message);
}
</pre>
</li>
<li>At the top of the file, import the {@link android.widget.EditText} class.
<p>In Android Studio, press Alt + Enter (option + return on Mac) to import missing classes.</p>
</li>
<li>Assign the text to a local <code>message</code> variable, and use the
{@link android.content.Intent#putExtra putExtra()} method to add its text value to the intent.
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
public void sendMessage(View view) {
Intent intent = new Intent(this, DisplayMessageActivity.class);
EditText editText = (EditText) findViewById(R.id.edit_message);
String message = editText.getText().toString();
intent.putExtra(EXTRA_MESSAGE, message);
}
</pre>
<p class="note"><strong>Note:</strong>
You now need an import statement for <code>android.widget.EditText</code>.
You'll define the <code>EXTRA_MESSAGE</code> constant in a moment.</p>
<p>An {@link android.content.Intent} can carry a collection of various data types as key-value
<p>An {@link android.content.Intent} can carry data types as key-value
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 the key
for your intent's extra using a
public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code
MainActivity} class:</p>
</li>
<li>At the top of the {@code MyActivity} class, add the {@code EXTRA_MESSAGE} definition as
follows:
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
public class MainActivity extends ActionBarActivity {
public final static String EXTRA_MESSAGE = "com.example.myfirstapp.MESSAGE";
public class MyActivity extends ActionBarActivity {
public final static String EXTRA_MESSAGE = "com.mycompany.myfirstapp.MESSAGE";
...
}
</pre>
<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>
<p>For the next activity to query the extra data, you should define the key
for your intent's extra using a public constant. It's generally a good practice to define keys for
intent extras using your app's package name as a prefix. This ensures the keys are unique, in case
your app interacts with other apps.</p>
</li>
<!-- <h2 id="StartActivity">Start the Second Activity</h2> -->
<li>In the {@code sendMessage()} method, to finish the intent, call the
{@link android.app.Activity#startActivity startActivity()} method, passing it the
{@link android.content.Intent} object created in step 1.
<h2 id="StartActivity">Start the Second Activity</h2>
<p>To start an activity, call {@link android.app.Activity#startActivity
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>
</ol>
<p>With this new code, the complete {@code sendMessage()} method that's invoked by the Send
button now looks like this:</p>
<p class="code-caption">java/com.mycompany.myfirstapp/MyActivity.java</p>
<pre>
/** Called when the user clicks the Send button */
public void sendMessage(View view) {
@@ -198,70 +234,92 @@ public void sendMessage(View view) {
}
</pre>
<p>Now you need to create the {@code DisplayMessageActivity} class in order for this to
work.</p>
<p>The system receives this call and starts an instance of the {@link android.app.Activity}
specified by the {@link android.content.Intent}. Now you need to create the
{@code DisplayMessageActivity} class in order for this to work.</p>
</li>
</ol>
<h2 id="CreateActivity">Create the Second Activity</h2>
<p>All subclasses of {@link android.app.Activity} must implement the
{@link android.app.Activity#onCreate onCreate()} method. This method is where the activity receives
the intent with the message, then renders the message. Also, the
{@link android.app.Activity#onCreate onCreate()} method must define the activity
layout with the {@link android.app.Activity#setContentView setContentView()} method. This is where
the activity performs the initial setup of the activity components.</p>
<h3>Create a new activity using Android Studio</h3>
<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>
<img src="{@docRoot}images/training/firstapp/studio-new-activity.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The new activity wizard in Android Studio.</p>
</div>
<p>To create a new activity using Eclipse:</p>
<p>Android Studio includes a stub for the
{@link android.app.Activity#onCreate onCreate()} method when you create a new activity.</p>
<ol>
<li>Click <strong>New</strong> <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:
<li>In Android Studio, in the <code>java</code> directory, select the package,
<strong>com.mycompany.myfirstapp</strong>, right-click, and select
<strong>New > Activity > Blank Activity</strong>.</li>
<li>In the <strong>Choose options</strong> window, fill in the activity details:
<ul>
<li><strong>Project</strong>: MyFirstApp</li>
<li><strong>Activity Name</strong>: DisplayMessageActivity</li>
<li><strong>Layout Name</strong>: activity_display_message</li>
<li><strong>Fragment Layout Name</strong>: fragment_display_message</li>
<li><strong>Title</strong>: My Message</li>
<li><strong>Hierarchial Parent</strong>: com.example.myfirstapp.MainActivity</li>
<li><strong>Navigation Type</strong>: None</li>
<li><strong>Hierarchical Parent</strong>: com.mycompany.myfirstapp.MyActivity</li>
<li><strong>Package name</strong>: com.mycompany.myfirstapp</li>
</ul>
<p>Click <strong>Finish</strong>.</p>
</li>
<li>Open the {@code DisplayMessageActivity.java} file.
<p>The class already includes an implementation of the required
{@link android.app.Activity#onCreate onCreate()} method. You will update the implementation of this
method later. It also includes an implementation of
{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}, which handles the action
bar's <em>Up</em> behavior. Keep these two methods as they are for now.</p>
<!-- Android Studio does not create a Fragment placeholder
<p>Also, the file includes a <code>PlaceholderFragment</code> class that extends
{@link android.app.Fragment}. This activity does not implement fragments, but you might use this
later in the training. Fragments decompose application functionality and UI into reusable modules.
For more information on fragments, see the
<a href="{@docRoot}guide/components/fragments.html">Fragments API Guide</a> and follow the training,
<a href="{@docRoot}training/basics/fragments/index.html">Building A Dynamic UI with Fragments</a>.
</p>
-->
</li>
<li> Remove the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method.
<p>You won't need it for this app.</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 this
activity:</p>
<ul>
<li>The class
already includes an implementation of the required {@link android.app.Activity#onCreate onCreate()}
method. You will update the implementation of this method later.</li>
<li>There's also an implementation of the {@link android.app.Activity#onCreateOptionsMenu
onCreateOptionsMenu()} method, but
you won't need it for this app so you can remove it.</li>
<li>There's also an implementation of {@link android.app.Activity#onOptionsItemSelected
onOptionsItemSelected()} which handles the behavior for the action bar's <em>Up</em> behavior.
Keep this one the way it is.</li>
<li>There's also a <code>PlaceholderFragment</code> class that extends
{@link android.app.Fragment}. You will not need this class in the final version of this
activity.</li>
</ul>
<p>Fragments decompose application functionality and UI into reusable modules. For more
information on fragments, see the <a href="{@docRoot}guide/components/fragments.html">Fragments
API Guide</a>. The final version of this activity does not use fragments.</p>
<!-- Not needed for Android Studio
<p class="note"><strong>Note:</strong> Your activity may look different if you did not use
the latest version of the ADT plugin. Make sure you install the latest version of the
<a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT plugin</a> to complete this tutorial.</p>
-->
<p>The {@code DisplayMessageActivity} class should now look like this:</p>
<p>If you're developing with Android Studio, you can run the app now, but not much happens.
Clicking the Send button starts the second activity, but it uses
a default "Hello world" layout provided by the template. You'll soon update the
activity to instead display a custom text view.</p>
<h3>Create the activity without Android Studio</h3>
<p>If you're using a different IDE or the command line tools, do the following:</p>
<ol>
<li>Create a new file named {@code DisplayMessageActivity.java} in the project's <code>src/</code>
directory, next to the original {@code MyActivity.java} file.</li>
<li>Add the following code to the file:
<pre>
public class DisplayMessageActivity extends ActionBarActivity {
@@ -307,63 +365,44 @@ public class DisplayMessageActivity extends ActionBarActivity {
}
</pre>
<p>If you used an IDE other than Eclipse, update your {@code DisplayMessageActivity}
class with the above code.</p>
<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. This method is where you must define the activity layout
with the {@link android.app.Activity#setContentView setContentView()} method
and is where you should
perform initial setup for the activity components.</p>
<p class="note"><strong>Note:</strong> If you are using an IDE other than Eclipse, your project
<p class="note"><strong>Note:</strong> If you are using an IDE other than Android Studio, your project
does not contain the {@code activity_display_message} layout that's requested by
{@link android.app.Activity#setContentView setContentView()}. That's OK because
you will update this method later and won't be using that layout.</p>
</li>
<h3 id="AddTitle">Add the title string</h3>
<p>If you used Eclipse, you can skip to the <a href="#AddToManifest">next section</a>,
because the template provides
the title string for the new activity.</p>
<p>If you're using an IDE other than Eclipse,
add the new activity's title to the {@code strings.xml} file:</p>
<li>To your {@code strings.xml} file, add the new activity's title as follows:
<pre>
&lt;resources>
...
&lt;string name="title_activity_display_message">My Message&lt;/string>
&lt;/resources>
</pre>
</li>
<h3 id="AddToManifest">Add it to the manifest</h3>
<p>All activities must be declared in your manifest file, <code>AndroidManifest.xml</code>, using an
<a
href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity>}</a> element.</p>
<p>When you use the Eclipse tools to create the activity, it creates a default entry. If you're
using a different IDE, you need to add the manifest entry yourself. It should
look like this:</p>
<li>In your manifest file, <code>AndroidManifest.xml</code>, within the <code>Application</code>
element, add the
<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity>}</a> element
for your {@code DisplayMessageActivity} class, as follows:
<pre>
&lt;application ... >
...
&lt;activity
android:name="com.example.myfirstapp.DisplayMessageActivity"
android:name="com.mycompany.myfirstapp.DisplayMessageActivity"
android:label="@string/title_activity_display_message"
android:parentActivityName="com.example.myfirstapp.MainActivity" >
android:parentActivityName="com.mycompany.myfirstapp.MyActivity" >
&lt;meta-data
android:name="android.support.PARENT_ACTIVITY"
android:value="com.example.myfirstapp.MainActivity" />
android:value="com.mycompany.myfirstapp.MyActivity" />
&lt;/activity>
&lt;/application>
</pre>
</li>
</ol>
<p>The <a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code
android:parentActivityName}</a> attribute declares the name of this activity's parent activity
within the app's logical hierarchy. The system uses this value
@@ -376,20 +415,16 @@ the <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code
&lt;meta-data>}</a> element as shown here.</p>
<p class="note"><strong>Note:</strong> Your Android SDK should already include
the latest Android Support Library. It's included with the ADT Bundle but if you're using
a different IDE, you should have installed it during the
<a href="{@docRoot}sdk/installing/adding-packages.html">Adding Platforms and Packages</a> step.
When using the templates in Eclipse, the Support Library is automatically added to your app project
the latest Android Support Library, which you installed during the
<a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK Packages</a> step.
When using the templates in Android Studio, the Support Library is automatically added to your app project
(you can see the library's JAR file listed under <em>Android Dependencies</em>). If you're not using
Eclipse, you need to manually add the library to your project&mdash;follow the guide for <a
Android Studio, you need to manually add the library to your project&mdash;follow the guide for <a
href="{@docRoot}tools/support-library/setup.html">setting up the Support Library</a>
then return here.</p>
<p>If you're developing with Eclipse, you can run the app now, but not much happens.
Clicking the Send button starts the second activity but it uses
a default "Hello world" layout provided by the template. You'll soon update the
activity to instead display a custom text view, so if you're using a different IDE,
don't worry that the app won't yet compile.</p>
<p>If you're using a different IDE than Android Studio, don't worry that the app won't yet compile.
You'll soon update the activity to display a custom text view.</p>
<h2 id="ReceiveIntent">Receive the Intent</h2>
@@ -397,24 +432,55 @@ don't worry that the app won't yet compile.</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 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 MainActivity}:</p>
within the intent.</p>
<ol>
<li>In the <code>java/com.mycompany.myfirstapp</code> directory, edit the
{@code DisplayMessageActivity.java} file.</li>
<li>In the {@link android.app.Activity#onCreate onCreate()} method, remove the following line:
<pre>
setContentView(R.layout.activity_display_message);
</pre>
<li>Get the intent and assign it to a local variable.
<pre>
Intent intent = getIntent();
String message = intent.getStringExtra(MainActivity.EXTRA_MESSAGE);
</pre>
</li>
<li>At the top of the file, import the {@link android.content.Intent} class.
<p>In Android Studio, press Alt + Enter (option + return on Mac) to import missing classes.</p>
</li>
<li>Extract the message delivered by {@code MyActivity} with the
{@link android.content.Intent#getStringExtra getStringExtra()} method.
<pre>
String message = intent.getStringExtra(MyActivity.EXTRA_MESSAGE);
</pre>
</li>
</ol>
<h2 id="DisplayMessage">Display the Message</h2>
<p>To show the message on the screen, create a {@link android.widget.TextView} widget and set the
text using {@link android.widget.TextView#setText setText()}. Then add the {@link
android.widget.TextView} as the root view of the activity’s layout by passing it to {@link
android.app.Activity#setContentView setContentView()}.</p>
<ol>
<li>In the {@link android.app.Activity#onCreate onCreate()} method, create a {@link android.widget.TextView} object.
<pre>
TextView textView = new TextView(this);
</pre>
</li>
<li>Set the text size and message with {@link android.widget.TextView#setText setText()}.
<pre>
textView.setTextSize(40);
textView.setText(message);
</pre>
</li>
<li>Then add the {@link android.widget.TextView} as the root view of the activity’s layout by
passing it to {@link android.app.Activity#setContentView setContentView()}.
<pre>
setContentView(textView);
</pre>
</li>
<li>At the top of the file, import the {@link android.widget.TextView} class.
<p>In Android Studio, press Alt + Enter (option + return on Mac) to import missing classes.</p>
</li>
</ol>
<p>The complete {@link android.app.Activity#onCreate onCreate()} method for {@code
DisplayMessageActivity} now looks like this:</p>
@@ -426,7 +492,7 @@ public void onCreate(Bundle savedInstanceState) {
// Get the message from the intent
Intent intent = getIntent();
String message = intent.getStringExtra(MainActivity.EXTRA_MESSAGE);
String message = intent.getStringExtra(MyActivity.EXTRA_MESSAGE);
// Create the text view
TextView textView = new TextView(this);