Android Applications for Java ME Developers

main.xml and Friends

The other part of an Activity are the associated XML files. An Activity has a layout containing a number of views, an options menu that appears when the menu key is pressed, and contextual menus that appear when you touch and hold a view. Options menus should contain menu items that apply to the Activity as a whole; contextual menus are for choices that apply to the currently selected views.

Each Activity has associated XML files that specify the layout of the screen, views, and menus when the Activity is on the top of the stack. You will be creating one layout XML file for each Activity you create in your application. You may also be creating an options menu XML file. This is where a consistent and well thought out naming scheme will help you. You will find the layout XML files in the layout subdirectory under the res (resources) directory and the options menu in the menu subdirectory. Images, drawings, and the other visual components are placed in the neighboring drawables directory. By default, an application project contains one XML file called main containing a default layout.

Google supplies a layout editor for creating the UI in a drag and drop manner. Interface Builder it is not. Someday it may be usable, but as of now you are probably better off finding a third party UI editor, or editing the XML files by hand. If you liked writing code to create your UI, editing XML files by hand should make you very happy.

I know that some of you will still feel strongly about coding your own UI at this point. Let me give you two other reasons to use XML files: orientation and screen size. Unlike Java ME applications, Android applications need to be able to rotate the screen to match the current orientation of the phone. If you code your UI, then you will need to write all the code to handle the changes in orientation that will occur. This starts to be a lot of code to write and debug. Also, Google is committed to increasing the number of display sizes and aspect ratios supported so hand coding and testing the UI is going to get a lot harder and more tedious quickly. (If you are still determined to code your own UI, as you might need to for a game or some truly dynamic UI system, Android does support code-built user interfaces, Canvas views, and views for Open GL ES graphics.)

Android has pretty much all the standard layout managers and view items that you would expect, and a few you might not. To receive events from and change the state of view widgets, you need to assign them an ID. In your code, you will locate the view object by ID, then assign an event listener or change its state as needed. I'll get into IDs in a moment and in some detail as these are rather critical, but I have to talk about string values first.

strings.xml

I mentioned the images for the UI are in the drawables directory. The strings for the UI are in the values directory in the file strings.xml. The strings file contains all the strings that your application will display, each identified by an ID for easy reference in the other XML files and in your code.

Why the separation? Internationalization and localization, of course! Unlike Java ME, Android has full internationalization and localization support built in, and Android handsets ship with a large number of languages by default, so there is no good reason your application should not eventually be able support all of them. If you follow a simple rule to internationalize your application at the start, even if you never plan on localizing your application for anything other than your own language, you will be in a far, far better position to take advantage of international demand and markets. If your application is good enough, you might be surprised at the number of people who will help you create localizations for their language for free. Trust me, you would rather put up one application that is able to support lots of languages from the start than try to deal with internationalizing later, or worse, keep track of a whole bunch of separate applications, one for each language.

What is the rule? If you will display a string where someone can see it, put the string in the strings.xml file and reference it by ID in your code or in other XML files. This includes the application name in the Android Manifest file! When you create a new localization, a directory with a strings.xml file will be created for the localization. You may then edit that strings file to contain the appropriate text for that language. The directory name will encode the language and region applicable to the enclosed strings.xml file.

The main.xml file may be localized the same way. In addition to language localizations for layout you may also add variations for orientation of the device (between portrait and landscape) and different screen sizes.

IDs

I have mentioned IDs a couple of times. IDs are not something that exist within Java ME and so take a bit of getting used to. Within strings.xml, main.xml, and other files you assign an ID for each string, view, image, etc. These IDs are all collected together into a single R.java file that is generated automatically for you. In your code, you reference the ID with the notation R.string.name, R.drawable.name, R.layout.name, etc. In the string case name is the name of the string within the string.xml file; in the other cases it is the name of the XML files themselves. Within the XML files, you use the notation @+name when specifying the ID and @type/nameto reference the ID. The @+ notation indicates to the build system that name is an ID that should be added to the R.java file if not already present.

If you can, use the ID form of a method. However, some methods expect a string, drawable, or some other type, so you need to obtain the corresponding type before you make the method call. Sometimes you can use Context.gettype(). If not, the call you need is Resource.gettype().

Hello World Example

This is an example of all the components listed above in a project, including two localizations. Why two localizations? Because I really want you to think about internationalizing and localizing your code from the start. Note that I have changed this version of Hello World slightly to show you internationalizing the application name in the Android system in addition to internationalizing the application itself.

