Develop your first Android Application

Creating an Android Project

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 also have the ADT plugin installed (version 20.0.0 or higher). If you don't have these, follow the guide to Installing the Android SDK before you start this lesson.

Create a Project with Eclipse

---

1. In Eclipse, click New Android App Project in the toolbar. (If you don’t see this button, then you have not installed the ADT plugin—see Installing the Eclipse Plugin.)


Figure 1. The New Android App Project wizard in Eclipse.
2. Fill in the form that appears:
   • Application Name is the app name that appears to users. For this project, use "My First App."
   • Project Name is the name of your project directory and the name visible in Eclipse.
   • Package Name 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.
   • Build SDK 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 SDK Manager). 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.
   • Minimum Required SDK is the lowest version of Android that your app supports. To support as many devices as possible, you should set this to the lowest version available that allows your app to provide its core feature set. If any feature of your app is possible only on newer versions of Android and it's not critical to the app's core feature set, you can enable the feature only when running on the versions that support it. Leave this set to the default value for this project.
     
   Click Next.
   
3. The following screen provides tools to help you create a launcher icon for your app. 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 Iconography design guide.
   Click Next.
   
4. Now you can select an activity template from which to begin building your app. For this project, select BlankActivity and click Next.
   
5. Leave all the details for the activity in their default state and click Finish.

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

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 from a command line:

1. Change directories into the Android SDK’s tools/ path.
2. 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 Adding Platforms and Packages.
3. Execute:

   android create project --target <target-id> --name MyFirstApp \
   --path <path-to-workspace>/MyFirstApp --activity MainActivity \
   --package com.example.myfirstapp
   

   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.

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

Running Your App

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 immediately run the app.

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

The 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 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 app, the default 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.

Run on a Real Device

---

If you have a real Android-powered device, here's how you can install and run your app:

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

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. Make sure the Android SDK platform-tools/ directory is included in your PATH environment variable, then execute:

   adb install bin/MyFirstApp-debug.apk

3. On your device, locate MyFirstActivity and open it.

That's how you build and run your Android app on a device! 

Run on the Emulator

---

Whether you’re using Eclipse or the command line, to run your app on the emulator 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 devices.

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

To create an AVD:

1. Launch the Android Virtual Device Manager:
   1. In Eclipse, click Android Virtual Device Manager from the toolbar.
   2. From the command line, change directories to <sdk>/tools/ and execute:

      android avd

2. In the Android Virtual Device Manager panel, click New.
3. Fill in the details for the AVD. Give it a name, a platform target, an SD card size, and a skin (HVGA is default).
4. Click Create AVD.
5. Select the new AVD from the Android Virtual Device Manager and click Start.
6. After the emulator boots up, unlock the emulator screen.

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. Make sure the Android SDK platform-tools/ directory is included in your PATH environment variable, then execute:

   adb install bin/MyFirstApp-debug.apk

3. On the emulator, locate MyFirstActivity and open it.

That's how you build and run your Android app on the emulator! 

 Building a Simple User Interface

The graphical user interface for an Android app is built using a hierarchy of View and ViewGroup objects. View objects are usually UI widgets such as buttons or text fields and 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 View and ViewGroup so you can define your UI in XML using a hierarchy of UI elements.

Alternative Layouts
Declaring your UI layout in XML rather than runtime code is useful for several reasons, but it's especially important so you can create different layouts for different screen sizes. For example, you can create two versions of a layout and tell the system to use one on "small" screens and the other on "large" screens. For more information, see the class about Supporting Different Devices.

Figure 1. Illustration of how ViewGroup objects form branches in the layout and contain other View objects.

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.

Create a Linear Layout

---

Open the activity_main.xml file from the res/layout/ directory.

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

The BlankActivity template you used to start this project creates the activity_main.xml file with a RelativeLayout root view and a TextView child view.
First, delete the <TextView> element and change the <RelativeLayout> element to <LinearLayout>. Then add the android:orientation attribute and set it to "horizontal". The result looks like this:

<?xml version="1.0" encoding="utf-8"?>
<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" >
</LinearLayout>

LinearLayout is a view group (a subclass of ViewGroup) that lays out child views in either a vertical or horizontal orientation, as specified by the android:orientation attribute. Each child of a LinearLayout appears on the screen in the order in which it appears in the XML.
The other two attributes, android:layout_width and android:layout_height, are required for all views in order to specify their size.
Because the 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 "match_parent". This value declares that the view should expand its width or height to match the width or height of the parent view.
For more information about layout properties, see the Layout guide.

Add a Text Field

---

