Class VectorMapEngine

java.lang.Object
com.codename1.maps.vector.VectorMapEngine
public final class VectorMapEngine extends Object

The pure-Codename One map renderer behind MapView (and the NativeMap fallback).

It maintains the camera (center + fractional zoom), pulls tiles from a TileSource, rasterizes vector tiles once into 256px buffers (or decodes raster tiles), caches them in an LRU TileCache, and on each paint blits the visible buffers scaled to the fractional zoom and places labels with the LabelEngine. All drawing uses the framework Graphics API -- there is no native peer.

A vector map zooms past the deepest level its source serves: beyond it the deepest tile's geometry is drawn again for each smaller area on screen ("overzoom"), the way vector map renderers reach street level from data that stops at zoom 14.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VectorMapEngine(TileSource source, MapStyle style)
    Creates an engine over source, styled by style.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clearCache()
    Drops all cached tiles (e.g. on low memory).
    void
    fitBounds(MapBounds bounds, int padding)
    Moves the camera so bounds fits the viewport inset by padding.
    LatLng
    getCenter()
    The geographic coordinate at the center of the viewport.
    double
    getMaxZoom()
    The largest zoom level the camera can reach.
    double
    getMinZoom()
    The smallest zoom level the tile source serves.
    double
    getPixelRatio()
    The current device pixel ratio (see setPixelRatio(double)).
    TileSource
    getSource()
    The active tile source.
    MapStyle
    getStyle()
    The active style.
    MapBounds
    getVisibleBounds()
    The geographic bounds currently visible, or null before layout.
    double
    getZoom()
    The current fractional zoom level.
    boolean
    hasPendingTiles()
    Whether any tile requested for the current view is still loading (i.e. the basemap is not yet fully rendered).
    boolean
    hasRenderedVisibleTiles()
    True when the currently visible tile set has been requested and every visible tile has finished loading/decoding/rendering into the tile cache.
    Point
    latLngToScreen(LatLng coord)
    Geographic to component-relative pixel.
    void
    paint(Graphics g, int originX, int originY, int width, int height)
    Paints the basemap and labels into g, offset by originX,originY.
    void
    paintLabels(Graphics g)
    Draws the labels of the basemap painted by the last paintTiles(Graphics, int, int, int, int) call.
    void
    paintTiles(Graphics g, int originX, int originY, int width, int height)
    Paints the basemap without its labels, and remembers the labels in view for the next paintLabels(Graphics) call.
    void
    panPixels(double dx, double dy)
    Pans the camera by a pixel delta (used for drag gestures).
    LatLng
    screenToLatLng(int x, int y)
    Component-relative pixel to geographic.
    void
    setCenter(LatLng center)
    Recenters the camera at center, keeping the current zoom.
    void
    setPixelRatio(double ratio)
    Sets the device pixel ratio: physical pixels per logical (256px) map pixel.
    void
    setRepaintCallback(Runnable r)
    Sets the callback invoked (on the EDT) whenever a tile finishes loading and the map needs to repaint.
    void
    setSource(TileSource source)
    Replaces the tile source, clearing cached tiles.
    void
    setStyle(MapStyle style)
    Replaces the style, clearing rendered tiles so they redraw.
    void
    setViewport(int width, int height)
    Sets the pixel size of the viewport (called by the host component on layout before painting and coordinate conversion).
    void
    setZoom(double zoom)
    Sets the zoom level, clamped to the source's min/max.
    void
    zoomAround(double newZoom, int sx, int sy)
    Zooms to newZoom while keeping the geographic point currently under the component pixel sx,sy fixed (used for pinch and double-tap).

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • VectorMapEngine

      public VectorMapEngine(TileSource source, MapStyle style)
      Creates an engine over source, styled by style.

  • Method Details

    • setRepaintCallback

      public void setRepaintCallback(Runnable r)
      Sets the callback invoked (on the EDT) whenever a tile finishes loading and the map needs to repaint.

    • setSource

      public void setSource(TileSource source)
      Replaces the tile source, clearing cached tiles.

    • getSource

      public TileSource getSource()
      The active tile source.

    • setStyle

      public void setStyle(MapStyle style)
      Replaces the style, clearing rendered tiles so they redraw.

    • getStyle

      public MapStyle getStyle()
      The active style.

    • setCenter

      public void setCenter(LatLng center)
      Recenters the camera at center, keeping the current zoom.

    • getCenter

      public LatLng getCenter()
      The geographic coordinate at the center of the viewport.

    • setZoom

      public void setZoom(double zoom)
      Sets the zoom level, clamped to the source's min/max.

    • getZoom

      public double getZoom()
      The current fractional zoom level.

    • getMinZoom

      public double getMinZoom()
      The smallest zoom level the tile source serves.

    • getMaxZoom

      public double getMaxZoom()
      The largest zoom level the camera can reach. For a vector source this is six levels past the deepest level the source serves (see the class notes), up to zoom 22; a source that serves deeper tiles than that keeps its own deepest level. A raster source stops at its own deepest level, since stretching a bitmap only blurs it.

    • setViewport

      public void setViewport(int width, int height)
      Sets the pixel size of the viewport (called by the host component on layout before painting and coordinate conversion).

    • setPixelRatio

      public void setPixelRatio(double ratio)
      Sets the device pixel ratio: physical pixels per logical (256px) map pixel. On a 3x retina screen pass 3 so a tile spans 768 device pixels and the map shows the same area it would on a 1x screen. Values <= 0 are ignored. Changing it discards rendered tiles so they re-rasterize at the new resolution.

    • getPixelRatio

      public double getPixelRatio()
      The current device pixel ratio (see setPixelRatio(double)).

    • hasPendingTiles

      public boolean hasPendingTiles()
      Whether any tile requested for the current view is still loading (i.e. the basemap is not yet fully rendered). Goes true after the first paint that needs uncached tiles and back to false once they have all arrived. Best-effort readiness signal (tile bookkeeping happens on the EDT).

    • hasRenderedVisibleTiles

      public boolean hasRenderedVisibleTiles()
      True when the currently visible tile set has been requested and every visible tile has finished loading/decoding/rendering into the tile cache. Calling this may request missing visible tiles, so it can be used as a deterministic readiness probe before the first paint has run.

    • latLngToScreen

      public Point latLngToScreen(LatLng coord)
      Geographic to component-relative pixel.

    • panPixels

      public void panPixels(double dx, double dy)
      Pans the camera by a pixel delta (used for drag gestures). A positive dx moves the map content to the right.

    • zoomAround

      public void zoomAround(double newZoom, int sx, int sy)
      Zooms to newZoom while keeping the geographic point currently under the component pixel sx,sy fixed (used for pinch and double-tap).

    • screenToLatLng

      public LatLng screenToLatLng(int x, int y)
      Component-relative pixel to geographic.

    • getVisibleBounds

      public MapBounds getVisibleBounds()
      The geographic bounds currently visible, or null before layout.

    • fitBounds

      public void fitBounds(MapBounds bounds, int padding)
      Moves the camera so bounds fits the viewport inset by padding.

    • paint

      public void paint(Graphics g, int originX, int originY, int width, int height)

      Paints the basemap and labels into g, offset by originX,originY. The caller is responsible for clipping to the component bounds and for drawing overlays (markers/shapes) afterwards.

      This is paintTiles(Graphics, int, int, int, int) followed by paintLabels(Graphics); call those two instead to draw shapes such as a route between them, so the route does not cover the street names, as on familiar street maps.

    • paintTiles

      public void paintTiles(Graphics g, int originX, int originY, int width, int height)
      Paints the basemap without its labels, and remembers the labels in view for the next paintLabels(Graphics) call.

    • paintLabels

      public void paintLabels(Graphics g)
      Draws the labels of the basemap painted by the last paintTiles(Graphics, int, int, int, int) call. Does nothing before one.

    • clearCache

      public void clearCache()
      Drops all cached tiles (e.g. on low memory).