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	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

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.