# Class NativeMap

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Container
com.codename1.maps.NativeMap

All Implemented Interfaces:
  `MapSurface, Animation, Editable, StyleListener, Iterable<Component>`

public class NativeMap extends Container implements MapSurface

A native-rendered map. When the build wired in a native provider (Apple MapKit, Google Maps, Bing, Huawei, ... selected via the `maps.provider` build hint) and it is available on the device, `NativeMap` embeds that provider's native view as a `PeerComponent`. Otherwise -- on the simulator, on devices without the selected provider, or when no provider was wired in at all -- it transparently falls back to an embedded pure-vector `MapView`. Either way it exposes the same `MapSurface` API, so application code is identical.

The public API never names a provider; which one (if any) backs a given build is decided entirely by build hints through `MapProviderRegistry`.

- ## Field Summary

  ### Fields inherited from class Component

  `BASELINE, BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, CROSSHAIR_CURSOR, DEFAULT_CURSOR, DRAG_REGION_IMMEDIATELY_DRAG_X, DRAG_REGION_IMMEDIATELY_DRAG_XY, DRAG_REGION_IMMEDIATELY_DRAG_Y, DRAG_REGION_LIKELY_DRAG_X, DRAG_REGION_LIKELY_DRAG_XY, DRAG_REGION_LIKELY_DRAG_Y, DRAG_REGION_NOT_DRAGGABLE, DRAG_REGION_POSSIBLE_DRAG_X, DRAG_REGION_POSSIBLE_DRAG_XY, DRAG_REGION_POSSIBLE_DRAG_Y, E_RESIZE_CURSOR, HAND_CURSOR, LEFT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NW_RESIZE_CURSOR, RIGHT, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, TOP, W_RESIZE_CURSOR, WAIT_CURSOR`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NativeMap()`
  Creates a native map centered on the equator at a low zoom.
  `NativeMap(LatLng center, double zoom)`
  Creates a native map at the given initial camera.
  `NativeMap(LatLng center, double zoom, TileSource fallbackSource, MapStyle fallbackStyle)`
  Creates a native map at the given initial camera, specifying the tile source and style used by the pure-vector `MapView` when no native provider is available.

- ## 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`
  `dispose()`
  Releases the native or web view backing this map and detaches it.
  `static void`
  `fireCameraChange(int mapId)`
  Invoked from native code when the camera settles after movement.
  `static void`
  `fireLongPress(int mapId, int x, int y)`
  Invoked from native code when the map is long-pressed.
  `static void`
  `fireMarkerClick(int mapId, long markerKey)`
  Invoked from native code when a marker is tapped (`markerKey` is the value returned by `MapProvider.addMarker(int, byte[], double, double, String, String, float, float)`).
  `static void`
  `fireTap(int mapId, int x, int y)`
  Invoked from native code when the map is tapped.
  `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.
  `protected void`
  `initComponent()`
  Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state
  `boolean`
  `isLoadingTiles()`
  Whether the vector engine still has tiles in flight for the current view.
  `boolean`
  `isMapReady()`
  Whether the native map has finished its initial render.
  `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.

  ### Methods inherited from class Container

  `add, add, add, add, add, add, addAll, addComponent, addComponent, addComponent, addComponent, animateHierarchy, animateHierarchyAndWait, animateHierarchyFade, animateHierarchyFadeAndWait, animateLayout, animateLayoutAndWait, animateLayoutFade, animateLayoutFadeAndWait, animateUnlayout, animateUnlayoutAndWait, applyRTL, calcPreferredSize, cancelRepaints, clearClientProperties, constrainHeightWhenScrollable, constrainWidthWhenScrollable, contains, createAnimateHierarchy, createAnimateHierarchyFade, createAnimateLayout, createAnimateLayoutFade, createAnimateLayoutFadeAndWait, createAnimateMotion, createAnimateUnlayout, createReplaceTransition, dragInitiated, drop, encloseIn, encloseIn, findDropTargetAt, findFirstFocusable, fireClicked, flushReplace, forceRevalidate, getBottomGap, getChildrenAsList, getClosestComponentTo, getComponentAt, getComponentAt, getComponentCount, getComponentIndex, getGridPosX, getGridPosY, getLayout, getLayoutHeight, getLayoutWidth, getLeadComponent, getLeadParent, getResponderAt, getSafeAreaRoot, getScrollIncrement, getSideGap, getUIManager, initLaf, invalidate, isEnabled, isSafeArea, isSafeAreaRoot, isScrollableX, isScrollableY, isSelectableInteraction, isSurface, iterator, iterator, keyPressed, keyReleased, layoutContainer, morph, morphAndWait, paint, paintComponentBackground, paintGlass, paramString, pointerPressed, refreshTheme, removeAll, removeComponent, replace, replace, replaceAndWait, replaceAndWait, replaceAndWait, revalidate, revalidateLater, revalidateWithAnimationSafety, scrollComponentToVisible, setCellRenderer, setEnabled, setLayout, setLeadComponent, setSafeArea, setSafeAreaRoot, setScrollable, setScrollableX, setScrollableY, setScrollIncrement, setShouldCalcPreferredSize, setShouldLayout, setUIManager, updateTabIndices`

  ### Methods inherited from class Component

  `addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, animate, announceForAccessibility, bindProperty, blocksSideSwipe, calcScrollSize, contains, containsOrOwns, createStyleAnimation, deinitialize, deinitializeCustomStyle, dragEnter, dragExit, dragFinished, draggingOver, drawDraggedImage, focusGained, focusLost, getAbsoluteX, getAbsoluteY, getAccessibilityText, getAllStyles, getAnimationManager, getBaseline, getBaselineResizeBehavior, getBindablePropertyNames, getBindablePropertyTypes, getBorder, getBoundPropertyValue, getBounds, getBounds, getClientProperty, getCloudBoundProperty, getCloudDestinationProperty, getComponentForm, getComponentState, getCursor, getDefaultDragTransparency, getDirtyRegion, getDisabledStyle, getDraggedx, getDraggedy, getDragImage, getDragRegionStatus, getDragSpeed, getDragTransparency, getEditingDelegate, getHeight, getInlineAllStyles, getInlineDisabledStyles, getInlinePressedStyles, getInlineSelectedStyles, getInlineStylesTheme, getInlineUnselectedStyles, getInnerHeight, getInnerPreferredH, getInnerPreferredW, getInnerWidth, getInnerX, getInnerY, getLabelForComponent, getName, getNativeOverlay, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getOuterHeight, getOuterPreferredH, getOuterPreferredW, getOuterWidth, getOuterX, getOuterY, getOwner, getParent, getPreferredH, getPreferredSize, getPreferredSizeStr, getPreferredTabIndex, getPreferredW, getPressedStyle, getPropertyNames, getPropertyTypeNames, getPropertyTypes, getPropertyValue, getSameHeight, getSameWidth, getScrollable, getScrollAnimationSpeed, getScrollDimension, getScrollOpacity, getScrollOpacityChangeSpeed, getScrollX, getScrollY, getSelectCommandText, getSelectedRect, getSelectedStyle, getStyle, getTabIndex, getTensileLength, getTextSelectionSupport, getTooltip, getUIID, getUnselectedStyle, getVisibleBounds, getVisibleBounds, getWidth, getX, getY, growShrink, handlesInput, hasFixedPreferredSize, hasFocus, hideNativeOverlay, initCustomStyle, initDisabledStyle, initPressedStyle, initSelectedStyle, initUnselectedStyle, installDefaultPainter, isAlwaysTensile, isBlockLead, isCellRenderer, isChildOf, isDragActivated, isDragAndDropOperation, isDraggable, isDragRegion, isDropTarget, isEditable, isEditing, isFlatten, isFocusable, isGrabsPointerEvents, isHidden, isHidden, isHideInLandscape, isHideInPortrait, isHScrollThumbGrabbed, isHScrollThumbHover, isIgnorePointerEvents, isInClippingRegion, isInitialized, isOpaque, isOwnedBy, isPinchBlocksDragAndDrop, isRippleEffect, isRTL, isScrollable, isScrollVisible, isSetCursorSupported, isSmoothScrolling, isSnapToGrid, isStickyDrag, isTactileTouch, isTactileTouch, isTensileDragEnabled, isTraversable, isVisible, isVScrollThumbGrabbed, isVScrollThumbHover, keyRepeated, laidOut, longKeyPress, longPointerPress, onScrollX, onScrollY, onSetFocusable, paintBackground, paintBackgrounds, paintBorder, paintBorderBackground, paintComponent, paintComponent, paintIntersectingComponentsAbove, paintLock, paintLockRelease, paintRippleOverlay, paintScrollbars, paintScrollbarX, paintScrollbarY, paintShadows, parsePreferredSize, pinch, pinch, pinchReleased, pointerDragged, pointerDragged, pointerHover, pointerHoverPressed, pointerHoverReleased, pointerPressed, pointerReleased, pointerReleased, putClientProperty, refreshTheme, refreshTheme, remove, removeDragFinishedListener, removeDragOverListener, removeDropListener, removeFocusListener, removeLongPressListener, removePointerDraggedListener, removePointerPressedListener, removePointerReleasedListener, removeScrollListener, removeStateChangeListener, repaint, repaint, requestFocus, resetFocusable, respondsToPointerEvents, scrollRectToVisible, scrollRectToVisible, setAccessibilityText, setAlwaysTensile, setBlockLead, setBoundPropertyValue, setCloudBoundProperty, setCloudDestinationProperty, setComponentState, setCursor, setDefaultDragTransparency, setDirtyRegion, setDisabledStyle, setDraggable, setDragTransparency, setDropTarget, setEditingDelegate, setFlatten, setFocus, setFocusable, setGrabsPointerEvents, setHandlesInput, setHeight, setHidden, setHidden, setHideInLandscape, setHideInPortrait, setHorizontalScrollBounds, setIgnorePointerEvents, setInitialized, setInlineAllStyles, setInlineDisabledStyles, setInlinePressedStyles, setInlineSelectedStyles, setInlineStylesTheme, setInlineUnselectedStyles, setIsScrollVisible, setLabelForComponent, setName, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setOpaque, setOwner, setPinchBlocksDragAndDrop, setPreferredH, setPreferredSize, setPreferredSizeStr, setPreferredTabIndex, setPreferredW, setPressedStyle, setPropertyValue, setPullToRefresh, setRippleEffect, setRTL, setSameHeight, setSameSize, setSameWidth, setScrollAnimationSpeed, setScrollOpacityChangeSpeed, setScrollSize, setScrollVisible, setScrollX, setScrollY, setSelectCommandText, setSelectedStyle, setSize, setSmoothScrolling, setSnapToGrid, setTabIndex, setTactileTouch, setTensileDragEnabled, setTensileLength, setTooltip, setTraversable, setUIID, setUIID, setUIIDFinal, setUnselectedStyle, setVerticalScrollBounds, setVisible, setWidth, setX, setY, shouldBlockSideSwipe, shouldBlockSideSwipeLeft, shouldBlockSideSwipeRight, shouldRenderComponentSelection, showNativeOverlay, startEditingAsync, stopEditing, stripMarginAndPadding, styleChanged, toImage, toString, unbindProperty, updateNativeOverlay, visibleBoundsContains`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Iterable

  `forEach`