<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (C) 2007 The Android Open Source Project

     Declare the contents of this Android application.  The namespace
     attribute brings in the Android platform namespace, and the package
     supplies a unique name for the application.  When writing your
     own application, the package name must be changed from "com.example.*"
     to come from a domain that you own or have control over. -->

<manifest xmlns:android="http://schemas.android.com/apk/res/android"  
    package="com.example.android.helloactivity">

    <!-- The application tag supplies the name as presented 
         to the end user. Note that this name is specified by
         a resource id. This allows you to localize the name
         in the appropriate strings.xml file. -->
    <application android:label="@string/application_name">

        <!-- The application contains an activity named HelloActivity -->
        <activity android:name="HelloActivity">
            <intent-filter>

                <!-- MAIN indicates that this activity is the one that
                     should be started when the application is started -->
                <action android:name="android.intent.action.MAIN"/>

                <!-- LAUNCHER indicates that this is the activity that 
                     should be shown in the application Launcher -->
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

/*
 * Copyright (C) 2007 The Android Open Source Project
 *
 * Copyright (C) 2009 Motorola, Inc.
 */

package com.example.android.helloactivity;

import android.app.Activity;
import android.os.Bundle;

/**
 * A minimal "Hello, World!" application.
 */

public class HelloActivity extends Activity {

    public HelloActivity() {
    }

    /**
     * onCreate is called when the activity is first created.
     */

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Set the layout for this activity.  You can find it
        // in res/layout/hello_activity.xml by default, or in a localized 
        // version in the res/layout_* directories.

        // Notice that the view is referenced by id. This allows the correct 
        // layout to be selected based on local, geometry, and orientation.
        // Many sample applications in tutorials will show the layout being
        // specified by a string - a reference to a specific file. 
        // DO NOT do this! Always use an id instead. 

        setContentView(R.layout.hello_activity);
    }
}

<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (C) 2007 The Android Open Source Project
-->

<!-- A layout is a view, so we can use any view. In this case we are
     using an EditText view instead of a layout manager as there is only
     one view to display. -->
<EditText xmlns:android="http://schemas.android.com/apk/res/android" 
    android:id="@+id/text"  
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:textSize="18sp"
    android:autoText="true"
    android:capitalize="sentences"
    android:text="@string/hello_activity_text_text" />

<?xml version="1.0" encoding="utf-8"?>

<!--
Copyright (C) 2007 The Android Open Source Project 
-->

<resources>
    <string name="hello_activity_text_text">Hello, World!</string>
    <string name="application_name">Hello World</string>
</resources>

<?xml version="1.0" encoding="utf-8"?>

<!--
Copyright (C) 2009 Motorola, Inc.
-->

<resources>
    <string name="hello_activity_text_text">こんにちは世！</string>
    <string name="application_name">こんにちは世</string>
</resources>

Layout

This is a more complex layout with a layout managers, an editable text view, a couple of buttons, and an image. It is a good example of building a complex layout from a couple of nested layouts. The outermost layout lays out two views vertically: the edit text view and a second linear layout. The nested linear layout places two buttons and an image in a horizontal row. The views that we wish to access have IDs so that we can locate them within the Activity code. The IDs also have one other very important effect when orientation changes. I'll cover that after I finish with this example.

<?xml version="1.0" encoding="utf-8"?>

<!--
Copyright (C) 2007 The Android Open Source Project 
-->

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent" android:layout_height="fill_parent"
    android:orientation="vertical">

    <!--
    First view is a text editor. We want it to use all available
    horizontal space, and stretch to fill whatever vertical space is
    available to it. Note the use of the "id" attribute, which allows us
    to find this object from the Java code.
    -->

    <EditText android:id="@+id/editor" android:layout_width="fill_parent"
         android:layout_height="0dip" android:autoText="true"
         android:capitalize="sentences" android:layout_weight="1"
         android:freezesText="true">
         <requestFocus />
    </EditText>

    <!--
    Next view is another linear layout manager, now horizontal. We give it
    a custom background; see colors.xml for the definition of
    drawable/semi_black
    -->

    <LinearLayout android:layout_width="wrap_content"
         android:layout_height="wrap_content" android:layout_gravity="center_vertical"
         android:gravity="center_horizontal" android:orientation="horizontal"
         android:background="@drawable/semi_black">

        <!--
        On the left: the "back" button. See styles.xml for the definition of
        style/ActionButton, which we use to hold common attributes that are
        used for both this and the clear button. See strings.xml for the
        definition of string/back.
        -->

        <Button android:id="@+id/back" style="@style/ActionButton"
             android:text="@string/back" />

        <!-- In the middle: a custom image, -->
        <ImageView android:id="@+id/image" android:layout_width="wrap_content"
             android:layout_height="wrap_content" android:paddingLeft="4dip"
             android_paddingRight="4dip" android:src="@drawable/violet" />

        <!--
        On the right: another button, this time with its text color changed
        to red. Again, see colors.xml for the definition.
        -->

        <Button android:id="@+id/clear" style="@style/ActionButton"
             android:text="@string/clear" android:textColor="@color/red" />

        </LinearLayout>
