MapsGL iOS - Map Controller

A map controller provides the interface between your map view, which is created using a third-party mapping library such as Mapbox or MapLibre, and the functionality available within the MapsGL SDK. Therefore, you will be working with a map controller instance most of the time when managing data sources and layers or controlling the animation timeline.

To start working with your map, you’ll need to create a map controller instance that corresponds to the mapping library you’re using. Refer to the list of supported third-party mapping library that MapsGL currently integrates with to determine which map controller you need to instantiate as it is based on your chosen mapping library.

The following examples demonstrate a Mapbox-based setup. If you are using MapLibre, create your controller with MapLibreMapController from MapsGLMapLibre instead.

SwiftUI


import SwiftUI
import MapboxMaps
import MapsGLMaps
import MapsGLMapbox // Needed only if you are using SPM
//import MapsGL // Needed only if you are using CocoaPods
import Combine
 
let xweatherClientID = "FILL_IN_WITH_YOUR_CLIENT_ID"
let xweatherClientSecret = "FILL_IN_WITH_YOUR_CLIENT_SECRET"
let mapboxAccessToken = "FILL_IN_WITH_YOUR_MAPBOX_PUBLIC_ACCESS_TOKEN"
 
struct MyMapView : View {
	class Coordinator {
		/// MapsGL's controller that manages adding/removing MapsGL weather layers to/from the `MapboxMaps.MapView`.
		var mapController: MapboxMapController!
		
		/// Holds Combine subscriptions to MapsGL events and other Combine subscriptions.
		var cancellables: Set<AnyCancellable> = []
	}
	private let coordinator = Coordinator()
	
	var body: some View {
		MapReader { proxy in
			Map(initialViewport: .camera(
					center: CLLocationCoordinate2D(latitude: 50.0, longitude: 10.0),
					zoom: 2.5
			))
			.mapStyle(.dark)
			.ignoresSafeArea()
			.onAppear {
				guard let map = proxy.map else { return }
				
				try! map.setProjection(.init(name: .mercator)) // Set 2D map projection
				
				// Set up the MapsGL `MapboxMapController`, which will handle
				// 	adding/removing MapsGL weather layers to the `MapboxMaps.MapView`.
				let mapController = MapboxMapController(
					map: map,
					window: UIWindow?.none,
					account: XweatherAccount(id: xweatherClientID, secret: xweatherClientSecret)
				)
				coordinator.mapController = mapController
				
				// Once the map has completed initial load…
				mapController.subscribe(to: MapEvents.Load.self) { _ in
					// Add the wind particles layer.
					do {
						var layerConfig = WeatherService.WindParticles(service: mapController.service)
						layerConfig.layer.paint.particle.density = .extreme
						try mapController.addWeatherLayer(config: layerConfig)
					} catch {
						NSLog("Failed to add weather layer: \(error)")
					}
				}.store(in: &coordinator.cancellables)
			}
		}
	}
	
	private static let _staticInit: Void = {
		MapboxOptions.accessToken = mapboxAccessToken
	}()
	private let _staticInit: Void = Self._staticInit
}
 
#Preview {
	MyMapView()
}

A full example of how to set up MapsGL with Mapbox with SwiftUI can be found in the mapsgl-apple-sdk repository’s Demo directory , particularly in this content view .

UIKit


import UIKit
import MapboxMaps
import MapsGLMaps
import MapsGLMapbox // Needed only if you are using SPM
//import MapsGL // Needed only if you are using CocoaPods
import Combine
 
let xweatherClientID = "FILL_IN_WITH_YOUR_CLIENT_ID"
let xweatherClientSecret = "FILL_IN_WITH_YOUR_CLIENT_SECRET"
let mapboxAccessToken = "FILL_IN_WITH_YOUR_MAPBOX_PUBLIC_ACCESS_TOKEN"
 
class MyMapViewController : UIViewController {
	@IBOutlet private var mapView: MapboxMaps.MapView!
	
	/// MapsGL's controller that manages adding/removing MapsGL weather layers to/from the `MapboxMaps.MapView`.
	private var controller: MapboxMapController!
	
	/// Holds Combine subscriptions to MapsGL events and other Combine subscriptions.
	private var cancellables: Set<AnyCancellable> = []
	
	override func viewDidLoad() {
		super.viewDidLoad()
		
		// Create a `MapboxMaps.MapView`
		mapView = MapboxMaps.MapView(frame: view.bounds)
		mapView.mapboxMap.styleURI = .dark
		try! mapView.mapboxMap.setProjection(.init(name: .mercator)) // Set 2D map projection
		mapView.mapboxMap.setCamera(to: .init(center: CLLocationCoordinate2D(latitude: 50.0, longitude: 10.0), zoom: 2.5))
		mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
		view.addSubview(mapView)
		
		// Set up the MapsGL `MapboxMapController`, which will handle adding and removing MapsGL layers to the `MapboxMaps.MapView`.
		let xweatherAccount = XweatherAccount(id: xweatherClientID, secret: xweatherClientSecret)
		controller = MapboxMapController(map: mapView, account: xweatherAccount)
		
		// Once the map has completed initial load…
		controller.onLoad.observe { _ in
			// Add the wind particles layer.
			do {
				var layerConfig = WeatherService.WindParticles(service: controller.service)
				layerConfig.layer.paint.particle.density = .extreme
				try controller.addWeatherLayer(config: layerConfig)
			} catch {
				NSLog("Failed to add weather layer: \(error)")
			}
		}.store(in: &cancellables)
	}
	
	private static let _staticInit: Void = {
		MapboxOptions.accessToken = mapboxAccessToken
	}()
	private let _staticInit: Void = MyMapViewController._staticInit
}

A full example of how to set up MapsGL with Mapbox with UIKit can be found in the mapsgl-apple-sdk repository’s Demo directory , particularly in this view controller .

Managing Map Data

With a map controller created, you can start adding data to your map. To do so, you can quickly add our pre-configured weather layers to your map without needing to create the data sources and layers directly. Review our guide on using weather layers for more information.

Alternatively, for custom datasets you’ll need to set up the appropriate data sources, layers and render styles for your data and visualization requirements. You’ll first want to start by adding data sources to your map, so review the data sources guide next for more information.

Map Controls

You can include additional controls to your map controller, such as a legend or real-time data inspector. These controls provide additional functionality related to the map and/or active data layers on the map.

Legend Control

A legend control is responsible for managing the collection of legends currently visible within the context of an interface or map and provides the interface needed for adding and removing legends.

Legend control with multiple layers

To add a legend control to your map controller, just call add(legendControl:) and place the control’s view in the app’s view hierarchy:


let control = LegendControl()
controller.add(legendControl: control)

Properties of the legend control can be modified before or after the control has been added to the MapController. See the Legend Control documentation for more information about the supported options.

You can also remove the legend control from your map after it’s been added:


controller.removeLegendControl();

Refer to the legend control documentation for more information on configuring and using the control.

Data Inspector Control

A data inspector control allows you to view the underlying data for each visible map layer that supports feature queries. It can be configured to function in one of two types of modes: only display when the map is clicked, or real-time streaming data as the user pans over the map.

Data inspector control with multiple layers

To add a data inspector control to your map controller, just call addDataInspectorControl() and provide the host view to insert the control’s callout view into. The control instance will be returned when calling this method:


let control = controller.addDataInspectorControl(constrainedTo: mapView)

You can also remove the data inspector control from your map after it’s been added:


controller.removeDataInspectorControl()

Refer to the data inspector control documentation for more information on configuring and using the control.