×
Namespaces

Variants
Actions
(Difference between revisions)

Implementing a custom MapUrlProvider overlay with Maps API for Java ME

From Nokia Developer Wiki
Jump to: navigation, search
jappit (Talk | contribs)
(Jappit - Initial version of the article, showing client and server implementation of a custom MapUrlProvider)
 
jappit (Talk | contribs)
m (Jappit - fixed creationg date and small typo)
Line 120: Line 120:
 
== Summary ==
 
== Summary ==
  
The [http://www.jappit.com/j2me/locationapi/index.html?com/nokia/maps/map/MapUrlProvider.html MapUrlProvider] allows to easily define interfaces to remote providers of map tiles. If an app need more control over the generated map tiles, then the [http://www.jappit.com/j2me/locationapi/index.html?com/nokia/maps/map/MapProvider.html MapProvider] should be used instead.
+
The [http://www.jappit.com/j2me/locationapi/index.html?com/nokia/maps/map/MapUrlProvider.html MapUrlProvider] allows to easily define interfaces to remote providers of map tiles. If an application needs more control over the generated map tiles, then the [http://www.jappit.com/j2me/locationapi/index.html?com/nokia/maps/map/MapProvider.html MapProvider] should be used instead.
  
  
Line 135: Line 135:
 
|keywords=Location API, Ovi Maps, Form, CustomItem, Gauge
 
|keywords=Location API, Ovi Maps, Form, CustomItem, Gauge
 
|id= <!-- Article Id (Knowledge base articles only) -->
 
|id= <!-- Article Id (Knowledge base articles only) -->
|creationdate=28 June, 2011 -->
+
|creationdate=29 June, 2011 -->
 
|author=[[User:jappit]]
 
|author=[[User:jappit]]
 
}}
 
}}

Revision as of 12:48, 29 June 2011

This article explains how to implement a custom MapUrlProvider and how to add it as overlay over a map by using the Java ME Location API

Contents

Introduction

JavaMELocationAPI MapOverlay.png

The Ovi Maps Java ME Location API offers a feature to easily add new transparent layers over the default map tiles, or to replace the default tiles with custom ones, thanks to the MapProvider object.

MapProvider and MapUrlProvider

A MapProvider object is responsible for generating the map tile Images that are displayed by a MapDisplay. Those Image objects are generated and returned by the getTileImage() object, that returns a tile corresponding to a row/column/zoom and with a given width and height.

The row and column parameters are generated by using the Mercator projection, and a sample implementation is available on the MapProvider JavaDocs page.

The MapProvider base class has a direct subclass, MapUrlProvider, that allows to retrieve tiles from remote providers, and integrates all the logic for fetching and generating the tile Image objects.

This is done by implementing a method that returns the URL of the remote tile, corresponding to the given row, column, zoom, width and height parameters:

public String getTileUrl(int zoom, int column, int row, int width, int height) 
{
}

Implementing a CustomMapUrlProvider

The CustomMapUrlProvider class must extend MapUrlProvider, as shown below.

public class CustomMapUrlProvider extends MapUrlProvider
{
}

The MapUrlProvider defines two abstract methods, that must be implemented by the extending class:

  • public String getTileUrl(int zoom, int column, int row, int width, int height) that returns the URL of a given tile
  • public String getName() that returns the name of the custom map provider

Since the tile image must be generated by a remote script or page, the getTileUrl method has to pass all its parameter to the remote Web server, and so the generated URL has to contain those parameters in its query string.

public String getTileUrl(int zoom, int column, int row, int width, int height) 
{
return "http://www.nokiadevs.com/various/custommapprovider/index.php?" +
"column=" + column + "&" +
"row=" + row + "&" +
"zoom=" + zoom + "&" +
"width=" + width + "&" +
"height=" + height;
}

The getName() method can be simply implemented by returning a name for the implemented custom map provider.

public String getName()
{
return "My Map URL Provider";
}

Adding the CustomMapUrlProvider to a MapDisplay

Once the custom provider has been implemented, it is necessary to add it to the desired MapDisplay object. This can be done by using the MapDisplay addMapOverlay() method.

myMapDisplay.addMapOverlay(new CustomMapUrlProvider());

Implementing the provider's server

A MapUrlProvider server can be implemented in any available technology (for instance, Java, PHP, Perl). The following code snippet shows how to write a simple script that generate tiles with a thin border and with the column and row parameters displayed on the tile itself.

<?php 
 
$row = $_REQUEST['row'];
$column = $_REQUEST['column'];
$width = $_REQUEST['width'];
$height = $_REQUEST['height'];
$zoom = $_REQUEST['zoom'];
 
// create an empty image with the given width and height
$image = imagecreatetruecolor($width, $height);
 
// set the background color as transparent
$black = imagecolorallocate($image, 0, 0, 0);
imagecolortransparent($image, $black);
 
// create the needed colors
$redColor = imagecolorallocatealpha($image, 255, 0, 0, 0);
$grayColor = imagecolorallocatealpha($image, 10, 10, 10, 0);
 
// paint a border around the tile image
imagerectangle($image, 0, 0, $width - 1, $height - 1, $redColor);
 
// write the column and row parameters on the tile
$text = $column . ' - ' . $row;
imagestring($image, 5, $width / 2 - 50, $height / 2 + 1, $text, $grayColor);
imagestring($image, 5, $width / 2 - 50, $height / 2, $text, $redColor);
 
// send the image to the client
header("Content-type: image/png");
imagepng($image);
 
?>

The final result of applying the CustomMapUrlProvider defined above is visible in the following screenshot.

JavaMELocationAPI CustomMapUrlProvider.png

Resources

A sample MIDlet showing the CustomMapUrlProvider in action is available for download here: File:CustomMapUrlProviderMIDlet.zip

Full source code of the CustomMapUrlProvider class is available here: File:CustomMapUrlProvider.java.zip

Summary

The MapUrlProvider allows to easily define interfaces to remote providers of map tiles. If an application needs more control over the generated map tiles, then the MapProvider should be used instead.


Article Metadata
Code ExampleTested with
Devices(s): X3-02
Compatibility
Platform(s): S40, Symbian^1, Symbian^3
Series 40
Symbian
Device(s): All
Article
Keywords: Location API, Ovi Maps, Form, CustomItem, Gauge
Created: jappit (29 June, 2011 -->)
Last edited: jappit (29 Jun 2011)
153 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×