Package com.massifmaps.ui

Class BaseMapView

java.lang.Object
com.massifmaps.ui.BaseMapView
public class BaseMapView extends Object
A platform independent main view class for all mapping operations.
Allows the user to manipulate the map and access various related components.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BaseMapView()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelAllTasks()
    Cancels all qued tasks such as tile and vector data fetches.
    void
    clearAllCaches()
    Releases memory occupied by all caches.
    void
    clearPreloadingCaches()
    Releases the memory occupied by the preloading area.
    void
    finishRendering()
    Finish all rendering (wait until all rendering commands have finished executing).
    void
    flyTo(MapPos pos, float zoom, float durationSeconds)
    Moves the camera to a position and a zoom level in ONE animation, pulling back over a
    long move and coming down at the target (Van Wijk & Nuij's optimal path).
    void
    flyTo(MapPos pos, float zoom, float rotation, float tilt, float durationSeconds)
    Moves the camera to a position, zoom, rotation and tilt in one animation.
    void
    flyTo(MapPos pos, float zoom, float rotation, float tilt, float climbHeight, float durationSeconds)
    Moves the camera to a position, zoom, rotation and tilt in one animation, climbing over
    the way there.
    MapPos
    getCameraPos()
    Returns the position the camera itself is above, which at a low tilt is nowhere near the
    focus - the focus is what the camera looks AT, kilometres out in front of it.
    float
    getFlightProgress()
    How far along a flyTo animation is, from 0 to 1, or -1 when none is running.
    MapPos
    getFocusPos()
    Returns the position that the camera is currently looking at.
    Layers
    getLayers()
    Returns the Layers object, that can be used for adding and removing map layers.
    MapEventListener
    getMapEventListener()
    Returns the map event listener.
    MapRenderer
    getMapRenderer()
    Returns the MapRenderer object, that can be used for controlling rendering options.
    Options
    getOptions()
    Returns the Options object, that can be used for modifying various map options.
    RedrawRequestListener
    getRedrawRequestListener()
    Returns the redraw request listener.
    float
    getRotation()
    Returns the map rotation in degrees.
    static String
    getSDKVersion()
    Returns the SDK version and build info.
    float
    getTilt()
    Returns the tilt angle in degrees.
    float
    getZoom()
    Returns the zoom level.
    boolean
    isFlightActive()
    Returns true while a flyTo animation is running.
    ScreenPos
    mapToScreen(MapPos mapPos)
    Calculates the screen position corresponding to a map position, using the current view parameters.
    void
    moveTo(MapPos pos, float zoom)
    Points the camera at a position and a zoom level IMMEDIATELY, with no animation.

    Prefer it over setFocusPos + setZoom: with restricted panning on, the focus is clamped so
    the viewport stays inside the pan bounds, so the same target is clamped hard at a world
    view and not at all up close.
    void
    moveTo(MapPos pos, float zoom, float rotation, float tilt)
    The same, also setting rotation and tilt.
    void
    moveToFitBounds(MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, boolean resetRotation, boolean resetTilt, float durationSeconds)
    Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible.
    Also supports resetting the tilt and rotation angles over the course of the animation.
    This method does not work before the screen size is set.
    void
    moveToFitBounds(MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, float durationSeconds)
    Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible.
    This method does not work before the screen size is set.
    void
    onDrawFrame()
    Draws a single frame to the current graphics context.
    void
    onInputEvent(int event, float x1, float y1, float x2, float y2)
    Handles a user input event.
    void
    onSurfaceChanged(int width, int height)
    Changes the screen size of the map view.
    void
    onSurfaceCreated()
    Prepares renderers for drawing.
    void
    onSurfaceDestroyed()
    Stops renderer.
    void
    onWheelEvent(int delta, float x, float y)
    Handles a wheel-rotation event.
    void
    pan(MapVec deltaPos, float durationSeconds)
    Pans the view relative to the current focus position.
    void
    rotate(float deltaAngle, float durationSeconds)
    Rotates the view relative to the current rotation value.
    void
    rotate(float deltaAngle, MapPos targetPos, float durationSeconds)
    Rotates the view relative to the current rotation value.
    MapPos
    screenToMap(ScreenPos screenPos)
    Calculates the map position corresponding to a screen position, using the current view parameters.
    void
    setFocusPos(MapPos pos, float durationSeconds)
    Sets the new absolute focus position.
    void
    setMapEventListener(MapEventListener mapEventListener)
    Sets the map event listener.
    void
    setRedrawRequestListener(RedrawRequestListener listener)
    Sets the listener which will notified when the map needs to be redrawn
    void
    setRotation(float angle, float durationSeconds)
    Sets the new absolute rotation value.
    void
    setRotation(float angle, MapPos targetPos, float durationSeconds)
    Sets the new absolute rotation value.
    void
    setTilt(float tilt, float durationSeconds)
    Sets the new absolute tilt value.
    void
    setZoom(float zoom, float durationSeconds)
    Sets the new absolute zoom value.
    void
    setZoom(float zoom, MapPos targetPos, float durationSeconds)
    Sets the new absolute zoom value.
    void
    stopFlight()
    Stops a flight started with flyTo, leaving the camera where it is.
    void
    tilt(float deltaTilt, float durationSeconds)
    Tilts the view relative to the current tilt value.
    void
    zoom(float deltaZoom, float durationSeconds)
    Zooms the view relative to the current zoom value.
    void
    zoom(float deltaZoom, MapPos targetPos, float durationSeconds)
    Zooms the view relative to the current zoom value.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • BaseMapView

      public BaseMapView()

  • Method Details

    • getSDKVersion

      public static String getSDKVersion()
      Returns the SDK version and build info. The result should be used only for reporting purposes.
      Returns:
      The SDK version and build info.

    • onSurfaceCreated

      public void onSurfaceCreated()
      Prepares renderers for drawing. Has to be called again if the graphics context was lost.

    • onSurfaceChanged

      public void onSurfaceChanged(int width, int height)
      Changes the screen size of the map view. Calling this method before
      onSurfaceCreated is called results in undefined behaviour.
      Parameters:
      width - The new width of the map view.
      height - The new height of the map view.

    • onDrawFrame

      public void onDrawFrame()
      Draws a single frame to the current graphics context. Calling this method before
      onSurfaceCreated and onSurfaceChanged are called results in undefined behaviour.

    • onSurfaceDestroyed

      public void onSurfaceDestroyed()
      Stops renderer. Rendering may resume only after onSurfaceCreated is called again.

    • finishRendering

      public void finishRendering()
      Finish all rendering (wait until all rendering commands have finished executing).

    • onInputEvent

      public void onInputEvent(int event, float x1, float y1, float x2, float y2)
      Handles a user input event.
      Parameters:
      event - The event type. First pointer down = 0, second pointer down = 1, either pointer moved = 2,
      gesture canceled = 3, first pointer up = 4, second pointer up = 5.
      x1 - The x coordinate of the first pointer. -1 if there are no coordinates.
      y1 - The y coordinate of the first pointer. -1 if there are no coordinates.
      x2 - The x coordinate of the second pointer. -1 if there are no coordinates.
      y2 - The y coordinate of the second pointer. -1 if there are no coordinates.

    • onWheelEvent

      public void onWheelEvent(int delta, float x, float y)
      Handles a wheel-rotation event.
      Parameters:
      delta - The number of ticks wheel changed with sign showing the direction of change.
      x - The x coordinate of the pointer.
      y - The y coordinate of the pointer.

    • getLayers

      public Layers getLayers()
      Returns the Layers object, that can be used for adding and removing map layers.
      Returns:
      The Layer object.

    • getOptions

      public Options getOptions()
      Returns the Options object, that can be used for modifying various map options.
      Returns:
      the Option object.

    • getMapRenderer

      public MapRenderer getMapRenderer()
      Returns the MapRenderer object, that can be used for controlling rendering options.
      Returns:
      the MapRenderer object.

    • getFocusPos

      public MapPos getFocusPos()
      Returns the position that the camera is currently looking at.
      Returns:
      The current focus position in the coordinate system of the base projection.

    • getCameraPos

      public MapPos getCameraPos()
      Returns the position the camera itself is above, which at a low tilt is nowhere near the
      focus - the focus is what the camera looks AT, kilometres out in front of it. This is the
      viewpoint: where a first-person camera stands, and where a top-down view has to be centred
      to come back to the same place.
      Returns:
      The camera's ground position in the coordinate system of the base projection.

    • getRotation

      public float getRotation()
      Returns the map rotation in degrees. 0 means looking north, 90 means west, -90 means east and 180 means south.
      Returns:
      The map rotation in degrees in range of (-180 .. 180].

    • getTilt

      public float getTilt()
      Returns the tilt angle in degrees. 0 means looking directly at the horizon, 90 means looking directly down.
      Returns:
      The tilt angle in degrees.

    • getZoom

      public float getZoom()
      Returns the zoom level. The value returned is never negative, 0 means absolutely zoomed out and all other
      values describe some level of zoom.
      Returns:
      The zoom level.

    • pan

      public void pan(MapVec deltaPos, float durationSeconds)
      Pans the view relative to the current focus position. The deltaPos vector is expected to be in
      the coordinate system of the base projection. The new calculated focus position will be clamped to
      the world bounds and to the bounds set by Options::setPanBounds.

      If durationSeconds > 0 the panning operation will be animated over time. If the previous panning animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      deltaPos - The relative coordinate shift.
      durationSeconds - The duration in which the panning operation will be completed in seconds.

    • setFocusPos

      public void setFocusPos(MapPos pos, float durationSeconds)
      Sets the new absolute focus position. The new focus position is expected to be in
      the coordinate system of the base projection. The new focus position will be clamped to
      the world bounds and to the bounds set by Options::setPanBounds.

      If durationSeconds > 0 the panning operation will be animated over time. If the previous panning animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      pos - The new absolute focus position.
      durationSeconds - The duration in which the panning operation will be completed in seconds.

    • moveTo

      public void moveTo(MapPos pos, float zoom)
      Points the camera at a position and a zoom level IMMEDIATELY, with no animation.

      Prefer it over setFocusPos + setZoom: with restricted panning on, the focus is clamped so
      the viewport stays inside the pan bounds, so the same target is clamped hard at a world
      view and not at all up close. Setting the focus first therefore pins it to the middle of
      the bounds - the equator, on an opening map - and the zoom that follows does not undo it.
      This applies the two in whichever order avoids that.

      Unlike flyTo, it needs no frame, so it is also the call for pointing the camera before
      the map has drawn.
      Parameters:
      pos - The target position in base projection coordinate system.
      zoom - The target zoom level.

    • moveTo

      public void moveTo(MapPos pos, float zoom, float rotation, float tilt)
      The same, also setting rotation and tilt. See moveTo.
      Parameters:
      pos - The target position in base projection coordinate system.
      zoom - The target zoom level.
      rotation - The rotation in degrees.
      tilt - The tilt in degrees.

    • flyTo

      public void flyTo(MapPos pos, float zoom, float durationSeconds)
      Moves the camera to a position and a zoom level in ONE animation, pulling back over a
      long move and coming down at the target (Van Wijk & Nuij's optimal path). Unlike
      setFocusPos + setZoom, which run on their own clocks and cross the map at the final
      zoom, this keeps the whole path in view.
      Parameters:
      pos - The target position in base projection coordinate system.
      zoom - The target zoom level.
      durationSeconds - The duration in seconds, or 0 to derive it from the length of
      the path - a move twice as far then does not take twice as long.
      0 is NOT "immediate"; for that use moveTo.

      A flight asked for before the map has drawn its first frame RUNS FROM THAT FIRST FRAME:
      the path is set up against the view it actually starts from, which is not known until
      there is one. It is not dropped and it does not snap.

    • flyTo

      public void flyTo(MapPos pos, float zoom, float rotation, float tilt, float durationSeconds)
      Moves the camera to a position, zoom, rotation and tilt in one animation. See flyTo.
      Parameters:
      pos - The target position in base projection coordinate system.
      zoom - The target zoom level.
      rotation - The target rotation in degrees.
      tilt - The target tilt in degrees.
      durationSeconds - The duration in seconds, or 0 to derive it from the path.

    • flyTo

      public void flyTo(MapPos pos, float zoom, float rotation, float tilt, float climbHeight, float durationSeconds)
      Moves the camera to a position, zoom, rotation and tilt in one animation, climbing over
      the way there. The target position's Z is the height the viewpoint ends at, and the
      climb is added to it as a parabola: highest halfway, back to nothing at both ends - a
      plane's flight, which is also how you clear what stands between the two ends.
      Parameters:
      pos - The target position in base projection coordinate system; its Z is the target height.
      zoom - The target zoom level.
      rotation - The target rotation in degrees.
      tilt - The target tilt in degrees.
      climbHeight - The extra height at the middle of the path, in the base projection's units.
      durationSeconds - The duration in seconds, or 0 to derive it from the path.

    • stopFlight

      public void stopFlight()
      Stops a flight started with flyTo, leaving the camera where it is.

    • isFlightActive

      public boolean isFlightActive()
      Returns true while a flyTo animation is running.
      Returns:
      True if the camera is in flight.

    • getFlightProgress

      public float getFlightProgress()
      How far along a flyTo animation is, from 0 to 1, or -1 when none is running. It is the
      value the camera is actually at, so an app animating its own state alongside the move
      (a layer fading in, a mode switching over) reads it rather than running its own clock.
      Returns:
      The flight progress, or -1.

    • rotate

      public void rotate(float deltaAngle, float durationSeconds)
      Rotates the view relative to the current rotation value. Positive values rotate clockwise, negative values counterclockwise.
      The new calculated rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable
      is set to false.

      If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      deltaAngle - The delta rotation value in degrees.
      durationSeconds - The duration in which the rotation operation will be completed in seconds.

    • rotate

      public void rotate(float deltaAngle, MapPos targetPos, float durationSeconds)
      Rotates the view relative to the current rotation value. Positive values rotate clockwise, negative values counterclockwise.
      The new calculated rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable
      is set to false.

      Rotating is done around the specified target position, keeping it at the same location on the screen.

      If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      deltaAngle - The delta angle value in degrees.
      targetPos - The zooming target position in the coordinate system of the base projection.
      durationSeconds - The duration in which the rotation operation will be completed in seconds.

    • setRotation

      public void setRotation(float angle, float durationSeconds)
      Sets the new absolute rotation value. 0 means look north, 90 means west, -90 means east and 180 means south.
      The rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable
      is set to false.

      If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      angle - The new absolute angle value in degrees.
      durationSeconds - The duration in which the rotation operation will be completed in seconds.

    • setRotation

      public void setRotation(float angle, MapPos targetPos, float durationSeconds)
      Sets the new absolute rotation value. 0 means look north, 90 means west, -90 means east and 180 means south.
      The rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable
      is set to false.

      Rotating is done around the specified target position, keeping it at the same location on the screen.

      If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      angle - The new absolute angle value in degrees.
      targetPos - The zooming target position in the coordinate system of the base projection.
      durationSeconds - The duration in which the rotation operation will be completed in seconds.

    • tilt

      public void tilt(float deltaTilt, float durationSeconds)
      Tilts the view relative to the current tilt value. Positive values tilt the view down towards the map,
      negative values tilt the view up towards the horizon. The new calculated tilt value will be clamped to
      the range of [30 .. 90] and to the range set by Options::setZoomRange.

      If durationSeconds > 0 the tilting operation will be animated over time. If the previous tilting animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      deltaTilt - The number of degrees the camera should be tilted by.
      durationSeconds - The duration in which the tilting operation will be completed in seconds.

    • setTilt

      public void setTilt(float tilt, float durationSeconds)
      Sets the new absolute tilt value. 0 means look directly at the horizon, 90 means look directly down. The
      minimum tilt angle is 30 degrees and the maximum is 90 degrees. The tilt value can be further constrained
      by the Options::setTiltRange method. Values exceeding these ranges will be clamped.

      If durationSeconds > 0 the tilting operation will be animated over time. If the previous tilting animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      tilt - The new absolute tilt value in degrees.
      durationSeconds - The duration in which the tilting operation will be completed in seconds.

    • zoom

      public void zoom(float deltaZoom, float durationSeconds)
      Zooms the view relative to the current zoom value. Positive values zoom in, negative values zoom out.
      The new calculated zoom value will be clamped to the range of [0 .. 24] and to the range set by Options::setZoomRange.

      If durationSeconds > 0 the zooming operation will be animated over time. If the previous zooming animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      deltaZoom - The delta zoom value.
      durationSeconds - The duration in which the zooming operation will be completed in seconds.

    • zoom

      public void zoom(float deltaZoom, MapPos targetPos, float durationSeconds)
      Zooms the view relative to the current zoom value. Positive values zoom in, negative values zoom out.
      The new calculated zoom value will be clamped to the range of [0 .. 24] and to the range set by Options::setZoomRange.

      Zooming is done towards the specified target position, keeping it at the same location on the screen.

      If durationSeconds > 0 the zooming operation will be animated over time. If the previous zooming animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      deltaZoom - The delta zoom value.
      targetPos - The zooming target position in the coordinate system of the base projection.
      durationSeconds - The duration in which the zooming operation will be completed in seconds.

    • setZoom

      public void setZoom(float zoom, float durationSeconds)
      Sets the new absolute zoom value. The minimum zoom value is 0, which means absolutely zoomed out and the maximum
      zoom value is 24. The zoom value can be further constrained by the Options::setZoomRange method. Values
      exceeding these ranges will be clamped.

      If durationSeconds > 0 the zooming operation will be animated over time. If the previous zooming animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      zoom - The new absolute zoom value.
      durationSeconds - The duration in which the zooming operation will be completed in seconds.

    • setZoom

      public void setZoom(float zoom, MapPos targetPos, float durationSeconds)
      Sets the new absolute zoom value. The minimum zoom value is 0, which means absolutely zoomed out and the maximum
      zoom value is 24. The zoom value can be further constrained by the Options::setZoomRange method. Values
      exceeding these ranges will be clamped.

      Zooming is done towards the specified target position, keeping it at the same location on the screen.

      If durationSeconds > 0, the zooming operation will be animated over time. If the previous zooming animation has not
      finished by the time this method is called, it will be stopped.
      Parameters:
      zoom - The new absolute zoom value.
      targetPos - The zooming target position in the coordinate system of the base projection.
      durationSeconds - The duration in which the zooming operation will be completed in seconds.

    • moveToFitBounds

      public void moveToFitBounds(MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, float durationSeconds)
      Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible.
      This method does not work before the screen size is set.
      Parameters:
      mapBounds - The bounding box on the map to be made visible in the base projection's coordinate system.
      screenBounds - The screen bounding box where to fit the map bounding box.
      integerZoom - If true, then closest integer zoom level will be used. If false, exact fractional zoom level will be used.
      durationSeconds - The duration in which the operation will be completed in seconds.

    • moveToFitBounds

      public void moveToFitBounds(MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, boolean resetRotation, boolean resetTilt, float durationSeconds)
      Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible.
      Also supports resetting the tilt and rotation angles over the course of the animation.
      This method does not work before the screen size is set.
      Parameters:
      mapBounds - The bounding box on the map to be made visible in the base projection's coordinate system.
      screenBounds - The screen bounding box where to fit the map bounding box.
      integerZoom - If true, then closest integer zoom level will be used. If false, exact fractional zoom level will be used.
      resetTilt - If true, view will be untilted. If false, current tilt will be kept.
      resetRotation - If true, rotation will be reset. If false, current rotation will be kept.
      durationSeconds - The duration in which the operation will be completed in seconds.

    • getMapEventListener

      public MapEventListener getMapEventListener()
      Returns the map event listener. May be null.
      Returns:
      The map event listener.

    • setMapEventListener

      public void setMapEventListener(MapEventListener mapEventListener)
      Sets the map event listener. If a null pointer is passed no map events will be generated. The default is null.
      Parameters:
      mapEventListener - The new map event listener.

    • getRedrawRequestListener

      public RedrawRequestListener getRedrawRequestListener()
      Returns the redraw request listener.
      Returns:
      The redraw request listener.

    • setRedrawRequestListener

      public void setRedrawRequestListener(RedrawRequestListener listener)
      Sets the listener which will notified when the map needs to be redrawn
      Parameters:
      listener - The redraw listener.

    • screenToMap

      public MapPos screenToMap(ScreenPos screenPos)
      Calculates the map position corresponding to a screen position, using the current view parameters.
      Parameters:
      screenPos - The screen position.
      Returns:
      The calculated map position in base projection coordinate system. If the given screen position is not on the map, NaNs are returned.

    • mapToScreen

      public ScreenPos mapToScreen(MapPos mapPos)
      Calculates the screen position corresponding to a map position, using the current view parameters.
      Parameters:
      mapPos - The map position in base projection coordinate system.
      Returns:
      The calculated screen position. Can be off-screen.

    • cancelAllTasks

      public void cancelAllTasks()
      Cancels all qued tasks such as tile and vector data fetches. Tasks that have already started
      may continue until they finish. Tasks that are added after this method call are not affected.

    • clearPreloadingCaches

      public void clearPreloadingCaches()
      Releases the memory occupied by the preloading area. Calling this method releases some
      memory if preloading is enabled, but means that the area right outside the visible area has to be
      fetched again.

    • clearAllCaches

      public void clearAllCaches()
      Releases memory occupied by all caches. Calling this means that everything has to be fetched again,
      including the visible area.