startNavigation static method

TaskHandler? startNavigation(
  1. Route route, {
  2. void onNavigationInstruction(
    1. NavigationInstruction instruction,
    2. Set<NavigationInstructionUpdateEvents> events
    )?,
  3. void onNavigationStarted()?,
  4. void onTextToSpeechInstruction(
    1. String textInstruction
    )?,
  5. void onWaypointReached(
    1. Landmark landmark
    )?,
  6. void onDestinationReached(
    1. Landmark landmark
    )?,
  7. void onRouteUpdated(
    1. Route route
    )?,
  8. void onBetterRouteDetected(
    1. Route route,
    2. int travelTime,
    3. int delay,
    4. int timeGain,
    )?,
  9. void onBetterRouteRejected(
    1. GemError reason
    )?,
  10. void onBetterRouteInvalidated()?,
  11. void onSkipNextIntermediateDestinationDetected()?,
  12. void onTurnAround()?,
  13. void onError(
    1. GemError error
    )?,
  14. void onNotifyStatusChange(
    1. NavigationStatus status
    )?,
  15. void onRouteCalculationStarted()?,
  16. void onRouteCalculationCompleted(
    1. GemError error
    )?,
})

Real-time GPS navigation session.

Starts turn-by-turn navigation using position data from PositionService. Provides comprehensive event callbacks for instruction updates, waypoint arrivals, route recalculations, better route detection, and error handling. Navigation continues until destination is reached, cancelled, or an error occurs.

Prerequisites

  • Valid navigable route calculated via RoutingService.
  • PositionService configured with live GPS or custom data source.
  • Appropriate GPS permissions granted (for live GPS).

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:
  • 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:
  • 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:

Returns

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

See also:

Implementation

static TaskHandler? startNavigation(
  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 OperationResult result = staticMethod(
    'NavigationService',
    'startNavigation',
    args: <String, dynamic>{'route': route.pointerId, 'simulation': false},
  );

  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);
}