MSFBaseMapView

Objective-C


@interface MSFBaseMapView : NSObject {
  void *swigCPtr;
  BOOL swigCMemOwn;
}

Swift

class MSFBaseMapView : NSObject

A platform independent main view class for all mapping operations. Allows the user to manipulate the map and access various related components.

  • Returns the SDK version and build info. The result should be used only for reporting purposes.

    Declaration

    Objective-C

    + (NSString *)getSDKVersion;

    Swift

    class func getSDKVersion() -> String!

    Return Value

    The SDK version and build info.

  • Undocumented

    Declaration

    Objective-C

    -(id)init;

    Swift

    init!()
  • Prepares renderers for drawing. Has to be called again if the graphics context was lost.

    Declaration

    Objective-C

    - (void)onSurfaceCreated;

    Swift

    func onSurfaceCreated()
  • Changes the screen size of the map view. Calling this method before onSurfaceCreated is called results in undefined behaviour.

    Declaration

    Objective-C

    - (void)onSurfaceChanged:(int)width height:(int)height;

    Swift

    func onSurfaceChanged(_ width: Int32, height: Int32)

    Parameters

    width

    The new width of the map view.

    height

    The new height of the map view.

  • Draws a single frame to the current graphics context. Calling this method before onSurfaceCreated and onSurfaceChanged are called results in undefined behaviour.

    Declaration

    Objective-C

    - (void)onDrawFrame;

    Swift

    func onDrawFrame()
  • Stops renderer. Rendering may resume only after onSurfaceCreated is called again.

    Declaration

    Objective-C

    - (void)onSurfaceDestroyed;

    Swift

    func onSurfaceDestroyed()
  • Finish all rendering (wait until all rendering commands have finished executing).

    Declaration

    Objective-C

    - (void)finishRendering;

    Swift

    func finishRendering()
  • Handles a user input event.

    Declaration

    Objective-C

    - (void)onInputEvent:(int)event
                      x1:(float)x1
                      y1:(float)y1
                      x2:(float)x2
                      y2:(float)y2;

    Swift

    func onInputEvent(_ event: Int32, x1: Float, y1: Float, x2: Float, y2: Float)

    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.

  • Handles a wheel-rotation event.

    Declaration

    Objective-C

    - (void)onWheelEvent:(int)delta x:(float)x y:(float)y;

    Swift

    func onWheelEvent(_ delta: Int32, x: Float, y: Float)

    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.

  • Returns the Layers object, that can be used for adding and removing map layers.

    Declaration

    Objective-C

    - (MSFLayers *)getLayers;

    Swift

    func getLayers() -> MSFLayers!

    Return Value

    The Layer object.

  • Returns the Options object, that can be used for modifying various map options.

    Declaration

    Objective-C

    - (MSFOptions *)getOptions;

    Swift

    func getOptions() -> MSFOptions!

    Return Value

    the Option object.

  • Returns the MapRenderer object, that can be used for controlling rendering options.

    Declaration

    Objective-C

    - (MSFMapRenderer *)getMapRenderer;

    Swift

    func getMapRenderer() -> MSFMapRenderer!

    Return Value

    the MapRenderer object.

  • Returns the position that the camera is currently looking at.

    Declaration

    Objective-C

    - (MSFMapPos *)getFocusPos;

    Swift

    func getFocusPos() -> MSFMapPos!

    Return Value

    The current focus position in the coordinate system of the base projection.

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

    Declaration

    Objective-C

    - (MSFMapPos *)getCameraPos;

    Swift

    func getCameraPos() -> MSFMapPos!

    Return Value

    The camera’s ground position in the coordinate system of the base projection.

  • Returns the map rotation in degrees. 0 means looking north, 90 means west, -90 means east and 180 means south.

    Declaration

    Objective-C

    - (float)getRotation;

    Swift

    func getRotation() -> Float

    Return Value

    The map rotation in degrees in range of (-180 .. 180].

  • Returns the tilt angle in degrees. 0 means looking directly at the horizon, 90 means looking directly down.

    Declaration

    Objective-C

    - (float)getTilt;

    Swift

    func getTilt() -> Float

    Return Value

    The tilt angle in degrees.

  • Returns the zoom level. The value returned is never negative, 0 means absolutely zoomed out and all other values describe some level of zoom.

    Declaration

    Objective-C

    - (float)getZoom;

    Swift

    func getZoom() -> Float

    Return Value

    The zoom level.

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

    Declaration

    Objective-C

    - (void)pan:(MSFMapVec *)deltaPos durationSeconds:(float)durationSeconds;

    Swift

    func pan(_ deltaPos: MSFMapVec!, durationSeconds: Float)

    Parameters

    deltaPos

    The relative coordinate shift.

    durationSeconds

    The duration in which the panning operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)setFocusPos:(MSFMapPos *)pos durationSeconds:(float)durationSeconds;

    Swift

    func setFocus(_ pos: MSFMapPos!, durationSeconds: Float)

    Parameters

    pos

    The new absolute focus position.

    durationSeconds

    The duration in which the panning operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)moveTo:(MSFMapPos *)pos zoom:(float)zoom;

    Swift

    func move(to pos: MSFMapPos!, zoom: Float)

    Parameters

    pos

    The target position in base projection coordinate system.

    zoom

    The target zoom level.

  • The same, also setting rotation and tilt. See moveTo.

    Declaration

    Objective-C

    - (void)moveTo:(MSFMapPos *)pos
              zoom:(float)zoom
          rotation:(float)rotation
              tilt:(float)tilt;

    Swift

    func move(to pos: MSFMapPos!, zoom: Float, rotation: Float, tilt: Float)

    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.

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

    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.

    Declaration

    Objective-C

    - (void)flyTo:(MSFMapPos *)pos
                   zoom:(float)zoom
        durationSeconds:(float)durationSeconds;

    Swift

    func fly(to pos: MSFMapPos!, zoom: Float, durationSeconds: Float)

    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.

  • Moves the camera to a position, zoom, rotation and tilt in one animation. See flyTo.

    Declaration

    Objective-C

    - (void)flyTo:(MSFMapPos *)pos
                   zoom:(float)zoom
               rotation:(float)rotation
                   tilt:(float)tilt
        durationSeconds:(float)durationSeconds;

    Swift

    func fly(to pos: MSFMapPos!, zoom: Float, rotation: Float, tilt: Float, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)flyTo:(MSFMapPos *)pos
                   zoom:(float)zoom
               rotation:(float)rotation
                   tilt:(float)tilt
            climbHeight:(float)climbHeight
        durationSeconds:(float)durationSeconds;

    Swift

    func fly(to pos: MSFMapPos!, zoom: Float, rotation: Float, tilt: Float, climbHeight: Float, durationSeconds: Float)

    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.

  • Stops a flight started with flyTo, leaving the camera where it is.

    Declaration

    Objective-C

    - (void)stopFlight;

    Swift

    func stopFlight()
  • Returns true while a flyTo animation is running.

    Declaration

    Objective-C

    - (BOOL)isFlightActive;

    Swift

    func isFlightActive() -> Bool

    Return Value

    True if the camera is in flight.

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

    Declaration

    Objective-C

    - (float)getFlightProgress;

    Swift

    func getFlightProgress() -> Float

    Return Value

    The flight progress, or -1.

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

    Declaration

    Objective-C

    - (void)rotate:(float)deltaAngle durationSeconds:(float)durationSeconds;

    Swift

    func rotate(_ deltaAngle: Float, durationSeconds: Float)

    Parameters

    deltaAngle

    The delta rotation value in degrees.

    durationSeconds

    The duration in which the rotation operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)rotate:(float)deltaAngle
              targetPos:(MSFMapPos *)targetPos
        durationSeconds:(float)durationSeconds;

    Swift

    func rotate(_ deltaAngle: Float, targetPos: MSFMapPos!, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)setRotation:(float)angle durationSeconds:(float)durationSeconds;

    Swift

    func setRotation(_ angle: Float, durationSeconds: Float)

    Parameters

    angle

    The new absolute angle value in degrees.

    durationSeconds

    The duration in which the rotation operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)setRotation:(float)angle
              targetPos:(MSFMapPos *)targetPos
        durationSeconds:(float)durationSeconds;

    Swift

    func setRotation(_ angle: Float, targetPos: MSFMapPos!, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)tilt:(float)deltaTilt durationSeconds:(float)durationSeconds;

    Swift

    func tilt(_ deltaTilt: Float, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)setTilt:(float)tilt durationSeconds:(float)durationSeconds;

    Swift

    func setTilt(_ tilt: Float, durationSeconds: Float)

    Parameters

    tilt

    The new absolute tilt value in degrees.

    durationSeconds

    The duration in which the tilting operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)zoom:(float)deltaZoom durationSeconds:(float)durationSeconds;

    Swift

    func zoom(_ deltaZoom: Float, durationSeconds: Float)

    Parameters

    deltaZoom

    The delta zoom value.

    durationSeconds

    The duration in which the zooming operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)zoom:(float)deltaZoom
              targetPos:(MSFMapPos *)targetPos
        durationSeconds:(float)durationSeconds;

    Swift

    func zoom(_ deltaZoom: Float, targetPos: MSFMapPos!, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)setZoom:(float)zoom durationSeconds:(float)durationSeconds;

    Swift

    func setZoom(_ zoom: Float, durationSeconds: Float)

    Parameters

    zoom

    The new absolute zoom value.

    durationSeconds

    The duration in which the zooming operation will be completed in seconds.

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

    Declaration

    Objective-C

    - (void)setZoom:(float)zoom
              targetPos:(MSFMapPos *)targetPos
        durationSeconds:(float)durationSeconds;

    Swift

    func setZoom(_ zoom: Float, targetPos: MSFMapPos!, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)moveToFitBounds:(MSFMapBounds *)mapBounds
               screenBounds:(MSFScreenBounds *)screenBounds
                integerZoom:(BOOL)integerZoom
            durationSeconds:(float)durationSeconds;

    Swift

    func move(toFit mapBounds: MSFMapBounds!, screenBounds: MSFScreenBounds!, integerZoom: Bool, durationSeconds: Float)

    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.

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

    Declaration

    Objective-C

    - (void)moveToFitBounds:(MSFMapBounds *)mapBounds
               screenBounds:(MSFScreenBounds *)screenBounds
                integerZoom:(BOOL)integerZoom
              resetRotation:(BOOL)resetRotation
                  resetTilt:(BOOL)resetTilt
            durationSeconds:(float)durationSeconds;

    Swift

    func move(toFit mapBounds: MSFMapBounds!, screenBounds: MSFScreenBounds!, integerZoom: Bool, resetRotation: Bool, resetTilt: Bool, durationSeconds: Float)

    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.

  • Returns the map event listener. May be null.

    Declaration

    Objective-C

    - (MSFMapEventListener *)getMapEventListener;

    Swift

    func getMapEventListener() -> MSFMapEventListener!

    Return Value

    The map event listener.

  • Sets the map event listener. If a null pointer is passed no map events will be generated. The default is null.

    Declaration

    Objective-C

    - (void)setMapEventListener:(MSFMapEventListener *)mapEventListener;

    Swift

    func setMapEventListener(_ mapEventListener: MSFMapEventListener!)

    Parameters

    mapEventListener

    The new map event listener.

  • Returns the redraw request listener.

    Declaration

    Objective-C

    - (MSFRedrawRequestListener *)getRedrawRequestListener;

    Swift

    func getRedrawRequestListener() -> MSFRedrawRequestListener!

    Return Value

    The redraw request listener.

  • Sets the listener which will notified when the map needs to be redrawn

    Declaration

    Objective-C

    - (void)setRedrawRequestListener:(MSFRedrawRequestListener *)listener;

    Swift

    func setRedrawRequestListener(_ listener: MSFRedrawRequestListener!)

    Parameters

    listener

    The redraw listener.

  • Calculates the map position corresponding to a screen position, using the current view parameters.

    Declaration

    Objective-C

    - (MSFMapPos *)screenToMap:(MSFScreenPos *)screenPos;

    Swift

    func screen(toMap screenPos: MSFScreenPos!) -> MSFMapPos!

    Parameters

    screenPos

    The screen position.

    Return Value

    The calculated map position in base projection coordinate system. If the given screen position is not on the map, NaNs are returned.

  • Calculates the screen position corresponding to a map position, using the current view parameters.

    Declaration

    Objective-C

    - (MSFScreenPos *)mapToScreen:(MSFMapPos *)mapPos;

    Swift

    func map(toScreen mapPos: MSFMapPos!) -> MSFScreenPos!

    Parameters

    mapPos

    The map position in base projection coordinate system.

    Return Value

    The calculated screen position. Can be off-screen.

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

    Declaration

    Objective-C

    - (void)cancelAllTasks;

    Swift

    func cancelAllTasks()
  • 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.

    Declaration

    Objective-C

    - (void)clearPreloadingCaches;

    Swift

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

    Declaration

    Objective-C

    - (void)clearAllCaches;

    Swift

    func clearAllCaches()
  • Undocumented

    Declaration

    Objective-C

    -(void)dealloc;

    Swift

    func dealloc()