NavigationManager
public
class
NavigationManager
extends Object
java.lang.Object | |
↳ | androidx.car.app.navigation.NavigationManager |
Manager for communicating navigation related events with the host.
Navigation apps must use this interface to coordinate with the car system for navigation specific resources such as vehicle cluster and heads-up displays.
When a navigation app receives a user action to start navigating, it should call navigationStarted()
to indicate it is currently navigating. When the app receives a user action
to end navigation or when the destination is reached, navigationEnded()
should be
called.
Navigation apps must also register a NavigationManagerCallback
to handle callbacks to
NavigationManagerCallback.onStopNavigation()
issued by the host.
Summary
Public methods | |
---|---|
void
|
clearNavigationManagerCallback()
Clears the callback for receiving navigation manager events. |
void
|
navigationEnded()
Notifies the host that the app has ended active navigation. |
void
|
navigationStarted()
Notifies the host that the app has started active navigation. |
void
|
setNavigationManagerCallback(Executor executor, NavigationManagerCallback callback)
Sets a callback to start receiving navigation manager events. |
void
|
setNavigationManagerCallback(NavigationManagerCallback callback)
Sets a callback to start receiving navigation manager events. |
void
|
updateTrip(Trip trip)
Sends the destinations, steps, and trip estimates to the host. |
Inherited methods | |
---|---|
Public methods
clearNavigationManagerCallback
public void clearNavigationManagerCallback ()
Clears the callback for receiving navigation manager events.
Throws | |
---|---|
IllegalStateException |
if navigation is started (see navigationStarted()
for more info), or if the current thread is not the main thread
|
navigationEnded
public void navigationEnded ()
Notifies the host that the app has ended active navigation.
Only one app may be actively navigating in the car at any time and ownership is managed by the host. The app must call this method to inform the system that it has ended navigation, for example, in response to the user cancelling navigation or upon reaching the destination.
This method is idempotent.
Throws | |
---|---|
IllegalStateException |
if the current thread is not the main thread |
navigationStarted
public void navigationStarted ()
Notifies the host that the app has started active navigation.
Only one app may be actively navigating in the car at any time and ownership is managed by the host. The app must call this method to inform the system that it has started navigation in response to user action.
This function can only called if
setNavigationManagerCallback(NavigationManagerCallback)
has been
called with a non-null
value. The callback is required so that a signal to stop
navigation from the host can be handled using
NavigationManagerCallback.onStopNavigation()
.
This method is idempotent.
Throws | |
---|---|
IllegalStateException |
if no navigation manager callback has been set, or if the current thread is not the main thread |
setNavigationManagerCallback
public void setNavigationManagerCallback (Executor executor, NavigationManagerCallback callback)
Sets a callback to start receiving navigation manager events.
Parameters | |
---|---|
executor |
Executor : the executor which will be used for invoking the callback |
callback |
NavigationManagerCallback : the NavigationManagerCallback to use |
Throws | |
---|---|
IllegalStateException |
if the current thread is not the main thread |
setNavigationManagerCallback
public void setNavigationManagerCallback (NavigationManagerCallback callback)
Sets a callback to start receiving navigation manager events.
Note that the callback events will be executed on the main thread using
Looper.getMainLooper()
. To specify the execution thread, use
setNavigationManagerCallback(Executor, NavigationManagerCallback)
.
Parameters | |
---|---|
callback |
NavigationManagerCallback : the NavigationManagerCallback to use |
Throws | |
---|---|
IllegalStateException |
if the current thread is not the main thread |
updateTrip
public void updateTrip (Trip trip)
Sends the destinations, steps, and trip estimates to the host.
The data may be rendered at different places in the car such as the instrument cluster screen or the heads-up display.
This method should only be invoked once the navigation app has called navigationStarted()
, or else the updates will be dropped by the host. Once the app has
called navigationEnded()
or received
NavigationManagerCallback.onStopNavigation()
it should stop sending updates.
As the location changes, and in accordance with speed and rounded distance changes, the
TravelEstimate
s in the provided Trip
should be rebuilt and this method called
again. For example, when the next step is greater than 10 kilometers away and the display
unit is kilometers, updates should occur roughly every kilometer.
Data provided to the cluster display depends on the vehicle capabilities. In some
instances the information may not be shown at all. On some vehicles Maneuver
s of unknown type may be skipped while on other
displays the associated icon may be shown.
Parameters | |
---|---|
trip |
Trip : destination, steps, and trip estimates to be sent to the host |
Throws | |
---|---|
HostException |
if the call is invoked by an app that is not declared as a navigation app in the manifest |
IllegalStateException |
if the call occurs when navigation is not started (see
navigationStarted() for more info), or if the
current thread is not the main thread |
IllegalArgumentException |
if any of the destinations, steps, or trip position is not well formed |