The Android SDK includes many sample apps that can help you learn Android by inspecting how different APIs are used to build a mobile application. These sample apps are available for download through the Android SDK Manager. Learn how to easily create Eclipse projects around these sample apps, compile them, and use them in your own projects.

Part 0: Getting Started

This tutorial is for the Java developer just getting started learning Android app development, who is familiar with Eclipse, and who has installed the Android SDK with the Android Developer Plugin for Eclipse. If you are not prepared, see the previous tutorials in this series.

Step 1: Download the Android Samples

The Android SDK Samples can be downloaded using the Android SDK Manager. The samples are organized by the API Level they were designed for, and can be downloaded under the label "Samples for SDK". On a related note, the Google API add-on downloads tend to come with samples specifically to illustrate their usage.

As you're aware, the Android SDK Manager downloads samples into a directory under your SDK installation. You could use these to start the project. You could even copy them out so you don't modify the originals. But, that's not how we're going to do it! There’s a better way!

Step 2: Start the Sample Project Wizard

In Eclipse, choose File > New > Other..., then expand the Android folder, and choose "Android Sample Project".

Step 3: Pick a Build Target

Next, you'll be presented with a list of build targets. What you see here is directly related to which API Level samples you have installed through the Android SDK Manager. What you see in our screenshot is probably overkill. Few will want to target Android 1.1 (Really).

You can only choose one build target for your project. To follow along, choose Android 4.1, Android Open Source Project, which is API Level 16.

Step 4: Pick a Sample Project

On the next screen, you'll be shown a variety of compatible sample projects to choose from. Projects that end in "> tests" are JUnit test projects that match up to a primary project. They are less interesting for the beginner, so stick to non-test projects for now.

Pick a sample project, then type in a name if you'd like to change it. Changing the name is useful if you've already created the sample project once and want to create a new version within the sample Eclipse workspace. To continue following along, pick ApiDemos. We're naming it "ApiDemo 4.1" so as not to confuse it with other ApiDemos samples from other SDK versions.

Step 5: Explore a Sample Project

Your new project will now show up in Eclipse. You can look through its files, packages, and the structure of the sample app. The ApiDemos sample app is particularly big, as it has sample code to demonstrate almost every core Android API.

Step 6: Launch a Sample Project

Let's compile and launch our new sample project on the emulator. First, start your emulator and wait for it to fully launch (forget how this works? See Android Virtual Device Creation).

Next, choose Run > Run Configurations...

Double-click on Android Application (or right-click and choose New). On the first tab, choose the Browse... button, pick your new sample project, and click OK.

Now fill in the Name field. We usually name our Run Configurations with the project name to avoid confusion but you can name it whatever you like. Run and Debug Configurations have different options such that you could want multiple configurations for a single project.

On the Target tab, check the radio button for "Always prompt to pick device." Take note of some of the other Run Configuration options, like the network speed and latency; we're not going to use any of these options right now but it’s worth knowing where they are.

Now click the Run button. You should get the Android Device Chooser dialog now. This dialog will display any currently connected Android devices and running emulator instances in the top section, as well as offer the option of launching a new emulator instance via a compatible AVD configuration on-the-fly.

Pick the emulator you already have running and click the OK button. You'll see something like, "Uploading ApiDemo 4.1.apk onto device 'emulator-5554'" in the Eclipse console while the binary is being copied to the emulator and installed. After a moment, the ApiDemos sample app will launch within the emulator.

Step 7: Try More Sample Apps

Now that you know how to create an Eclipse project for and run an Android SDK sample app, you can create any that you'd like. Remember that each API may have a different set of sample apps. Explore them. For example, here's an image of the Weather List Widget sample app:

Step 8: Try Samples on Your Device

Connect your Android phone or tablet up to your development machine (forget how? Read Connecting Physical Android Devices To Your Development Machine). Your device will appear in the Android Device Chooser whenever you try to launch your app via its Run Configuration. As long as the app’s API target meets the API level version requirements for the sample app, you should be able to load it and run it in just the same as the emulator.

Conclusion

You've learned how to create projects out of the sample apps through a few simple steps in Eclipse. You've also learned how to run them on the emulator and even your own Android devices! You're well on your way to Android development. What kinds of apps are you looking forward to creating? Which sample app was your favorite? Let us know in the comments!

About the Authors

Mobile developers Lauren Darcey and Shane Conder have coauthored several books on Android development: an in-depth programming book entitled Android Wireless Application Development (now in it's third edition as a two-volume set), Sams Teach Yourself Android Application Development in 24 Hours, and Learning Android Application Programming for the Kindle Fire: A Hands-On Guide to Building Your First Android Application. When not writing, they spend their time developing mobile software at their company and providing consulting services. They can be reached at via email to [email protected], via their blog at androidbook.blogspot.com, and on Twitter @androidwireless.

Need More Help Writing Android Apps? Check out our Latest Books and Resources!