An activity is a component that presents a user interface so that the user can interact with an app. For example, Android's Contacts app includes an activity for entering a new contact, its Phone app includes an activity for dialing a phone number, and its Calculator app includes an activity for performing basic calculations (see Figure 1-2).

Figure 1.2. The main activity of Android's Calculator app lets the user perform basic calculations.

Although an app can include a single activity, it's more typical for apps to include multiple activities. For example, Calculator also includes an "advanced panel" activity that lets the user calculate square roots, perform trigonometry, and carry out other advanced mathematical operations.

A service is a component that runs in the background for an indefinite period of time, and which doesn't provide a user interface. As with an activity, a service runs on the process's main thread; it must spawn another thread to perform a time-consuming operation. Services are classified as local or remote.

Consider a service that plays music in response to a user's music choice via an activity. The user selects the song to play via this activity, and a service is started in response to the selection. The service plays the music on another thread to prevent the Application Not Responding dialog box (discussed in Appendix C) from appearing.

A broadcast receiver is a component that receives and reacts to broadcasts. Many broadcasts originate in system code; for example, an announcement is made to indicate that the timezone has been changed or the battery power is low.

Apps can also initiate broadcasts. For example, an app may want to let other apps know that some data has finished downloading from the network to the device and is now available for them to use.

A content provider is a component that makes a specific set of an app's data available to other apps. The data can be stored in the Android filesystem, in an SQLite database, or in any other manner that makes sense.

Content providers are preferable to directly accessing raw data because they decouple component code from raw data formats. This decoupling prevents code breakage when formats change.

You've read the previous introduction to Android and are eager to develop your first Android app. However, you must install Android SDK 2.3 before you can develop apps.

Google provides an Android SDK 2.3 distribution file for each of the Windows, Intel-based Mac OS X, and Linux operating systems. Download and unarchive the appropriate file for your platform and move its unarchived home directory to a convenient location. You might also want to update your PATH environment variable so that you can access the SDK's command-line tools from anywhere in your filesystem.

Before downloading and installing this file, you must be aware of SDK requirements. You cannot use the SDK if your development platform doesn't meet these requirements.

Android SDK 2.3 supports the following operating systems:

You'll quickly discover that Android SDK 2.3 is organized into various components: SDK tools, SDK Platform tools, different versions of the Android platform (also known as the Android software stack), SDK add-ons, USB driver for Windows, samples, and offline documentation. Each component requires a minimum amount of disk storage space; the total required amount of space depends upon which components you choose to install:

Finally, you should ensure that the following additional software is installed:

Point your browser to http://developer.android.com/sdk/index.html and download one of android-sdk_r08-windows.zip (Windows), android-sdk_r08-mac_86.zip (Mac OS X), and android-sdk_r08-linux_86.tgz (Linux).

For example, if you run Windows XP, download android-sdk_r08-windows.zip. After unarchiving this file, move the unarchived android-windows-sdk home directory to a convenient location in your filesystem; for example, you might move the unarchived C:unzippedandroid-sdk_r08-windowsandroid-sdk-windows home directory to the root directory on your C: drive, resulting in C:android-sdk-windows.

A subsequent examination of android-windows-sdk shows that this home directory contains the following subdirectories and files:

The tools directory contains a variety of useful tools, including the following:

Installing the Android SDK is insufficient for developing Android apps; you must also install at least one Android platform.

Use the SDK Manager tool to install an Android platform.

Run SDK Manager. This tool presents the Android SDK and AVD Manager dialog box, followed by the Refresh Sources and Choose Packages to Install dialog boxes.

Android SDK and AVD Manager identifies virtual devices, installed packages, and available packages. It also lets you configure proxy server and other settings.

When this dialog box appears, the Installed packages entry in the list appearing on the right side of the dialog box is highlighted, and the pane to the right of that list identifies all packages that have been installed. If you're installing Android for the first time, this pane reveals that only the Android SDK tools (revision 8) component has been installed.

After presenting this dialog box, SDK Manager scans Google's servers for available component packages to install. The Refresh Sources dialog box reveals its progress.

After SDK Manager finishes its scan, it presents the Choose Packages to Install dialog box (see Figure 1-6) to let you choose those SDK components you want to install.

Figure 1.6. The Packages list identifies those packages that can be installed.

