A Guide for the Android Developer Guide

(also known as: the Android Developer Guide translated to understandable English)

by Dennis Sheil of Panacea Supplies

Last updated: June 19, 2011

You can e-mail me: "dsheil at vartmp dot com". E-mail me especially if you find errors, or the like. If you have questions about how to do something in Android, I would try Stack Overflow first before e-mailing me though. And read the Android Developer's Guide.

This tutorial is kind of "What the Android Developer's Guide didn't tell you" meets "The Android Developer Guide stripped of all the useless junk you don't need to know yet". Thus "A Guide for the Android Developer Guide". I'm writing the guide I wish I had read before reading the Android Developer Guide. This guide is not spectacular, but it does the job and should save you time and leave you a little less confused than I was reading the Android Developer's Guide.

This guide is intended for people who have an intermediate knowledge of Java, but are completely or mostly unfamiliar with the Android API. A little bit of knowledge of how a Linux system works is helpful as well, although if you know Java well, you can learn the Linux stuff as you go. It's expected you know your way around a computer and the Internet somewhat, but know little to nothing about the Android API

The first thing you need to know about developing for Android is you don't need an Android phone to develop for the Android! It's a good thing to have, but there are free Android emulators from Google, free IDEs like Eclipse to develop on and so forth, so you can start developing without spending a dime on anything aside from your computer. It's good to test your application on a real phone before pushing it out to the whole world, but you can borrow a friend's Android to test it if need be, or even go down to your local phone/electronics store where they often have working, net-connected Androids on display.

Download the SDK and run it

OK, so you're all ready and set to begin developing for the Android. First, download the Android SDK, which includes the emulator. Congratulations, you now have a nascent Android emulator, which does most of what a real Android can do (minus access to Android Market, or a working camera, or that sort of thing). So unpack the SDK. Don't just unpack it randomly, unpack it to a somewhat fixed directory location that you will use for a few weeks (or months).

Android has instructions for what to do next which you can read if you want. I just cut a lot of the blather out here, and also tell you the good things to do which they won't, such as to avoid installing the Android 3 API, since it is currently (June 19, 2011) slow and buggy, and you should wait a few months to download it as they should be releasing a nicer one in a few months, hopefully.

So go in the unpacked SDK directory and run tools/android. The Android SDK and AVD manager will pop up. Go to Available Packages and then Android Repository. It will say a bunch of stuff. What you need the most (as of June 19, 2011) in order of importance is:

1) Android SDK Tools
2) Android SDK Platform-tools
3) "SDK Platform Android 2.3.3, API 10".

With those three things you can start. But also get:

3) Samples for SDK API 10, revision 1
4) Documentation

It's also a good idea to get an earlier version of Android, 2.1 would be my choice. So get

5) "SDK Platform Android 2.1-update1, API 7".
6) Samples for SDK API 7

If you have room and time, grab everything, why not.

Create your first emulator

Then go to virtual devices. You will eventually be creating a number of these, but start with one. Go to New. For name type something like android2.3.3-api-10-wvga800. Target is Android 2.3.3, API 10. SD Card size can be whatever you want - maybe 30-50MB is good, it's up to you. Skin should be WVGA800. Do the default hardware.

Note: These are not the best specs for *every* emulator, just for your first one. Later you will make other emulators - with target 2.1, API 7. Or with an HVGA skin. Or whatever. But you have good specs for the first one. So Create AVD.

So now you made your first emulator. Highlight it and hit Start. If it is too big for your screen, that is often adjustable. It takes a while for the emulator to load. So learn this lesson while you are impatiently waiting for the emulator to load - you should keep your emulators running while developing. They take a minute (or more) to start, so why keep wasting that time opening and closing it? Keep it open all the time until you're done working for the day and then close it.

OK your Android emulator came up. If your computer is Internet connected, go to the Browser application on the Android emulator and see if you can browse the web. You should be able to. Your emulator does not have the Market app, does not have a camera and so forth, but it has a lot of what a normal Android has. Play around with the emulator a little, especially the dev tools and settings apps.

Download Eclipse

