Skip to main content

Trip progress

Additional Developer Resources

Many navigation applications display data related to trip progress including the estimated time to arrival and the distance remaining. The Mapbox Navigation SDK offers a trip progress UI component that you can drop into your application reduce to development time.

The Navigation SDK uses the RouteProgress class to hold information about your user's progress along a route. The information is then used to display indicators of trip progress on the device's screen. Read more about the information included in the route progress object in the Route progress guide.

Use the default trip progress UI component​

The trip progress view UI component (MapboxTripProgressView) is refreshed by route progress events and displays:

  • Estimated time to arrival
  • Distance remaining
  • Estimated time remaining
EXAMPLE
Render trip progress information

Draw trip progress information using the Trip Progress API and MapboxTripProgressView.

Add the view to the layout​

Start by adding the MapboxTripProgressView to your XML layout file.

<com.mapbox.navigation.ui.tripprogress.view.MapboxTripProgressView
    android:id="@+id/tripProgressView"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent" />

Create an instance of the trip progress API​

In your activity or fragment instantiate the MapboxTripProgressApi class. The MapboxTripProgressApi consumes route progress data and produces trip related data that is consumed by the MapboxTripProgressView in the view layout.

You'll need to create a TripProgressUpdateFormatter to pass to MapboxTripProgressApi. The data in the view is formatted by different formatting class implementations. There are default options, but you can use your own formatting implementations to customize the formatting of the data along with the appearance.

// Define formatter options
private val tripProgressFormatter: TripProgressUpdateFormatter by lazy {

    /* 
    Here a distance formatter with default values is being created. The distance 
    remaining formatter can also come from MapboxNavigation just be sure it is
    instantiated and configured first. The formatting options in MapboxNavigation
    can be found at: MapboxNavigation::navigationOptions::distanceFormatterOptions
    */
    val distanceFormatterOptions =
        DistanceFormatterOptions.Builder(this).build()

    /*
    These are Mapbox formatters being created with default values. You can
    provide your own custom formatters by implementing the appropriate interface.
    The expected output of a formatter is a SpannableString that is applied to
    the view component in MapboxTripProgressView.
    */
		TripProgressUpdateFormatter.Builder(this)
			.distanceRemainingFormatter(DistanceRemainingFormatter(distanceFormatterOptions))
	      	.timeRemainingFormatter(TimeRemainingFormatter(this))
			.estimatedTimeToArrivalFormatter(EstimatedTimeToArrivalFormatter(this))
			.build()
}

// Create an instance of the trip progress API
private val tripProgressApi: MapboxTripProgressApi by lazy {
    MapboxTripProgressApi(tripProgressFormatter)
}

Create an instance of the trip progress view​

Once you've added the view to the XML layout file, you can reference it in your activity or fragment. Register a RouteProgressObserver to update the trip progress component during navigation.

// Reference the view
tripProgressView = findViewById(R.id.tripProgressView)

// Update the view whenever there's an update to route progress
private val routeProgressObserver = object : RouteProgressObserver {
    override fun onRouteProgressChanged(routeProgress: RouteProgress) {            
        tripProgressApi.getTripProgress(routeProgress).let { update ->
            tripProgressView.render(update)
        }
    }
}

Start and stop receiving route progress events​

The route progress observer is registered with the MapboxNavigation class (for example, in onStart()). Be sure to unregister the route progress observer in onStop() or onDestroy().

mapboxNavigation.registerRouteProgressObserver(routeProgressObserver)

Customize trip progress​

The trip progress API takes several different formatting implementations, which can be replaced by your own implementation. The resulting SpannableString will be applied to the view element in the trip progress view component.

Since the Mapbox implementations return a SpannableString you can also customize the data and appearance of the data in the trip progress view by using the Mapbox formatter in your implementation and modifying the SpannableString before returning the end result to be displayed in the view.

Additional Developer Resources
Was this page helpful?