The Choose Packages to Install dialog box shows a Packages list that identifies those packages that can be installed. It displays checkmarks beside packages that have been accepted for installation, and displays Xs beside those packages that have been rejected for installation.

For the highlighted package, Package Description & License presents a package description, a list of other packages that are dependent on this package being installed, information about the archive that houses the package, and additional information. Also, you can select a radio button to accept or reject the package.

Because this book focuses on Android 2.3, the only packages that you need to install are Android SDK Platform-tools, revision 1 and SDK Platform Android 2.3, API 9, revision 1. All other checked package entries can be unchecked by clicking the Reject radio button on their respective panes.

After making sure that only these entries are checked, click the Install button to begin installation. Figure 1-7 shows you the resulting Installing Archives dialog box.

Figure 1.7. The Installing Archives dialog box reveals the progress of downloading and installing each selected package archive.

You'll probably encounter the ADB Restart dialog box, which tells you that a package dependent on Android Debug Bridge (ADB) has been updated, and asking you whether you want to restart ADB now. Click the Yes button, which closes ADB Restart, then click Close on the Installing Archives dialog box.

You should now observe the Android SDK and AVD Manager's Installed packages pane also displaying Android SDK Platform-tools, revision 1 and SDK Platform Android 2.3, API 9, revision 1 in addition to Android SDK Tools, revision 8. You should also observe the following new subdirectories:

platform-tools contains development tools that may be updated with each platform release. Its tools include aapt (Android Asset Packaging Tool – view, create, and update Zip-compatible archives (.zip, .jar, .apk); and compile resources into binary assets), adb (Android Debug Bridge – manage the state of an emulator instance or an Android-powered device), and dx (Dalvik Executable – generate Android bytecode from Java .class files). android-9 stores Android 2.3 data and user interface-oriented files.

After installing the Android SDK and an Android platform, you're ready to start creating Android apps. However, you won't be able to run those apps via the emulator tool until you create an Android Virtual Device (AVD), a device configuration that represents an Android device.

Use the SDK Manager tool to create an AVD.

Run SDK Manager if necessary. Click the Android SDK and AVD Manager dialog box's Virtual devices entry in the list on the left. You should see the pane shown in Figure 1-8.

Figure 1.8. No AVDs are initially installed.

Click the New button. Figure 1-9 shows you the resulting Create new Android Virtual Device (AVD) dialog box.

Figure 1.9. An AVD consists of a name, a target platform, an SD Card, a skin, and hardware properties.

Figure 1-9 reveals that an AVD has a name, targets a specific Android platform, can emulate an SD card, and provides a skin with a certain screen resolution. Enter test_AVD for the name, select Android 2.3 – API Level 9 for the target platform, and enter 100 into the Size field for the SD card. Selecting Android 2.3 – API Level 9 results in Default (HVGA) being selected for the skin with an Abstracted LCD density property set to 160 dots per inch (dpi).

After entering the previous values and keeping the screen defaults, finish AVD creation by clicking Create AVD. The AVD pane in Figure 1-8 will now include an entry for test_AVD.

Although it's easier to use SDK Manager to create an AVD, you can also accomplish this task via the android tool by specifying android create avd -n name -t targetID [-option value].... Given this syntax, name identifies the device configuration (such as target_AVD), targetID is an integer ID that identifies the targeted Android platform (you can obtain this integer ID by executing android list targets), and [-option value]... identifies a series of options (such as SD card size).

If you don't specify sufficient options, android prompts to create a custom hardware profile. Press the Enter key if you don't want a custom hardware profile and prefer to use the default hardware emulation options. For example, the android create avd -n test_AVD -t 1 command line causes an AVD named test_AVD to be created. This command line assumes that 1 corresponds to the Android 2.3 platform and prompts to create a custom hardware profile.

You must start the AVD, which can take a few minutes to get started, before you can install and run apps on it, and want to know how to accomplish this task.

Use the SDK Manager tool to start the AVD. Or, start the AVD by using the emulator tool.

Refer to Figure 1-8 and you'll notice a disabled Start button. This button is no longer disabled after an AVD entry is created. Click Start to run the emulator tool with the highlighted AVD entry as the emulator's device configuration.

A Launch Options dialog box appears. This dialog box identifies the AVD's skin and screen density. It also provides unchecked checkboxes for scaling the resolution of the emulator's display to match the physical device's screen size, and for wiping user data.

