TGMapView


@interface TGMapView : UIView <UIGestureRecognizerDelegate>

TGMapView is a flexible and customizable map view managing the lifecycle of an OpenGL ES map. This view provides gesture handlers for tap, double-tap, long press, pan, pinch, rotate, and shove gestures.

The public interface provides dynamic map marker placement, change of camera view settings, and map description changes through scene updates.

This view uses scene files described by the Tangram scene format allowing you to fully customize your map using your own data. Some pre-made basemap styles can be found here using Nextzen data sources.

To use basemap styles you can sign up for an API key and load it through your application:

let sceneURL = URL("https://www.nextzen.org/carto/bubble-wrap-style/9/bubble-wrap-style.zip");
let sceneUpdates = [ TGSceneUpdate(path: "global.sdk_api_key", value: "YOUR_API_KEY") ];
view.loadScene(from: sceneURL, with: sceneUpdates);

Note

All the screen positions used in this inteface are in logical pixel or drawing coordinate system (based on a UIKit coordinate system), which is independent of the phone pixel density. Refer to the Apple documentation regarding Coordinate Systems and Drawing in iOS for more information.

Initialize the View

Loading Scenes

  • Load a scene file synchronously from a URL with a list of updates.

    If an error occurs while applying updates the new scene will not be applied. See TGSceneUpdate for details.

    Declaration

    Objective-C

    - (int)loadSceneFromURL:(nonnull NSURL *)url
            withUpdates:(nullable NSArray<TGSceneUpdate *> *)updates;

    Swift

    func loadScene(from url: URL, with updates: [TGSceneUpdate]?) -> Int32

    Parameters

    url

    An http(s) or file URL for the scene file.
    updates

    A list of TGSceneUpdate to apply to the scene, or nil.

    Return Value

    The integer ID for the new scene or -1 if the scene cannot be loaded.

  • Load a scene file asynchronously from a URL with a list of updates.

    Calls -[TGMapViewDelegate mapView:didLoadScene:withError:] on the mapViewDelegate when it completes.

    If an error occurs while applying updates the new scene will not be applied. See TGSceneUpdate for details.

    Declaration

    Objective-C

    - (int)loadSceneAsyncFromURL:(nonnull NSURL *)url
                 withUpdates:(nullable NSArray<TGSceneUpdate *> *)updates;

    Swift

    func loadSceneAsync(from url: URL, with updates: [TGSceneUpdate]?) -> Int32

    Parameters

    url

    An http(s) or file URL for the scene file.
    updates

    A list of TGSceneUpdate to apply to the scene, or nil.

    Return Value

    The integer ID for the new scene or -1 if the scene cannot be loaded.

  • Load a scene synchronously from string with a list of updates.

    Calls -[TGMapViewDelegate mapView:didLoadScene:withError:] on the mapViewDelegate when it completes.

    If an error occurs while applying updates the new scene will not be applied. See TGSceneUpdate for details.

    Declaration

    Objective-C

    - (int)loadSceneFromYAML:(nonnull NSString *)yaml
           relativeToURL:(nonnull NSURL *)url
             withUpdates:(nullable NSArray<TGSceneUpdate *> *)updates;

    Swift

    func loadScene(fromYAML yaml: String, relativeTo url: URL, with updates: [TGSceneUpdate]?) -> Int32

    Parameters

    yaml

    YAML scene string.
    url

    The base URL used to resolve relative URLs in the scene.
    updates

    A list of TGSceneUpdate to apply to the scene, or nil.

    Return Value

    The integer ID for the new scene or -1 if the scene cannot be loaded.

  • Load a scene asynchronously from string with a list of updates.

    Calls -[TGMapViewDelegate mapView:didLoadScene:withError:] on the mapViewDelegate when it completes.

    If an error occurs while applying updates the new scene will not be applied. See TGSceneUpdate for details.

    Declaration

    Objective-C

    - (int)loadSceneAsyncFromYAML:(nonnull NSString *)yaml
                relativeToURL:(nonnull NSURL *)url
                  withUpdates:(nullable NSArray<TGSceneUpdate *> *)updates;

    Swift

    func loadSceneAsync(fromYAML yaml: String, relativeTo url: URL, with updates: [TGSceneUpdate]?) -> Int32

    Parameters

    yaml

    YAML scene string.
    url

    The base URL used to resolve relative URLs in the scene.
    updates

    A list of TGSceneUpdate to apply to the scene, or nil.

    Return Value

    The integer ID for the new scene or -1 if the scene cannot be loaded.