</LinearLayout>

Styles

You may recall that I mentioned that you can change the default style to customize your appearance. In the layout file above, a button style was referenced. The style specification, located in the res/values, directory, is as follows.

<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (C) 2007 The Android Open Source Project
-->

<resources>
    <style name="ActionButton">
        <item name="android:layout_width">wrap_content</item>
        <item name="android:layout_height">wrap_content</item>
        <item name="android:textAppearance">@style/TextAppearance.ActionButton</item>
    </style>

    <style name="TextAppearance" parent="android:TextAppearance">
    </style>

    <style name="TextAppearance.ActionButton">
        <item name="android:textStyle">italic</item>
    </style>
</resources>

Option Menu Layout

The option menu layout is shown below. Note that this is not in the sample application included with MOTODEV Studio. That version shows a programmatic method of creating the options menu. The problem with the sample is that it is only partially internationalized — you would not be able to completely localize the menu. Here, I create two fully internationalized menu items with string labels and numeric & character shortcuts.

<?xml version="1.0" encoding="utf-8"?>

<!--
Copyright (C) 2009 Motorola, Inc.
-->

<!--
This file describes the options menu of the main SkeletonApp activity
user interface.
-->

<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:title="@string/back" android:id="@+id/menu_back"
        android:alphabeticShortcut="@string/back_char_shortcut"
        android:numericShortcut="@string/back_num_shortcut"></item>
    <item android:title="@string/clear" android:id="@+id/menu_clear"
        android:alphabeticShortcut="@string/clear_char_shortcut"
        android:numericShortcut="@string/clear_num_shortcut"></item>
</menu>

Strings

<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (C) 2007 The Android Open Source Project
     
     Copyright (C) 2009 Motorola, Inc.
-->

<resources>
    <!-- Simple strings. -->
    <string name="skeleton_app">Skeleton App</string>
    <string name="back">Back</string>
    <string name="clear">Clear</string>
    <!-- This is a complex string containing style runs. -->
    <string name="main_label">Hello <u>th<ignore>e</ignore>re</u>, <i>you</i> 
        <b>Activity</b>!</string>
    <string name="back_char_shortcut">b</string>
    <string name="clear_char_shortcut">c</string>
    <string name="back_num_shortcut">0</string>
    <string name="clear_num_shortcut">1</string>
</resources>

Java Source

I'll present it here, and then go over a couple of points.

/*
 * Copyright (C) 2007 The Android Open Source Project
 * 
 * Copyright (C) 2009 Motorola, Inc.
 */

package com.example.android.skeletonapp;

import android.app.Activity;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.EditText;

public class SkeletonActivity extends Activity {

	private EditText mEditor;

	public SkeletonActivity() {
	}

	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		// Inflate our UI from its XML layout description.
		setContentView(R.layout.skeleton_activity);

		// Find the text editor view inside the layout, because we
		// want to do various programmatic things with it.
		mEditor = (EditText) findViewById(R.id.editor);

		// Set the initial content of the EditText view.
		mEditor.setText(R.string.main_label);

		// Hook up button presses to the appropriate event handler.
		((Button) findViewById(R.id.back)).setOnClickListener(mBackListener);
		((Button) findViewById(R.id.clear)).setOnClickListener(mClearListener);
	}
	
	/**
	 * A call-back for when the user presses the back button.
	 */
	OnClickListener mBackListener = new OnClickListener() {
		public void onClick(View v) {
			finish();
		}
	};

	/**
	 * A call-back for when the user presses the clear button.
	 */
	OnClickListener mClearListener = new OnClickListener() {
		public void onClick(View v) {
			mEditor.setText("");
		}
	};
	/**
	 * Called when the activity's options menu needs to be created.
	 * The menu views and other resources will only be loaded if the menu
	 * key is actually pressed, saving memory, time, and battery in those cases 
	 * where the menu is never used.
	 */
	@Override
	public boolean onCreateOptionsMenu(Menu menu) {
		super.onCreateOptionsMenu(menu);
		
		// Inflate our menu from its XML  description.
		getMenuInflater().inflate(R.menu.skeleton_options_menu, menu);
		return true;
	}

	/**
	 * Called right before the activity's option menu is displayed. 
	 * Enable/disable menu items as needed based on the Activity state.
	 */
	@Override
	public boolean onPrepareOptionsMenu(Menu menu) {
		super.onPrepareOptionsMenu(menu);

		// Before showing the menu, we need to decide whether the clear menu
		// item should be enabled. It will only be enabled if there is text to clear.
		menu.findItem(R.id.menu_clear).setEnabled(mEditor.getText().length() > 0);
		return true;
	}

	/**
	 * Called when a menu item is selected.
	 * In this example, the menu items and UI buttons have the same functionality.
	 * To avoid error prone duplication of code, the buttons' listeners are called
	 * to actually implement the menu/button action.
	 */
	@Override
	public boolean onOptionsItemSelected(MenuItem item) {
		switch (item.getItemId()) {
		case R.id.menu_back:
			mBackListener.onClick(findViewById(R.id.back));
			return true;
		case R.id.menu_clear:
			mClearListener.onClick(findViewById(R.id.clear));
			return true;
		}
		return super.onOptionsItemSelected(item);
	}
}

