# Class MapView

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

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

public class MapView extends Container implements MapSurface

A pure-vector map component: it renders entirely through the Codename One `Graphics` API (the built-in `VectorMapEngine`) and never embeds a native peer, so it composes cleanly with the rest of the UI -- dialogs, lists and overlays draw over it without the clipping limitations of a native view.

`MapView` works identically on every platform including the simulator and the web. By default it shows the free, keyless OpenFreeMap vector basemap (real OpenStreetMap data) so it renders real maps with zero configuration and no API key; point it at any other `TileSource` (a keyed MVT endpoint, a raster source such as `RasterTileSource.openStreetMap()`, or a bundled offline tileset) as needed. For a native-rendered map (Apple MapKit, Google Maps, ...) use `NativeMap`, which falls back to this component when no native provider is wired in.

- ## 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
  `MapView()`
  Creates a map showing the free, keyless OpenFreeMap vector basemap (real OpenStreetMap data) centered on the equator at a low zoom.
  `MapView(TileSource source)`
  Creates a map backed by `source` with the default light style.
  `MapView(TileSource source, MapStyle style)`
  Creates a map backed by `source` and styled by `style` (the style is only consulted for vector sources).

- ## 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.
  `protected Dimension`
  `calcPreferredSize()`
  Calculates the preferred size based on component content.
  `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.
  `VectorMapEngine`
  `getEngine()`
  The underlying vector engine, for advanced configuration (tile cache, source and style swapping).
  `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`
  `longPointerPress(int x, int y)`
  If this Component is focused this method is invoked when the user presses and holds the pointer on the Component
  `void`
  `moveCamera(LatLng target, double zoom)`
  Convenience to recenter at `target` and set `zoom` in one call.
  `protected void`
  `paintBackground(Graphics g)`
  This method paints the Component background, it should be overriden by subclasses to perform custom background drawing.
  `protected boolean`
  `pinch(float scale)`
  Invoked by subclasses interested in handling pinch to zoom events, if true is returned other drag events will not be broadcast
  `void`
  `pointerDragged(int x, int y)`
  If this Component is focused, the pointer dragged event will call this method
  `void`
  `pointerPressed(int x, int y)`
  If this Component is focused, the pointer pressed event will call this method
  `void`
  `pointerReleased(int x, int y)`
  If this Component is focused, the pointer released event will call this method
  `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.
  `MapView`
  `setStyle(MapStyle style)`
  Replaces the style.
  `MapView`
  `setTileSource(TileSource source)`
  Replaces the tile source.
  `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, 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, 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

  `addContextMenuListener, addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addMouseWheelListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, addStylusListener, 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, initComponent, 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, onScrollX, onScrollY, onSetFocusable, paintBackgrounds, paintBorder, paintBorderBackground, paintComponent, paintComponent, paintIntersectingComponentsAbove, paintLock, paintLockRelease, paintRippleOverlay, paintScrollbars, paintScrollbarX, paintScrollbarY, paintShadows, parsePreferredSize, pinch, pinchReleased, pointerDragged, pointerHover, pointerHoverPressed, pointerHoverReleased, pointerPressed, pointerReleased, putClientProperty, refreshTheme, refreshTheme, remove, removeContextMenuListener, removeDragFinishedListener, removeDragOverListener, removeDropListener, removeFocusListener, removeLongPressListener, removeMouseWheelListener, removePointerDraggedListener, removePointerPressedListener, removePointerReleasedListener, removeScrollListener, removeStateChangeListener, removeStylusListener, repaint, repaint, requestFocus, resetFocusable, respondsToPointerEvents, rotation, 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

  - ### MapView

    public MapView()
    Creates a map showing the free, keyless OpenFreeMap vector basemap (real OpenStreetMap data) centered on the equator at a low zoom.

  - ### MapView

    public MapView(TileSource source)
    Creates a map backed by `source` with the default light style.

  - ### MapView

    public MapView(TileSource source, MapStyle style)
    Creates a map backed by `source` and styled by `style` (the style is only consulted for vector sources).

- ## Method Details

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

  - ### getEngine

    public VectorMapEngine getEngine()
    The underlying vector engine, for advanced configuration (tile cache, source and style swapping).

  - ### setTileSource

    public MapView setTileSource(TileSource source)
    Replaces the tile source.

  - ### setStyle

    public MapView setStyle(MapStyle style)
    Replaces the style.

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

  - ### asComponent

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

  - ### paintBackground

    protected void paintBackground(Graphics g)
    Description copied from class: `Component`

    This method paints the Component background, it should be overriden by subclasses to perform custom background drawing.

    ###### Parameters

    - `g`: the component graphics
    Overrides:
      `paintBackground` in class `Component`

  - ### pointerPressed

    public void pointerPressed(int x, int y)

    If this Component is focused, the pointer pressed event will call this method

    ###### Parameters

    - `x`: the pointer x coordinate

    - `y`: the pointer y coordinate

    Overrides:
      `pointerPressed` in class `Container`

  - ### pointerDragged

    public void pointerDragged(int x, int y)

    If this Component is focused, the pointer dragged event will call this method

    ###### Parameters

    - `x`: the pointer x coordinate

    - `y`: the pointer y coordinate

    Overrides:
      `pointerDragged` in class `Component`

  - ### pointerReleased

    public void pointerReleased(int x, int y)

    If this Component is focused, the pointer released event will call this method

    ###### Parameters

    - `x`: the pointer x coordinate

    - `y`: the pointer y coordinate

    Overrides:
      `pointerReleased` in class `Component`

  - ### longPointerPress

    public void longPointerPress(int x, int y)
    If this Component is focused this method is invoked when the user presses and holds the pointer on the Component
    Overrides:
      `longPointerPress` in class `Component`

  - ### pinch

    protected boolean pinch(float scale)
    Description copied from class: `Component`

    Invoked by subclasses interested in handling pinch to zoom events, if true is returned other drag events will not be broadcast

    ###### Parameters

    - `scale`: @param scale the scaling of the pinch operation a number larger than 1 means scaling up and smaller than 1 means scaling down. It is recommended that code would threshold the number (so a change between 1.0 and 1.02 shouldn't necessarily trigger zoom). Notice that this number is relevant to current zoom levels and unaware of them so you should also enforce limits of maximum/minimum zoom levels.

    ###### Returns

    false by default

    Overrides:
      `pinch` in class `Component`

  - ### calcPreferredSize

    protected Dimension calcPreferredSize()
    Description copied from class: `Container`

    Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

    ###### Returns

    the calculated preferred size based on component content

    Overrides:
      `calcPreferredSize` in class `Container`