- ## Constructor Details

  - ### NativeMap

    public NativeMap()
    Creates a native map centered on the equator at a low zoom.

  - ### NativeMap

    public NativeMap(LatLng center, double zoom)
    Creates a native map at the given initial camera.

  - ### NativeMap

    public NativeMap(LatLng center, double zoom, TileSource fallbackSource, MapStyle fallbackStyle)
    Creates a native map at the given initial camera, specifying the tile source and style used by the pure-vector `MapView` when no native provider is available. Useful for an offline or branded fallback basemap (and for deterministic tests).

- ## Method Details

  - ### initComponent

    protected void initComponent()
    Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state
    Overrides:
      `initComponent` in class `Component`

  - ### dispose

    public void dispose()
    Releases the native or web view backing this map and detaches it. Call this when you are finished with a `NativeMap` you will not show again so a provider that keeps a live view -- in particular the web provider's `BrowserComponent`, whose map JavaScript runs a continuous animation loop -- stops consuming CPU/GPU in the background instead of being left running. After `dispose()` the map should not be reused.

  - ### getCameraPosition

    public CameraPosition getCameraPosition()
    The current camera position (target, zoom, bearing, tilt).
    Specified by:
      `getCameraPosition` in interface `MapSurface`

  - ### setCameraPosition

    public void setCameraPosition(CameraPosition position)
    Moves the camera to `position`, animating where the backend supports it.
    Specified by:
      `setCameraPosition` in interface `MapSurface`

  - ### moveCamera

    public void moveCamera(LatLng target, double zoom)
    Convenience to recenter at `target` and set `zoom` in one call.
    Specified by:
      `moveCamera` in interface `MapSurface`

  - ### getZoom

    public double getZoom()
    The current zoom level.
    Specified by:
      `getZoom` in interface `MapSurface`

  - ### setZoom

    public void setZoom(double zoom)
    Sets the zoom level, keeping the current center.
    Specified by:
      `setZoom` in interface `MapSurface`

  - ### getMinZoom

    public double getMinZoom()
    The smallest zoom level the backend permits.
    Specified by:
      `getMinZoom` in interface `MapSurface`

  - ### getMaxZoom

    public double getMaxZoom()
    The largest zoom level the backend permits.
    Specified by:
      `getMaxZoom` in interface `MapSurface`

  - ### getCenter

    public LatLng getCenter()
    The geographic coordinate at the center of the viewport.
    Specified by:
      `getCenter` in interface `MapSurface`

  - ### setCenter

    public void setCenter(LatLng center)
    Recenters the viewport at `center`, keeping the current zoom.
    Specified by:
      `setCenter` in interface `MapSurface`

  - ### getVisibleRegion

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

  - ### fitBounds

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

  - ### addMarker

    public Marker addMarker(MarkerOptions options)
    Adds a marker described by `options` and returns its live handle.
    Specified by:
      `addMarker` in interface `MapSurface`

  - ### removeMarker

    public void removeMarker(Marker marker)
    Removes a previously added marker.
    Specified by:
      `removeMarker` in interface `MapSurface`

  - ### addPolyline

    public Polyline addPolyline(Polyline polyline)
    Adds a polyline and returns it for chaining.
    Specified by:
      `addPolyline` in interface `MapSurface`

  - ### removePolyline

    public void removePolyline(Polyline polyline)
    Removes a previously added polyline.
    Specified by:
      `removePolyline` in interface `MapSurface`

  - ### addPolygon

    public Polygon addPolygon(Polygon polygon)
    Adds a polygon and returns it for chaining.
    Specified by:
      `addPolygon` in interface `MapSurface`

  - ### removePolygon

    public void removePolygon(Polygon polygon)
    Removes a previously added polygon.
    Specified by:
      `removePolygon` in interface `MapSurface`

  - ### addCircle

    public Circle addCircle(Circle circle)
    Adds a circle and returns it for chaining.
    Specified by:
      `addCircle` in interface `MapSurface`

  - ### removeCircle

    public void removeCircle(Circle circle)
    Removes a previously added circle.
    Specified by:
      `removeCircle` in interface `MapSurface`

  - ### clearMapObjects

    public void clearMapObjects()
    Removes every marker, polyline, polygon and circle.
    Specified by:
      `clearMapObjects` in interface `MapSurface`

  - ### latLngToScreen

    public Point latLngToScreen(LatLng coord)
    Converts a geographic coordinate to a pixel relative to this component.
    Specified by:
      `latLngToScreen` in interface `MapSurface`

  - ### screenToLatLng

    public LatLng screenToLatLng(int x, int y)
    Converts a pixel relative to this component to a geographic coordinate.
    Specified by:
      `screenToLatLng` in interface `MapSurface`

  - ### addTapListener

    public void addTapListener(MapTapListener l)
    Registers a tap listener.
    Specified by:
      `addTapListener` in interface `MapSurface`

  - ### removeTapListener

    public void removeTapListener(MapTapListener l)
    Unregisters a tap listener.
    Specified by:
      `removeTapListener` in interface `MapSurface`

  - ### addLongPressListener

    public void addLongPressListener(MapTapListener l)
    Registers a long-press listener.
    Specified by:
      `addLongPressListener` in interface `MapSurface`

  - ### removeLongPressListener

    public void removeLongPressListener(MapTapListener l)
    Unregisters a long-press listener.
    Specified by:
      `removeLongPressListener` in interface `MapSurface`

  - ### addCameraChangeListener

    public void addCameraChangeListener(CameraChangeListener l)
    Registers a camera-change listener.
    Specified by:
      `addCameraChangeListener` in interface `MapSurface`

  - ### removeCameraChangeListener

    public void removeCameraChangeListener(CameraChangeListener l)
    Unregisters a camera-change listener.
    Specified by:
      `removeCameraChangeListener` in interface `MapSurface`

  - ### isNativeMap

    public 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.
    Specified by:
      `isNativeMap` in interface `MapSurface`

  - ### isMapReady

    public boolean isMapReady()
    Whether the native map has finished its initial render. For the web provider this reflects the Google Maps `tilesloaded` event, so a caller (e.g. a screenshot test) can wait for the real map to paint instead of a fixed delay. Providers without an async-readiness signal report ready once their peer exists.

  - ### isLoadingTiles

    public 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. Delegates to the embedded vector map when this `NativeMap` fell back to it; a real native provider loads its own tiles, so false.
    Specified by:
      `isLoadingTiles` in interface `MapSurface`

  - ### asComponent

    public Component asComponent()
    This surface as a Codename One `Component` for layout purposes.
    Specified by:
      `asComponent` in interface `MapSurface`

  - ### fireTap

    public static void fireTap(int mapId, int x, int y)
    Invoked from native code when the map is tapped.

  - ### fireLongPress

    public static void fireLongPress(int mapId, int x, int y)
    Invoked from native code when the map is long-pressed.

  - ### fireMarkerClick

    public static void fireMarkerClick(int mapId, long markerKey)
    Invoked from native code when a marker is tapped (`markerKey` is the value returned by `MapProvider.addMarker(int, byte[], double, double, String, String, float, float)`).

  - ### fireCameraChange

    public static void fireCameraChange(int mapId)
    Invoked from native code when the camera settles after movement.