OK, onto development. If you do not have the Eclipse IDE, download it (or get it by yum or apt-get if you are on a Linux). "Eclipse IDE for Java Developers" works fine, if you want the extra bells and whistles in "Eclipse IDE for Java EE Developers", then get that instead. If you're unfamiliar with Eclipse, I recommend before connecting it to Android, you read the Eclipse documentation, start a new project, write a simple "Hello World" class, run the Java Application and look for the output. If you prefer another IDE for developing, that's fine, but start out with Eclipse as your IDE, and once you know what you're doing, switch over to your preferred IDE.

OK you know how to write Hello World apps with Eclipse now. Now download the latest Android Development Tools plug-in for Eclipse. This page explains how to do that. When the ADT plug-in first came out, it was buggy and had a lot of hassles associated with it. But now it is years later - and the ADT plug-in is still buggy and causes hassles! But it is a little better then it used to be. You should be able to at least install it nowadays without a problem. One thing you'll do when installing the plug-in is pointing to that directory you unpacked the SDK into. If you ever move that directory, you will have to point your Eclipse ADT plug-in to the new location.

Write your first Android app, then your second one, then...

Now you should write your first Hello World application in Android. The Android tutorial is good in this respect. It tells you to "Create an AVD". You've already done that! Create another one if you want, why not? The Hello World tutorial is pretty good, it's the next parts that I didn't like. They suggest doing a Notepad tutorial. I thought that was not good at all. You can try it if you want, I'd avoid it. The Hello Views tutorials are better. Start with Linear Layout and Table Layout. Those are very useful, you'll use both layouts over and over again when programming, and they are easy to learn. One thing they say on the page:

"Tip: After you have pasted sample code into an Eclipse project, press Ctrl (or Cmd) + Shift + O to import the required packages."

This is a very good tip and will save you many headaches.

After doing Linear layouts and Table layouts, do a tab layout. It's a little harder, but not that hard. Then do a ListView. ListView's are a little complicated, but if you follow the tutorial, that one should work. You can do the Spinner widget as well. Like the ListView, this is more complex then the other stuff, but it works from the tutorial.

Know the Activity component, forget the other three components for now

OK, back to the Android tutorial. It says for application components: "Application components are the essential building blocks of an Android application....There are four different types of application components: Activities, Services, Content providers and Broadcast receivers". This is correct, and the only one you have to worry about at this point in time is Activities, forget the other ones until you need to deal with them.

Later on that page it says: "Therefore, unlike applications on most other systems, Android applications don't have a single entry point (there's no main() function, for example)." Correct. Android is first going to look in your AndroidManifest.xml. The main action and the launcher category usually will be associated with one particular activity class, and that is the class which will launch initially. Android won't be looking for main(), it will be looking for that Activity's onCreate() method.

What is an Activity? "An activity represents a single screen with a user interface." Correct. Your Activity classes will be normal Java classes that extends the Activity class. They will display something on the screen. Period.

Intents

OK, we're going down the page of this dev guide.

"You can start an activity (or give it something new to do) by passing an Intent to startActivity() or startActivityForResult() (when you want the activity to return a result)."

Correct. You have one class. A class that extends Activity. A class that displays something to the screen. Maybe it is a TextView view. Maybe it has a LinearLayout Layout. Maybe it is a table layout. Maybe it is a ListView. Maybe is is a screen with some kind of layout or View with a button on the screen.

You want to go to a different activity. A second Activity-extending class you wrote, that does something different than your first Activity extending class. That looks different than your Activity extending class. An Intent gets you from one Activity class to another.