Intents Example

This is an example of using intents to include a system Activity into the application. I have changed the previous example to allow entry of a valid URL' replacing the back button with a view button. When pressed, a new Activity is started to view the specified URL. In this case, I use the built-in browser activity. So this application consists of my Activity and a system Activity.

<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright (C) 2007 The Android Open Source Project 
-->

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent" android:layout_height="fill_parent"
android:orientation="vertical">

<EditText android:id="@+id/editor" android:layout_width="fill_parent"
android:layout_height="0dip" android:autoText="true"
android:capitalize="sentences" android:layout_weight="1"
android:freezesText="true">
<requestFocus />
    </EditText>

    <LinearLayout android:layout_width="wrap_content"
        android:layout_height="wrap_content" android:layout_gravity="center_vertical"
        android:gravity="center_horizontal" android:orientation="horizontal"
        android:background="@drawable/semi_black">

       <Button style="@style/ActionButton"
            android:id="@+id/view" android:text="@string/view"/>

        <Button android:id="@+id/clear" style="@style/ActionButton"
            android:text="@string/clear" android:textColor="@color/red" />

       </LinearLayout>
</LinearLayout>

<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright (C) 2009 Motorola, Inc.
-->

<!--
This file describes the options menu of the main SkeletonApp activity
user interface.
-->
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:title="@string/view" android:id="@+id/menu_view"
        android:alphabeticShortcut="@string/view_char_shortcut"
        android:numericShortcut="@string/view_num_shortcut"></item>
    <item android:title="@string/clear" android:id="@+id/menu_clear"
        android:alphabeticShortcut="@string/clear_char_shortcut"
        android:numericShortcut="@string/clear_num_shortcut"></item>
</menu>

<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (C) 2007 The Android Open Source Project
     
     Copyright (C) 2009 Motorola, Inc.
-->

<!-- This file contains resource definitions for displayed strings, allowing
     them to be changed based on the locale and options. -->

<resources>
    <!-- Simple strings. -->
    <string name="app_name">Web App</string>
    <string name="view">View</string>
    <string name="clear">Clear</string>
    <string name="main_label">http://</string>
    <string name="view_char_shortcut">v</string>
    <string name="clear_char_shortcut">c</string>
    <string name="view_num_shortcut">0</string>
    <string name="clear_num_shortcut">1</string>
    <string name="Invalid_URL">Please enter a valid URL.</string>
</resources>

/*
 * Copyright (C) 2007 The Android Open Source Project
 * 
 * Copyright (C) 2009 Motorola, Inc.
 */

package com.webapp;

import java.net.URL;
import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.EditText;
import android.widget.Toast;


public class WebApp extends Activity {

private EditText mEditor;

public WebApp() {
}

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.webapp_activity);

    // Find the text editor view inside the layout, because we
    // want to do various programmatic things with it.
    mEditor = (EditText) findViewById(R.id.editor);

    // Set the initial content of the EditText view and move the insertion
    // point to the end of the string.
    mEditor.setText(R.string.main_label);
    mEditor.setSelection(getText(R.string.main_label).length());

    // Hook up button presses to the appropriate event handler.
    ((Button) findViewById(R.id.view)).setOnClickListener(mViewListener);
    ((Button) findViewById(R.id.clear)).setOnClickListener(mClearListener);
}

/**
 * A call-back for when the user presses the back button.
 */
