Creating custom maps with Nutiteq's Map SDK

Comments

15 Sep
2009

Article Review by Larry101 (20090915)

I created a new project in Netbeans and had the code in this example running on my phone in under 15 minutes! An excellent article highlighting an extremely useful framework which makes creating your own mobile map-based applications almost ridiculously easy.

The article describes how to use Nutiteq's MGMap library to effortlessly create map-based applications using Java ME. Developers simply have to download and reference the jar file from their project, register for a license key and implement an application using the provided components. The MapComponent class allows the creation of Canvas-based mapping interfaces. The component takes care of downloading and rendering of the map tile images, while still allowing a large degree of customisation. The zip file which contains the jar file to reference from your project also includes several sample applications which you can install and play around with. All examples come complete with source code, making it really easy to understand how the library works and it's full functionality.

The ease of use of this framework is likely to lead to many useful and interesting mobile map applications in the future.

Jairo.junoth - Jairo.Junoth

Hi,

i get an error in the paint() method of MapScreen :

   protected void paint(Graphics g) {
       // 6. define to repaint of map
       map.paint(g);
   }

Error: found : javax.microedition.lcdui.Graphics required : com.nuniteq.wrappers.Graphics

but in the "MapScreen" class javax.microedition.lcdui.Graphics is imported, please help me..

thanks already

jairo.junoth 01:46, 6 October 2011 (EEST)

Hamishwillee - Try the forums or private messaging

Hi