(Can you pass variables like Strings through the Intent? Can you send a URI "pointer" to data through an Intent? Yes. But don't worry about that yet.)

You create an Intent object. One of the parameters sent to the constructor will be the other Activity class you want to launch. You then run startActivityforResult() (or if you want, startActivity() ) with that Intent object as a parameter. Boom, you should now be in your other Activity class. Does this sound confusing? Believe me, it is 1000 times less confusing then everything that I read explaining this.

Clicking something on your screen

How do you tell if something on your screen is clicked? Read Hello Forms. Create a custom Button. The tutorial shows you how to set an onClick listener on the button. You have to set listeners on things to see if someone clicks on them or not. Or touches them. Or focuses on them. Or keys on to them. And so on. See how it pops up a Toast message? Toast messages are little widget notifications messages you can pop up on the Android. Comment out that Toast, and put in an intent for another Activity class you have. Now when you click on the button, instead of a message popping up, now you go to your other activity. Hit the back button to get back (or make a button over on that screen to get you back - or whatever).

What kind of phone should you primarily be designing for?

Go on your emulator. Hit Control-F11 or Control-F12. See how your emulator moves, and changes shape? Just like an Android can. Are people going to use your app in vertical (portrait) mode, or horizontal (landscape) mode, or both? I would favor starting with making your app look good on portrait. Once that is done, work on landscape. If you don't want to do landscape, lock your app so that people can only use it in portrait mode (yes, you can do that). It's better to do both, but do what you want.

I said to make a WVGA800 screen for your first emulator. Which is 480x800. Which is what most people have (many have 480x854). Most people have this, in high density (about 240 dots per inch). The screen is usually about four inches. This is the most common. So test in this emulator first.

Some people have older (or cheaper) phones of the same size (four inches) but in medium density (about 160 dots per inch). You should have an emulator for this as well - make an emulator with an HVGA screen, with a density of 160. Test your app in this as well. Less and less people have these nowadays, but there are still a significant number of people who still have these phones (as of June 19th, 2011). So see how your app looks on this emulator as well. When doing layout, use "dp" instead of "px", to avoid some of the work of dealing with all of these sizes. Theoretically, you can test a million sizes, and densities, and so forth, but testing for normal sized medium density and normal sized high density covers 95% of what is out there - the older medium density phones, and the more common newer high density phones. Also make sure to make a WVGA854 target emulator, not just a WVGA800. You normally have to do very little work to make WVGA854 look nice if WVGA800 looks nice.

What else? Google recommends you target the latest API, and fallback for other stuff. Once you know what you're doing, that is a good idea. For now, target the 2.1 API, and do the 2.2, 2.3 bells and whistles if the phone running your app is running those versions. About 28% of phones still run an API that is 2.1 or earlier. As time goes on that number will diminish.

XML hell

Also: Are you a Java expert or an XML expert? Note this if the former but not the latter: Anything you can do in XML with Android, you can do in Java. Anything. It may not be easy to figure out how, but it is always doable.

Here is the deal: Eventually, you *do* want to use a lot of XML. It makes your life easier on Android. But. There is a steep learning curve, or at least a decent-sized one. Not just for xml, but for the Andoid way of using xml. So do a little xml dabbling right off the bat, but learn how to do everything programmatically in java code. Write some Android programs that don't use xml at all, except for maybe looking up the name of the application. You are a programmer, not an XML layouter! Learn how to do absolutely everything in Java code if need be - LinearLayout, Tables, Buttons, TextViews, ListViews etc. Once you can do it one time in pure Java, once you at least are capable of doing it in pure Java, if only doing it that one time, *then* start using it the XML way.

XML does make life easier on Android. You lay it out and that's it. XML is especially good for static screens. XML is even good for screens where the widgets and views (buttons, TextViews etc.) are statically placed, but the words on them are dynamic - you can target things by the ID before you do a setContentView() call. When things are really, really dynamic, it runs into a little trouble, or a need for XML wizardry anyhow. Learn how to make everything in code if you have to. Then start adding the XML parts when it makes life easier for you. Especially if the screen layout is somewhat static. To learn how to do things in Java code, search stackoverflow.com for stuff like "Android programmatically textview" or "Android programmatically button" and the like. Android's documentation explains how to do this as well, although sometimes in a convoluted manner.

This is all I can think of for now that bugs me about the Android tutorials and documentation. If I think of anything else I'll update this. I have two applications on Android Market. If you think the layout of my applications could be better than they are, the problem is I spent days being confused by the Android Dev Guide instead of working on my layout!

In all sincerity though, I like what Google has done, I like the open platform nature of Android and a lot about it. But their documentation, their Eclipse ADT plug-in, their slow as hell Android 3 emulator and the like can sometimes cause frustration. I have a lot of positive feelings about Android, even though this document might not reflect it. Maybe reading this will help you avoid some of the anguish and anxiety I went through initially.

Up to /var/tmp