To create a user-editable text field, add an <EditText> element inside the <LinearLayout>.
Like every View object, you must define certain XML attributes to specify the EditText object's properties. Here’s how you should declare it inside the <LinearLayout> element:

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

About resource objects

A resource object is simply a unique integer name that's associated with an app resource, such as a bitmap, layout file, or string.
Every resource has a corresponding resource object defined in your project's gen/R.java file. You can use the object names in the R class to refer to your resources, such as when you need to specify a string value for the android:hint attribute. You can also create arbitrary resource IDs that you associate with a view using the android:id attribute, which allows you to reference that view from other code.
The SDK tools generate the R.java each time you compile your app. You should never modify this file by hand.
For more information, read the guide to Providing Resources.

About these attributes:

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 sign (@) is required when you're referring to any resource object from XML. It is followed by the resource type (id in this case), a slash, then the resource name (edit_message).
The plus sign (+) 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 gen/R.java file that refers to the EditText element. Once the resource ID is declared once this way, other references to the ID do not need the plus sign. Using the plus sign is necessary only when specifying a new resource ID and not needed for concrete resources such as strings or layouts. See the sidebox for more information about resource objects.

android:layout_width and 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 "match_parent", then the EditText element would fill the screen, because it would match the size of the parent LinearLayout. For more information, see the Layouts guide.

android:hint

This is a default string to display when the text field is empty. Instead of using a hard-coded string as the value, the "@string/edit_message" value refers to a string resource defined in a separate file. Because this refers to a concrete resource (not just an identifier), it does not need the plus sign. However, because you haven't defined the string resource yet, you’ll see a compiler error at first. You'll fix this in the next section by defining the string.

Note: This string resource has the same name as the element ID: edit_message. However, references to resources are always scoped by the resource type (such as id or string), so using the same name does not cause collisions.

Add String Resources

---

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.
By default, your Android project includes a string resource file at res/values/strings.xml. Open this file and delete the <string> element named "hello_world". Then add a new one named "edit_message" and set the value to "Enter a message."
While you’re in this file, also add a "Send" 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>
    <string name="menu_settings">Settings</string>
    <string name="title_activity_main">MainActivity</string>
</resources>

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

Add a Button

---

Now add a <Button> to the layout, immediately following the <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. This button doesn't need the android:id attribute, because it won't be referenced from the activity code.

Make the Input Box Fill in the Screen Width

---

The layout is currently designed so that both the EditText and Button widgets are only as big as necessary to fit their content, as shown in figure 2.

Figure 2. The EditText and Button widgets have their widths set to "wrap_content".

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 with the text field. You can do this inside a LinearLayout with the weight property, which you can specify using the android:layout_weight attribute.
The weight value is a number that specifies the amount of remaining space each view should consume, relative to the amount consumed by sibling views. This works kind of like the amount of ingredients in a drink recipe: "2 parts vodka, 1 part coffee liqueur" means two-thirds of the drink is vodka. For example, if you give one view a weight of 2 and another one a weight of 1, the sum is 3, so the first view fills 2/3 of the remaining space and the second view fills the rest. If you add a third view and give it a weight of 1, then the first view (with weight of 2) now gets 1/2 the remaining space, while the remaining two each get 1/4.
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 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 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 EditText element.

Figure 3. The EditText widget is given all the layout weight, so fills the remaining space in the 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"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_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:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/button_send" />
</LinearLayout>

This layout is applied by the default Activity class that the SDK tools generated when you created the project, so you can now run the app to see the results:

• In Eclipse, click Run from the toolbar.
• Or from a command line, change directories to the root of your Android project and execute:

  ant debug
  adb install bin/MyFirstApp-debug.apk

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.

Starting Another Activity

• Installing the SDK

After completing the previous lesson, 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 MainActivity that starts a new activity when the user clicks 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 android:onClick attribute to the <Button> element:

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

The android:onClick attribute’s value, "sendMessage", is the name of a method in your activity that the system calls when the user clicks the button.

Open the MainActivity class and add the corresponding method:

