diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 4dc915f0683df..8af4a1cd143e8 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -194,7 +194,7 @@ contains property types that define the size and position for each child view, a appropriate for the view group. As you can see in figure 1, the parent view group defines layout parameters for each child view (including the child view group).

- +

Figure 1. Visualization of a view hierarchy with layout parameters associated with each view.

diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index 83c8150003679..45c9ac9b05ccc 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -51,7 +51,7 @@ as shown in the diagram below. This hierarchy tree can be as simple or complex a can build it up using Android's set of predefined widgets and layouts, or with custom Views that you create yourself.

- +

In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the diff --git a/docs/html/images/layoutparams.png b/docs/html/images/layoutparams.png index 7473dccf20627..d99625e2efa95 100644 Binary files a/docs/html/images/layoutparams.png and b/docs/html/images/layoutparams.png differ diff --git a/docs/html/images/training/firstapp/adt-firstapp-setup.png b/docs/html/images/training/firstapp/adt-firstapp-setup.png new file mode 100644 index 0000000000000..c09256282d745 Binary files /dev/null and b/docs/html/images/training/firstapp/adt-firstapp-setup.png differ diff --git a/docs/html/images/training/firstapp/edittext_gravity.png b/docs/html/images/training/firstapp/edittext_gravity.png new file mode 100644 index 0000000000000..f78e67671c11a Binary files /dev/null and b/docs/html/images/training/firstapp/edittext_gravity.png differ diff --git a/docs/html/images/training/firstapp/edittext_wrap.png b/docs/html/images/training/firstapp/edittext_wrap.png new file mode 100644 index 0000000000000..156776d776994 Binary files /dev/null and b/docs/html/images/training/firstapp/edittext_wrap.png differ diff --git a/docs/html/images/training/firstapp/firstapp.png b/docs/html/images/training/firstapp/firstapp.png new file mode 100644 index 0000000000000..d69cd2008fd5a Binary files /dev/null and b/docs/html/images/training/firstapp/firstapp.png differ diff --git a/docs/html/images/viewgroup.png b/docs/html/images/viewgroup.png index a4c2518f12af0..2c86ddbd18746 100644 Binary files a/docs/html/images/viewgroup.png and b/docs/html/images/viewgroup.png differ diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd new file mode 100644 index 0000000000000..847163a7acff5 --- /dev/null +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -0,0 +1,363 @@ +page.title=Building a Simple User Interface +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Running Your App +previous.link=running-app.html +next.title=Starting Another Activity +next.link=starting-activity.html + +@jd:body + + + +

+
+ +

This lesson teaches you to

+ +
    +
  1. Use a Linear Layout
  2. +
  3. Add a Text Input Box
  4. +
  5. Add String Resources
  6. +
  7. Add a Button
  8. +
  9. Make the Input Box Fill in the Screen Width
  10. +
+ + +

You should also read

+ + + +
+
+ + + +

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 +invisible view containers that define how the child views are laid out, such as in a +grid or a vertical list.

+ +

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.

+ + + + + +

Figure 1. Illustration of how {@link +android.view.ViewGroup} objects form branches in the layout and contain {@link +android.view.View} objects.

+ +

In this lesson, you'll create a layout in XML that includes a text input 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.

+ + + +

Use a Linear Layout

+ +

Open the main.xml file from the res/layout/ +directory (every new Android project includes this file by default).

+ +

Note: 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 main.xml tab at +the bottom of the screen to open the XML editor.

+ +

By default, the main.xml 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.

+ +

First, delete the {@link android.widget.TextView} element and change the value +{@code +android:orientation} to be "horizontal". The result looks like this:

+ +
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent"
+    android:orientation="horizontal" >
+</LinearLayout>
+
+ +

{@link android.widget.LinearLayout} is a view group (a subclass of {@link +android.view.ViewGroup}) that lays out child views in either a vertical or horizontal orientation, +as specified by the {@code +android:orientation} attribute. Each child of a {@link android.widget.LinearLayout} appears on +the screen in the order in which it appears in the XML.

+ +

The other two attributes, {@code +android:layout_width} and {@code +android:layout_height}, are required for all views in order to specify their size.

+ +

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 +"fill_parent".

+ +

Note: Beginning with Android 2.2 (API level 8), +"fill_parent" has been renamed "match_parent" to better reflect the +behavior. The reason is that if you set a view to "fill_parent" it does not expand to +fill the remaining space after sibling views are considered, but instead expands to +match the size of the parent view no matter what—it will overlap any sibling +views.

+ +

For more information about layout properties, see the XML Layout guide.

+ + + +

Add a Text Input Box

+ +

