MapboxMap

 
public final class MapboxMap : MapboxMapProtocol
extension MapboxMap: MapEventsObservable

Undocumented

  • The style object supports run time styling.

    Declaration

    Swift

    public internal(set) var style: Style { get }

Style loading

  • Loads a style from a StyleURI, calling a completion closure when the style is fully loaded or there has been an error during load.

    Declaration

    Swift

    public func loadStyleURI(_ styleURI: StyleURI, completion: ((Result<Style, Error>) -> Void)? = nil)

    Parameters

    styleURI

    StyleURI to load
    completion

    Closure called when the style has been fully loaded. The Result type encapsulates the Style or error that occurred. See MapLoadingError

  • Loads a style from a JSON string, calling a completion closure when the style is fully loaded or there has been an error during load.

    Declaration

    Swift

    public func loadStyleJSON(_ JSON: String, completion: ((Result<Style, Error>) -> Void)? = nil)

    Parameters

    styleURI

    Style JSON string
    completion

    Closure called when the style has been fully loaded. The Result type encapsulates the Style or error that occurred. See MapLoadingError

Prefetching

  • When loading a map, if prefetchZoomDelta is set to any number greater than 0, the map will first request a tile for zoom - prefetchZoomDelta in an attempt to display a full map at lower resolution as quick as possible.

    It will get clamped at the tile source minimum zoom. The default delta is 4.

    Declaration

    Swift

    public var prefetchZoomDelta: UInt8 { get set }

  • Gets the resource options for the map.

    All optional fields of the returned object are initialized with the actual values.

    Note

    The result of this property is different from the ResourceOptions that were provided to the map’s initializer.

    Declaration

    Swift

    public var resourceOptions: ResourceOptions { get }

  • Clears temporary map data.

    Clears temporary map data from the data path defined in the given resource options. Useful to reduce the disk usage or in case the disk cache contains invalid data.

    Note

    Calling this API will affect all maps that use the same data path and does not affect persistent map data like offline style packages.

    Declaration

    Swift

    public static func clearData(for resourceOptions: ResourceOptions, completion: @escaping (Error?) -> Void)

    Parameters

    resourceOptions

    The resource options that contain the map data path to be used
    completion

    Called once the request is complete

  • Gets elevation for the given coordinate.

    Note

    Elevation is only available for the visible region on the screen.

    Declaration

    Swift

    public func elevation(at coordinate: CLLocationCoordinate2D) -> Double?

    Parameters

    coordinate

    Coordinate for which to return the elevation.

    Return Value

    Elevation (in meters) multiplied by current terrain exaggeration, or empty if elevation for the coordinate is not available.

Camera Fitting

  • Transforms a view’s frame into a set of coordinate bounds

    Declaration

    Swift

    public func coordinateBounds(for rect: CGRect) -> CoordinateBounds

    Parameters

    rect

    The rect whose bounds will be transformed into a set of map coordinate bounds.

    Return Value

    A CoordinateBounds object that represents the southwest and northeast corners of the view’s bounds.

  • Transforms a set of map coordinate bounds to a CGRect relative to the MapView.

    Declaration

    Swift

    public func rect(for coordinateBounds: CoordinateBounds) -> CGRect

    Parameters

    coordinateBounds

    The coordinateBounds that will be converted into a rect relative to the MapView

    Return Value

    A CGRect whose corners represent the vertices of a set of CoordinateBounds.