Delegates

Changing the Map Viewport

  • The current position and orientation of the map camera.

    Setting this property will move the map immediately. To animate the movement use -[TGMapView setCameraPosition:withDuration:easeType:callback:] or -[TGMapView flyToCameraPosition:withDuration:callback:]

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) TGCameraPosition *_Nonnull cameraPosition;

    Swift

    @NSCopying var cameraPosition: TGCameraPosition { get set }

  • The minimum zoom level for the map view.

    The default minimum zoom is 0. Values less than the default will be clamped. Assigning a value greater than the current maximum zoom will set the maximum zoom to this value.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat minimumZoomLevel;

    Swift

    var minimumZoomLevel: CGFloat { get set }

  • The maximum zoom level for the map view.

    The default maximum zoom is 20.5. Values greater than the default will be clamped. Assigning a value less than the current minimum zoom will set the minimum zoom to this value.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat maximumZoomLevel;

    Swift

    var maximumZoomLevel: CGFloat { get set }

  • Assign a TGCameraType to the view camera

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) TGCameraType cameraType;

    Swift

    var cameraType: TGCameraType { get set }

  • Move the map camera to a new position with an easing animation.

    Declaration

    Objective-C

    - (void)setCameraPosition:(nonnull TGCameraPosition *)cameraPosition
             withDuration:(NSTimeInterval)duration
                 easeType:(TGEaseType)easeType
                 callback:(nullable void (^)(BOOL))callback;

    Swift

    func setCameraPosition(_ cameraPosition: TGCameraPosition, withDuration duration: TimeInterval, easeType: TGEaseType, callback: ((Bool) -> Void)? = nil)

    Parameters

    cameraPosition

    The new camera position
    duration

    The animation duration in seconds
    easeType

    The type of easing animation
    callback

    A callback to execute when the animation completes

  • Move the map camera to a new position with an animation that pans and zooms in a smooth arc.

    The animation duration is calculated based on the distance to the new camera position assuming a speed scaling factor of 1.0

    Declaration

    Objective-C

    - (void)flyToCameraPosition:(nonnull TGCameraPosition *)cameraPosition
                   callback:(nullable void (^)(BOOL))callback;

    Swift

    func fly(to cameraPosition: TGCameraPosition, callback: ((Bool) -> Void)? = nil)

    Parameters

    cameraPosition

    The new camera position
    callback

    A callback to execute when the animation completes

  • Move the map camera to a new position with an animation that pans and zooms in a smooth arc.

    Declaration

    Objective-C

    - (void)flyToCameraPosition:(nonnull TGCameraPosition *)cameraPosition
               withDuration:(NSTimeInterval)duration
                   callback:(nullable void (^)(BOOL))callback;

    Swift

    func fly(to cameraPosition: TGCameraPosition, withDuration duration: TimeInterval, callback: ((Bool) -> Void)? = nil)

    Parameters

    cameraPosition

    The new camera position
    duration

    Duration of the animation in seconds
    callback

    A callback to execute when the animation completes

  • Move the map camera to a new position with an animation that pans and zooms in a smooth arc.

    The animation duration is calculated based on the distance to the new camera position and the specified speed

    Declaration

    Objective-C

    - (void)flyToCameraPosition:(nonnull TGCameraPosition *)cameraPosition
                  withSpeed:(CGFloat)speed
                   callback:(nullable void (^)(BOOL))callback;

    Swift

    func fly(to cameraPosition: TGCameraPosition, withSpeed speed: CGFloat, callback: ((Bool) -> Void)? = nil)

    Parameters

    cameraPosition

    The new camera position
    speed

    Specified speed scaling factor
    callback

    A callback to execute when the animation completes

  • Get a camera position that encloses the given bounds with at least the given amount of padding on each side.

    Declaration

    Objective-C

    - (nonnull TGCameraPosition *)cameraThatFitsBounds:(TGCoordinateBounds)bounds
                                       withPadding:(UIEdgeInsets)padding;

    Swift

    func cameraThatFitsBounds(_ bounds: TGCoordinateBounds, withPadding padding: UIEdgeInsets) -> TGCameraPosition

    Parameters

    bounds

    The map bounds to enclose
    padding

    The minimum distance to keep between the bounds and the edges of the view

  • The longitude and latitude of the center of the map view

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CLLocationCoordinate2D position;

    Swift

    var position: CLLocationCoordinate2D { get set }

  • The zoom level of the map view

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat zoom;

    Swift

    var zoom: CGFloat { get set }

  • The orientation of to the map view clockwise from true North

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CLLocationDirection bearing;

    Swift

    var bearing: CLLocationDirection { get set }

  • The tilt angle of the map view in degrees away from straight down

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat pitch;

    Swift

    var pitch: CGFloat { get set }