To create a user-editable text box, add an {@link android.widget.EditText +<EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}. The {@link +android.widget.EditText} class is a subclass of {@link android.view.View} that displays an editable +text box.

+ +

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 <LinearLayout>} element:

+ +
+    <EditText android:id="@+id/edit_message"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:hint="@string/edit_message" />
+
+ + + + +

About these attributes:

+ +
+
{@code android:id}
+
This provides a unique identifier for the view, which you can use to reference the object +from your app code, such as to read and manipulate the object (you'll see this in the next +lesson). + +

The at-symbol (@) 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—for example, the string resource uses the same name.)

+ +

The plus-symbol (+) 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, edit_message, to create a new identifier in +your project's {@code gen/R.java} file that is now assiciated with the {@link +android.widget.EditText} element. Once the resource ID is created, other references to the ID do not +need the plus symbol. See the sidebox for more information about resource objects.

+ +
{@code +android:layout_width} and {@code +android:layout_height}
+
Instead of using specific sizes for the width and height, the "wrap_content" 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 "fill_parent", then the {@link android.widget.EditText} +element would fill the screen, because it'd match the size of the parent {@link +android.widget.LinearLayout}. For more information, see the XML Layouts guide.
+ +
{@code +android:hint}
+
This is a default string to display when the text box is empty. Instead of using a hard-coded +string as the value, the value given in this example refers to a string resource. When you add the +{@code +"@string/edit_message"} value, you’ll see a compiler error because there’s no matching string +resource by that name. You'll fix this in the next section by defining the string +resource.
+
+ + + +

Add String Resources

+ +

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 +localize your app to different languages by providing alternative definitions for each +string.

+ +

By default, your Android project includes a string resource file at +res/values/strings.xml. Open this file, delete the existing "hello" +string, and add one for the +"edit_message" string used by the {@link android.widget.EditText <EditText>} +element.

+ +

While you’re in this file, also add a string for the button you’ll soon add, called +"button_send".

+ +

The result for strings.xml looks like this:

+ +
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">My First App</string>
+    <string name="edit_message">Enter a message</string>
+    <string name="button_send">Send</string>
+</resources>
+
+ +

For more information about using string resources to localize your app for several languages, +see the Supporting Various Devices +class.

+ + + + +

Add a Button

+ +

Now add a {@link android.widget.Button <Button>} to the layout, immediately following the +{@link android.widget.EditText <EditText>} element:

+ +
+    <Button
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/button_send" />
+
+ +

The height and width are set to "wrap_content" so the button is only as big as +necessary to fit the button's text.

+ + + +

Make the Input Box Fill in the Screen Width

+ +

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.

+ + +

Figure 2. The {@link android.widget.EditText} and {@link +android.widget.Button} widgets have their widths set to +"wrap_content".

+ +

This works fine for the button, but not as well for the text box, 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 box. +{@link android.widget.LinearLayout} enables such a design with the weight property, which +you can specify using the {@code +android:layout_weight} attribute.

+ +

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 +parts vodka, 1 part coffee liquer" 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.

+ +

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 +android.widget.EditText} element, give it a weight of 1 and leave the button with no weight.

+ +
+    <EditText
+        android:layout_weight="1"
+        ... />
+
+ +

In order 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 +"wrap_content" 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.

+
+    <EditText
+        android:layout_weight="1"
+        android:layout_width="0dp"
+        ... />
+
+ +

Figure 3 +shows the result when you assign all weight to the {@link android.widget.EditText} element.

+ + +

Figure 3. The {@link android.widget.EditText} widget is +given all the layout weight, so fills the remaining space in the {@link +android.widget.LinearLayout}.

+ +

Here’s how your complete layout file should now look:

+ +
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent"
+    android:orientation="horizontal">
+    <EditText android:id="@+id/edit_message"
+        android:layout_weight="1"
+        android:layout_width="0dp"
+        android:layout_height="wrap_content"
+        android:hint="@string/edit_message" />
+    <Button android:id="@+id/button_send"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/button_send" />
+</LinearLayout>
+
+ +

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 +results:

+ + + +

Continue to the next lesson to learn how you can respond to button presses, read content +from the text field, start another activity, and more.

+ + + diff --git a/docs/html/training/basics/firstapp/creating-project.jd b/docs/html/training/basics/firstapp/creating-project.jd new file mode 100644 index 0000000000000..5a89f2e7b8e4e --- /dev/null +++ b/docs/html/training/basics/firstapp/creating-project.jd @@ -0,0 +1,142 @@ +page.title=Creating an Android Project +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +next.title=Running Your App +next.link=running-app.html + +@jd:body + + + +
+
+ +