Click the Launch button to launch the emulator with the AVD. SDK Manager responds by briefly displaying a Starting Android Emulator dialog box, followed by command windows (on Windows XP), and by finally displaying the emulator window.

The emulator window is divided into a left pane that displays the Android logo on a black background followed by the home screen, and a right pane that displays phone controls and a keyboard. Figure 1-10 shows these panes for the test_AVD device.

Figure 1.10. The emulator window presents the home screen on the left, and phone controls and a keyboard on the right.

If you've previously used an Android device, you're probably familiar with the home screen, the phone controls, and the keyboard. If not, there are a few items to keep in mind:

While the AVD is running, you can interact with it by using your mouse to "touch" the touchscreen and your keyboard to "press" the AVD keys. Table 1-2 shows you the mappings between AVD keys and keyboard keys.

Table 1-2 refers to the -trace startup option in the context of toggle code profiling. This option lets you store profiling results in a file when starting the AVD via the emulator tool.

For example, emulator -avd test_AVD-trace results.txt starts the emulator for device configuration test_AVD, and also stores profiling results in results.txt when you press F9. Press F9 again to stop code profiling.

Figure 1-10 displays 5554:test_AVD in the titlebar. The 5554 value identifies a console port that you can use to dynamically query and otherwise control the environment of the AVD.

You can connect to the AVD's console by specifying telnet localhost console-port. For example, specify telnet localhost 5554 to connect to test_AVD's console. Figure 1-11 shows you the resulting command window on Windows XP.

Figure 1.11. Type a command name by itself for command-specific help.

Now that you've installed the Android SDK, installed an Android platform, and created and started an AVD, you're ready to create an app, and install and run this app on the AVD. Although you could create an app based on Listing 1-2's SimpleActivity class, you'll probably find this recipe's UC app to be more interesting (and useful).

UC (an acronym for Units Converter) is an app that lets you convert between types of units. For example, you can convert a specific number of degrees Celsius to its equivalent number of degrees Fahrenheit, a specific number of pounds to its equivalent number of kilograms, and so on.

UC consists of a single activity (also named UC) that presents a user interface (revealed in Recipe 1-7) consisting of an input/output textfield for entering the number of units to convert and displaying the conversion result, a spinner for choosing a conversion, and buttons for clearing the textfield, performing the conversion, and closing the app.

Listing 1-9 presents the UC activity's source code.

// UC.java

package com.apress.uc;

import android.app.Activity;

import android.os.Bundle;

import android.text.Editable;
import android.text.TextWatcher;

import android.view.View;

import android.widget.AdapterView;
import android.widget.ArrayAdapter;
import android.widget.Button;
import android.widget.EditText;
import android.widget.Spinner;

public class UC extends Activity
{
   private int position = 0;

   private double[] multipliers =

{
      0.0015625,         // Acres to square miles
      101325.0,          // Atmospheres to Pascals
      100000.0,          // Bars to Pascals
      0,                 // Degrees Celsius to Degrees Fahrenheit (placeholder)
      0,                 // Degrees Fahrenheit to Degrees Celsius (placeholder)
      0.00001,           // Dynes to Newtons
      0.3048,            // Feet/Second to Metres/Second
      0.0284130625,      // Fluid Ounces (UK) to Litres
      0.0295735295625,   // Fluid Ounces (US) to Litres
      746.0,             // Horsepower (electric) to Watts
      735.499,           // Horsepower (metric) to Watts
      1/1016.0469088,    // Kilograms to Tons (UK or long)
      1/907.18474,       // Kilograms to Tons (US or short)
      1/0.0284130625,    // Litres to Fluid Ounces (UK)
      1/0.0295735295625, // Litres to Fluid Ounces (US)
      331.5,             // Mach Number to Metres/Second
      1/0.3048,          // Metres/Second to Feet/Second
      1/331.5,           // Metres/Second to Mach Number
      0.833,             // Miles/Gallon (UK) to Miles/Gallon (US)
      1/0.833,           // Miles/Gallon (US) to Miles/Gallon (UK)
      100000.0,          // Newtons to Dynes
      1/101325.0,        // Pascals to Atmospheres
      0.00001,           // Pascals to Bars
      640.0,             // Square Miles to Acres
      1016.0469088,      // Tons (UK or long) to Kilograms
      907.18474,         // Tons (US or short) to Kilograms
      1/746.0,           // Watts to Horsepower (electic)
      1/735.499          // Watts to Horsepower (metric)
   };

