What's that? A new upgrade to a higher Android OS is available for your phone and provider? Say it ain't so! If you’ve just gotten the good word that a new version of the Android OS is available for you to upgrade to, you might have one thought above all others: dude, that's totally sweet. Of course, if you're thinking about how difficult it's going to be to get your hands on the new version and actually have it work, don't worry: it's really not as hard as you might think to get this done. You just need to follow a few steps.

Ready to get started? Great, so are we:

First and foremost, you will want to make sure that you actually back up all of your files. And yes, we do mean all of them. Everything's going to get erased because it's a total operating system change. You want to make sure that your contacts, photos, videos, and everything else that's customized is backed up as much as possible. Your apps too, if you want to just move them back when they're finished.

From there, you will need to also make sure that you have plenty of space on that shiny SD card of yours. It's tempting to try to stick things onto an already crowded SD Card, but hits is not something that you want to deal with having no space for -- it will ruin your chances of a smooth Android installation.

The last step really is to download the new file package, which can be pretty big. You don't want to go with an unstable Internet connection for this, as it's going to make it very, very difficult to get anything correctly installed. You will need a Wi-Fi stable connection that you can use for a little while -- long enough to download the package.

Thankfully, everything else is automated. You aren't going to have to worry about making ten thousand decisions at once. The phone knows what to do, and you can count on your Android phone to do it well.

Now, you might think that there are going to be problems with installing a new operating system, but it's really not the case. Of course, if you need help you can always stop into any of the many Android forums online. They know how to get things done for you, and they can show you a few tips and tricks that really go beyond the scope of this guide. Why not get started today, you'll definitely be glad that you did!

Downloading non-market applications from our AndroidApps directory is simple on Android. Here’s what you do:

First, head over to the main settings of your T-Mobile G1

Then go to Applications>Unknown Sources and click OK

Visit Android Apps and download your desired application (should have a .apk extension)

Run the file and install the app

Remember: you won’t be able to view the application from Market Downloads but it will be available in your “pull-up” menu and you can add the icon to your desktop by long-pressing and selecting it in “applications”.

1

To start developing Android Applications, you need to download the SDK (Software Development Kit). At the moment, the best IDE (Integrated Development Environment) for Android is Eclipse. Below is a step-by-step installation guide to get you ready to start developing.

  1. Download the newest Android SDK from the Google Android Page.
  2. Download Eclipse Classic Ganymede from the Eclipse website. (To run Eclipse, you also need to have the Java Runtime Environment (JRE) installed)
  3. After downloading the SDK unpack the archive to a folder on your computer.
  4. Do the same for Eclipse
  5. To install the ADT (Android Development Tools) plugin for Eclipse, startup Eclipse and select HelpSoftware Updates….
  6. In the dialog that appears, click the Available Software tab.
  7. Click Add Site…
  8. Enter https://dl-ssl.google.com/android/eclipse/ (if you are getting an error about the site not responding, change https into http.
  9. Back in the Available Software view, you should see the plugin. Select the checkbox next to Developer Tools and click Install…
  10. On the subsequent Install window, “Android Developer Tools”, and “Android Editors” should both be checked. The Android Editors feature is optional, but recommended. If you choose to install it, you need the WST plugin mentioned earlier in this page.
    Click
    Finish.
  11. Restart Eclipse
  12. After restart: Select WindowPreferences… to open the Preferences panel.
  13. Select Android from the left panel.
  14. For the SDK Location in the main panel, click Browse… and locate the SDK directory.
  15. Click Apply, then OK.

The following tutorial addresses how to perform ‘hit’ testing for user ‘clicks’ in a View. By hit testing, we mean the ability to determine when a user’s selection of a specific Point in a View overlaps with a region that we are monitoring for further action.

In other words at the end of this MapView tutorial, your users will be able to click on any icon that you draw onto the map, and you’ll be able to take whatever action you like such as displaying a transparent popup window (as we do in the tutorial).

Here’s what the final result will look like:

Screenshot of Tutorial 2 results

We’ll assume you already know how to add a MapView to a layout and create an Overlay and will jump right into how to test whether a user selection ‘hit’ one of those mapped icons.

Our icons are rendered by an extension of Overlay we have named MapLocationOverlay which has 2 primary methods called during an Overlay.draw(). We’ll go through each of these in detail:

drawMapLocations(canvas, mapView, shadow);
drawInfoWindow(canvas,
mapView, shadow);

More important perhaps, we’ll discuss the following method which performs the hit testing of each user tap on the screen.

isHitMapLocation(mapView,point);

Starting with locations on our MapView

We start by creating a class, MapLocation, to store our map location name, latitude, & longitude. Four instances of MapLocation are created as shown in the screenshot of San Francisco above:

mapLocations = new ArrayList<MapLocation>();
mapLocations.add(new MapLocation(”North Beach”,37.799800872802734,-122.40699768066406));
mapLocations.add(new MapLocation(”China Town”,37.792598724365234,-122.40599822998047));
mapLocations.add(new MapLocation(”Fisherman’s Wharf”,37.8091011047,-122.416000366));
mapLocations.add(new MapLocation(”Financial District”,37.79410171508789,-122.4010009765625));

