Get Started - iOS

# Latest release
binary "https://trimblemaps.jfrog.io/artifactory/carthage/TrimbleMaps.json" == 2.0.0
binary "https://trimblemaps.jfrog.io/artifactory/carthage/TrimbleMapsMobileEvents.json" == 1.0.0
binary "https://trimblemaps.jfrog.io/artifactory/carthage/TrimbleMapsAccounts.json" == 2.0.0

carthage bootstrap --platform iOS --use-xcframeworks

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your precise location is used to show your location on the map.</string>

<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>map</key>
  <string>Please enable precise location to show your location on the map.</string>
</dict>

import Foundation
import UIKit
import Flutter
import TrimbleMaps
import TrimbleMapsAccounts

/**
 * A PlatformView that wraps the Trimble Map SDK's TMGLMapView and
 * exposes zoom, style, and center controls via a MethodChannel.
 * It also handles TMGLMapView lifecycle events.
 */
class TrimbleMapView: NSObject, FlutterPlatformView, AccountManagerDelegate {
    private var frame: CGRect
    private let viewId: Int64                    // Unique identifier for this map view instance
    private let apiKey: String                   // API key for Trimble Maps services
    private let region: Region                   // Region for Trimble Maps services
    private var containerView: UIView            // Container view returned to Flutter
    private var mapView: TMGLMapView?            // The core native Trimble MapView instance
    private var channel: FlutterMethodChannel?   // MethodChannel for communication between Flutter and this native view
    private var isMapReady: Bool = false         // Flag to track if map is ready

    init(
        frame: CGRect,
        viewIdentifier viewId: Int64,
        arguments args: Any?,
        binaryMessenger messenger: FlutterBinaryMessenger?
    ) {
        self.viewId = viewId
        self.frame = frame

        // Create container view that will hold the map
        self.containerView = UIView(frame: frame)
        self.containerView.backgroundColor = .systemBackground

        // Extract the API key and region from arguments
        if let argsDict = args as? [String: Any],
           let apiKey = argsDict["apiKey"] as? String {
            self.apiKey = apiKey
        } else {
            self.apiKey = ""
            print("TrimbleMapView: Warning - No API key provided")
        }

        // Parse region from arguments, default to worldwide
        if let argsDict = args as? [String: Any],
           let regionString = argsDict["region"] as? String {
            switch regionString.lowercased() {
            case "northamerica":
                self.region = .northAmerica
            case "europe":
                self.region = .europe
            default:
                self.region = .worldwide
            }
        } else {
            self.region = .worldwide
        }

        super.init()

        print("TrimbleMapView: Initializing for viewId=\(viewId)")

        // Initialize the MethodChannel
        // The channel name includes the viewId to ensure uniqueness if multiple maps are shown.
        if let messenger = messenger {
            self.channel = FlutterMethodChannel(
                name: "trimble_map_view_\(viewId)",
                binaryMessenger: messenger
            )

            // Set up Method Call Handler
            // This listener waits for method calls invoked from the Flutter side using the channel.
            self.channel?.setMethodCallHandler { [weak self] (call: FlutterMethodCall, result: @escaping FlutterResult) in
                self?.handleMethodCall(call: call, result: result)
            }
        }

        // Check if account is already loaded and licensed
        if AccountManager.default.state == .loaded &&
           AccountManager.default.isLicensed(licensedFeature: .mapsSdk) {
            print("TrimbleMapView: Account already loaded, initializing map immediately")
            initializeMapView()
        } else {
            // Initialize Trimble Maps Account (Authentication)
            // Only set account if not already loaded
            let account = Account(apiKey: self.apiKey, region: self.region)
            AccountManager.default.account = account
            AccountManager.default.delegate = self
        }
    }

    // MARK: - Map Initialization

    /// Creates and adds the TMGLMapView to the container view
    private func initializeMapView() {
        guard mapView == nil else { return } // Prevent duplicate initialization

        // Create the TMGLMapView UI component
        let map = TMGLMapView(frame: containerView.bounds)
        map.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        map.styleURL = TMGLStyle.mobileDayStyleURL

        containerView.addSubview(map)
        self.mapView = map
        self.isMapReady = true

        // Notify Flutter that the map is ready to be interacted with
        self.channel?.invokeMethod("mapReady", arguments: nil)
        print("TrimbleMapView: Map initialized and 'mapReady' notification sent to Flutter")
    }

    // MARK: - AccountManagerDelegate

    func stateChanged(newStatus: AccountManagerState) {
        if newStatus == .loaded {
            if AccountManager.default.isLicensed(licensedFeature: .mapsSdk) {
                DispatchQueue.main.async { [weak self] in
                    guard let self = self else { return }
                    print("TrimbleMapView: Account loaded, initializing map")
                    self.initializeMapView()
                }
            } else {
                print("TrimbleMapView: Account is not licensed for Maps SDK")
            }
        }
    }

    // MARK: - Method Call Handling