/** Called when the user clicks 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).

In order for the system to match this method to the method name given to android:onClick, the signature must be exactly as shown. Specifically, the method must:

• Be public
• Have a void return value
• Have a View as the only parameter (this will be the View that was clicked)

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

Build an Intent

---

An Intent is an object that provides runtime binding between separate components (such as two activities). The 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.

Inside the sendMessage() method, create an Intent to start an activity called DisplayMessageActivity:

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

The constructor used here takes two parameters:

• A Context as its first parameter (this is used because the Activity class is a subclass of Context)
• The Class of the app component to which the system should deliver the Intent (in this case, the activity that should be started)

Sending an intent to other apps

The intent created in this lesson is what's considered an explicit intent, because the Intent specifies the exact app component to which the intent should be given. However, intents can also be implicit, in which case the Intent does not specify the desired component, but allows any app installed on the device to respond to the intent as long as it satisfies the meta-data specifications for the action that's specified in various Intent parameters. For more information, see the class about Interacting with Other Apps.

Note: The reference to 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 it can carry a bundle of data to the activity as well. So, use findViewById() to get the EditText element and add its text value 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 Intent can carry a collection of various data types as key-value pairs called extras. The putExtra() method takes the key name in the first parameter and the value in the second parameter.

In order for the next activity to query the extra data, you should define your key using a public constant. So add the EXTRA_MESSAGE definition to the top of the MainActivity class:

public class MainActivity extends Activity {
    public final static String EXTRA_MESSAGE = "com.example.myfirstapp.MESSAGE";
    ...
}

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.

Start the Second Activity

---

To start an activity, you simply need to call startActivity() and pass it your Intent. The system receives this call and starts an instance of the Activity specified by the Intent.

With this new code, the complete sendMessage() method that's invoked by the Send button now looks like this:

/** Called when the user clicks the Send button */
public void sendMessage(View view) {
    Intent intent = new Intent(this, DisplayMessageActivity.class);
    EditText editText = (EditText) findViewById(R.id.edit_message);
    String message = editText.getText().toString();
    intent.putExtra(EXTRA_MESSAGE, message);
    startActivity(intent);
}

Now you need to create the DisplayMessageActivity class in order for this to work.

Create the Second Activity

---

Figure 1. The new activity wizard in Eclipse.

To create a new activity using Eclipse:

1. Click New in the toolbar.
2. In the window that appears, open the Android folder and select Android Activity. Click Next.
3. Select BlankActivity and click Next.
4. Fill in the activity details:
   • Project: MyFirstApp
   • Activity Name: DisplayMessageActivity
   • Layout Name: activity_display_message
   • Navigation Type: None
   • Hierarchial Parent: com.example.myfirstapp.MainActivity
   • Title: My Message
   Click Finish.
   

If you're using a different IDE or the command line tools, create a new file named DisplayMessageActivity.java in the project's src/ directory, next to the original MainActivity.java file.

Open the DisplayMessageActivity.java file. If you used Eclipse to create it, the class already includes an implementation of the required onCreate() method. There's also an implementation of the onCreateOptionsMenu() method, but you won't need it for this app so you can remove it. The class should look like this:

public class DisplayMessageActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
    }
}

All subclasses of Activity must implement the 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 perform initial setup for the activity components.

Add it to the manifest

You must declare all activities in your manifest file, AndroidManifest.xml, using an <activity> element.

When you use the Eclipse tools to create the activity, it creates a default entry. It should look like this:

<application ... >
    ...
    <activity
        android:name=".DisplayMessageActivity"
        android:label="@string/title_activity_display_message" >
        <meta-data
            android:name="android.support.PARENT_ACTIVITY"
            android:value="com.example.myfirstapp.MainActivity" />
    </activity>
</application>

The <meta-data> element declares the name of this activity's parent activity within the app's logical hierarchy. The Android Support Library uses this information to implement default navigation behaviors, such as Up navigation.

Note: During installation, you should have downloaded the latest Support Library. Eclipse automatically includes this library in your app project (you can see the library's JAR file listed under Android Dependencies). If you're not using Eclipse, you may need to manually add the library to your project—follow this guide for setting up the Support Library.

The app is now runnable because the Intent in the first activity now resolves to the DisplayMessageActivity class. If you run the app now, clicking the Send button starts the second activity, but it's still using the default "Hello world" layout.

Receive the Intent

---

Every Activity is invoked by an Intent, regardless of how the user navigated there. You can get the Intent that started your activity by calling getIntent() and retrieve the data contained within it.

In the DisplayMessageActivity class’s onCreate() method, get the intent and extract the message delivered by MainActivity:

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

Display the Message

---

To show the message on the screen, create a TextView widget and set the text using setText(). Then add the TextView as the root view of the activity’s layout by passing it to setContentView().

The complete onCreate() method for 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(MainActivity.EXTRA_MESSAGE);

    // Create the text view
    TextView textView = new TextView(this);
    textView.setTextSize(40);
    textView.setText(message);

    // Set the text view as the activity layout
    setContentView(textView);
}

You can now run the app. When it opens, type a message in the text field, click Send, and the message appears on the second activity.

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

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