Coordinate Conversions

  • Convert a longitude and latitude to a view position.

    Declaration

    Objective-C

    - (CGPoint)viewPositionFromCoordinate:(CLLocationCoordinate2D)coordinate;

    Swift

    func viewPosition(from coordinate: CLLocationCoordinate2D) -> CGPoint

    Parameters

    coordinate

    The geographic coordinate to convert

    Return Value

    The view position of the input coordinate

  • Convert a position in view coordinates into the longitude and latitude of the corresponding geographic location.

    Declaration

    Objective-C

    - (CLLocationCoordinate2D)coordinateFromViewPosition:(CGPoint)viewPosition;

    Swift

    func coordinate(fromViewPosition viewPosition: CGPoint) -> CLLocationCoordinate2D

    Parameters

    viewPosition

    the position in view coordinates to convert

    Return Value

    the longitude and latitude

Markers

  • Remove all the Markers from the map.

    Declaration

    Objective-C

    - (void)markerRemoveAll;

    Swift

    func markerRemoveAll()

  • Create a marker and add it to the map.

    Note

    The new Marker will not be usable until you set its styling, geometry, or image depending on your use case.

    Declaration

    Objective-C

    - (nonnull TGMarker *)markerAdd;

    Swift

    func markerAdd() -> TGMarker

    Return Value

    The new Marker.

  • Remove a Marker from the map.

    Note

    Do not use a Marker after removing it from the map.

    Declaration

    Objective-C

    - (void)markerRemove:(nonnull TGMarker *)marker;

    Swift

    func markerRemove(_ marker: TGMarker)

    Parameters

    marker

    The Marker to remove.

  • Access the Markers added to the map.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSArray<TGMarker *> *_Nonnull markers;

    Swift

    var markers: [TGMarker] { get }

File Handling

  • Assign the resource root for this map view.

    Scene file URLs will be resolved relative to this URL.

    Note

    By default the resource root is the main bundle resource URL. Using the default resource root: scene.yaml is resolved to file://<main bundle path>/Resources/scene.yaml, /path/scene.yaml is resolved to file:///path/scene.yaml, and https://my.host/scene.yaml is resolved to itself.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSURL *_Nonnull resourceRoot;

    Swift

    var resourceRoot: URL { get set }

