android:label for the display name of the activity, and (frequently) an intent-filter child element describing under what conditions this activity will be displayed. The stock activity element sets up your activity to appear in the launcher, so users can choose to run it. As you’ll see later in this book, you can have several activities in one project if you so choose.
You may also have one or more receiver elements indicating non-activities that should be triggered under certain conditions, such as when an SMS message comes in. These are called intent receivers and are described in Chapter 23.
You may have one or more provider elements indicating content providers — components that supply data to your activities and, with your permission, other activities in other applications on the device. These wrap up databases or other data stores into a single API that any application can use. Later you’ll see how to create content providers and how to use content providers that you or others create.
Finally, you may have one or more service elements describing services — long-running pieces of code that can operate independent of any activity. The quintessential example is the MP3 player, where you want the music to keep playing even if the user pops open other activities and the MP3 player’s user interface is “misplaced.” Chapters 30 and 31 cover how to create and use services.
Achieving the Minimum
Android, like most operating systems, goes through various revisions, versions, and changes. Some of these affect the Android SDK, meaning there are new classes, methods, or parameters you can use that you could not in previous versions of the SDK.
If you want to ensure your application is run only on devices that have a certain version (or higher) of the Android environment, you will want to add a uses-sdk element as a child of the root manifest element in your AndroidManifest.xml file. The uses-sdk element has one attribute, minSdkVersion, indicating which SDK version your application requires:
<manifest xmlns:android='http://schemas.android.com/apk/res/android'
package='com.commonsware.android.search'>
<uses-sdk minSdkVersion='2' />
...
</manifest>
At the time of this writing, there are two possible minSdkVersion values:
• 1, indicating the original Android 1.0 SDK
• 2, indicating the Android 1.1 SDK
If you leave the uses-sdk element out entirely, it will behave as though minSdkVersion is set to 1.
If you set uses-sdk, the application will install only on compatible devices. You do not have to specify the latest SDK, but if you choose an older one, it is up to you to ensure your application works on every SDK version you claim is compatible. For example, if you leave off uses-sdk, in effect you are stipulating that your application works on every Android SDK version ever released, and it is up to you to test your application to determine if this is indeed the case.
PART 2
Activities
CHAPTER 4
Creating a Skeleton Application
Every programming-language or -environment book starts off with the ever-popular “Hello, World!” demonstration: just enough of a program to prove you can build things, not so much
that you cannot understand what is going on. However, the typical “Hello, World!” program has no interactivity (that is, it just dumps the words to a console), and so is really boring.
This chapter demonstrates a simple project, but one using Advanced Push-Button Technology and the current time to show you how a simple Android activity works.
Begin at the Beginning
To work with anything in Android, you need a project. With ordinary Java, if you wanted, you could just write a program as a single file, compile it with javac, and run it with java, without any other support structures. Android is more complex, but to help keep it manageable Google has supplied tools to help create the project. If you are using an Android-enabled IDE, such as Eclipse with the Android plugin (available in the Android SDK), you can create a project inside of the IDE (select File>New>Project, then choose Android>Android Project).
If you are using tools that are not Android-enabled, you can use the activitycreator script, found in the tools/ directory in your SDK installation. Just pass activitycreator the package name of the activity you want to create and an --out switch indicating where the project files should be generated. Here’s an example:
activitycreator --out /path/to/my/project/dir
com.commonsware.android.Now
You will wind up with a handful of pre-generated files, as described in Chapter 2. We’ll be using these files for the rest of this chapter.
You can also download the project directories of the samples shown in this book in a ZIP file on the CommonsWare Web site[6]. These projects are ready for use; you do not need to run activitycreator on those unpacked samples.
The Activity
Your project’s src/ directory contains the standard Java-style tree of directories based upon the Java package you used when you created the project (i.e., com.commonsware.android resulted in src/com/commonsware/android/). Inside the innermost directory you should find a pregenerated source file named Now.java, which is where your first activity will go. This activity will contain a single button that displays the time the button was last pushed (or the time the application was started if the button hasn’t been pushed).
Open Now.java in your editor and paste in the following code:
package com.commonsware.android.skeleton;
import android.app.Activity;