Debug options

  • The array of MapDebugOptions. Setting this property to an empty array disables previously enabled MapDebugOptions. The default value is an empty array.

    Declaration

    Swift

    public var debugOptions: [MapDebugOptions] { get set }

  • Returns the map’s options

    Declaration

    Swift

    public var options: MapOptions { get }

  • Calculates a CameraOptions to fit a CoordinateBounds

    Declaration

    Swift

    public func camera(for coordinateBounds: CoordinateBounds,
                   padding: UIEdgeInsets,
                   bearing: Double?,
                   pitch: Double?) -> CameraOptions

    Parameters

    coordinateBounds

    The coordinate bounds that will be displayed within the viewport.
    padding

    The new padding to be used by the camera.
    bearing

    The new bearing to be used by the camera.
    pitch

    The new pitch to be used by the camera.

    Return Value

    A CameraOptions that fits the provided constraints

  • Calculates a CameraOptions to fit a list of coordinates.

    Declaration

    Swift

    public func camera(for coordinates: [CLLocationCoordinate2D],
                   padding: UIEdgeInsets,
                   bearing: Double?,
                   pitch: Double?) -> CameraOptions

    Parameters

    coordinates

    Array of coordinates that should fit within the new viewport.
    padding

    The new padding to be used by the camera.
    bearing

    The new bearing to be used by the camera.
    pitch

    The new pitch to be used by the camera.

    Return Value

    A CameraOptions that fits the provided constraints

  • Calculates a CameraOptions to fit a list of coordinates into a sub-rect of the map.

    Adjusts the zoom of camera to fit coordinates into rect.

    Returns the provided camera with zoom adjusted to fit coordinates into rect, so that the coordinates on the left, top and right of the effective camera center at the principal point of the projection (defined by padding) fit into the rect.

    Note

    This method may fail if the principal point of the projection is not inside rect or if there is insufficient screen space, defined by principal point and rect, to fit the geometry.

    Declaration

    Swift

    public func camera(for coordinates: [CLLocationCoordinate2D],
                   camera: CameraOptions,
                   rect: CGRect) -> CameraOptions

    Parameters

    coordinates

    The coordinates to frame within rect.
    camera

    The camera for which the zoom should be adjusted to fit coordinates. camera.center must be non-nil.
    rect

    The rectangle inside of the map that should be used to frame coordinates.

    Return Value

    A CameraOptions that fits the provided constraints, or cameraOptions if an error occurs.

  • Calculates a CameraOptions to fit a geometry

    Declaration

    Swift

    public func camera(for geometry: Geometry,
                   padding: UIEdgeInsets,
                   bearing: CGFloat?,
                   pitch: CGFloat?) -> CameraOptions

    Parameters

    geometry

    The geoemtry that will be displayed within the viewport.
    padding

    The new padding to be used by the camera.
    bearing

    The new bearing to be used by the camera.
    pitch

    The new pitch to be used by the camera.

    Return Value

    A CameraOptions that fits the provided constraints

CameraOptions to CoordinateBounds

  • Returns the coordinate bounds corresponding to a given CameraOptions

    Declaration

    Swift

    public func coordinateBounds(for camera: CameraOptions) -> CoordinateBounds

    Parameters

    camera

    The camera for which the coordinate bounds will be returned.

    Return Value

    CoordinateBounds for the given CameraOptions

  • Returns the coordinate bounds and zoom for a given CameraOptions.

    Declaration

    Swift

    public func coordinateBoundsZoom(for camera: CameraOptions) -> CoordinateBoundsZoom

    Parameters

    camera

    The camera for which the CoordinateBoundsZoom will be returned.

    Return Value

    CoordinateBoundsZoom for the given CameraOptions

  • Returns the unwrapped coordinate bounds and zoom for a given CameraOptions.

    This function is particularly useful, if the camera shows the antimeridian.

    Declaration

    Swift

    public func coordinateBoundsZoomUnwrapped(for camera: CameraOptions) -> CoordinateBoundsZoom

    Parameters

    camera

    The camera for which the CoordinateBoundsZoom will be returned.

    Return Value

    CoordinateBoundsZoom for the given CameraOptions

Screen coordinate conversion

  • Converts a point in the mapView’s coordinate system to a geographic coordinate. The point must exist in the coordinate space of the MapView

    Declaration

    Swift

    public func coordinate(for point: CGPoint) -> CLLocationCoordinate2D

    Parameters

    point

    The point to convert. Must exist in the coordinate space of the MapView

    Return Value

    A CLLocationCoordinate that represents the geographic location of the point.

  • Converts a map coordinate to a CGPoint, relative to the MapView.

    Declaration

    Swift

    public func point(for coordinate: CLLocationCoordinate2D) -> CGPoint

    Parameters

    coordinate

    The coordinate to convert.

    Return Value

    A CGPoint relative to the UIView.

  • Converts map coordinates to an array of CGPoint, relative to the MapView.

    Declaration

    Swift

    public func points(for coordinates: [CLLocationCoordinate2D]) -> [CGPoint]

    Parameters

    coordinates

    The coordinate to convert.

    Return Value

    An array of CGPoint relative to the UIView.

  • Converts points in the mapView’s coordinate system to geographic coordinates. The points must exist in the coordinate space of the MapView.

    Declaration

    Swift

    public func coordinates(for points: [CGPoint]) -> [CLLocationCoordinate2D]

    Parameters

    point

    The point to convert. Must exist in the coordinate space of the MapView

    Return Value

    A CLLocationCoordinate that represents the geographic location of the point.