Rendering Behavior

  • Request the view to draw another frame.

    Typically there is no need to call this. The map view re-draws automatically when needed.

    Declaration

    Objective-C

    - (void)requestRender;

    Swift

    func requestRender()

  • The rate you want the map view to re-draw its contents.

    The default value is 60 frames per second.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSInteger preferredFramesPerSecond;

    Swift

    var preferredFramesPerSecond: Int { get set }

  • The CADisplayLink used by the renderer. Exposed mostly for the ability to pause/unpause rendering without having to initiate a scene update, as animations defined within the stylesheet force a continuous rendering regardless of the continuous setting defined in code.

    Note

    This property is manipulated by the rendering subsystem depending on lifecycle events coming from the OS as well as certain events within Tangram itself. As such, do not expect your manipulation of individual settings (such as paused) to be long lived. An example of this is setting displayLink.paused to YES, then backgrounding and foregrounding the app. Tangram will respond to the OS lifecycle events and pause/unpause the map rendering, respectively, thereby overriding your setting. This is intended functionality and will not be changed.

    Note

    This property, even though it is marked NS_ASSUME_NONNULL at the top of the header, will be nil until the view is added to some kind of view hierarchy (window or subview). In a future PR we should clean up this assumption, but until then, you have been warned :)

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) CADisplayLink *_Nonnull displayLink;

    Swift

    var displayLink: CADisplayLink { get }

  • If continuous is YES, the map view will re-draw continuously. Otherwise, the map will re-draw only when an event changes the map view.

    Scenes can be configured as animated (see the animated property documentation for details). When a scene is loaded this property is set to match the animated value from the scene.

    Note

    Changing this property will override the inferred value from the scene. Enabling continuous rendering can significantly increase the energy usage of an application.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL continuous;

    Swift

    var continuous: Bool { get set }

Gesture Recognizers

  • Replaces the tap gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UITapGestureRecognizer *_Nonnull tapGestureRecognizer;

    Swift

    var tapGestureRecognizer: UITapGestureRecognizer { get set }

  • Replaces the double tap gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UITapGestureRecognizer *_Nonnull doubleTapGestureRecognizer;

    Swift

    var doubleTapGestureRecognizer: UITapGestureRecognizer { get set }

  • Replaces the pan gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UIPanGestureRecognizer *_Nonnull panGestureRecognizer;

    Swift

    var panGestureRecognizer: UIPanGestureRecognizer { get set }

  • Replaces the pinch gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UIPinchGestureRecognizer *_Nonnull pinchGestureRecognizer;

    Swift

    var pinchGestureRecognizer: UIPinchGestureRecognizer { get set }

  • Replaces the rotation gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UIRotationGestureRecognizer *_Nonnull rotationGestureRecognizer;

    Swift

    var rotationGestureRecognizer: UIRotationGestureRecognizer { get set }

  • Replaces the shove gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UIPanGestureRecognizer *_Nonnull shoveGestureRecognizer;

    Swift

    var shoveGestureRecognizer: UIPanGestureRecognizer { get set }

  • Replaces the long press gesture recognizer used by the map view and adds it to the UIView.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    UILongPressGestureRecognizer *_Nonnull longPressGestureRecognizer;

    Swift

    var longPressGestureRecognizer: UILongPressGestureRecognizer { get set }

Map region change state notifiers

  • Client can use these to trigger explicit TGMapRegionChangeState changes Notifies that client is going to begin map region animation

    Declaration

    Objective-C

    - (void)notifyGestureDidBegin;

    Swift

    func notifyGestureDidBegin()

  • Client can use these to trigger explicit TGMapRegionChangeState changes Notifies that client is animating map region

    Declaration

    Objective-C

    - (void)notifyGestureIsChanging;

    Swift

    func notifyGestureIsChanging()

  • Client can use these to trigger explicit TGMapRegionChangeState changes Notifies that client is stopping animating map region

    Declaration

    Objective-C

    - (void)notifyGestureDidEnd;

    Swift

    func notifyGestureDidEnd()

Data Layers

  • Adds a named data layer to the map.

    Note

    You cannot create more than one data source with the same name. If you call this with a name that is already in use, the previously returned object will be returned again.

    Declaration

    Objective-C

    - (nullable TGMapData *)addDataLayer:(nonnull NSString *)name
                    generateCentroid:(BOOL)generateCentroid;

    Swift

    func addDataLayer(_ name: String, generateCentroid: Bool) -> TGMapData?

    Parameters

    name

    The name of the data layer.
    generateCentroid

    If YES, a point feature will be added at the centroid of every polygon feature. This can be useful for labeling.

    Return Value

    The map data, or nil if the data source can’t be initialized.