OnClickListener mViewListener = new OnClickListener() {
public void onClick(View v) {
     try {
         // first, check to see if this is a valid URL
         // do not keep a reference to the object as the exception
         // side effect is what is of interest here.
         new URL(mEditor.getText().toString());

         // Create a Uri from the string. An intent with a VIEW action
         // requires a Uri object (note: Uri and URI are different!)
         Uri uri = Uri.parse(mEditor.getText().toString());

         // I intend to view the uri
         Intent intent = new Intent(Intent.ACTION_VIEW, uri);

         // start an Activity to view the uri
         // Android will look at the uri to determine the proper viewer
         startActivity(intent)
         } catch (Exception e) {
             Toast toast = Toast.makeText(getApplicationContext(),
                 R.string.Invalid_URL, Toast.LENGTH_SHORT);
             toast.show();
             }
     }
};

/**
 * A call-back for when the user presses the clear button.
 */
OnClickListener mClearListener = new OnClickListener() {
public void onClick(View v) {
     mEditor.setText(R.string.main_label);
     mEditor.setSelection(getText(R.string.main_label).length());
     }
};

@Override
public boolean onCreateOptionsMenu(Menu menu) {
     super.onCreateOptionsMenu(menu);

     // Inflate our menu from its XML description.
     getMenuInflater().inflate(R.menu.web_options_menu, menu);
     return true;
     }

@Override
public boolean onPrepareOptionsMenu(Menu menu) {
     super.onPrepareOptionsMenu(menu);

     // Before showing the menu, we need to decide whether the clear menu
     // item should be enabled. It will only be enabled if the text has been
     // changed.
     menu.findItem(R.id.menu_clear).setEnabled(
         !mEditor.getText().toString().equals(
             getText(R.string.main_label)));
     return true;
    }

/**
 * Called when a menu item is selected. In this example, the menu items and
 * UI buttons have the same functionality. To avoid error prone duplication
 * of code, the buttons' listeners are called to actually implement the
 * menu/button action.
 */
@Override
public boolean onOptionsItemSelected(MenuItem item) {
     switch (item.getItemId()) {
         case R.id.menu_view:
             mViewListener.onClick(findViewById(R.id.view));
             return true;
         case R.id.menu_clear;
             mClearListener.onClick(findViewById(R.id.clear));
             return true;
         }
     return super.onOptionsItemSelected(item);
     }
}

UI State and IDs

What happens if a user is in the middle of entering text when, to make it easier to read, they change orientation? Android helps you out a lot in this case. The state for each View with an ID is automatically captured before the Activity is killed, and the state is restored after the call to onCreate() when the Activity is restarted. The state of Views without an ID is not restored, so make sure that you assign an ID to every view who's state you want restored automatically.

This is why the SkeletonApp works even though there is no call to onSaveInstanceState() — all the interesting state is in the EditText view, which was assigned an ID.

Services

The parts of an application that hang around and do things for you, but are not displayed on the screen, are Services. You might initially think of services as an additional thread in the application, but you would be wrong. Think instead of a daemon process – a process that runs in the background and does things for you.

Services are also described in the Android Manifest and are launched by Intents in the same way as Activities. The main differences are that they do not have any visible components, so their lifecycle is different than Activities, and more than one Activity may make use of them at one time.

Services generally run in separate processes, so you will be making RPC calls to them. Not to worry about this too much; Google has created a reasonably simple proxy method to encapsulate the RPC calls. You will use the Android Interface Definition Language (aidl) to define the interface. The build system will create a couple of classes for you, and you use those classes to build the service and to use the service.

By the way, don't mess around with any files that the build system generates for you. I promise you many hours of nasty errors and debugging if you do.

Content Providers

Content Providers are data sources or destinations provided by other applications. For example the Contacts application has a content provider you may access to get names, addresses, or phone numbers. You may also write your own Content Provider if you wish to supply information to or receive updates to your information from other applications. A Content Provider exposes its data to other applications as a table in a database. Values are returned in a Cursor, a collection of rows. You may use the Cursor to read rows and columns in the resulting data.

In order to use a Content Provider you must have the URI that identifies the provider and the names and types of data you want. This information is available for each public content provider, such as the contacts database. When retrieving values, you may use a record ID or an SQL type WHERE clause to select one or more records.

Access to Content Providers may be governed by permissions.

Broadcast Receivers

Broadcast Receivers allow your application to respond to system events or events generated by other applications. Like Services, they have no user visible appearance. As the system can generate many events, it is important that Broadcast Receivers act quickly on the information they receive. Normally you will use a Broadcast Receiver to start a Service or notify the user via a Notification that something of interest has happened.

Copyright © 2009, Motorola, Inc. All rights reserved except as otherwise explicitly indicated.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.