CarContext
public
class
CarContext
extends ContextWrapper
java.lang.Object | |||
↳ | android.content.Context | ||
↳ | android.content.ContextWrapper | ||
↳ | com.google.android.libraries.car.app.CarContext |
The CarContext class is a ContextWrapper
subclass accessible to your CarAppService
and Screen
instances, which provides access to car services such as the
ScreenManager
for managing the screen stack, the AppManager
for general
app-related functionality such as accessing a surface for drawing your navigation app’s map, and
the NavigationManager
used by turn-by-turn navigation apps to communicate navigation
metadata and other navigation-related events with the host. See Access the navigation templates
for a comprehensive list of library functionality available to navigation apps.
Whenever you use a CarContext to load resources, the following configuration elements come from the car screen's configuration, and not the phone:
- Screen width.
- Screen height.
- Screen pixel density (DPI).
- Night mode (See
isDarkMode()
).
Please refer here, on how to use configuration qualifiers in your resources.
See also:
Summary
Constants | |
---|---|
String |
ACTION_NAVIGATE
Standard action for navigating to a location. |
String |
APP_SERVICE
Manages all app events such as invalidating the UI, showing a toast, etc. |
String |
NAVIGATION_SERVICE
Manages all navigation events such as starting navigation when focus is granted, abandoning navigation when focus is lost, etc. |
String |
SCREEN_MANAGER_SERVICE
Manages the screens of the app, including the screen stack. |
Inherited constants |
---|
Public methods | |
---|---|
void
|
finishCarApp()
Requests to finish the car app. |
<T>
T
|
getCarService(Class<T> serviceClass)
Returns the a car service, by class. |
Object
|
getCarService(String name)
Provides a car service by name. |
String
|
getCarServiceName(Class<?> serviceClass)
Gets the name of the car service that is represented by the specified class. |
OnBackPressedDispatcher
|
getOnBackPressedDispatcher()
Returns the |
boolean
|
isDarkMode()
Returns |
void
|
startCarApp(Intent intent)
Starts a car app on the car screen. |
static
void
|
startCarApp(Intent notificationIntent, Intent appIntent)
Starts the car app on the car screen. |
Inherited methods | |
---|---|
Constants
ACTION_NAVIGATE
public static final String ACTION_NAVIGATE
Standard action for navigating to a location.
Used as the Intent
's action for starting a navigation via startCarApp(Intent)
.
Constant Value: "com.google.android.libraries.car.app.action.NAVIGATE"
APP_SERVICE
public static final String APP_SERVICE
Manages all app events such as invalidating the UI, showing a toast, etc.
Constant Value: "app_manager"
NAVIGATION_SERVICE
public static final String NAVIGATION_SERVICE
Manages all navigation events such as starting navigation when focus is granted, abandoning navigation when focus is lost, etc.
Constant Value: "navigation_manager"
SCREEN_MANAGER_SERVICE
public static final String SCREEN_MANAGER_SERVICE
Manages the screens of the app, including the screen stack.
Constant Value: "screen_manager"
Public methods
finishCarApp
public void finishCarApp ()
Requests to finish the car app.
Call this when your app is done and should be closed.
At some point after this call, CarAppService.onCarAppFinished()
will be called, and
eventually the OS will destroy your CarAppService
.
getCarService
public T getCarService (Class<T> serviceClass)
Returns the a car service, by class.
Currently supported classes are: AppManager
, NavigationManager
, ScreenManager
.
Parameters | |
---|---|
serviceClass |
Class : the class of the requested service. |
Returns | |
---|---|
T |
The car service instance. |
Throws | |
---|---|
IllegalArgumentException |
if serviceClass is not the class of a supported car
service. |
NullPointerException |
if serviceClass is null .
|
getCarService
public Object getCarService (String name)
Provides a car service by name.
The class of the returned object varies by the requested name.
Currently supported car services, and their respective classes, are:
APP_SERVICE
- An
AppManager
for communication between the app and the host. NAVIGATION_SERVICE
- A
NavigationManager
for management of navigation updates. SCREEN_MANAGER_SERVICE
- A
ScreenManager
for management ofScreen
s.
Parameters | |
---|---|
name |
String : The name of the car service requested. This should be one of APP_SERVICE ,
NAVIGATION_SERVICE or SCREEN_MANAGER_SERVICE . |
Returns | |
---|---|
Object |
The car service instance. |
Throws | |
---|---|
IllegalArgumentException |
if name does not refer to a valid car service. |
NullPointerException |
if name is null .
|
getCarServiceName
public String getCarServiceName (Class<?> serviceClass)
Gets the name of the car service that is represented by the specified class.
Parameters | |
---|---|
serviceClass |
Class : the class of the requested service. |
Returns | |
---|---|
String |
the car service name to use with getCarService(String) . |
Throws | |
---|---|
IllegalArgumentException |
if serviceClass is not the class of a supported car
service. |
NullPointerException |
if serviceClass is null . |
See also:
getOnBackPressedDispatcher
public OnBackPressedDispatcher getOnBackPressedDispatcher ()
Returns the OnBackPressedDispatcher
that will be triggered when the user clicks a back
button.
The default back press behavior is to call ScreenManager.pop()
.
To override the default behavior, register a OnBackPressedCallback
via calling OnBackPressedDispatcher.addCallback(LifecycleOwner, OnBackPressedCallback)
.
Using the LifecycleOwner
ensures that your callback is only registered while its Lifecycle
is at least Lifecycle.State.STARTED
.
If there is a OnBackPressedCallback
that is added and enabled, and
you'd like to remove the top Screen
as a part of the callback, you MUST call
ScreenManager.pop()
in the callback. The default behavior is overridden when you have a
callback enabled.
Returns | |
---|---|
OnBackPressedDispatcher |
isDarkMode
public boolean isDarkMode ()
Returns true
if the car is set to dark mode.
Navigation applications must redraw their map with the proper dark colors when the host determines that conditions warrant it, as signaled by the value returned by this method.
Whenever the dark mode status changes, you will receive a call to CarAppService.onCarConfigurationChanged(Configuration)
.
Returns | |
---|---|
boolean |
startCarApp
public void startCarApp (Intent intent)
Starts a car app on the car screen.
The target application will get the Intent
via CarAppService.onCreateScreen(Intent)
or CarAppService.onNewIntent(Intent)
.
Supported Intent
s:
- An
Intent
to navigate. - The action must be
ACTION_NAVIGATE
.- The data URI scheme must be either a latitude,longitude pair, or a + separated string query as follows:
- 1) "geo:12.345,14.8767" for a latitude, longitude pair.
- 2) "geo:0,0?q=123+Main+St,+Seattle,+WA+98101" for an address.
- 3) "geo:0,0?q=a+place+name" for a place to search for.
- The data URI scheme must be either a latitude,longitude pair, or a + separated string query as follows:
- An
Intent
to make a phone call. - The
Intent
must be created as defined here. - An
Intent
to start this app in the car. - The component name of the intent must be the one for the
CarAppService
that contains thisCarContext
. If the component name is for a different component, the method will throw aSecurityException
.
Parameters | |
---|---|
intent |
Intent : the Intent to send to the target application. |
Throws | |
---|---|
SecurityException |
if the app attempts to start a different app explicitly or does not have permissions for the requested action. |
InvalidParameterException |
if intent does not meet the criteria defined. |
NullPointerException |
if intent is null .
|
startCarApp
public static void startCarApp (Intent notificationIntent, Intent appIntent)
Starts the car app on the car screen.
Use this method if the app has received a broadcast due to a notification action.
Parameters | |
---|---|
notificationIntent |
Intent : the Intent that the app received via broadcast due to a user
taking an action on a notification in the car. |
appIntent |
Intent : the Intent to use for starting the car app. See startCarApp(Intent) for the documentation on valid Intent s. |
Throws | |
---|---|
InvalidParameterException |
if notificationIntent is not an Intent
received from a broadcast, due to an action taken by the user in the car. |
NullPointerException |
if either notificationIntent or appIntent are
null .
|