    private func handleMethodCall(call: FlutterMethodCall, result: @escaping FlutterResult) {
        print("TrimbleMapView: Received method call from Flutter: \(call.method)")

        guard let mapView = self.mapView else {
            result(FlutterError(code: "MAP_NOT_READY", message: "Map view is not initialized", details: nil))
            return
        }

        switch call.method {
        case "zoomIn":
            // Get current zoom level and increase it
            let currentZoom = mapView.zoomLevel
            mapView.setZoomLevel(currentZoom + 1, animated: true)
            result(nil)
            print("TrimbleMapView: zoomIn executed")

        case "zoomOut":
            // Get current zoom level and decrease it
            let currentZoom = mapView.zoomLevel
            mapView.setZoomLevel(currentZoom - 1, animated: true)
            result(nil)
            print("TrimbleMapView: zoomOut executed")

        case "toggleStyle":
            // Check the current style and switch to the other
            let currentStyle = mapView.styleURL
            let newStyle: URL
            if currentStyle == TMGLStyle.mobileDayStyleURL {
                newStyle = TMGLStyle.mobileNightStyleURL
            } else {
                newStyle = TMGLStyle.mobileDayStyleURL
            }
            mapView.styleURL = newStyle
            print("TrimbleMapView: toggleStyle executed, set to: \(newStyle)")
            result(nil)

        case "center":
            // Extract arguments sent from Flutter
            guard let args = call.arguments as? [String: Any],
                  let lat = args["lat"] as? Double,
                  let lng = args["lng"] as? Double else {
                result(FlutterError(code: "INVALID_ARGUMENT", message: "lat and lng must be provided", details: nil))
                return
            }

            print("TrimbleMapView: center executing for Lat: \(lat), Lng: \(lng)")

            // Create a coordinate and center the map on it
            let coordinate = CLLocationCoordinate2D(latitude: lat, longitude: lng)
            mapView.setCenter(coordinate, zoomLevel: 8.0, animated: true)
            result(nil)

        default:
            print("TrimbleMapView: Method not implemented: \(call.method)")
            result(FlutterMethodNotImplemented)
        }
    }

    // MARK: - FlutterPlatformView Implementation

    /**
     * Returns the container UIView that Flutter will embed.
     * The TMGLMapView is added to this container once the account is licensed.
     */
    func view() -> UIView {
        return containerView
    }

    // MARK: - Cleanup

    deinit {
        print("TrimbleMapView: Cleaning up MethodChannel and MapView")
        // Remove the method call handler to break the communication link.
        channel?.setMethodCallHandler(nil)
        // Note: TMGLMapView cleanup is handled automatically by iOS
    }
}

import Foundation
import Flutter

/**
 * Factory responsible for creating instances of TrimbleMapView.
 * Extends FlutterPlatformViewFactory to integrate with Flutter's
 * platform view mechanism using StandardMessageCodec.
 */
class TrimbleMapViewFactory: NSObject, FlutterPlatformViewFactory {
    private var messenger: FlutterBinaryMessenger

    init(messenger: FlutterBinaryMessenger) {
        self.messenger = messenger
        super.init()
    }

    /**
     * Called by Flutter when a new platform view is needed.
     * @param frame The frame for the view
     * @param viewId Unique identifier for this view instance
     * @param args Initialization parameters passed from Dart
     * @return A new instance of TrimbleMapView
     */
    func create(
        withFrame frame: CGRect,
        viewIdentifier viewId: Int64,
        arguments args: Any?
    ) -> FlutterPlatformView {
        // Create and return the native TrimbleMapView with provided frame, view ID, arguments, and messenger
        return TrimbleMapView(
            frame: frame,
            viewIdentifier: viewId,
            arguments: args,
            binaryMessenger: messenger
        )
    }

    /**
     * Returns the codec used to encode/decode arguments.
     * StandardMessageCodec is the default mechanism Flutter uses.
     */
    func createArgsCodec() -> FlutterMessageCodec & NSObjectProtocol {
        return FlutterStandardMessageCodec.sharedInstance()
    }
}

import Flutter
import UIKit

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
      GeneratedPluginRegistrant.register(with: self)

      if let pluginRegistrar = self.registrar(forPlugin: "TrimbleMapViewPlugin") {
          let factory = TrimbleMapViewFactory(messenger: pluginRegistrar.messenger())
          pluginRegistrar.register(factory, withId: "trimble_map_view")
      }

      return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

import 'package:flutter/foundation.dart';	// Provides defaultTargetPlatform
import 'package:flutter/material.dart';  	// Material widgets and theming
import 'package:flutter/services.dart';  	// MethodChannel and message codecs

void main() {
  // Ensure Flutter framework is fully initialized before creating the app
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());                	// Launch the app
}

/// Root widget of the application
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
	return const MaterialApp(
  	// IMPORTANT: Replace 'YOUR_API_KEY' with your actual Trimble Maps API key
  	home: MapWithControls(
    	apiKey: 'YOUR_API_KEY',
    	region: 'worldwide', // Options: 'worldwide', 'northAmerica', 'europe'
  	),
	);
  }
}