This lesson teaches you to

+ +
    +
  1. Create a Project with Eclipse
  2. +
  3. Create a Project with Command Line Tools
  4. +
+ +

You should also read

+ + + + +
+
+ +

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.

+ +

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.

+ +

Note: You should already have the Android SDK installed, and if +you're using Eclipse, you should have installed the ADT plugin as well. If you have not installed +these, see Installing the Android SDK and return here +when you've completed the installation.

+ + +

Create a Project with Eclipse

+ +
+ +

Figure 1. The new project wizard in Eclipse.

+
+ +
    +
  1. In Eclipse, select File > New > Project. +The resulting dialog should have a folder labeled Android. (If you don’t see the +Android folder, +then you have not installed the ADT plugin—see Installing the ADT Plugin).
  2. +
  3. Open the Android folder, select Android Project and click +Next.
  4. +
  5. Enter a project name (such as "MyFirstApp") and click Next.
  6. +
  7. Select a build target. This is the platform version against which you will compile your app. +

    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.

    +

    If you don't see any built targets listed, you need to install some using the Android SDK +Manager tool. See step 4 in the +installing guide.

    +

    Click Next.

  8. +
  9. Specify other app details, such as the: + +

    Click Finish.

    +
  10. +
+ +

Your Android project is now set up with some default files and you’re ready to begin +building the app. Continue to the next lesson.

+ + + +

Create a Project with Command Line Tools

+ +

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:

+ +
    +
  1. Change directories into the Android SDK’s tools/ path.
  2. +
  3. Execute: +
    android list targets
    +

    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 +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.

    +

    If you don't see any targets listed, you need to +install some using the Android SDK +Manager tool. See step 4 in the +installing guide.

  4. +
  5. Execute: +
    +android create project --target <target-id> --name MyFirstApp \
    +--path <path-to-workspace>/MyFirstApp --activity MyFirstActivity \
    +--package com.example.myapp
    +
    +

    Replace <target-id> with an id from the list of targets (from the previous step) +and replace +<path-to-workspace> with the location in which you want to save your Android +projects.

  6. +
+ +

Your Android project is now set up with several default configurations and you’re ready to begin +building the app. Continue to the next lesson.

+ +

Tip: Add the platform-tools/ as well as the +tools/ directory to your PATH environment variable.

+ + + + diff --git a/docs/html/training/basics/firstapp/index.jd b/docs/html/training/basics/firstapp/index.jd new file mode 100644 index 0000000000000..a95ed8e7f879a --- /dev/null +++ b/docs/html/training/basics/firstapp/index.jd @@ -0,0 +1,64 @@ +page.title=Building Your First App + +trainingnavtop=true +startpage=true +next.title=Creating an Android Project +next.link=creating-project.html + +@jd:body + +
+
+ +

Dependencies and prerequisites

+ + + +
+
+ +

Welcome to Android application development!

+ +

This class teaches you how to build your first Android app. You’ll learn how to create an Android +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.

+ +

Before you start this class, be sure that you have your development environment set up. You need +to:

+
    +
  1. Download the Android SDK Starter Package.
  2. +
  3. Install the ADT plugin for Eclipse (if you’ll use the Eclipse IDE).
  4. +
  5. Download the latest SDK tools and platforms using the SDK Manager.
  6. +
+ +

If you haven't already done this setup, read Installing +the SDK. Once you've finished the setup, you're ready to begin this class.

+ +

This class uses a tutorial format that incrementally builds a small Android app in order to teach +you some fundamental concepts about Android development, so it's important that you follow each +step.

+ +

Start the first lesson ›

+ + +

Lessons

+ +
+
Creating an Android Project
+
Shows how to create a project for an Android app, which includes a set of default +app files.
+ +
Running Your Application
+
Shows how to run your app on an Android-powered device or the Android +emulator.
+ +
Building a Simple User Interface
+
Shows how to create a new user interface using an XML file.
+ +
Starting Another Activity
+
Shows how to respond to a button press, start another activity, send it some +data, then receive the data in the subsequent activity.
+
diff --git a/docs/html/training/basics/firstapp/running-app.jd b/docs/html/training/basics/firstapp/running-app.jd new file mode 100644 index 0000000000000..2398fa0895e80 --- /dev/null +++ b/docs/html/training/basics/firstapp/running-app.jd @@ -0,0 +1,178 @@ +page.title=Running Your App +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Creating a Project +previous.link=creating-project.html +next.title=Building a Simple User Interface +next.link=building-ui.html + +@jd:body + + + +
+
+ +

This lesson teaches you to

