MidMaps is a tiny Google Maps library for Java ME applications.

With MidMaps you can integrate Google Maps into your J2ME applications in few, easy steps!

How to use it?

MidMaps is designed to be simple. You don’t need to deal with threads, connections or other boring stuff like that: all you have to do is to create a map and display it on in your application.

Creating a simple map

To get a map object, you have to perform two steps:

  1. First, instantiate a new GoogleMaps object: 
    GoogleMaps gMaps = new GoogleMaps();
  2. Then, create a new GoogleStaticMap instance by using the createMap() method: 
    GoogleStaticMap map = gMaps.createMap(mapWidth, mapHeight, GoogleStaticMap.FORMAT_PNG);

Once you have created a map, it is necessary to define its handler. The handler has an important role: it gets automatically called each time the map object is updated, or when an error occurs: this way, you can know when you need to repaint the map, or how to notify the user about what’s going on. The handler has to implement the GoogleStaticMapHandler interface, that defines two methods:

public void GoogleStaticMapUpdated(GoogleStaticMap map);
public void GoogleStaticMapUpdateError(GoogleStaticMap map, int errorCode, String errorMessage);

The first one is called when a map is updated, so that your MIDlet knows that it must be repainted. The second one gets called when an error occurs (e.g.: when there is a network issue and the map image cannot be downloaded).

Once you’ve created your handler, you have to pass it to the GoogleStaticMap instance with the setHandler() method:

map.setHandler(mapHandler);

Now, how to actually load a map? First, it is necessary to define a location for the map:

  1. create a GoogleMapsCoordinates instance with the preferred latitude and longitude values
  2. use the GoogleStaticMap setCenter() method
map.setCenter(new GoogleMapsCoordinates(41.8954656, 12.4823243));

and then, you have to update() the map:

map.update();

After you’ve called update, the map image will be loaded and, when finished (or when an error occurs) the GoogleStaticMapHandler will be called. If the map is correctly loaded, you can actually draw it by using its draw(Graphics g, int left, int top, int attach) method.

Complete example

Below you can see a full example on how MidMaps can be used to display a map on a Canvas.

import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Graphics;
 
import com.jappit.midmaps.googlemaps.GoogleMaps;
import com.jappit.midmaps.googlemaps.GoogleMapsCoordinates;
import com.jappit.midmaps.googlemaps.GoogleStaticMapHandler;
import com.jappit.midmaps.googlemaps.GoogleStaticMap;
 
public class GoogleMapsSimpleCanvas extends Canvas implements GoogleStaticMapHandler
{
	GoogleMaps gMaps = null;
	GoogleStaticMap map = null;
 
	public GoogleMapsSimpleCanvas()
	{
		gMaps = new GoogleMaps();
 
		map = gMaps.createMap(getWidth(), getHeight(), GoogleStaticMap.FORMAT_PNG);
 
		map.setHandler(this);
 
		map.setCenter(new GoogleMapsCoordinates(41.8954656, 12.4823243));
 
		map.setZoom(15);
 
		map.update();
	}
 
	protected void paint(Graphics g)
	{
		map.draw(g, 0, 0, Graphics.TOP | Graphics.LEFT);
	}
	public void GoogleStaticMapUpdateError(GoogleStaticMap map, int errorCode, String errorMessage)
	{
		System.out.println("map error: " + errorCode + ", " + errorMessage);
	}
	public void GoogleStaticMapUpdated(GoogleStaticMap map)
	{
		repaint();
	}
}

Markers

You can add markers to a map by using the GoogleMapsMarker class. You create a marker by specifying its location:

GoogleMapsMarker marker = new GoogleMapsMarker(new GoogleMapsCoordinates(41.8954656, 12.4823243));

Optionally, you can customize the marker by setting its color, size and and label (must be a single character):

marker.setColor(GoogleStaticMap.COLOR_GREEN);
marker.setColor(GoogleMapsMarker.SIZE_TINY);
marker.setLabel('P');

Then, you add the marker to your GoogleStaticMap instance with the addMarker() method:

map.addMarker(marker);

Here’s an example of 2 different markers added to the previous map.

GoogleMapsMarker redMarker = new GoogleMapsMarker(new GoogleMapsCoordinates(41.8954656, 12.4823243));
redMarker.setColor(GoogleStaticMap.COLOR_RED);
redMarker.setSize(GoogleMapsMarker.SIZE_MID);
 
GoogleMapsMarker blueMarker = new GoogleMapsMarker(new GoogleMapsCoordinates(41.8964656, 12.4843243));
blueMarker.setColor(GoogleStaticMap.COLOR_BLUE);
blueMarker.setSize(GoogleMapsMarker.SIZE_SMALL);
blueMarker.setLabel('R');
 
map.addMarker(redMarker);
map.addMarker(blueMarker);

Paths

Paths can be easily defined by using the GoogleMapsPath class. To create a new Path, just istantiate a new GoogleMapsPath object:

GoogleMapsPath path = new GoogleMapsPath();

And then add the path points with the addPoint() method:

path.addPoint(new GoogleMapsCoordinates(41.8954656, 12.4823243));
path.addPoint(new GoogleMapsCoordinates(41.8934656, 12.4833243));

Path weight, color and fill color can be customized with the following methods:

