startSimulation static method

TaskHandler? startSimulation(Route route, { void onNavigationInstruction(NavigationInstruction instruction, Set<NavigationInstructionUpdateEvents> events)?, void onNavigationStarted()?, void onTextToSpeechInstruction(String textInstruction)?, void onWaypointReached(Landmark landmark)?, void onDestinationReached(Landmark landmark)?, void onRouteUpdated(Route route)?, void onBetterRouteDetected(Route route, int travelTime, int delay, int timeGain,)?, void onBetterRouteRejected(GemError reason)?, void onBetterRouteInvalidated()?, void onSkipNextIntermediateDestinationDetected()?, void onTurnAround()?, void onError(GemError error)?, void onNotifyStatusChange(NavigationStatus status)?, void onRouteCalculationStarted()?, void onRouteCalculationCompleted(GemError error)?, double speedMultiplier = 1.0, })

Simulated navigation session.

Starts turn-by-turn navigation using simulated position data based on the Route. Provides comprehensive event callbacks for instruction updates, waypoint arrivals, route recalculations, better route detection, and error handling. Simulation continues until destination is reached, cancelled, or an error occurs.

Prerequisites

• Valid navigable route calculated via RoutingService.
• No GPS permissions required since position is simulated.

Parameters

• route: Route to navigate. Obtain via RoutingService.calculateRoute.
• onNavigationInstruction: Callback for instruction updates. Arguments:
  • instruction: Updated navigation instruction.
  • events: Set of events triggering the update (turn updated, lane info updated, etc.).
• onNavigationStarted: Callback when navigation begins (first valid position received).
• onTextToSpeechInstruction: Callback for TTS text. Arguments:
  • textInstruction: Text to be spoken by TTS engine. See SoundPlayingService to enable TTS.
• onWaypointReached: Callback when intermediate waypoint reached. Arguments:
  • landmark: Reached waypoint landmark.
• onDestinationReached: Callback when final destination reached. Arguments:
  • landmark: Destination landmark.
• onRouteUpdated: Callback when route recalculated. Arguments:
  • route: New route after recalculation.
• onBetterRouteDetected: Callback when better route found (requires RoutePreferences.avoidTraffic). Arguments:
  • route: Better route.
  • travelTime: Better route travel time (seconds).
  • delay: Traffic delay on better route (seconds).
  • timeGain: Time saved vs. current route (seconds). -1 if original route has roadblocks.
• onBetterRouteRejected: Callback when better route check fails. Arguments:
  • reason: Rejection error code.
• onBetterRouteInvalidated: Callback when previously detected better route becomes invalid.
• onSkipNextIntermediateDestinationDetected: Callback when user appears to be skipping next waypoint. Might be the time to call skipNextIntermediateDestination.
• onTurnAround: Callback when recalculated route requires opposite direction travel.
• onError: Callback for navigation errors. Arguments:
  • error: Error code. Possible values:
    • GemError.success: Completed successfully.
    • GemError.cancel: Cancelled by user.
    • GemError.waypointAccess: Waypoint unreachable with current preferences.
    • GemError.connectionRequired: Online calculation needed but offline-only mode set.
    • GemError.expired: Map data version no longer supported by online service.
    • GemError.routeTooLong: Online routing timeout.
    • GemError.invalidated: Map data changed during calculation.
    • GemError.noMemory: Insufficient memory for route calculation.
• onNotifyStatusChange: Callback for navigation status changes. Arguments:
  • status: New status (running, waiting for GPS, waiting for route, etc.).
• onRouteCalculationStarted: Callback when route (re)calculation begins.
• onRouteCalculationCompleted: Callback when route (re)calculation finishes. Arguments:
  • error: Error code if calculation failed, GemError.success otherwise.
• speedMultiplier: Simulation speed multiplier. Defaults to 1.0 (real-time speed).

Returns

• (TaskHandler?) Handler for the navigation session, or null if initialization failed (geographic search failure). Use with cancelNavigation to stop navigation.

See also:

• startSimulation - Start simulated navigation without GPS.
• cancelNavigation - Stop navigation session.
• NavigationInstruction - Real-time turn-by-turn instruction details.
• RoutingService.calculateRoute - Route calculation.
• PositionService - Position data source configuration.
• SoundPlayingService - Text-to-speech configuration.

Implementation

static TaskHandler? startSimulation(
  final Route route, {
  final void Function(
    NavigationInstruction instruction,
    Set<NavigationInstructionUpdateEvents> events,
  )?
  onNavigationInstruction,
  final void Function()? onNavigationStarted,
  final void Function(String textInstruction)? onTextToSpeechInstruction,
  final void Function(Landmark landmark)? onWaypointReached,
  final void Function(Landmark landmark)? onDestinationReached,
  final void Function(Route route)? onRouteUpdated,
  final void Function(Route route, int travelTime, int delay, int timeGain)?
  onBetterRouteDetected,
  final void Function(GemError reason)? onBetterRouteRejected,
  final void Function()? onBetterRouteInvalidated,
  final void Function()? onSkipNextIntermediateDestinationDetected,
  final void Function()? onTurnAround,
  final void Function(GemError error)? onError,
  final void Function(NavigationStatus status)? onNotifyStatusChange,
  final void Function()? onRouteCalculationStarted,
  final void Function(GemError error)? onRouteCalculationCompleted,
  final double speedMultiplier = 1.0,
}) {
  final OperationResult result = staticMethod(
    'NavigationService',
    'startNavigation',
    args: <String, dynamic>{
      'route': route.pointerId,
      'simulation': true,
      'speedMultiplier': speedMultiplier,
    },
  );

  final int gemApiError = result['gemApiError'];

  if (GemErrorExtension.isErrorCode(gemApiError)) {
    final GemError errorCode = GemErrorExtension.fromCode(gemApiError);
    onError?.call(errorCode);
    return null;
  }

  final int listenerId = result['result'];

  final NavigationListener listener = NavigationListener.init(listenerId);
  listener.registerAll(
    onNavigationStarted: onNavigationStarted,
    onNavigationInstructionUpdated:
        (
          final NavigationInstruction instruction,
          final Set<NavigationInstructionUpdateEvents> events,
        ) {
          onNavigationInstruction?.call(instruction, events);
        },
    onWaypointReached: onWaypointReached,
    onDestinationReached: (final Landmark destination) {
      onDestinationReached?.call(destination);
    },
    onNavigationError: (final GemError error) {
      GemKitPlatform.instance.unregisterEventHandler(listener.id);
      onError?.call(error);
    },
    onRouteUpdated: onRouteUpdated,
    onNavigationSound: onTextToSpeechInstruction,
    onNotifyStatusChange: onNotifyStatusChange,
    onBetterRouteDetected: onBetterRouteDetected,
    onBetterRouteRejected: onBetterRouteRejected,
    onBetterRouteInvalidated: onBetterRouteInvalidated,
    onSkipNextIntermediateDestinationDetected:
        onSkipNextIntermediateDestinationDetected,
    onTurnAround: onTurnAround,
    onRouteCalculationStarted: onRouteCalculationStarted,
    onRouteCalculationCompleted: onRouteCalculationCompleted,
  );

  GemKitPlatform.instance.registerEventHandler(listener.id, listener);
  return TaskHandlerImpl(listener.id);
}