Camera options setters/getters

  • Changes the map view by any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not passed via the camera options argument. It is not guaranteed that the provided CameraOptions will be set, the map may apply constraints resulting in a different CameraState.

    Important

    This method does not cancel existing animations. Call CameraAnimationsManager.cancelAnimations()to cancel existing animations.

    Declaration

    Swift

    public func setCamera(to cameraOptions: CameraOptions)

    Parameters

    cameraOptions

    New camera options

  • Returns the current camera state

    Declaration

    Swift

    public var cameraState: CameraState { get }

  • Sets/get the map view with the free camera options.

    FreeCameraOptions provides more direct access to the underlying camera entity. For backwards compatibility the state set using this API must be representable with CameraOptions as well. Parameters are clamped to a valid range or discarded as invalid if the conversion to the pitch and bearing presentation is ambiguous. For example orientation can be invalid if it leads to the camera being upside down or the quaternion has zero length.

    Declaration

    Swift

    public var freeCameraOptions: FreeCameraOptions { get set }

    Parameters

    freeCameraOptions

    The free camera options to set.

  • Returns the bounds of the map.

    Declaration

    Swift

    public var cameraBounds: CameraBounds { get }

  • Sets the bounds of the map.

    Throws

    MapError

    Declaration

    Swift

    public func setCameraBounds(with options: CameraBoundsOptions) throws

    Parameters

    options

    New camera bounds. Nil values will not take effect.

Drag API

  • Prepares the drag gesture to use the provided screen coordinate as a pivot point. This function should be called each time when user starts a dragging action (e.g. by clicking on the map). The following dragging will be relative to the pivot.

    Declaration

    Swift

    public func dragStart(for point: CGPoint)

    Parameters

    point

    Screen point

  • Calculates target point where camera should move after drag. The method should be called after dragStart and before dragEnd.

    Declaration

    Swift

    public func dragCameraOptions(from: CGPoint, to: CGPoint) -> CameraOptions

    Parameters

    fromPoint

    The point from which the map is dragged.
    toPoint

    The point to which the map is dragged.

    Return Value

    The camera options object showing end point.

  • Ends the ongoing drag gesture. This function should be called always after the user has ended a drag gesture initiated by dragStart.

    Declaration

    Swift

    public func dragEnd()

Gesture and Animation Flags

  • If implementing a custom animation mechanism, call this method when the animation begins. Must always be paired with a corresponding call to endAnimation()

    Declaration

    Swift

    public func beginAnimation()

  • If implementing a custom animation mechanism, call this method when the animation ends. Must always be paired with a corresponding call to beginAnimation()

    Declaration

    Swift

    public func endAnimation()

  • If implementing a custom gesture, call this method when the gesture begins. Must always be paired with a corresponding call to endGesture()

    Declaration

    Swift

    public func beginGesture()

  • If implementing a custom gesture, call this method when the gesture ends. Must always be paired with a corresponding call to beginGesture()

    Declaration

    Swift

    public func endGesture()

MapFeatureQueryable

  • Queries the map for rendered features.

    Declaration

    Swift

    public func queryRenderedFeatures(for shape: [CGPoint], options: RenderedQueryOptions? = nil, completion: @escaping (Result<[QueriedFeature], Error>) -> Void)

    Parameters

    shape

    Screen point coordinates (point, line string or box) to query for rendered features.
    options

    Options for querying rendered features.
    completion

    Callback called when the query completes

  • Queries the map for rendered features.

    Declaration

    Swift

    public func queryRenderedFeatures(in rect: CGRect, options: RenderedQueryOptions? = nil, completion: @escaping (Result<[QueriedFeature], Error>) -> Void)

    Parameters

    rect

    Screen rect to query for rendered features.
    options

    Options for querying rendered features.
    completion

    Callback called when the query completes

  • Queries the map for rendered features.

    Declaration

    Swift

    public func queryRenderedFeatures(at point: CGPoint, options: RenderedQueryOptions? = nil, completion: @escaping (Result<[QueriedFeature], Error>) -> Void)

    Parameters

    point

    Screen point at which to query for rendered features.
    options

    Options for querying rendered features.
    completion

    Callback called when the query completes

  • Queries the map for source features.

    Declaration

    Swift

    public func querySourceFeatures(for sourceId: String,
                                options: SourceQueryOptions,
                                completion: @escaping (Result<[QueriedFeature], Error>) -> Void)

    Parameters

    sourceId

    Style source identifier used to query for source features.
    options

    Options for querying source features.
    completion

    Callback called when the query completes

  • Queries for feature extension values in a GeoJSON source.

      1. `children`: returns the children of a cluster (on the next zoom
    level).
  2. `leaves`: returns all the leaves of a cluster (given its cluster_id)
  3. `expansion-zoom`: returns the zoom on which the cluster expands
    into several children (useful for "click to zoom" feature).
    • args: Used for further query specification when using ‘leaves’ extensionField. Now only support following two args:
      1. `limit`: the number of points to return from the query (must
        use type 'UInt64', set to maximum for all points)
  2. `offset`: the amount of points to skip (for pagination, must
        use type 'UInt64')
    • completion: The result could be a feature extension value containing either a value (expansion-zoom) or a feature collection (children or leaves). An error is passed if the operation was not successful.

    Declaration

    Swift

    public func queryFeatureExtension(for sourceId: String,
                                  feature: Feature,
                                  extension: String,
                                  extensionField: String,
                                  args: [String: Any]? = nil,
                                  completion: @escaping (Result<FeatureExtensionValue, Error>) -> Void)

    Parameters

    sourceId

    The identifier of the source to query.
    feature

    Feature to look for in the query.
    extension

    Currently supports keyword supercluster.
    extensionField

    Currently supports following three extensions:
    args

    Used for further query specification when using ‘leaves’ extensionField. Now only support following two args:
    completion

    The result could be a feature extension value containing either a value (expansion-zoom) or a feature collection (children or leaves). An error is passed if the operation was not successful.

