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

CarAppService

public abstract class CarAppService
extends Service implements LifecycleOwner

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ com.google.android.libraries.car.app.CarAppService


The base class for implementing a car app that runs in the car.

Accessing Location

When the app is running in the car display, the system will not consider it as being in the foreground, and hence it will considered in the background for the purpose of retrieving location as described here.

To reliably get location for your car app, we recommended that you use a foreground service.

Summary

Inherited constants

Public constructors

CarAppService()

Public methods

void dump(FileDescriptor fd, PrintWriter writer, String[] args)
void finish()

Requests to finish the car app.

final CarContext getCarContext()

Returns the CarContext for this car app.

HostInfo getHostInfo()

Retrieves information about the host attached to this service.

Lifecycle getLifecycle()

Returns the CarAppService's Lifecycle.

IBinder onBind(Intent intent)

Handles the host binding to this car app.

void onCarAppFinished()

Notifies that this car app has finished and should be treated as if it is destroyed.

void onCarConfigurationChanged(Configuration newConfiguration)

Notifies that the CarContext's Configuration has changed.

abstract Screen onCreateScreen(Intent intent)

Requests the first Screen for the application.

final void onDestroy()

Handles the system destroying this CarAppService.

void onNewIntent(Intent intent)

Notifies that the car app has received a new Intent.

final boolean onUnbind(Intent intent)

Handles the host unbinding from this car app.

Inherited methods

Public constructors

CarAppService

public CarAppService ()

Public methods

dump

public void dump (FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

Parameters
fd FileDescriptor

writer PrintWriter

args String

finish

public void finish ()

Requests to finish the car app.

Call this when your app is done and should be closed.

At some point after this call onCarAppFinished() will be called, and eventually the system will destroy this CarAppService.

getCarContext

public final CarContext getCarContext ()

Returns the CarContext for this car app.

The CarContext is not fully initialized until this car app's Lifecycle.State is at least Lifecycle.State.CREATED

Returns
CarContext

See also:

getHostInfo

public HostInfo getHostInfo ()

Retrieves information about the host attached to this service.

Returns
HostInfo

See also:

getLifecycle

public Lifecycle getLifecycle ()

Returns the CarAppService's Lifecycle.

Here are some of the ways you can use the car app's Lifecycle:

What each lifecycle related event means for a car app:

Lifecycle.Event.ON_CREATE
The car app has just been launched, and this car app is being initialized. onCreateScreen(Intent) will be called at a point after this call.
onCreateScreen(Intent)
The host is ready for this car app to create the first Screen so that it can display its template.
Lifecycle.Event.ON_START
The application is now visible in the car screen.
Lifecycle.Event.ON_RESUME
The user can now interact with this application.
Lifecycle.Event.ON_PAUSE
The user can no longer interact with this application.
Lifecycle.Event.ON_STOP
The application is no longer visible.
onCarAppFinished()
Either this car app has requested to be finished (see finish()), or the host has finished this car app. Unless this is a navigation app, after a period of time that the app is no longer displaying in the car, the host may finish this car app.
Lifecycle.Event.ON_DESTROY
The OS has now destroyed this CarAppService instance, and it is no longer valid.

Listeners that are added in Lifecycle.Event.ON_START, should be removed in Lifecycle.Event.ON_STOP.

Listeners that are added in Lifecycle.Event.ON_CREATE should be removed in Lifecycle.Event.ON_DESTROY.

Returns
Lifecycle

See also:

onBind

public IBinder onBind (Intent intent)

Handles the host binding to this car app.

This method is final to ensure this car app's lifecycle is handled properly.

Use onCreateScreen(Intent) and onNewIntent(Intent) instead to handle incoming Intents.

Parameters
intent Intent

Returns
IBinder

onCarAppFinished

public void onCarAppFinished ()

Notifies that this car app has finished and should be treated as if it is destroyed.

The Screens in the stack managed by the ScreenManager are now all destroyed and removed from the screen stack.

onCreateScreen(Intent) will be called if the user reopens the app before the system has destroyed it.

For the purposes of the app's lifecycle, you should perform similar destroy functions that you would when this instance's Lifecycle becomes Lifecycle.State.DESTROYED.

Called by the system, do not call this method directly.

See also:

onCarConfigurationChanged

public void onCarConfigurationChanged (Configuration newConfiguration)

Notifies that the CarContext's Configuration has changed.

At the time that this function is called, the CarContext's resources object will have been updated to return resource values matching the new configuration.

Called by the system, do not call this method directly.

Parameters
newConfiguration Configuration

See also:

onCreateScreen

public abstract Screen onCreateScreen (Intent intent)

Requests the first Screen for the application.

This method is invoked when this car app is first opened by the user.

Once the method returns, Screen.getTemplate() will be called on the Screen returned, and the app will be displayed on the car screen.

To pre-seed a back stack, you can push Screens onto the stack, via ScreenManager.push(Screen) during this method call.

This method is invoked the first time the app is started, or if this CarAppService instance has been previously finished and the system has not yet destroyed this car app (See onCarAppFinished()).

Called by the system, do not call this method directly.

Parameters
intent Intent: the intent that was used to start this app. If the app was started with a call to CarContext.startCarApp(Intent), this intent will be equal to the intent passed to that method.

Returns
Screen

onDestroy

public final void onDestroy ()

Handles the system destroying this CarAppService.

This method is final to ensure this car app's lifecycle is handled properly.

Use a LifecycleObserver to observe this car app's Lifecycle.

See also:

onNewIntent

public void onNewIntent (Intent intent)

Notifies that the car app has received a new Intent.

Once the method returns, Screen.getTemplate() will be called on the Screen that is on top of the Screen stack managed by the ScreenManager, and the app will be displayed on the car screen.

In contrast to onCreateScreen(Intent), this method is invoked when the app has already been launched and has not been finished.

Often used to update the current Screen or pushing a new one on the stack, based off of the information in the intent.

Called by the system, do not call this method directly.

Parameters
intent Intent: the intent that was used to start this app. If the app was started with a call to CarContext.startCarApp(Intent), this intent will be equal to the intent passed to that method.

onUnbind

public final boolean onUnbind (Intent intent)

Handles the host unbinding from this car app.

This method is final to ensure this car app's lifecycle is handled properly.

Use onCarAppFinished() instead.

Parameters
intent Intent

Returns
boolean