Ghoscher's Blog

Welcome to the fifth and final part of my tutorial on how to create a map app for Android without using Google™ APIs :).

Series outline:

• Series aim.
• Theory you need to know.
• App design.
• Writing a TilesManager.
• Writing a TilesProvider.
• Seeing results with MapView.
• Adding web support.
• Creating MapView in XML.
• Extra: Fuchs Maps.

______________________________________

So up until now we didn’t see any results :(, this is where everything changes :D.

In this part we’ll write three classes:

MapView: a custom view to render and manipulate the map.

MapAppActivity: the main (and only) activity for the app, mainly creates the MapView and handles activity state changes.

MapViewLocationListener : An extended LocationListener that knows how to deal with a MapView.

MapView:

First thing you should know about this view is that it contains two gps locations, one for the actual phone gps location and the other one for the view center. The first is to draw a marker the the users position and the second is to freely move\drag the map, so the longitude,latitude coordinates of the pixel at the center of the view is represented by the second gps location. If we want to enable auto follow we just make the second gps location match the first one, this way the user’s location will always be at the center of the view.

Let’s start with the fields and the constructor of MapView:

package com.mapapp.views;

import java.util.Collection;

import android.content.Context;
import android.graphics.Bitmap;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Point;
import android.graphics.Rect;
import android.location.Location;
import android.view.MotionEvent;
import android.view.View;

import com.mapapp.helpers.PointD;
import com.mapapp.tileManagement.Tile;
import com.mapapp.tileManagement.TilesManager;
import com.mapapp.tileManagement.TilesProvider;

public class MapView extends View
{
	// Needed to pass to View constructor
	protected Context context;

	// MapView dimensions
	protected int viewWidth, viewHeight;

	// Provides us with tiles
	protected TilesProvider tileProvider;

	// Handles calculations
	protected TilesManager tileManager;

	// Different paints
	protected Paint fontPaint;
	protected Paint bitmapPaint = new Paint();
	protected Paint circlePaint = new Paint();

	// The location of the view center in longitude, latitude
	protected PointD seekLocation = new PointD(0, 0);
	// Location of the phone using Gps data
	protected Location gpsLocation = null;
	// If true then seekLocation will always match gpsLocation
	protected boolean autoFollow = false;

	// An image to draw at the phone's position
	protected Bitmap positionMarker;

	// touch position values kept for panning\dragging
	protected PointD lastTouchPos = new PointD(-1, -1);

	public MapView(Context context, int viewWidth, int viewHeight, TilesProvider tilesProvider, Bitmap positionMarker)
	{
		super(context);
		this.context = context;

		// Tiles provider is passed not created.
		// The idea is to hide the actual tiles source from the view
		// This way the view doesn't care whether the source is a database or the internet
		this.tileProvider = tilesProvider;

		// These values will be used later
		this.viewWidth = viewWidth;
		this.viewHeight = viewHeight;

		// Get the marker image
		this.positionMarker = positionMarker;

		// Creating a TilesManager assuming that the tile size is 256*256.
		// You might want to pass tile size as a parameter or even calculate it somehow
		tileManager = new TilesManager(256, viewWidth, viewHeight);

		// Initializes paints
		initPaints();

		// Fetching tiles from the tilesProvider
		fetchTiles();
	}

	@Override
	protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
	{
		// Setting width,height that was passed in the constructor as the view's dimensions
		setMeasuredDimension(viewWidth, viewHeight);
	}

The code is well commented I guess, since we’re extending a View we must override onMeasere and call
setMeasuredDimension inside it passing the dimensions from the constructors. This is to ensure that the view has the desired width and height.

Now to initPaints and fetchTiles:

	void initPaints()
	{
		// Font paint is used to draw text
		fontPaint = new Paint();
		fontPaint.setColor(Color.DKGRAY);
		fontPaint.setShadowLayer(1, 1, 1, Color.BLACK);
		fontPaint.setTextSize(20);

		// Used to draw a semi-transparent circle at the phone's gps location
		circlePaint.setARGB(70, 170, 170, 80);
		circlePaint.setAntiAlias(true);
	}

	void fetchTiles()
	{
		// Update tilesManager to have the center of the view as its location
		tileManager.setLocation(seekLocation.x, seekLocation.y);

		// Get the visible tiles indices as a Rect
		Rect visibleRegion = tileManager.getVisibleRegion();

		// Tell tiles provider what tiles we need and which zoom level.
		// The tiles will be stored inside the tilesProvider.
		// We can get those tiles later when drawing the view
		tileProvider.fetchTiles(visibleRegion, tileManager.getZoom());
	}

Hopefully you remember how TilesManager works, it takes a location and returns the range of tiles needed to fill the MapView, so we first set the location of the TilesManager to the center of our MapView (Longitude,Latitude coordinates) then we get the result as a rectangle, then we pass this rectangle to the TilesProvider which fetches all the tiles included in the rectangle and stores them in a Hashtable inside itself.

Next thing is drawing the map, since we’re extending a View we override onDraw to draw out view contents, onDraw takes a Canvas object as parameter, the canvas object is used to draw text\images\shapes on the view.

The problem here is how to figure out the right position to draw the tiles. It’s easy if we were drawing the full world map a, we just convert longitude & latitude to pixels and draw them on the map.

In our case we are only drawing part of the world map and we need to have seekLocation at the center of the MapView, so in onDraw we calculate an offset value and pass it to all other drawing functions.

here’s the code for that and I guess it’s well commented, an image after the code should explain more.

	@Override
	protected void onDraw(Canvas canvas)
	{
		// Clear the view to grey
		canvas.drawARGB(255, 100, 100, 100);

		// To draw the map we need to find the position of the pixel representing the center of the view.
		// We need the position to be relative to the full world map, lets call this pixel position "pix"
		// pix.x will range from 0 to (2^zoom)*tileSize-1, same for pix.y
		// To draw anything on the map we subtract pix from the original position
		// It's just like dragging the map so that the pixel representing the gps location gets into the center of the view

		// In a square world map,
		// we need to know pix location as two values from 0.0 to 1.0
		PointD pixRatio = TilesManager.calcRatio(seekLocation.x, seekLocation.y);

		// Full world map width in pixels
		int mapWidth = tileManager.mapSize() * 256;
		Point pix = new Point((int) (pixRatio.x * mapWidth), (int) (pixRatio.y * mapWidth));

		/*
		 * Subtracting pix from each tile position will result in pix being drawn at the top left corner of the view
		 * To drag it to the center we add (viewWidth/2, viewHeight/2) to the final result
		 * pos.x = pos.x - pix.x + viewWidth/2f
		 * pos.x = pox.x - (pix.x - viewWidth/2f)
		 * ---> offset.x =  (pix.x - viewWidth/2f)
		 * same for offset.y
		 */

		Point offset = new Point((int) (pix.x - viewWidth / 2f), (int) (pix.y - viewHeight / 2f));
		// offset is now ready to use

		// Drawing tiles in a separate function to make the code more readable
		drawTiles(canvas, offset);

		// Draw the marker that pinpoints the user's location
		drawMarker(canvas, offset);
	}

Top left: we drag the map to make the marker have the position of (0,0) in MapView
Top right : we need to center the marker in MapView
Bottom left : the final result we want

So to draw anything in the map we first obtain its position in the full world map then subtract offset from that position, for tiles we just multiply the index of the tile with tile width in pixels, so tiles x positions are like: 0, 256, 512, 1024… since in our case tileWidth is equal to 256.

	void drawTiles(Canvas canvas, Point offset)
	{
		// Get tiles from the Hashtable inside tilesProvider
		Collection tilesList = tileProvider.getTiles().values();

		// x,y are the calculated offset

		// Go trough all the available tiles
		for (Tile tile : tilesList)
		{
			// We act as if we're drawing a map of the whole world at a specific
			// zoom level
			// The top left corner of the map occupies the pixel (0,0) of the
			// view
			int tileSize = tileManager.getTileSize();
			long tileX = tile.x * tileSize;
			long tileY = tile.y * tileSize;

			// Subtract offset from the previous calculations
			long finalX = tileX - offset.x;
			long finalY = tileY - offset.y;

			// Draw the bitmap of the tiles using a simple paint
			canvas.drawBitmap(tile.img, finalX, finalY, bitmapPaint);
		}
	}

Important note: to draw a bitmap we used the simplest paint we can create, using other paints will slow down drawing!.

For the marker it’s the same, we just convert longitude latitude to pixels and subtract offset:

	void drawMarker(Canvas canvas, Point offset)
	{
		// x,y are the calculated offset

		// Proceed only if a gps fix is available
		if (gpsLocation != null)
		{
			// Get marker position in pixels as if we're going to draw it on a
			// world map where the top left corner of the map occupies the (0,0)
			// pixel of the view
			Point markerPos = tileManager.lonLatToPixelXY(gpsLocation.getLongitude(), gpsLocation.getLatitude());

			// Add offset to the marker position
			int markerX = markerPos.x - offset.x;
			int markerY = markerPos.y - offset.y;

			// Draw the marker and make sure you draw the center of the marker
			// at the marker location
			canvas.drawBitmap(positionMarker, markerX - positionMarker.getWidth() / 2, markerY - positionMarker.getHeight() / 2,
					bitmapPaint);

			// Around the marker we will draw a circle representing the accuracy of the gps fix
			// We first calculate its radius

			// Calculate how many meters one pixel represents
			float ground = (float) tileManager.calcGroundResolution(gpsLocation.getLatitude());

			// Location.getAccuracy() returns the accuracy in meters.
			float rad = gpsLocation.getAccuracy() / ground;

			canvas.drawCircle(markerX, markerY, rad, circlePaint);

			// Just drawing location info
			int pen = 1;
			canvas.drawText("lon:" + gpsLocation.getLongitude(), 0, 20 * pen++, fontPaint);
			canvas.drawText("lat:" + gpsLocation.getLatitude(), 0, 20 * pen++, fontPaint);
			canvas.drawText("alt:" + gpsLocation.getAltitude(), 0, 20 * pen++, fontPaint);
			canvas.drawText("Zoom:" + tileManager.getZoom(), 0, 20 * pen++, fontPaint);
		}
	}

We’re done now with the drawing part, we need to enable the user to drag the map:

Update 28/10/2012: Instead of reinventing the wheel there’s a class called GestureDetector that can detect many touch actions like clicking, double clicking, scrolling, I didn’t update the code here because that will break the connection with the post comments, so here’s the better implementation of MapView: MapView.java

and here’s the original unmodified code 🙂 :

	@Override
	public boolean onTouchEvent(MotionEvent event)
	{
		int action = event.getAction();

		if (action == MotionEvent.ACTION_DOWN)
		{
			// Keep touch position for later use (dragging)
			lastTouchPos.x = (int) event.getX();
			lastTouchPos.y = (int) event.getY();

			return true;
		}
		else if (action == MotionEvent.ACTION_MOVE)
		{
			autoFollow = false;

			PointD current = new PointD(event.getX(), event.getY());

			// Find how many pixels the users finger moved in both x and y
			PointD diff = new PointD(current.x - lastTouchPos.x, current.y - lastTouchPos.y);

			// In a full wolrd map, get the position of the center of the view in pixels
			Point pixels1 = tileManager.lonLatToPixelXY(seekLocation.x, seekLocation.y);

			// Subtract diff from that position
			Point pixels2 = new Point(pixels1.x - (int) diff.x, pixels1.y - (int) diff.y);

			// Reconvert the final result to longitude, latitude point
			PointD newSeek = tileManager.pixelXYToLonLat((int) pixels2.x, (int) pixels2.y);

			// Finally move the center of the view to the new location
			seekLocation = newSeek;

			// Refresh the view
			fetchTiles();
			invalidate(); // Causes the view to redraw itself

			// Prepare for the next drag event
			lastTouchPos.x = current.x;
			lastTouchPos.y = current.y;

			return true;
		}

		return super.onTouchEvent(event);
	}

The MapView class is almost finished, we will just add some small functions, the name should explain what each one does:

	// Fetch the tiles then draw, don't call to often
	public void refresh()
	{
		fetchTiles();
		invalidate();
	}

	// Like refresh but called from a non UI thread
	public void postRefresh()
	{
		fetchTiles();
		postInvalidate();
	}

	// Simply sets seek location to gpsLocation (if exists)
	public void followMarker()
	{
		if (gpsLocation != null)
		{
			seekLocation.x = gpsLocation.getLongitude();
			seekLocation.y = gpsLocation.getLatitude();
			autoFollow = true;

			fetchTiles();
			invalidate();
		}
	}

	public void zoomIn()
	{
		tileManager.zoomIn();
		onMapZoomChanged();
	}

	public void zoomOut()
	{
		tileManager.zoomOut();
		onMapZoomChanged();
	}

	protected void onMapZoomChanged()
	{
		tileProvider.clear();
		fetchTiles();
		invalidate();
	}

	// Returns the gps coordinates of the user
	public Location getGpsLocation()
	{
		return gpsLocation;
	}

	// Returns the gps coordinates of our view center
	public PointD getSeekLocation()
	{
		return seekLocation;
	}

	// Centers the given gps coordinates in our view
	public void setSeekLocation(double longitude, double latitude)
	{
		seekLocation.x = longitude;
		seekLocation.y = latitude;
	}

	// Sets the marker position
	public void setGpsLocation(Location location)
	{
		setGpsLocation(location.getLongitude(), location.getLatitude(), location.getAltitude(), location.getAccuracy());
	}

	// Sets the marker position
	public void setGpsLocation(double longitude, double latitude, double altitude, float accuracy)
	{
		if (gpsLocation == null) gpsLocation = new Location("");
		gpsLocation.setLongitude(longitude);
		gpsLocation.setLatitude(latitude);
		gpsLocation.setAltitude(altitude);
		gpsLocation.setAccuracy(accuracy);

		if (autoFollow) followMarker();

	}

	public int getZoom()
	{
		return tileManager.getZoom();
	}

	public void setZoom(int zoom)
	{
		tileManager.setZoom(zoom);
		onMapZoomChanged();
	}

Okay, that’s all for the MapView class, so this tutorial is almost over.


MapViewLocationListener:

a LocationListener is an interface that has a function we are interested in, it’s called

onLocationChanged(Location location);

Our location listener will implement this interface and whenever a change in location happens it will set the new location as the marker position in the MapView associated with this listener.
The full class code:

package com.mapapp.views;

import android.location.Location;
import android.location.LocationListener;
import android.os.Bundle;

public class MapViewLocationListener implements LocationListener
{
	MapView mapView;
	boolean stopped = false;

	public MapViewLocationListener(MapView mapView)
	{
		this.mapView = mapView;
	}

	@Override
	public void onLocationChanged(Location location)
	{
		if (!stopped && location != null)
		{
			// Set location and update the mapView
			mapView.setGpsLocation(location.getLongitude(), location.getLatitude(), location.getAltitude(), location.getAccuracy());
			mapView.postInvalidate();
		}
	}

	public void stop()
	{
		stopped = true;
		mapView = null;
	}

	@Override
	public void onProviderDisabled(String provider)
	{
	}

	@Override
	public void onProviderEnabled(String provider)
	{
	}

	@Override
	public void onStatusChanged(String provider, int status, Bundle extras)
	{
	}

}

MapAppActivity:

Very simple activity, it creates TilesProvider then creates a MapView passing the TilesProvider in the constructor, then the MapViewLocationListener is created and the MapView is passed in the constructor, what makes the class longer is adding activity state management, you don’t want the app to be reset when the user rotates his mobile, you also want the app to preserve the location in the map and the zoom level when another activity comes in front of your app. To do so we’ll override two functions in the activity: onSaveInstanceState, onRestoreInstanceState.

We also want the app to keep the seek location and zoom level of the MapView when the user closes the app and re opens it, to do so we will use the SharedPreferences.

Just one important note, I used onResume to initialize the app instead of on create for a simple reason, in the method onPause I’m releasing all the resources of the app, so I had to reload them when the activity starts again, the problem with onCreate is that it’s not always called, there are scenarios where the activity is started with the function onResume.

If you follow this link and scroll down to figure1 you see that an arrow goes from onPause (Where we unload our resources) directly to onResume, onCreate wasn’t called.

package com.mapapp.main;

import android.app.Activity;
import android.content.SharedPreferences;
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
import android.location.Location;
import android.location.LocationManager;
import android.os.Bundle;
import android.os.Environment;
import android.view.Display;
import android.view.KeyEvent;

import com.mapapp.helpers.PointD;
import com.mapapp.mapapp.R;
import com.mapapp.tileManagement.TilesProvider;
import com.mapapp.views.MapView;
import com.mapapp.views.MapViewLocationListener;

public class MapAppActivity extends Activity
{

	// Constant strings used in onSaveInstanceState, onRestoreInstanceState
	private final class Save
	{
		public final static String GPS_LON = "gpsLon";
		public final static String GPS_LAT = "gpsLAT";
		public final static String GPS_ALT = "gpsALT";
		public final static String GPS_ACC = "gpsAcc";
	}

	// Constant strings to save settings in SharedPreferences
	// Also used for restoring settings
	private final class Pref
	{
		public final static String SEEK_LON = "seek_lon";
		public final static String SEEK_LAT = "seek_lat";
		public final static String ZOOM = "zoom";
	}

	// Our only view, created in code
	MapView mapView;

	// Provides us with Tiles objects, passed to MapView
	TilesProvider tilesProvider;

	// Updates marker location in MapView
	MapViewLocationListener locationListener;

	Location savedGpsLocation;

	@Override
	protected void onResume()
	{
		// Create MapView
		initViews();

		// Restore zoom and location data for the MapView
		restoreMapViewSettings();

		// Creating and registering the location listener
		locationListener = new MapViewLocationListener(mapView);
		LocationManager locationManager = (LocationManager) getSystemService(LOCATION_SERVICE);
		locationManager.requestLocationUpdates(LocationManager.GPS_PROVIDER, 0, 0, locationListener);

		// Set our MapView as the main view for the activity
		setContentView(mapView);

		// Never ever forget this 🙂
		super.onResume();
	}

	void initViews()
	{
		// Creating the bitmap of the marker from the resources
		Bitmap marker = BitmapFactory.decodeResource(getResources(), R.drawable.marker);

		// Creating our database tilesProvider to pass it to our MapView
		String path = Environment.getExternalStorageDirectory() + "/mapapp/world.sqlitedb";
		tilesProvider = new TilesProvider(path);

		// Creating the mapView and make sure it fills the screen
		Display display = getWindowManager().getDefaultDisplay();
		mapView = new MapView(this, display.getWidth(), display.getHeight(), tilesProvider, marker);

		// If a location was saved while pausing the app then use it.
		if (savedGpsLocation != null) mapView.setGpsLocation(savedGpsLocation);

		// Update and draw the map view
		mapView.refresh();
	}

	@Override
	protected void onPause()
	{
		// Save settings before leaving
		saveMapViewSettings();

		// Mainly releases the MapView pointer inside the listener
		locationListener.stop();

		// Unregistering our listener
		LocationManager locationManager = (LocationManager) getSystemService(LOCATION_SERVICE);
		locationManager.removeUpdates(locationListener);

		// Closes the source of the tiles (Database in our case)
		tilesProvider.close();
		// Clears the tiles held in the tilesProvider
		tilesProvider.clear();

		// Release mapView pointer
		mapView = null;

		super.onPause();
	}

	@Override
	public boolean onKeyDown(int keyCode, KeyEvent event)
	{
		// Zooming
		if (keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_Z)
		{
			mapView.zoomIn();
			return true;
		}
		// Zooming
		else if (keyCode == KeyEvent.KEYCODE_VOLUME_DOWN || keyCode == KeyEvent.KEYCODE_X)
		{
			mapView.zoomOut();
			return true;
		}
		// Enable auto follow
		if (keyCode == KeyEvent.KEYCODE_H || keyCode == KeyEvent.KEYCODE_FOCUS)
		{
			mapView.followMarker();
			return true;
		}
		// Simulate being at some location, for testing only
		else if (keyCode == KeyEvent.KEYCODE_M || keyCode == KeyEvent.KEYCODE_MENU)
		{
			mapView.setGpsLocation(46.142578, -20.841015, 0, 182);
			mapView.invalidate();

			return false;
		}

		return super.onKeyDown(keyCode, event);
	}

	// Called manually to restore settings from SharedPreferences
	void restoreMapViewSettings()
	{
		SharedPreferences pref = getSharedPreferences("View_Settings", MODE_PRIVATE);

		double lon, lat;
		int zoom;

		lon = Double.parseDouble(pref.getString(Pref.SEEK_LON, "0"));
		lat = Double.parseDouble(pref.getString(Pref.SEEK_LAT, "0"));
		zoom = pref.getInt(Pref.ZOOM, 0);

		mapView.setSeekLocation(lon, lat);
		mapView.setZoom(zoom);
		mapView.refresh();
	}

	// Called manually to save settings in SharedPreferences
	void saveMapViewSettings()
	{
		SharedPreferences.Editor editor = getSharedPreferences("View_Settings", MODE_PRIVATE).edit();

		PointD seekLocation = mapView.getSeekLocation();
		editor.putString(Pref.SEEK_LON, Double.toString(seekLocation.x));
		editor.putString(Pref.SEEK_LAT, Double.toString(seekLocation.y));
		editor.putInt(Pref.ZOOM, mapView.getZoom());

		editor.commit();
	}

	@Override
	protected void onSaveInstanceState(Bundle outState)
	{
		if (mapView.getGpsLocation() != null)
		{
			outState.putDouble(Save.GPS_LON, mapView.getGpsLocation().getLongitude());
			outState.putDouble(Save.GPS_LAT, mapView.getGpsLocation().getLatitude());
			outState.putDouble(Save.GPS_ALT, mapView.getGpsLocation().getAltitude());
			outState.putFloat(Save.GPS_ACC, mapView.getGpsLocation().getAccuracy());
		}

		super.onSaveInstanceState(outState);
	}

	@Override
	protected void onRestoreInstanceState(Bundle savedInstanceState)
	{
		double gpsLon, gpsLat, gpsAlt;
		float gpsAcc;

		gpsLon = savedInstanceState.getDouble(Save.GPS_LON, 999);
		gpsLat = savedInstanceState.getDouble(Save.GPS_LAT, 999);
		gpsAlt = savedInstanceState.getDouble(Save.GPS_ALT, 999);
		gpsAcc = savedInstanceState.getFloat(Save.GPS_ACC, 999);

		if (gpsLon != 999 && gpsLat != 999 && gpsAlt != 999 && gpsAcc != 999)
		{
			savedGpsLocation = new Location(LocationManager.GPS_PROVIDER);
			savedGpsLocation.setLongitude(gpsLon);
			savedGpsLocation.setLatitude(gpsLat);
			savedGpsLocation.setAltitude(gpsAlt);
			savedGpsLocation.setAccuracy(gpsAcc);
		}

		super.onRestoreInstanceState(savedInstanceState);
	}
}

Last things you need to do:

1. add this image to your drawable folders
2. add this permission to your AndroidManifest.xml<uses-permission android:name=”android.permission.ACCESS_FINE_LOCATION” />
3. copy the world.sqlite database to /sdcard/mapapp/

The app should be working fine by now :D.

Here’s the final source code for the app : MapApp_Final Source Code.zip

And here’s the final Apk file: MapApp_Final.apk

I really hope you learned something from this tutorial 😀

It feels good to have your own app that displays a map and a location 😀

Please feel free to have any suggestions or notes about this tutorial since it’s my first on in Android programming :).

Want to support online maps? head to MapApp6: Web support :D.!