+ +
    +
  1. Run on a Real Device
  2. +
  3. Run on the Emulator
  4. +
+ +

You should also read

+ + + + +
+
+ + +

If you followed the previous lesson to create an +Android project, it includes a default set of "Hello World" source files that allow you to +run the app right away.

+ +

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.

+ +

Before you run your app, you should be aware of a few directories and files in the Android +project:

+ +
+
AndroidManifest.xml
+
This manifest file 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.
+
src/
+
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.
+
res/
+
Contains several sub-directories for app resources. Here are just a few: +
+
drawable-hdpi/
+
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.
+
layout/
+
Directory for files that define your app's user interface.
+
values/
+
Directory for other various XML files that contain a collection of resources, such as +string and color definitions.
+
+
+
+ +

When you build and run the default Android project, the default {@link android.app.Activity} +class in the src/ directory starts and loads a layout file from the +layout/ 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.

+ + + +

Run on a Real Device

+ +

Whether you’re using Eclipse or the command line, you need to:

+ +
    +
  1. Plug in your Android-powered device to your 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 OEM USB +Drivers document.
  2. +
  3. Ensure that USB debugging is enabled in the device Settings (open Settings +and navitage to Applications > Development on most devices, or select +Developer options on Android 4.0 and higher).
  4. +
+ +

To run the app from Eclipse, open one of your project's files and click +Run from the toolbar. Eclipse installs the app on your connected device and starts +it.

+ + +

Or to run your app from a command line:

+ +
    +
  1. Change directories to the root of your Android project and execute: +
    ant debug
  2. +
  3. Make sure the Android SDK platform-tools/ directory is included in your +PATH environment variable, then execute: +
    adb install bin/MyFirstApp-debug.apk
  4. +
  5. On your device, locate MyFirstActivity and open it.
  6. +
+ +

To start adding stuff to the app, continue to the next +lesson.

+ + + +

Run on the Emulator

+ +

Whether you’re using Eclipse or the command line, you need to first create an Android Virtual +Device (AVD). An AVD is a +device configuration for the Android emulator that allows you to model +different device configurations.

+ +
+ +

Figure 1. The AVD Manager showing a few virtual +devices.

+
+ +

To create an AVD:

+
    +
  1. Launch the Android Virtual Device Manager: +
      +
    1. In Eclipse, select Window > AVD Manager, or click the AVD +Manager icon in the Eclipse toolbar.
    2. +
    3. From the command line, change directories to <sdk>/tools/ and execute: +
      ./android avd
    4. +
    +
  2. +
  3. In the Android Virtual Device Device Manager panel, click New.
  4. +
  5. Fill in the details for the AVD. +Give it a name, a platform target, an SD card size, and a skin (HVGA is default).
  6. +
  7. Click Create AVD.
  8. +
  9. Select the new AVD from the Android Virtual Device Manager and click +Start.
  10. +
  11. After the emulator boots up, unlock the emulator screen.
  12. +
+ +

To run the app from Eclipse, open one of your project's files and click +Run from the toolbar. Eclipse installs the app on your AVD and starts it.

+ + +

Or to run your app from the command line:

+ +
    +
  1. Change directories to the root of your Android project and execute: +
    ant debug
  2. +
  3. Make sure the Android SDK platform-tools/ directory is included in your +PATH environment +variable, then execute: +
    adb install bin/MyFirstApp-debug.apk
  4. +
  5. On the emulator, locate MyFirstActivity and open it.
  6. +
+ + +

To start adding stuff to the app, continue to the next +lesson.

+ + + + + + + + + + + diff --git a/docs/html/training/basics/firstapp/starting-activity.jd b/docs/html/training/basics/firstapp/starting-activity.jd new file mode 100644 index 0000000000000..16a6fd82436e0 --- /dev/null +++ b/docs/html/training/basics/firstapp/starting-activity.jd @@ -0,0 +1,308 @@ +page.title=Starting Another Activity +parent.title=Building Your First App +parent.link=index.html + +trainingnavtop=true +previous.title=Building a Simpler User Interface +previous.link=building-ui.html + +@jd:body + + + +
+
+ +

This lesson teaches you to

+ +
    +
  1. Respond to the Send Button
  2. +
  3. Build an Intent
  4. +
  5. Start the Second Activity
  6. +
  7. Create the Second Activity +
      +
    1. Add it to the manifest
    2. +
    +
  8. +
  9. Receive the Intent
  10. +
  11. Display the Message
  12. +
+ +

You should also read

+ + + + +
+
+ + + +

After completing the previous lesson, you have an app that +shows an activity (a single screen) with a text box and a button. In this lesson, you’ll add some +code to MyFirstActivity that +starts a new activity when the user selects the Send button.