These map locations will be drawn to the MapView and used for testing user clicks.

Drawing Map Locations

Before we can test for users clicking our icon, we need to first learn how those icons are drawn to the screen. Once you are comfortable setting the screen coordinates for drawing of your icon, it will be simple to test those same coordinates for ‘hits’ (user clicks” on that icon).

Screen coordinates start at (0,0) in the upper-left and end at the bottom-right (screenWidth,screenHeight) of our screen. To draw our location’s icon, we must first know how to translate from the latitude/longitude coordinates of our map location to these x & y screen coordinates. Android provides this function for us via the Projection class which is available from the MapView passed in Overlay’s draw() method: MapView.getProjection()

public void draw(Canvas canvas, MapView mapView, boolean shadow)

To use Projection, simply pass an int[2] to Projection along with our location’s latitude/longitude as a Point. The projection does its magic and returns the screen coordinates of our map location.

int[] screenCoords = new int[2];
mapView.getProjection().getPointXY(testLocation.getPoint(), screenCoords);

As we will be drawing a bitmap balloon icon to the screen, we must ensuring that the bottom middle of our icon is directly on top of our location’s latitude & longitude screen coordinates (as shown in the image below). This accurate positioning of our icon will be key to hit testing later on.

Screen coordinates of icon

To draw the balloon icon then, we call drawBitmap() and ensure the top/left of our icon is properly offset.

canvas.drawBitmap(icon, screenCoords[0] – icon.width()/2, screenCoords[1] – icon.height(),null);

And that’s it, our icons is now properly drawn on the screen. Now we need to perform ‘hit’ tests for user interaction with these icons.

Listening for Map Taps & Then Testing for ‘Hits’

User taps on the MapView are captured by overriding Overlay’s onTouchEvent() method and then testing for overlap with our icons’ locations on the screen. If a hit occurs and new information popup displayed (or a prior information popup removed), then we invalidate the map so Overlay.draw() is called.

@Override
public boolean onTouchEvent(MotionEvent event, MapView mapView) {

// Store whether prior popup was displayed so call invalidate() to remove it if necessary.
boolean isRemovePriorPopup = selectedMapLocation != null;

// Next test whether a new popup should be displayed
selectedMapLocation = getHitMapLocation(mapView,event);
if ( isRemovePriorPopup || selectedMapLocation != null) {

mapView.invalidate();

}

// Lastly return true if we handled this onTap()
return selectedMapLocation != null;

}

So here’s the real point of this tutorial…how do we match the screen coordinates that the user clicks to the latitude & longitude of our icon on the map?

Just as we determined the location of our map for drawing on the screen, we will now create a Rectangle to represent that drawn icon and use the Rectangle.contains() method to test whether the user’s MotionEvent occurred within that Rectangle.