/// Stateful widget that hosts the native Trimble map and control buttons
class MapWithControls extends StatefulWidget {
  final String apiKey; // API Key passed from MyApp
  final String region; // Region for Trimble Maps services
  const MapWithControls({
    super.key,
    required this.apiKey,
    this.region = 'worldwide', // Options: 'worldwide', 'northAmerica', 'europe'
  });

  @override
  State<MapWithControls> createState() => _MapWithControlsState();
}

class _MapWithControlsState extends State<MapWithControls> {
  // Channel for communicating Dart -> Native (TrimbleMapView)
  late MethodChannel _channel;
  // Flag to track if the native map has finished loading its initial style
  bool _mapReady = false;

  /// Callback triggered by UiKitView widget AFTER the native view is created.
  void _onPlatformViewCreated(int id) {
	debugPrint('Native PlatformView created with id: $id');

	// Initialize the MethodChannel.
	// IMPORTANT: The channel name MUST match the one used in TrimbleMapView.swift
	_channel = MethodChannel('trimble_map_view_$id');

	// Set up a handler for messages FROM Native TO Dart.
	_channel.setMethodCallHandler((call) async {
  	debugPrint('Dart received method call: ${call.method}');
  	// Check if the native side signaled that the map is ready
  	if (call.method == 'mapReady') {
    	debugPrint('mapReady received from native, enabling controls.');
    	// Update state to enable UI controls that interact with the map
    	setState(() {
      	_mapReady = true;
    	});
  	}
  	// Handle other potential methods from native if needed
	});
  }

  @override
  Widget build(BuildContext context) {
	// This example uses UiKitView, so restrict to iOS platform
	if (defaultTargetPlatform != TargetPlatform.iOS) {
  	return const Scaffold(
    	body: Center(child: Text('This example currently supports iOS only.')),
  	);
	}

	// Main UI structure
	return Scaffold(
  	appBar: AppBar(title: const Text('Trimble Map Flutter Example')),
  	body: Stack( // Use Stack to overlay controls on top of the map
    	children: [
      	// The widget that embeds the native iOS view
      	UiKitView(
        	// IMPORTANT: Must match the viewType registered in AppDelegate.swift
        	viewType: 'trimble_map_view',
        	// Callback function called when the native view is created
        	onPlatformViewCreated: _onPlatformViewCreated,
        	// Parameters passed to the native PlatformViewFactory's 'create' method
        	creationParams: <String, dynamic>{
          	// IMPORTANT: Keys must match those expected in TrimbleMapView.swift
          	'apiKey': widget.apiKey,
          	'region': widget.region,
        	},
        	// Codec used for encoding 'creationParams', must match the factory
        	creationParamsCodec: const StandardMessageCodec(),
      	),

      	// Overlay container for control buttons
      	Positioned(
        	bottom: 20,
        	left: 20,
        	right: 20, // Allow buttons to space out if needed
        	child: Card( // Wrap buttons in a Card for better visibility
          	elevation: 4.0,
          	child: Padding(
            	padding: const EdgeInsets.all(8.0),
            	child: Wrap( // Use Wrap for button layout flexibility
              	spacing: 8.0, // Horizontal space between buttons
              	runSpacing: 4.0, // Vertical space if buttons wrap
              	alignment: WrapAlignment.center,
              	children: [
                	// --- Map Control Buttons ---

                	ElevatedButton(
                  	// Enable button only when _mapReady is true
                  	onPressed: _mapReady ? _zoomIn : null,
                  	child: const Text('Zoom In'),
                	),

                	ElevatedButton(
                  	onPressed: _mapReady ? _zoomOut : null,
                  	child: const Text('Zoom Out'),
                	),

                	ElevatedButton(
                  	onPressed: _mapReady ? _toggleStyle : null,
                  	child: const Text('Toggle Style'),
                	),

                	ElevatedButton(
                  	onPressed: _mapReady ? _centerMap : null,
                  	child: const Text('Center (CA)'),
                	),
              	],
            	),
          	),
        	),
      	),
    	],
  	),
	);
  }

  // --- Button Action Methods ---

  void _zoomIn() {
	debugPrint('Button: Zoom In');
	// Invoke the 'zoomIn' method on the native side via the channel
	_channel.invokeMethod('zoomIn');
  }

  void _zoomOut() {
	debugPrint('Button: Zoom Out');
	// Invoke the 'zoomOut' method on the native side
	_channel.invokeMethod('zoomOut');
  }

  void _toggleStyle() {
	debugPrint('Button: Toggle Style');
	// Invoke the 'toggleStyle' method on the native side
	_channel.invokeMethod('toggleStyle');
  }

  void _centerMap() {
	// Define coordinates (Example: somewhere in California)
	const double lat = 36.7783;
	const double lng = -119.4179;
	debugPrint('Button: Center Map ($lat, $lng)');
	// Invoke the 'center' method on the native side, passing arguments
	_channel.invokeMethod('center', <String, double>{
  	'lat': lat,
  	'lng': lng,
	});
  }
}