+ + +

Respond to the Send Button

+ +

To respond to the button's on-click event, open the main.xml layout file and add the +{@code android:onClick} +attribute to the {@link android.widget.Button <Button>} element:

+ +
+<Button android:id="@+id/button_send"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="@string/button_send"
+    android:onClick="sendMessage" />
+
+ +

The {@code +android:onClick} attribute’s value, sendMessage, is the name of a method in your +activity that you want to call when the user selects the button.

+ +

Add the corresponding method inside the MyFirstActivity class:

+ +
+/** Called when the user selects the Send button */
+public void sendMessage(View view) {
+    // Do something in response to button
+}
+
+ +

Tip: In Eclipse, press Ctrl + Shift + O to import missing classes +(Cmd + Shift + O on Mac).

+ +

Note that, in order for the system to match this method to the method name given to {@code android:onClick}, +the signature must be exactly as shown. Specifically, the method must:

+ + + +

Next, you’ll fill in this method to read the contents of the text box and deliver that text to +another activity.

+ + + +

Build an Intent

+ +

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 +variety of tasks, but most often they’re used to start another activity.

+ +

Inside the {@code sendMessage()} method, create an {@link android.content.Intent} to start +an activity called {@code DisplayMessageActvity}:

+ +
+Intent intent = new Intent(this, DisplayMessageActivity.class);
+
+ +

The constructor used here takes two parameters:

+ + + + +

Note: 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.

+ +

An intent not only allows you to start another activity, but 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:

+ +
+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);
+
+ +

An {@link android.content.Intent} can carry a collection of various data types as key-value +pairs called extras. The {@link android.content.Intent#putExtra putExtra()} method takes a +string as the key and the value in the second parameter.

+ +

In order for the next activity to query the extra data, you should define your keys using a +public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code +MyFirstActivity} class:

+ +
+public class MyFirstActivity extends Activity {
+    public final static String EXTRA_MESSAGE = "com.example.myapp.MESSAGE";
+    ...
+}
+
+ +

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.

+ + +

Start the Second Activity

+ +

To start an activity, you simply need to 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}.

+ +

With this method included, the complete {@code sendMessage()} method that's invoked by the Send +button now looks like this:

+ +
+/** Called when the user selects the Send button */
+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);
+    startActivity(intent);
+}
+
+ +

Now you need to create the {@code DisplayMessageActivity} class in order for this to +work.

+ + + +

Create the Second Activity

+ +

In your project, create a new class file under the src/<package-name>/ +directory called DisplayMessageActivity.java.

+ +

Tip: In Eclipse, right-click the package name under the +src/ directory and select New > Class. +Enter "DisplayMessageActivity" for the name and {@code android.app.Activity} for the superclass.

+ +

Inside the class, add the {@link android.app.Activity#onCreate onCreate()} callback method:

+ +
+public class DisplayMessageActivity extends Activity {
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+    }
+}
+
+ +

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.

+ + + +

Add it to the manifest

+ +

You must declare all activities in your manifest file, AndroidManifest.xml, using an +{@code <activity>} element.

+ +

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 MyFirstActivity). So +the declaration for DisplayMessageActivity can be simply one line of code inside the {@code <application>} +element:

+ +
+<application ... >
+    <activity android:name="com.example.myapp.DisplayMessageActivity" />
+    ...
+</application>
+
+ +

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 +second activity, but it doesn't show anything yet.

+ + +

Receive the Intent

+ +

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 +within it.

+ +

In the {@code DisplayMessageActivity} class’s {@link android.app.Activity#onCreate onCreate()} +method, get the intent and extract the message delivered by {@code MyFirstActivity}:

+ +
+Intent intent = getIntent();
+String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE);
+
+ + + +

Display the Message

+ +

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()}.

+ +

The complete {@link android.app.Activity#onCreate onCreate()} method for {@code +DisplayMessageActivity} now looks like this:

+ +
+@Override
+public void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+
+    // Get the message from the intent
+    Intent intent = getIntent();
+    String message = intent.getStringExtra(MyFirstActivity.EXTRA_MESSAGE);
+
+    // Create the text view
+    TextView textView = new TextView(this);
+    textView.setTextSize(40);
+    textView.setText(message);
+
+    setContentView(textView);
+}
+
+ +

You can now run the app, type a message in the text box, press Send, and view the message on the +second activity.

+ + +

Figure 1. Both activities in the final app, running +on Android 4.0. + +

That's it, you've built your first Android app!

+ +

To learn more about building Android apps, continue to follow the +basic training classes. The next class is Managing the Activity Lifecycle.

+ + + +