Trip progress
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 to reduce 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
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.components.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.