ObservableProtocol

  • Subscribes an observer to a list of events.

    MapboxMap holds a strong reference to observer while it is subscribed. To stop receiving notifications, pass the same observer to unsubscribe(_:events:).

    Note

    Prefer onNext(eventTypes:handler:), onNext(_:handler:), and onEvery(_:handler:) to using this lower-level APIs

    Declaration

    Swift

    public func subscribe(_ observer: Observer, events: [String])

    Parameters

    observer

    An object that will receive events of the types specified by events
    events

    Array of event types to deliver to observer

  • Unsubscribes an observer from a provided list of event types.

    MapboxMap holds a strong reference to observer while it is subscribed. To stop receiving notifications, pass the same observer to this method as was passed to subscribe(_:events:).

    Declaration

    Swift

    public func unsubscribe(_ observer: Observer, events: [String] = [])

    Parameters

    observer

    The object to unsubscribe
    events

    Array of event types to unsubscribe from. Pass an empty array (the default) to unsubscribe from all events.

Map Event handling

Map data clearing

  • Clears temporary map data.

    Clears temporary map data from the data path defined in the given resource options. Useful to reduce the disk usage or in case the disk cache contains invalid data.

    Note

    Calling this API will affect all maps that use the same data path and does not affect persistent map data like offline style packages.

    Declaration

    Swift

    public func clearData(completion: @escaping (Error?) -> Void)

    Parameters

    completion

    Called once the request is complete

Feature State

  • Update the state map of a feature within a style source. Update entries in the state map of a given feature within a style source. Only entries listed in the state map will be updated. An entry in the feature state map that is not listed in state will retain its previous value.

    Declaration

    Swift

    public func setFeatureState(sourceId: String, sourceLayerId: String? = nil, featureId: String, state: [String : Any])

    Parameters

    sourceId

    Style source identifier
    sourceLayerId

    Style source layer identifier (for multi-layer sources such as vector sources). Defaults to nil.
    featureId

    Identifier of the feature whose state should be updated
    state

    Map of entries to update with their respective new values

  • Get the state map of a feature within a style source.

    Declaration

    Swift

    public func getFeatureState(sourceId: String, sourceLayerId: String? = nil, featureId: String, callback: @escaping (Result<[String : Any], Error>) -> Void)

    Parameters

    sourceId

    Style source identifier.
    sourceLayerId

    Style source layer identifier (for multi-layer sources such as vector sources).
    featureId

    Identifier of the feature whose state should be queried.
    callback

    Feature’s state map or an empty map if the feature could not be found.

  • Removes entries from a feature state object. Remove a specified property or all property from a feature’s state object, depending on the value of stateKey.

    Declaration

    Swift

    public func removeFeatureState(sourceId: String, sourceLayerId: String? = nil, featureId: String, stateKey: String? = nil)

    Parameters

    sourceId

    The style source identifier
    sourceLayerId

    The style source layer identifier (for multi-layer sources such as vector sources). Defaults to nil.
    featureId

    The feature identifier of the feature whose state should be removed.
    stateKey

    The key of the property to remove. If nil, all feature’s state object properties are removed. Defaults to nil.

MapProjection