The article was created in 2009 and it is quite possible the author is no longer watching it. You could try private messaging them, but I suggest you raise a query on the appropriate discussion board (http://www.developer.nokia.com/Community/Discussion/forumdisplay.php?3-Mobile-Java) as this will get more recent advice. If you find the source of the problem, please add a note.

Regards

Hamish

hamishwillee 04:03, 11 October 2011 (EEST)

Skalogir - The code is now updated.

I have now reviewed and updated the code in this example, in order for the application to work properly.

skalogir 12:25, 4 November 2011 (EET)

Hamishwillee - Link to the licence key is broken

Does this still require the key? If not, can we update appropriately?

hamishwillee 08:11, 18 June 2013 (EEST)

Log in or Join to leave comments.

With following code you can easily add interactive, "slippy" mapping functions to your mobile application.

Article Metadata

---

Code Example

Source file: Media:CustomMapsMIDletSource.zip

Installation file: Media:CustomMapsMIDletBinaries.zip

---

Tested with

SDK: Nokia SDK 1.1 for Java

Devices(s): C3-01

---

Compatibility

Platform(s): Series 40, S60, Symbian

Dependencies: Mobile Map API

---

Article

Created: jaakl (15 Sep 2009)

Updated: skalogir (04 Nov 2011)

Reviewed: skalogir (19 Jun 2011)

Last edited: hamishwillee (18 Jun 2013)

You will get more interactive results, can use client-side caching (even stored map data) without worrying about license restrictions, as compared other API-s (like Google static maps API).

Download and install Nutiteq's Map SDK

1. Download package for Java ME from Nutiteq Mobile Map API downloads. For Nokia platforms (Series 40 or S60) use maps-lib-j2me-1_0_2.zip . It includes maps_lib-1.0.0.jar as actual library, and also javadocs, and a set of sample apps. Last version number may be larger by now.
2. Include maps_lib.jar file to your project, add it to the Build Path and be sure also to Export the library.

Get your license key

Create a license key [--hamishwillee : link here is broken] www.nutiteq.com/generate_key.html page (requires registration). Evaluation license key type is ok. Remember to enter same application and vendor name as in JAD file.

Quick overview for advanced developers

To use the library you have to create com.nutiteq.mapComponent() object and use it's methods.

1. Create class which implements MapListener

    public class MapScreen extends Canvas implements CommandListener, MapListener {

2. Create map object, specify initial view location and size of map.

    map = new MapComponent("MY_LICENSE_KEY", Mapper.instance, getWidth(), getHeight(), new WgsPoint(24.764580, 59.437420), 10);

3. MapListener implementation and defining is needed to get map update events from UI

    map.setMapListener(this);

4. Now start mapping actions (threads)

    map.startMapping();

5. Implement map painting to canvas

       protected void paint(Graphics g) {
           com.nutiteq.wrappers.Graphics graphicsWrapper = new com.nutiteq.wrappers.Graphics(g);        
           map.paint(graphicsWrapper);
       }

6. Implement MapListener methods

       public void mapClicked(WgsPoint pnt) {
       }
    
       public void mapMoved() {
       }
    
       public void needRepaint(boolean downloadReady) {
           // This repaint call is mandatory, otherwise map is not refreshed!
           repaint();
       }

7. Add UI controls (keypresses, pointer) to control map, menu commands and other stuff. See full source below.

Full basic application sources

Main MIDlet class (Mapper.java)

The only mapping-specific line here is "Log.enableAll();", which turns on logging in mapping library, it makes troubleshooting easier.

import javax.microedition.lcdui.Display;
import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;
 
import com.nutiteq.log.Log;
 
public class Mapper extends MIDlet {
 
    public static Mapper instance;
    private MapScreen screen;
 
    public Mapper() {
        instance = this;
    }
 
    protected void destroyApp(boolean arg0) throws MIDletStateChangeException {
        screen = null;
        instance.notifyDestroyed();
        instance = null;
    }
 
    protected void pauseApp() {
 
    }
 
    protected void startApp() throws MIDletStateChangeException {
        Log.enableAll();
        if (screen == null) {
          screen = new MapScreen();
        }
        Display.getDisplay(this).setCurrent(screen);
        screen.repaint();
    }
}

MapScreen.java class

package mapper;
 
import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.CommandListener;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Graphics;
import javax.microedition.midlet.MIDletStateChangeException;
 
import com.nutiteq.MapComponent;
import com.nutiteq.components.WgsPoint;
import com.nutiteq.controls.MGMapsKeysHandler;
import com.nutiteq.listeners.MapListener;
 
public class MapScreen extends Canvas implements CommandListener, MapListener {
    public static MapScreen instance;
    private final MapComponent map;
    private final Command exit = new Command("Exit", Command.EXIT, 0);
 
    public MapScreen() {
        instance = this;
 
        // 1. initialize map object, also set initial location and zoom
        // Note that default map source will be OpenStreetMap (Mapnik tiles)
        map = new MapComponent("MY_LICENSE_KEY", Mapper.instance, getWidth(),
                getHeight(), new WgsPoint(24.764580, 59.437420), 10);
 
        // 2. define keycode handler for keypresses.
        // We use a default set (arrows and 2468 for moving, # for zoom in, *
        // for zoom out)
        // you can define own keys instead of this
        MGMapsKeysHandler keyHandler = new MGMapsKeysHandler();
        map.setControlKeysHandler(keyHandler);
 
        // 3. set this class to listen map events: needRepaint, mapMoved and
        // mapClicked
        map.setMapListener(this);
 
        // 4. show default location pointer
        map.showDefaultCursor();
 
        // 5. start mapping threads and tasks in the library
        map.startMapping();
 
        // add Exit command to the midlet menu
        addCommand(exit);
        setCommandListener(this);
    }
 
    protected void paint(Graphics g) {
        // 6. define to repaint of map
        com.nutiteq.wrappers.Graphics graphicsWrapper = new com.nutiteq.wrappers.Graphics(g);        
        map.paint(graphicsWrapper);
    }
 
    // 7. Forward keypressing events to library using following methods
    protected void keyPressed(final int keyCode) {
        map.keyPressed(keyCode);
    }
 
    protected void keyReleased(final int keyCode) {
        map.keyReleased(keyCode);
    }
 
    protected void keyRepeated(final int keyCode) {
        map.keyRepeated(keyCode);
    }
 
    // Basic handler for Midlet menu action
    public void commandAction(Command c, Displayable d) {
 
        if (c == exit) {
   // 8. stop mapping properly before terminating Midlet.
   // NB! do not forget it, otherwise RMS cache index is not updated
            map.stopMapping();
            try {
                Mapper.instance.destroyApp(true);
            } catch (final MIDletStateChangeException ignore) {
            }
        }
    }
 
    // 9. Handlers for MapListener
    public void mapClicked(WgsPoint pnt) {
    }
 
    public void mapMoved() {
    }
 
    public void needRepaint(boolean downloadReady) {
        // 10. This repaint call is mandatory, otherwise map is not refreshed!
        repaint();
    }
 
}

Extra features from the library

1. Use Navteq MapTP map server as source

map.setMap(new MapTPMap("YOUR MAPTP KEY"));

2. Add a dynamic KML data source, say Panoramio images

map.addKmlService(new KmlUrlReader(
  "http://www.panoramio.com/panoramio.kml?LANG=en_US.utf8&", true));

3. Add individual placemarks on top of map: points, lines, polygons

 // 1. first load some image for point display. It could be also custom painted
 try {
   icon = Image.createImage("/x.png");
  } catch (IOException e) {}
 // 2. add it as a point
 map.addPlace(new Place(1, "Tallinn", icon, 24.764580, 59.437420));
 
 // 3. add a line
 WgsPoint[] linePoints = {
  new WgsPoint(24.76382468302337, 59.44325151314919),
  new WgsPoint(24.76344295658494, 59.4462352840583),
  new WgsPoint(24.76593650384734, 59.44530921763007),
  new WgsPoint(24.76804665483925, 59.44616268729941),
  new WgsPoint(24.76810500478219, 59.443291656657) };
 
  final PlaceLabel lineLabel = new PlaceLabel("Label for a line");
  Line line = new Line(linePoints, new LineStyle(0xFF00FF00, 1), lineLabel);
  map.addLine(line);
 
 // 4. make a polygon from same linePoints. Use default style here
  map.addPolygon(new Polygon(linePoints));

4. Add some visual overlays: animated zoom indicator and download indicator:

map.setZoomLevelIndicator(new DefaultZoomIndicator(0, 1));
map.showZoomLevelIndicator(true);
 
map.enableDownloadCounter();
map.enableDownloadDisplay();

5. Take a look to Library developer resources to see how to many use other features like:

• GPS and Cell-ID positioning
• Geocoding
• Routing
• Map overlays (hybrid maps)
• Map streaming for much faster map download
• Offline mapping: preloaded maps to application package or flash drive
• many more