MaplyViewController

Objective-C

@interface MaplyViewController : MaplyBaseViewController

Swift

class MaplyViewController : MaplyBaseViewController

This view controller implements a map.

This is the main entry point for displaying a 2D or 3D map. Create one of these, fill it with data and let your users mess around with it.

You can display a variety of features on the map, including tile base maps (MaplyQuadImageTilesLayer), vectors (MaplyVectorObject), shapes (MaplyShape), and others. Check out the add calls in the MaplyBaseViewController for details.

The Maply View Controller can be initialized in 3D map, 2D map mode. The 2D mode can be tethered to a UIScrollView if you want to handle gestures that way. That mode is very specific at the moment.

To get selection and tap callbacks, fill out the MaplyViewControllerDelegate and assign the delegate.

Most of the functionality is shared with MaplyBaseViewController. Be sure to look in there first.

  • Initialize as a flat or 3D map.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithMapType:(MaplyMapType)mapType;

    Swift

    init(mapType: MaplyMapType)

  • Initialize as a 2D map.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Swift

    init()

  • Set the coordinate system to use in display. The coordinate system needs to be valid in flat mode. The extents, if present, will be used to define the coordinate system origin. nil is the default and will result in a full web style Spherical Mercator.

    Declaration

    Objective-C

    @property (nonatomic, strong) MaplyCoordinateSystem *_Nullable coordSys;

    Swift

    var coordSys: MaplyCoordinateSystem? { get set }

  • Set the center of the display coordinate system.

    This is (0,0,0) by default. If you set it to something else all display coordinates will be offset from that origin.

    The option is useful when displaying small maps (of a city, say) at very high resolution.

    Declaration

    Objective-C

    @property (nonatomic) MaplyCoordinate3d displayCenter;

    Swift

    var displayCenter: MaplyCoordinate3d { get set }

  • Turn the pinch (zoom) gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool pinchGesture;

    Swift

    var pinchGesture: Bool { get set }

  • Turn the rotate gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool rotateGesture;

    Swift

    var rotateGesture: Bool { get set }

  • Turn the pan gesture on and off

    Pan gesture is on by default

    Declaration

    Objective-C

    @property (nonatomic) _Bool panGesture;

    Swift

    var panGesture: Bool { get set }

  • Turn the double tap to zoom gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool doubleTapZoomGesture;

    Swift

    var doubleTapZoomGesture: Bool { get set }

  • Turn the 2 finger tap to zoom out gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool twoFingerTapGesture;

    Swift

    var twoFingerTapGesture: Bool { get set }

  • Turn on the double tap and drag gesture to zoom in and out.

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool doubleTapDragGesture;

    Swift

    var doubleTapDragGesture: Bool { get set }

  • If set, we use a modified pan gesture recognizer to play nice with the scroll view. For the UIScrollView object, set clipsToBounds, pagingEnabled, and delaysContentTouches to YES, and set scrollEnabled and canCancelContentTouches to NO. Add swipe gesture recognizers to the scroll view to control paging, and call requirePanGestureRecognizerToFailForGesture: for each.

    Off by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool inScrollView;

    Swift

    var inScrollView: Bool { get set }

  • turn the touch to cancel animation gesture on and off

    off by default

    Declaration

    Objective-C

    @property (nonatomic) _Bool cancelAnimationOnTouch;

    Swift

    var cancelAnimationOnTouch: Bool { get set }

  • The current rotation away from north.

    Declaration

    Objective-C

    @property (nonatomic) float heading;

    Swift

    var heading: Float { get set }

  • The minimum angle, in degrees, which a rotate gesture must subtend before rotation begins. i.e., larger values are “stickier” default is zero, causing rotation to begin immediately

    Declaration

    Objective-C

    @property (nonatomic) float rotateGestureThreshold;

    Swift

    var rotateGestureThreshold: Float { get set }

  • If set, we’ll automatically move to wherever the user tapped.

    When on we’ll move the current location to wherever the user tapped if they tapped the globe. That’s true for selection as well. On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool autoMoveToTap;

    Swift

    var autoMoveToTap: Bool { get set }

  • Delegate for selection and location tapping.

    Fill in the MaplyViewControllerDelegate and assign it here to get callbacks for object selection and tapping.

    Declaration

    Objective-C

    @property (nonatomic, weak) NSObject<MaplyViewControllerDelegate> *_Nullable delegate;

    Swift

    weak var delegate: MaplyViewControllerDelegate? { get set }

  • Current height above terrain.

    In 3D map mode this is the height from which the user is viewing the map. Maps are usually -PI to +PI along their horizontal edges.

    Declaration

    Objective-C

    @property (nonatomic) float height;

    Swift

    var height: Float { get set }

  • 2D visual views can do some simple wrapping. This turns that on and off (off by default).

    On some 2D visual views we’re allowed to wrap across the edge of the world. This will attempt to do that.

    Declaration

    Objective-C

    @property (nonatomic) _Bool viewWrap;

    Swift

    var viewWrap: Bool { get set }

  • The box the view point can be in.

    This is the box the view point is allowed to be within. The view controller will constrain it to be within that box. Coordinates are in geographic (radians).

    Declaration

    Objective-C

    - (MaplyBoundingBox)getViewExtents;

    Swift

    func getViewExtents() -> MaplyBoundingBox

  • The box the view point can be in.

    This is the box the view point is allowed to be within. The view controller will constrain it to be within that box. Coordinates are in geographic (radians).

    Declaration

    Objective-C

    - (void)getViewExtentsLL:(MaplyCoordinate *_Nonnull)ll
                      ur:(MaplyCoordinate *_Nonnull)ur;

    Swift

    func getViewExtentsLL(_ ll: UnsafeMutablePointer<MaplyCoordinate>, ur: UnsafeMutablePointer<MaplyCoordinate>)

  • The box the view point can be in.

    This is the box the view point is allowed to be within. The view controller will constrain it to be within that box. Coordinates are in geographic (radians).

    Declaration

    Objective-C

    - (void)setViewExtents:(MaplyBoundingBox)box;

    Swift

    func setViewExtents(_ box: MaplyBoundingBox)

  • The box the view point can be in.

    This is the box the view point is allowed to be within. The view controller will constrain it to be within that box. Coordinates are in geographic (radians).

    Declaration

    Objective-C

    - (void)setViewExtentsLL:(MaplyCoordinate)ll ur:(MaplyCoordinate)ur;

    Swift

    func setViewExtentsLL(_ ll: MaplyCoordinate, ur: MaplyCoordinate)

  • Animate to the given position over time.

    Declaration

    Objective-C

    - (void)animateToPosition:(MaplyCoordinate)newPos time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, time howLong: TimeInterval)

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians)
    howLong

    A time in seconds.

  • Animate the given position to the screen position over time.

    This is similar to animateToPosition:time: except that it will attempt to match up the screen position and the geographic position. This is how you offset the location you’re looking at.

    If it’s impossible to move newPos to loc, then nothing happens.

    Declaration

    Objective-C

    - (_Bool)animateToPosition:(MaplyCoordinate)newPos
                  onScreen:(CGPoint)loc
                      time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, onScreen loc: CGPoint, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.
    loc

    The location on the screen where we’d like it to go.
    howLong

    How long in seconds to take getting there.

  • Animate the given position and height to the screen position over time.

    This is similar to animateToPosition:time: but it also takes a height paramater

    Declaration

    Objective-C

    - (void)animateToPosition:(MaplyCoordinate)newPos
                   height:(float)newHeight
                     time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, height newHeight: Float, time howLong: TimeInterval)

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.
    newHeight

    the view point height above the map.
    howLong

    How long in seconds to take getting there.

  • Animate to the given position, heading and height over time.

    Declaration

    Objective-C

    - (_Bool)animateToPosition:(MaplyCoordinate)newPos
                    height:(float)newHeight
                   heading:(float)newHeading
                      time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, height newHeight: Float, heading newHeading: Float, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians)
    newHeight

    New height to animate to.
    newHeading

    New heading to finish on.
    howLong

    A time interval in seconds.

  • Animate to the given position, heading and height over time.

    Declaration

    Objective-C

    - (_Bool)animateToPositionD:(MaplyCoordinateD)newPos
                     height:(double)newHeight
                    heading:(double)newHeading
                       time:(NSTimeInterval)howLong;

    Swift

    func animate(toPositionD newPos: MaplyCoordinateD, height newHeight: Double, heading newHeading: Double, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians) (double precision)
    newHeight

    New height to animate to. (double)
    newHeading

    New heading to finish on. (double)
    howLong

    A time interval in seconds.

  • Animate to the given position, screen position, heading and height over time.

    If it’s impossible to move newPos to loc, then nothing happens.

    Declaration

    Objective-C

    - (_Bool)animateToPosition:(MaplyCoordinate)newPos
                  onScreen:(CGPoint)loc
                    height:(float)newHeight
                   heading:(float)newHeading
                      time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, onScreen loc: CGPoint, height newHeight: Float, heading newHeading: Float, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians)
    loc

    The location on the screen where we’d like it to go.
    newHeight

    New height to animate to.
    newHeading

    New heading to finish on.
    howLong

    A time interval in seconds.

  • Set the center of the screen to the given position immediately.

    Declaration

    Objective-C

    - (void)setPosition:(MaplyCoordinate)newPos;

    Swift

    func setPosition(_ newPos: MaplyCoordinate)

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.

  • Set the center of the screen and the height offset immediately.

    Declaration

    Objective-C

    - (void)setPosition:(MaplyCoordinate)newPos height:(float)height;

    Swift

    func setPosition(_ newPos: MaplyCoordinate, height: Float)

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.
    height

    Height the view point above the map.

  • Return the current center position

    Declaration

    Objective-C

    - (MaplyCoordinate)getPosition;

    Swift

    func getPosition() -> MaplyCoordinate

  • Return the current view point’s height above the map.

    Declaration

    Objective-C

    - (float)getHeight;

    Swift

    func getHeight() -> Float

  • Return the current center position and height.

    Declaration

    Objective-C

    - (void)getPosition:(MaplyCoordinate *_Nonnull)pos
             height:(float *_Nonnull)height;

    Swift

    func getPosition(_ pos: UnsafeMutablePointer<MaplyCoordinate>, height: UnsafeMutablePointer<Float>)

    Parameters

    pos

    The center of the screen in geographic (lon/lat in radians).
    height

    The current view point’s height above the map.

  • Set the viewing state all at once

    This sets the position, height, screen position and heading all at once.

    Declaration

    Objective-C

    - (void)setViewState:(MaplyViewControllerAnimationState *_Nonnull)viewState;

    Swift

    func setViewState(_ viewState: MaplyViewControllerAnimationState)

  • Make a MaplyViewControllerAnimationState object from the current view state.

    This returns the current view parameters in a single MaplyViewControllerAnimationState.

    Declaration

    Objective-C

    - (nullable MaplyViewControllerAnimationState *)getViewState;

    Swift

    func getViewState() -> MaplyViewControllerAnimationState?

  • Return the closest a viewer is allowed to get to the map surface.

    Declaration

    Objective-C

    - (float)getMinZoom;

    Swift

    func getMinZoom() -> Float

    Return Value

    FLT_MIN if there’s no pitchDelegate set

  • Return the farthest away a viewer is allowed to get from the map surface

    Declaration

    Objective-C

    - (float)getMaxZoom;

    Swift

    func getMaxZoom() -> Float

    Return Value

    FLT_MIN if there’s no pitchDelegate set

  • Return the zoom limits for 3D map mode.

    Declaration

    Objective-C

    - (void)getZoomLimitsMin:(float *_Nonnull)minHeight
                     max:(float *_Nonnull)maxHeight;

    Swift

    func getZoomLimitsMin(_ minHeight: UnsafeMutablePointer<Float>, max maxHeight: UnsafeMutablePointer<Float>)

    Parameters

    minHeight

    The closest a viewer is allowed to get to the map surface.
    maxHeight

    The farthest away a viewer is allowed to get from the map surface.

  • Set the zoom limits for 3D map mode.

    Declaration

    Objective-C

    - (void)setZoomLimitsMin:(float)minHeight max:(float)maxHeight;

    Swift

    func setZoomLimitsMin(_ minHeight: Float, max maxHeight: Float)

    Parameters

    minHeight

    The closest a viewer is allowed to get to the map surface.
    maxHeight

    The farthest away a viewer is allowed to get from the map surface.

  • Return the geographic (lon/lat radians) coordinate in radians for a given screen point.

    Declaration

    Objective-C

    - (MaplyCoordinate)geoFromScreenPoint:(CGPoint)point;

    Swift

    func geo(fromScreenPoint point: CGPoint) -> MaplyCoordinate

    Return Value

    Returns the geo coordinate corresponding to a given screen point in radians.

  • Find a height that shows the given bounding box.

    This method will search for a height that shows the given bounding box within the view. The search is inefficient, so don’t call this a lot.

    Declaration

    Objective-C

    - (float)findHeightToViewBounds:(MaplyBoundingBox)bbox pos:(MaplyCoordinate)pos;

    Swift

    func findHeight(toViewBounds bbox: MaplyBoundingBox, pos: MaplyCoordinate) -> Float

    Parameters

    bbox

    The bounding box (in radians) we’re trying to view.
    pos

    Where the view will be looking.

  • Find a height that shows the given bounding box.

    This method will search for a height that shows the given bounding box within the view. The search is inefficient, so don’t call this a lot.

    This version takes a margin to add around the outside of the area.

    Declaration

    Objective-C

    - (float)findHeightToViewBounds:(MaplyBoundingBox)bbox
                            pos:(MaplyCoordinate)pos
                        marginX:(double)marginX
                        marginY:(double)marginY;

    Swift

    func findHeight(toViewBounds bbox: MaplyBoundingBox, pos: MaplyCoordinate, marginX: Double, marginY: Double) -> Float

    Parameters

    bbox

    The bounding box (in radians) we’re trying to view.
    pos

    Where the view will be looking.
    marginX

    Horizontal boundary around the area
    marginY

    Vertical boundary around the area

  • Return the extents of the current view

    Declaration

    Objective-C

    - (MaplyBoundingBox)getCurrentExtents;

    Swift

    func getCurrentExtents() -> MaplyBoundingBox

    Return Value

    Returns the Bounding Box (in radians) corresponding to the current view

  • Make a gesture recognizer’s success depend on the pan gesture recognizer’s failure.

    When using the map view within a scroll view, add swipe gesture recognizers to the scroll view to control paging, and call this method for each. See also the inScrollView property and its comment.

    Declaration

    Objective-C

    - (void)requirePanGestureRecognizerToFailForGesture:(id)other;

    Swift

    func requirePanGestureRecognizerToFail(forGesture other: Any!)

    Parameters

    other

    The other, subordinate gesture recognizer.