   @Override
   public void onCreate(Bundle savedInstanceState)
   {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);

      final EditText etUnits = (EditText) findViewById(R.id.units);

      final Spinner spnConversions = (Spinner) findViewById(R.id.conversions);
      ArrayAdapter<CharSequence> aa;
      aa = ArrayAdapter.
             createFromResource(this, R.array.conversions,
                                android.R.layout.simple_spinner_item);
      aa.setDropDownViewResource(android.R.layout.simple_spinner_item);
      spnConversions.setAdapter(aa);

      AdapterView.OnItemSelectedListener oisl;
      oisl = new AdapterView.OnItemSelectedListener()
      {
         @Override
         public void onItemSelected(AdapterView<?> parent, View view,
                                    int position, long id)
         {
            UC.this.position = position;
         }

@Override
         public void onNothingSelected(AdapterView<?> parent)
         {
            System.out.println("nothing");
         }
      };
      spnConversions.setOnItemSelectedListener(oisl);

      final Button btnClear = (Button) findViewById(R.id.clear);
      AdapterView.OnClickListener ocl;
      ocl = new AdapterView.OnClickListener()
      {
         @Override
         public void onClick(View v)
         {
            etUnits.setText("");
         }
      };
      btnClear.setOnClickListener(ocl);
      btnClear.setEnabled(false);

      final Button btnConvert = (Button) findViewById(R.id.convert);
      ocl = new AdapterView.OnClickListener()
      {
         @Override
         public void onClick(View v)
         {
            String text = etUnits.getText().toString();
            double input = Double.parseDouble(text);
            double result = 0;
            if (position == 3)
               result = input*9.0/5.0+32; // Celsius to Fahrenheit
            else
            if (position == 4)
               result = (input-32)*5.0/9.0; // Fahrenheit to Celsius
            else
               result = input*multipliers[position];
            etUnits.setText(""+result);
         }
      };
      btnConvert.setOnClickListener(ocl);
      btnConvert.setEnabled(false);

      Button btnClose = (Button) findViewById(R.id.close);
      ocl = new AdapterView.OnClickListener()
      {
         @Override
         public void onClick(View v)
         {
            finish();
         }
      };
      btnClose.setOnClickListener(ocl);

      TextWatcher tw;
      tw = new TextWatcher()
      {

@Override
         public void afterTextChanged(Editable s)
         {
         }

         @Override
         public void beforeTextChanged(CharSequence s, int start, int count,
                                       int after)
         {
         }

         @Override
         public void onTextChanged(CharSequence s, int start, int before,
                                   int count)
         {
            if (etUnits.getText().length() == 0)
            {
               btnClear.setEnabled(false);
               btnConvert.setEnabled(false);
            }
            else
            {
               btnClear.setEnabled(true);
               btnConvert.setEnabled(true);
            }
         }
      };
      etUnits.addTextChangedListener(tw);
   }
}

Listing 1-9 begins with a comment that conveniently identifies the source file (UC.java) describing the activity. This listing next presents a package statement that names the package (com.apress.uc), in which the source file's UC class is stored, followed by a series of import statements that import various Android API types.

Listing 1-9 next describes the UC class, which extends Activity. This class first declares position and multipliers fields:

All of the app's work takes place in the overriding onCreate(Bundle) method: no other methods are required, which helps to keep this app simple.

onCreate(Bundle) first invokes its same-named superclass method, a rule that must be followed by all overriding activity methods.

This method then executes setContentView(R.layout.main) to establish the app's user interface.

R.layout.main identifies a resource, a piece of data required by an app's code, and which you maintain independently of the code by storing it in a separate file.

You interpret this resource ID as follows:

R.layout.main is passed to Activity's void setContentView(int layoutResID) method to tell Android to create a user interface screen using the layout information stored in main.xml. Behind the scenes, Android creates the user interface components described in main.xml and positions them on the screen as specified by main.xml's layout data.

This user interface is based on views (abstractions of user interface components) and view groups (views that group related user interface components). Views are instances of classes that subclass the android.view.View class and are analogous to Java components. View groups are instances of classes that subclass the abstract android.view.ViewGroup class and are analogous to Java containers. Android refers to specific views (such as buttons or spinners) as widgets.