private MapLocation getHitMapLocation(MapView mapView, MotionEvent    event) {

// Track which MapLocation was hit…if any
MapLocation hitMapLocation = null;

RectF hitTestRecr = new RectF();
int[] screenCoords = new int[2];
Iterator<MapLocation> iterator = mapView.getMapLocations().iterator();
while(iterator.hasNext()) {

MapLocation testLocation = iterator.next();

// As above, translate MapLocation lat/long to screen coordinates
mapView.getProjection().getPointXY(testLocation.getPoint(), screenCoords);

// Use this information to create a ‘hit” testing Rectangle to represent the size
// of our location’s icon at the correct location on the screen.

// As we want the base of our balloon icon to be at the exact location of
//
our map location, we set our Rectangle’s location so the bottom-middle of
//
our icon is at the screen coordinates of our map location (shown above).
hitTestRecr.set(-bubbleIcon.width()/2,-bubbleIcon.height(),bubbleIcon.width()/2,0);

// Next, offset the Rectangle to location of our location’s icon on the screen.
hitTestRecr.offset(screenCoords[0],screenCoords[1]);

// Finally test for match between ‘hit’ Rectangle and location clicked by the user.
// If a hit occurred, then we stop processing and return the result;

if (hitTestRecr.contains(event.getX(),event.getY()) {

hitMapLocation = testLocation;
break;

}

}

return hitMapLocation;

}

And that’s it for hit testing. If a hit occurred in our Rectangle, we track the selected map location and render a popup window above the map location’s icon with the name of the location.

Drawing a Popup Information Window

The following code for displaying a popup window may look complex, but the goal is simple – to set the correct screen coordinates for the information window to display directly above & centered on our location’s icon.

private void drawInfoWindow(Canvas canvas, MapView mapView, boolean shadow) {

// Again get our screen coordinate
int[] selDestinationOffset = new int[2];
mapView.getProjection().getPointXY(selectedMapLocation.getPoint(), selDestinationOffset);

// Setup the info window with the right size & location
int INFO_WINDOW_WIDTH = 125;
int INFO_WINDOW_HEIGHT = 25;
RectF infoWindowRect = new RectF(0,0,INFO_WINDOW_WIDTH,INFO_WINDOW_HEIGHT);
int infoWindowOffsetX = selDestinationOffset[0]-INFO_WINDOW_WIDTH/2;
int infoWindowOffsetY = selDestinationOffset[1]-INFO_WINDOW_HEIGHT-bubbleIcon.height();
infoWindowRect.offset(infoWindowOffsetX,infoWindowOffsetY);

// Draw inner info window
canvas.drawRoundRect(infoWindowRect, 5, 5, getInnerPaint());

// Draw border for info window
canvas.drawRoundRect(infoWindowRect, 5, 5, getBorderPaint());

// Draw the MapLocation’s name
int TEXT_OFFSET_X = 10;
int TEXT_OFFSET_Y = 15;
canvas.drawText(selectedMapLocation.getName(),infoWindowOffsetX+TEXT_OFFSET_X,infoWindowOffsetY+TEXT_OFFSET_Y,getTextPaint());

}

And that’s it. Please let me know of any points that need clarification or that I should expand/improve upon.

Here is the .apk you can use along with the source files: tutorial2.zip.

In tutorial #4.1, I mentioned that we passed custom attributes for the text and image variables from the XML resource file to our custom class. This is a critical skill for performing true object-oriented programming and how to do it wasn’t obvious from Google’s Android API Demos.

Luckily I was pointed to the solution myself by an experienced Android programmer in Guatemala by the username of cadlg (thanks again!). If you want to see the official Google Android example though, look at Android’s APIDemos’ custom LabelView example.

So here we go. We’ll use the same code as Tutorial 4.1 to keep this simple.

Setting Up Your Custom Class’s XML Resource Files

We’ll only review the code for the TextOnlyButton as it’s identical in concept to the ImageOnlyButton.

First we’ll create a new file in /res/values called attrs.xml

<?xml version=”1.0? encoding=”utf-8??>
<resources>

<declare-styleable name=”TextOnlyButton”>

<attr name=”textColorNotFocused” format=”integer”/>
<attr name=”textColorFocused” format=”integer”/>

</declare-styleable>

</resources>

As you see, we first declared a ’styleable’ with the name of our custom Class. Two attributes were then added to contain the values of our focused & unfocused text colors. By default, attributes have values of String, but in our case, we needed integers to represent the resource id’s we’ll declare in our colors.xml file. You can also declare formats such as “boolean” & others if that suits the requirements of your own project.

Next, we declare values for these custom attributes in our layout’s XML file: tutorial4.xml

<LinearLayout xmlns:android=”http://schemas.android.com/apk/res/android”

xmlns:pj=”http://schemas.android.com/apk/res/com.pocketjourney.tutorials”
android:orientation=”vertical”
android:layout_width=”fill_parent”
android:layout_height=”fill_parent”
android:padding=”10px”>

<com.pocketjourney.view.TextOnlyButton

android:id=”@+id/text_only_button”
android:layout_width=”wrap_content”
android:layout_height=”wrap_content”
android:layout_marginTop=”5px”
style=”?android:attr/buttonStyleSmall”
android:text=”Text Button”
pj:textColorNotFocused=”@drawable/white”
pj:textColorFocused=”@drawable/android_orange”/>

</LinearLayout>

Referring to our new attributes is actually a two step process. First we declared a new namespace (in our case called ‘pj’ as short for PocketJourney) in the parent layout of our custom class:

xmlns:pj=”http://schemas.android.com/apk/res/com.pocketjourney.tutorials”

Next we specified the values of our new attributes in the XML usage of our TextOnlyButton:

pj:textColorNotFocused=”@drawable/white”
pj:textColorFocused=”@drawable/android_orange”

Now you can see why we specified our format=”integer”. Our custom attributes point to the resource id’s of colors specified in our colors.xml file.

Retrieving Custom Attributes During Class Instantiation

Since our Activity has many constructors, we delegate the attribute parsing to an init() method to keep our code clean.

int notFocusedTextColor, focusedTextColor;

private void init(AttributeSet attrs) {

Resources.StyledAttributes a = getContext().obtainStyledAttributes(attrs,R.styleable.TextOnlyButton);
notFocusedTextColor = a.getColor(R.styleable.TextOnlyButton_textColorNotFocused, 0xFF000000);
focusedTextColor = a.getColor(R.styleable.TextOnlyButton_textColorFocused, 0xFF000000);

}

By now you’ve undoubtedly seen the AttributeSet that is always passed into an Activity. Well now you get to use it. First we obtain the StyledAttributes instance by requesting just the StyledAttributes for our custom Class. Next, we call the getColor() and pass two variables: the name of the attribute we want along with a default value in case the user did not specify one.

Take note of our styled attribute’s name as it’s a combination of our custom class’s name and the attribute we specified in the attrs.xml file (e.g. TextOnlyButton_textColorNotFocused).

And That’s It

You can now readily pass your own custom attributes and keep your View variables cleanly enclosed in your XML files. You can download the source to see for yourself. Just look at Tutorial #4.