# Interface MapSurface

All Known Implementing Classes:
  `MapView, NativeMap`

public interface MapSurface

The provider-agnostic map API shared by the pure-vector `MapView` and the native-peer `NativeMap`.

Application code should program against `MapSurface` so it does not need to know whether the map is drawn by the built-in vector engine or by a native provider (Apple MapKit, Google Maps, ...). The two concrete components differ only in how they render; their behavior through this interface is identical, and a `NativeMap` with no native provider wired in transparently delegates to an embedded `MapView`.

Named `MapSurface` rather than `Map` to avoid clashing with `java.util.Map`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addCameraChangeListener(CameraChangeListener l)`
  Registers a camera-change listener.
  `Circle`
  `addCircle(Circle circle)`
  Adds a circle and returns it for chaining.
  `void`
  `addLongPressListener(MapTapListener l)`
  Registers a long-press listener.
  `Marker`
  `addMarker(MarkerOptions options)`
  Adds a marker described by `options` and returns its live handle.
  `Polygon`
  `addPolygon(Polygon polygon)`
  Adds a polygon and returns it for chaining.
  `Polyline`
  `addPolyline(Polyline polyline)`
  Adds a polyline and returns it for chaining.
  `void`
  `addTapListener(MapTapListener l)`
  Registers a tap listener.
  `Component`
  `asComponent()`
  This surface as a Codename One `Component` for layout purposes.
  `void`
  `clearMapObjects()`
  Removes every marker, polyline, polygon and circle.
  `void`
  `fitBounds(MapBounds bounds, int paddingPixels)`
  Moves and zooms the camera so `bounds` fits within the viewport, inset by `paddingPixels` on every edge.
  `CameraPosition`
  `getCameraPosition()`
  The current camera position (target, zoom, bearing, tilt).
  `LatLng`
  `getCenter()`
  The geographic coordinate at the center of the viewport.
  `double`
  `getMaxZoom()`
  The largest zoom level the backend permits.
  `double`
  `getMinZoom()`
  The smallest zoom level the backend permits.
  `MapBounds`
  `getVisibleRegion()`
  The geographic bounds currently visible, or `null` before layout.
  `double`
  `getZoom()`
  The current zoom level.
  `boolean`
  `isLoadingTiles()`
  Whether the vector engine still has tiles in flight for the current view.
  `boolean`
  `isNativeMap()`
  True when a native provider currently backs this surface; false for a pure-vector map or a `NativeMap` that fell back to the vector engine.
  `Point`
  `latLngToScreen(LatLng coord)`
  Converts a geographic coordinate to a pixel relative to this component.
  `void`
  `moveCamera(LatLng target, double zoom)`
  Convenience to recenter at `target` and set `zoom` in one call.
  `void`
  `removeCameraChangeListener(CameraChangeListener l)`
  Unregisters a camera-change listener.
  `void`
  `removeCircle(Circle circle)`
  Removes a previously added circle.
  `void`
  `removeLongPressListener(MapTapListener l)`
  Unregisters a long-press listener.
  `void`
  `removeMarker(Marker marker)`
  Removes a previously added marker.
  `void`
  `removePolygon(Polygon polygon)`
  Removes a previously added polygon.
  `void`
  `removePolyline(Polyline polyline)`
  Removes a previously added polyline.
  `void`
  `removeTapListener(MapTapListener l)`
  Unregisters a tap listener.
  `LatLng`
  `screenToLatLng(int x, int y)`
  Converts a pixel relative to this component to a geographic coordinate.
  `void`
  `setCameraPosition(CameraPosition position)`
  Moves the camera to `position`, animating where the backend supports it.
  `void`
  `setCenter(LatLng center)`
  Recenters the viewport at `center`, keeping the current zoom.
  `void`
  `setZoom(double zoom)`
  Sets the zoom level, keeping the current center.

- ## Method Details

  - ### getCameraPosition

    CameraPosition getCameraPosition()
    The current camera position (target, zoom, bearing, tilt).

  - ### setCameraPosition

    void setCameraPosition(CameraPosition position)
    Moves the camera to `position`, animating where the backend supports it.

  - ### moveCamera

    void moveCamera(LatLng target, double zoom)
    Convenience to recenter at `target` and set `zoom` in one call.

  - ### getZoom

    double getZoom()
    The current zoom level.

  - ### setZoom

    void setZoom(double zoom)
    Sets the zoom level, keeping the current center.

  - ### getMinZoom

    double getMinZoom()
    The smallest zoom level the backend permits.

  - ### getMaxZoom

    double getMaxZoom()
    The largest zoom level the backend permits.

  - ### getCenter

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

  - ### setCenter

    void setCenter(LatLng center)
    Recenters the viewport at `center`, keeping the current zoom.

  - ### getVisibleRegion

    MapBounds getVisibleRegion()
    The geographic bounds currently visible, or `null` before layout. (Named `getVisibleRegion` to avoid clashing with `Component.getVisibleBounds()`, which returns a pixel rectangle.)

  - ### fitBounds

    void fitBounds(MapBounds bounds, int paddingPixels)
    Moves and zooms the camera so `bounds` fits within the viewport, inset by `paddingPixels` on every edge.

  - ### addMarker

    Marker addMarker(MarkerOptions options)
    Adds a marker described by `options` and returns its live handle.

  - ### removeMarker

    void removeMarker(Marker marker)
    Removes a previously added marker.

  - ### addPolyline

    Polyline addPolyline(Polyline polyline)
    Adds a polyline and returns it for chaining.

  - ### removePolyline

    void removePolyline(Polyline polyline)
    Removes a previously added polyline.

  - ### addPolygon

    Polygon addPolygon(Polygon polygon)
    Adds a polygon and returns it for chaining.

  - ### removePolygon

    void removePolygon(Polygon polygon)
    Removes a previously added polygon.

  - ### addCircle

    Circle addCircle(Circle circle)
    Adds a circle and returns it for chaining.

  - ### removeCircle

    void removeCircle(Circle circle)
    Removes a previously added circle.

  - ### clearMapObjects

    void clearMapObjects()
    Removes every marker, polyline, polygon and circle.

  - ### latLngToScreen

    Point latLngToScreen(LatLng coord)
    Converts a geographic coordinate to a pixel relative to this component.

  - ### screenToLatLng

    LatLng screenToLatLng(int x, int y)
    Converts a pixel relative to this component to a geographic coordinate.

  - ### addTapListener

    void addTapListener(MapTapListener l)
    Registers a tap listener.

  - ### removeTapListener

    void removeTapListener(MapTapListener l)
    Unregisters a tap listener.

  - ### addLongPressListener

    void addLongPressListener(MapTapListener l)
    Registers a long-press listener.

  - ### removeLongPressListener

    void removeLongPressListener(MapTapListener l)
    Unregisters a long-press listener.

  - ### addCameraChangeListener

    void addCameraChangeListener(CameraChangeListener l)
    Registers a camera-change listener.

  - ### removeCameraChangeListener

    void removeCameraChangeListener(CameraChangeListener l)
    Unregisters a camera-change listener.

  - ### isNativeMap

    boolean isNativeMap()
    True when a native provider currently backs this surface; false for a pure-vector map or a `NativeMap` that fell back to the vector engine.

  - ### isLoadingTiles

    boolean isLoadingTiles()
    Whether the vector engine still has tiles in flight for the current view. Useful to defer a screenshot (or hide a spinner) until the basemap has finished loading. Always false for a native-provider-backed surface, which loads its own tiles outside the engine's knowledge.

  - ### asComponent

    Component asComponent()
    This surface as a Codename One `Component` for layout purposes.