Continuing, onCreate(Bundle) executes final EditText etUnits = (EditText) findViewById(R.id.units);. This statement first calls View's View findViewById(int id) method to find the EditText view declared in main.xml and identified as units, and instantiate android.widget.EditText and initialize it to this view's declarative information, and then saves this object's reference in local variable etUnits. This variable is final because it's subsequently accessed from an anonymous inner class.

In a similar manner, final Spinner spnConversions = (Spinner) findViewById(R.id.conversions); instantiates the android.widget.Spinner class using the declarative information that's stored in main.xml, and saves the resulting object reference for subsequent access.

onCreate(Bundle) next addresses the spinner object having no text to display, by first calling the android.widget.ArrayAdapter class's ArrayAdapter<CharSequence> createFromResource(Context context, int textArrayResId, int textViewResId) method, which returns an array adapter that supplies text messages to the spinner:

After calling createFromResource(Context, int, int), onCreate(Bundle) calls ArrayAdapter's void setDropDownViewResource(int resource) method with android.R.layout.simple_spinner_item as the argument. This method call creates the dropdown view portion of the spinner.

Now that the array adapter has been created and initialized with the appropriate unit conversion strings and layout information, onCreate(Bundle) attaches this information to the spinner by calling spnConversions.setAdapter(aa);. This method call allows the spinner widget to access this information and present a list of conversions to the user.

UC needs to keep track of the currently selected spinner item so that it can perform the appropriate conversion. onCreate(Bundle) makes this possible by registering a listener with the spinner that responds to item-selected events by assigning the spinner's position to the (previously mentioned) position variable.

onCreate(Bundle) first instantiates an anonymous class that implements ArrayAdapter's nested OnItemSelectedListener interface, and then registers this instance with the spinner by calling AdapterView's void setOnItemSelectedListener(AdapterView.OnItemSelectedListener listener) method.

OnItemSelectedListener's void onItemSelected(AdapterView<?> parent, View view, int position, long id) method is invoked whenever the user selects a new item, and is the perfect place to save the position. Although not needed, the companion void onNothingSelected(AdapterView<?> parent) method must also be implemented.

With the spinner out of the way, onCreate(Bundle) turns its attention to creating the Clear, Convert, and Close buttons. For each button, it invokes findByViewId(int) to obtain the button information from main.xml, and then instantiate the android.widget.Button class.

AdapterView's nested onClickListener interface is then employed to create listener objects, whose void onClick(View v) methods are invoked whenever the user clicks a button. Each listener is registered with its Button object by calling AdapterView's void setOnItemClickListener(AdapterView.OnItemClickListener listener) method.

The Clear button's click listener simply executes etUnits.setText("") to clear user input or a conversion result from the etUnits textfield. The Close button's click listener is equally simple; it invokes finish() to terminate the current activity and UC app. In contrast, the Convert button's click listener has more work to accomplish:

There's one more task for onCreate(Bundle) to perform: make sure that the Clear and Convert buttons are disabled when etUnits is empty. After all, there's no point clearing an empty textfield, and parseDouble() throws an exception when attempting to parse an empty textfield.

onCreate(Bundle) accomplishes this task by registering a textwatcher (an object whose class implements the android.text.TextWatcher interface) with the etUnits textfield, via android.widget.TextView's void addTextChangedListener(TextWatcher watcher) method. TextView is EditText's superclass.

TextWatcher declares void afterTextChanged(Editable s), void beforeTextChanged(CharSequence s, int start, int count, int after), and void onTextChanged(CharSequence s, int start, int before, int count) methods. Only the latter method is overridden to enable or disable the Clear and Convert buttons.

onTextChanged(s, int, int, int) first evaluates etUnits.getText().length(), which returns the textfield's length. If the length is 0 (empty textfield), the buttons are disabled via btnClear.setEnabled(false); and btnConvert.setEnabled(false);. Otherwise, they're enabled via btnClear.setEnabled(true); and btnConvert.setEnabled(true);.

Most of UC's resources are stored in XML files. For example, UC's widget and layout information is stored in main.xml, which Listing 1-10 presents.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:orientation="vertical"
   android:layout_width="fill_parent"
   android:layout_height="fill_parent"
   android:gravity="center_vertical"
   android:background="@drawable/gradientbg"
   android:padding="5dip">
   <LinearLayout android:layout_width="fill_parent"
      android:layout_height="wrap_content">
      <TextView android:layout_width="wrap_content"
         android:layout_height="wrap_content"
         android:layout_marginRight="10dip"
         android:text="@string/units"
         android:textColor="#000000"
         android:textSize="15sp"
         android:textStyle="bold"/>
      <EditText android:id="@+id/units"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         android:hint="type a number"
         android:inputType="numberDecimal|numberSigned"
         android:maxLines="1"/>
   </LinearLayout>