bluePath.setColor(GoogleStaticMap.COLOR_BLUE);
bluePath.setWeight(5);
bluePath.setFillColor(GoogleStaticMap.COLOR_GREEN);

Below you can see an example of 2 different paths added to the map defined above.

GoogleMapsPath path = new GoogleMapsPath();
path.addPoint(new GoogleMapsCoordinates(41.8954656, 12.4823243));
path.addPoint(new GoogleMapsCoordinates(41.8934656, 12.4833243));
path.addPoint(new GoogleMapsCoordinates(41.8944656, 12.4843243));
path.setColor(GoogleStaticMap.COLOR_RED);
path.setWeight(10);
map.addPath(path);
 
GoogleMapsPath bluePath = new GoogleMapsPath();
bluePath.addPoint(new GoogleMapsCoordinates(41.8954656, 12.4823243));
bluePath.addPoint(new GoogleMapsCoordinates(41.8964656, 12.4813243));
bluePath.addPoint(new GoogleMapsCoordinates(41.8934656, 12.4803243));
bluePath.setColor(GoogleStaticMap.COLOR_BLUE);
bluePath.setFillColor(GoogleStaticMap.COLOR_GREEN);
bluePath.setWeight(5);
map.addPath(bluePath);

Geocoding

Geocoding requires a Google Maps API key, so you have to get your own key to use this feature.

To start, you have to instantiate a Google Maps object by using your own API key:

GoogleMaps gMaps = new GoogleMaps("<your_api_key>");

Then, you have to get a GoogleMapsGeocoder instance by using the createGeocoder() method:

GoogleMapsGeocoder geocoder = gMaps.createGeocoder();

Then, as done for the GoogleStaticMap objects, also the GoogleMapsGeocoder objects require an handler to be defined. The GoogleMapsGeocoderHandler interface defines 2 methods:

public void GoogleMapsGeocodeSuccess(String address, GoogleMapsCoordinates coordinates, int accuracy);
public void GoogleMapsGeocodeError(String address, int errorCode, String errorDescription);

These 2 methods are called when a geocoding request successes or fails, respectively. Once you have implemented your GoogleMapsGeocoderHandler, you have to pass it to the GoogleMapsGeocoder instance created above:

geocoder.setHandler(geocoderHandler);

Done this, all is ready to geocode an address: to do this, just call the geocodeAddress() method:

geocoder.geocodeAddress("Rome, Italy");

When the geocoding ends, your handler will be notified via the GoogleMapsGeocodeSuccess() method. A possible implementation of such method is visible below:

public void GoogleMapsGeocodeSuccess(String address, GoogleMapsCoordinates coordinates, int accuracy)
{
	map.setCenter(coordinates);
 
	map.addMarker(new GoogleMapsMarker(coordinates));
 
	map.setZoom(GoogleMaps.getZoomForAccuracy(accuracy));
 
	map.update();
}

Since the geocoding operation returns an “accuracy” value, you can use this value to get a default zoom value for your map. To do this, you can use the GoogleMaps.getZoomForAccuracy() method, as shown above.

Below you can see the map generated by the previous code:

Moving and zooming the map

MidMaps has inbuilt functionalities that allow to easily move and zoom your maps.

To move a map around, it is enough to call the GoogleStaticMap move(int direction) method, passing as argument one of the four possible directions, specified by the Canvas static properties: UP, RIGHT, DOWN and LEFT.

Important: the move() method automatically calls the map update() functionality, so there is no need to call it explicitly.

Using the same Canvas example shown above, it is enough to add this keyPressed() method to allow users to freely move around on the map:

protected void keyPressed(int key)
{
	int gameAction = getGameAction(key);
 
	if(gameAction == Canvas.UP || gameAction == Canvas.RIGHT || gameAction == Canvas.DOWN || gameAction == Canvas.LEFT)
	{
		map.move(gameAction);
	}
}

Similarly, the GoogleStaticMap provides these methods to manage the zoom level:

As for the move() functionality, the zoomIn() and zoomOut() methods automatically call the map update process.

Drawing map images

You have two options to draw a map in your MIDlet.

  1. The first one, that was used in the examples above, is to use GoogleStaticMap draw() method. This method is especially useful when dealing with Canvas or CustomItem objects. 
    map.draw(myGraphics, 0, 0, Graphics.TOP | Graphics.LEFT);
  2. The second method is to get a reference to the map image via its getImage() method, and use it as a standard Image object. The code below shows how this method can be used to add and show a map image within a Form: 
    ImageItem mapItem = new ImageItem("My Map", map.getImage(), Item.LAYOUT_TOP, "Sample map");
 
myForm.append(mapItem);

Library, API reference and full sample code

The MidMaps library is available for download here: MidMaps – J2Me Google Maps library. The current release is compatible with devices supporting MIDP 2.0 and CLDC 1.1.

You can also download a full MIDlet, complete with source code, showing the various MidMaps functionalities in action:

To get more details, you can check out the full MidMaps API reference.

Feedback

MidMaps is currently at its first release, so any kind of feedback is highly welcome. Let me know if you find bugs, how MidMaps could be improved, or which features you would like to see implemented. Thank you! :) 

GoogleStaticMap map = gMaps.getMap(mapHandler, mapWidth, mapHeight, GoogleStaticMap.FORMAT_PNG);
Be Sociable, Share!