Google is committed to advancing racial equity for Black communities. See how.

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.

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 OnBackPressedDispatcher that will be triggered when the user clicks a back button.

boolean isDarkMode()

Returns true if the car is set to dark mode.

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"

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 of Screens.

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.

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

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.
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 this CarContext. If the component name is for a different component, the method will throw a SecurityException.

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 Intents.

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.