<Spinner android:id="@+id/conversions"
      android:layout_width="fill_parent"
      android:layout_height="wrap_content"
      android:prompt="@string/prompt"/>
   <LinearLayout android:layout_width="fill_parent"
      android:layout_height="wrap_content">
      <Button android:id="@+id/clear"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         android:layout_weight="1"
         android:text="@string/clear"/>
      <Button android:id="@+id/convert"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         android:layout_weight="1"
         android:text="@string/convert"/>
      <Button android:id="@+id/close"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         android:layout_weight="1"
         android:text="@string/close"/>
   </LinearLayout>
</LinearLayout>

Listing 1-10 begins by declaring a <LinearLayout> tag that specifies a layout (a view group that arranges contained views on an Android device's screen in some manner) for arranging contained widgets and nested layouts either horizontally or vertically across the screen.

The <LinearLayout> tag specifies several attributes for controlling this linear layout. These attributes include the following:

A second linear layout has been nested inside the first linear layout. Because no orientation attribute is specified, this layout lays out its widgets horizontally. As with the parent layout, layout_width is assigned "fill_parent". However, layout_height is assigned "wrap_content" to prevent this nested layout from occupying the entire screen.

The nested linear layout encapsulates textview and edittext elements. The textview element describes a widget that serves as a label for the widget described by the edittext element. The <textview> tag presents the following attributes in addition to layout_width and layout_height:

The <edittext> tag provides the following attributes:

Below the linear layout element lies a spinner element named conversions. This element is declared to fill the screen's width, but not the screen's height. Futhermore, its prompt attribute is assigned "@string/prompt" to prompt the user (on the dropdown view, which is shown in Figure 1-15) to select a conversion.

Below the spinner element lies another nested linear layout, encapsulating the Clear, Convert, and Close buttons. Each button is assigned a unique ID so it can be referenced from code. Its layout_weight attribute is assigned the same value as the other buttons' layout_weight attributes so that each button has the same width (it looks nicer).

Android let you declare shape resources (such as rectangles or ovals) as XML files. These shapes can be declared with straight or rounded corners, with gradient backgrounds, and with other attributes. For example, Listing 1-11 introduces a rectangle shape with a gradient background.

<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android">
   <gradient android:startColor="#fccb06"
      android:endColor="#fd6006"
      android:angle="270"/>
   <corners android:radius="10dp"/>
</shape>

The <shape> tag introduces a shape via its shape attribute. If this attribute is not present, the shape defaults to a rectangle.

The nested <gradient> tag defines the shape's color in terms of a gradient, which is specified via startColor, endColor, and angle attributes. The angle attribute specifies the direction that the gradient sweeps across the rectangle. If angle is not present, the angle defaults to 0 degrees.

The nested <corners> tag determines whether or not a rectangle shape has corners. If this tag is present, its attributes identify the degree of roundness for each or all corners. For example, the radius attribute in Listing 1-11 specifies that each corner has a radius of 10 density-independent pixels – dp is a synonym for dip.

Strings should be stored separately to facilitate localization of text. Android mandates that strings be stored in a file named strings.xml, which Listing 1-12 presents.

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <string name="app_name">Units Converter</string>
   <string name="clear">Clear</string>
   <string name="close">Close</string>
   <string name="convert">Convert</string>
   <string name="prompt">Select a conversion</string>
   <string name="units">Units</string>
</resources>

The strings.xml file stores its strings as a sequence of string elements that are nested in a resources element. Each <string> tag requires a unique name attribute whose content identifies the string, and which is referenced from code or some other resource. The string text is placed between the <string> and </string> tags.

Finally, the array of conversion strings is stored in arrays.xml. Listing 1-13 reveals this standard file's contents.

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <string-array name="conversions">
      <item>Acres to Square Miles</item>
      <item>Atmospheres to Pascals</item>
      <item>Bars to Pascals</item>
      <item>Degrees Celsius to Degrees Fahrenheit</item>
      <item>Degrees Fahrenheit to Degrees Celsius</item>
      <item>Dynes to Newtons</item>
      <item>Feet/Second to Metres/Second</item>
      <item>Fluid Ounces (UK) to Litres</item>
      <item>Fluid Ounces (US) to Litres</item>
      <item>Horsepower (electric) to Watts</item>
      <item>Horsepower (metric) to Watts</item>
      <item>Kilograms to Tons (UK or long)</item>
      <item>Kilograms to Tons (US or short)</item>
      <item>Litres to Fluid ounces (UK)</item>
      <item>Litres to Fluid ounces (US)</item>

<item>Mach Number to Metres/Second</item>
      <item>Metres/Second to Feet/Second</item>
      <item>Metres/Second to Mach Number</item>
      <item>Miles/Gallon (UK) to Miles/Gallon (US)</item>
      <item>Miles/Gallon (US) to Miles/Gallon (UK)</item>
      <item>Newtons to Dynes</item>
      <item>Pascals to Atmospheres</item>
      <item>Pascals to Bars</item>
      <item>Square Miles to Acres</item>
      <item>Tons (UK or long) to Kilograms</item>
      <item>Tons (US or short) to Kilograms</item>
      <item>Watts to Horsepower (electric)</item>
      <item>Watts to Horsepower (metric)</item>
   </string-array>
</resources>

Android lets you store arrays with different types of data in arrays.xml. For example, <string-array> indicates that the array contains strings. This tag requires a name attribute whose value uniquely identifies this array. Each array item is specified by placing its content between <item> and </item> tags.

You want to learn how to create UC using the Android SDK's command-line tools, but are not sure how to accomplish this task.

Use the android tool to create UC, and then use ant to build this project.

Your first step in creating UC is to use the android tool to create a project. When used in this way, android requires you to adhere to the following syntax (which is spread across multiple lines for readability):

android create project --target target_ID
                       --name your_project_name
                       --path /path/to/your/project/project_name
                       --activity your_activity_name
                       --package your_package_namespace

Except for --name (or –n), which specifies the project's name (if provided, this name will be used for the resulting .apk filename when you build your app), all of the following options are required:

Assuming a Windows XP platform, and assuming a C:prjdev hierarchy where the UC project is to be stored in C:prjdevUC, invoke the following command from anywhere in the filesystem to create UC:

android create project -t 1 -p C:prjdevUC -a UC -k com.apress.uc

This command creates various directories and adds files to some of these directories. It specifically creates the following file and directory structure within C:prjdevUC:

res contains the following directories:

Also, src contains the comapressuc directory structure, and the final uc subdirectory contains a skeletal UC.java source file. This skeletal file's contents are replaced with Listing 1-9.

Assuming that C:prjdevUC is current, build this app with the help of Apache's ant tool, which defaults to processing this directory's build.xml file. At the command line, specify ant followed by debug or release to indicate the build mode:

Build UC in debug mode by invoking ant debug from the C:prjdevUC directory. This command creates a gen subdirectory containing the ant-generated R.java file (in a comapressuc directory hierarchy), and stores the created UC-debug.apk file in the bin subdirectory.

You want to install the UC-debug.apk package file that you just created on the previously started AVD and run this app.

Use the adb tool to install UC. Navigate to the app launcher screen to run UC.

Assuming that the AVD is still running, execute adb install C:prjdevUCinUC-debug.apk to install UC-debug.apk on the AVD. After a few moments, you should see several messages similar to the following:

411 KB/s (19770 bytes in 0.046s)
        pkg: /data/local/tmp/UC-debug.apk
Success

From the home screen, click the app launcher icon (the rectangular grid icon centered at the bottom of the home screen) and scroll down on the result screen's list of app icons. Figure 1-12 shows you the Units Converter app entry.

Figure 1.12. The highlighted Units Converter app entry displays a custom icon (in an icon.png file, which is included in this book's code) that's also stored in drawable-mdpi.

Click the Units Converter icon and you should see the screen shown in Figure 1-13.

Figure 1.13. The Units textfield prompts the user to type a number.

Enter 37 into the Units textfield and you'll see the screen shown in Figure 1-14.

Figure 1.14. The Clear and Convert buttons are no longer disabled.

Click the spinner and you'll see the screen shown in Figure 1-15.

Figure 1.15. The spinner displays the prompt at the top of its drop-down list of conversion names.

Select "Degrees Celsius to Degrees Fahrenheit" and you'll see a screen similar to Figure 1-16.

Figure 1.16. The Units textfield displays the conversion result after clicking Convert.

Click Close to terminate the app and return to the launcher screen shown in Figure 1-12.

You're satisfied that UC works properly, and now you want to prepare it for publishing to Google's Android Market or another publishing service.

Before you can publish an app such as UC, you should version the app. You then build the app in release mode, and sign and align its app package.

Google's online Android Developer's Guide (http://developer.android.com/guide/index.html) provides extensive information on publishing an app. Rather than repeat the guide's information, this recipe presents the steps that are necessary to prepare UC for publishing.

ant release

keytool -genkey -v -keystore uc-release-key.keystore -alias uc_key -keyalg RSA
        -keysize 2048 -validity 10000

keytool -list -v -keystore uc-release-key.keystore

jarsigner -verbose -keystore uc-release-key.keystore bin/UC-unsigned.apk uc_key

adding: META-INF/MANIFEST.MF
   adding: META-INF/UC_KEY.SF
   adding: META-INF/UC_KEY.RSA
  signing: res/layout/main.xml
  signing: AndroidManifest.xml
  signing: resources.arsc
  signing: res/drawable-hdpi/icon.png
  signing: res/drawable-ldpi/icon.png
  signing: res/drawable-mdpi/gradientbg.xml
  signing: res/drawable-mdpi/icon.png
  signing: classes.dex

no manifest.
jar is unsigned. (signatures missing or not parsable)

zipalign [-f] [-v] <alignment>infile.apkoutfile.apk

zipalign –f –v 4 UC-unsigned.apk UC.apk

zipalign -c -v <alignment>existing.apk

zipalign –c –v 4 UC.apk

You prefer to develop apps using the Eclipse IDE.

To develop apps with Eclipse, you need to install an IDE such as Eclipse Classic 3.6.1. Furthermore, you need to install the ADT Plugin.

Before you can develop Android apps with Eclipse, you must complete at least the first two of the following three tasks:

You should complete these tasks in the order presented. You cannot install the ADT Plugin before installing Eclipse, and you cannot configure or use the ADT Plugin before installing the Android SDK and at least one Android platform.

The Eclipse.org website makes available for download several IDE packages that meet different requirements. Google places several stipulations and recommendations on which IDE package you should download and install:

Complete the following steps to install Eclipse Classic 3.6.1:

Complete the following steps to install the latest revision of the ADT Plugin:

To complete the installation of the ADT Plugin, you must configure this plugin by modifying the ADT preferences in Eclipse to point to the Android SDK home directory. Accomplish this task by completing the following steps:

Now that you've installed Eclipse Classic 3.6.1 and the ADT Plugin, you want to learn how to use this IDE/Plugin to develop UC.

You first need to create an Android Eclipse project named UC. You then introduce various source files and drag resources to various directories. Finally, you execute UC by selecting Run from the menubar.

The first task in developing UC with Eclipse is to create a new Android project. Complete the following steps to create this project:

Eclipse responds by creating a UC directory with the following subdirectories and files within your Eclipse workspace directory:

Close the Welcome tab. Eclipse presents the user interface that's shown in Figure 1-17.

Figure 1.17. Eclipse's user interface is organized around a menubar, a toolbar, several windows (such as Package Explorer and Outline), a statusbar, and a blank area that's reserved for editor windows.

This user interface is known as the workbench. The Package Explorer window appears on the left and presents an expandable list of nodes that identify the various projects in the current workspace and their components. Figure 1-17 reveals that UC is the only project in the workspace.

To learn how Eclipse organizes the UC project, click the + icon to the left of this node. Figure 1-18 reveals an expanded project hierarchy.

Figure 1.18. Additional + icons have been clicked to reveal more of UC's file organization.

Double-click the UC.java node. Eclipse responds by presenting the UC.java window that's revealed in Figure 1-19.

Figure 1.19. UC.java reveals skeletal content.

Replace UC.java's skeletal content with Listing 1-9 and disregard the errors that Eclipse reports. You'll correct these errors later.

Complete the following steps to introduce the necessary resources to this project:

Select Run from the menubar, and select Run from the resulting dropdown menu. On the resulting Run As dialog box, select Android Application and click OK.

If all goes well, Eclipse launches the emulator tool with the test_AVD device, installs the UC app, and causes this app to start running (see Figure 1-13).