Screenshots

  • Capture a screenshot of the map view.

    The captured screenshot will be delivered to the mapViewDelegate by the mapView:didCaptureScreenshot: method. The delegate must implement this method to receive the screenshot.

    Declaration

    Objective-C

    - (void)captureScreenshot:(BOOL)waitForViewComplete;

    Swift

    func captureScreenshot(_ waitForViewComplete: Bool)

    Parameters

    waitForViewComplete

    If YES, the view will wait for all parts of the map in the current view to finish loading before taking the screenshot.

Picking Map Objects

  • Set the radius in logical pixels to use when picking features on the map (default is 0.5).

    The -pick* methods will retrieve all interactive map objects from a circular area with this radius around the pick location. Setting a larger radius can help ensure that desired features are retrieved from an imprecise touch input.

    Declaration

    Objective-C

    - (void)setPickRadius:(CGFloat)pixels;

    Swift

    func setPickRadius(_ pixels: CGFloat)

    Parameters

    pixels

    The pick radius in logical pixels.

  • Select a visible feature marked as interactive from the map view.

    The pick result will be delivered to the mapViewDelegate by mapView:didSelectFeature:atScreenPosition:.

    The scene file determines which features can be picked. See the interactive property documentation for details.

    Declaration

    Objective-C

    - (void)pickFeatureAt:(CGPoint)viewPosition;

    Swift

    func pickFeature(at viewPosition: CGPoint)

    Parameters

    viewPosition

    The position in the view to pick from, in logical pixels.

  • Select a label marked as interactive from the map view.

    The pick result will be delivered to the mapViewDelegate by mapView:didSelectFeature:atScreenPosition:.

    The scene file determines which features can be picked. See the interactive property documentation for details.

    Declaration

    Objective-C

    - (void)pickLabelAt:(CGPoint)viewPosition;

    Swift

    func pickLabel(at viewPosition: CGPoint)

    Parameters

    viewPosition

    The position in the view to pick from, in logical pixels.

  • Select a Marker marked as interactive from the map view.

    The pick result will be delivered to the mapViewDelegate by mapView:didSelectFeature:atScreenPosition:.

    To pick a marker you must set the interactive property when styling it:

    TGMarker marker;
marker.styling = "{ style: 'points', interactive : true,  color: 'white', size: [30px, 30px], order: 500 }"

    Declaration

    Objective-C

    - (void)pickMarkerAt:(CGPoint)viewPosition;

    Swift

    func pickMarker(at viewPosition: CGPoint)

    Parameters

    viewPosition

    The position in the view to pick from, in logical pixels.

Memory Management

  • Reduce memory usage by freeing currently unused resources.

    Declaration

    Objective-C

    - (void)didReceiveMemoryWarning;

    Swift

    func didReceiveMemoryWarning()

Debugging

  • Set a TGDebugFlag on the map view.

    Declaration

    Objective-C

    - (void)setDebugFlag:(TGDebugFlag)debugFlag value:(BOOL)on;

    Swift

    func setDebugFlag(_ debugFlag: TGDebugFlag, value on: Bool)

    Parameters

    debugFlag

    The debug flag to set.
    on

    Whether the flag is on or off.

  • Get the status of a TGDebugFlag.

    Declaration

    Objective-C

    - (BOOL)getDebugFlag:(TGDebugFlag)debugFlag;

    Swift

    func getDebugFlag(_ debugFlag: TGDebugFlag) -> Bool

    Parameters

    debugFlag

    The debug flag to get the status of.

    Return Value

    Whether the flag is currently on or off for the map view.

  • Invert the state of a TGDebugFlag.

    Declaration

    Objective-C

    - (void)toggleDebugFlag:(TGDebugFlag)debugFlag;

    Swift

    func toggle(_ debugFlag: TGDebugFlag)

    Parameters

    debugFlag

    The debug flag to toggle the state of.