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 |
HostInfo
|
getHostInfo()
Retrieves information about the host attached to this service. |
Lifecycle
|
getLifecycle()
Returns the |
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 |
abstract
Screen
|
onCreateScreen(Intent intent)
Requests the first |
final
void
|
onDestroy()
Handles the system destroying this |
void
|
onNewIntent(Intent intent)
Notifies that the car app has received a new |
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
:
- Observe its
Lifecycle
by callingLifecycle.addObserver(LifecycleObserver)
. You can use theLifecycleObserver
to take specific actions whenever theScreen
receives differentLifecycle.Event
s. - Use this
CarAppService
to observeLiveData
s that may drive the backing data for your application.
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 Intent
s.
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 Screen
s 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 Screen
s 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 |
See also:
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. |
See also:
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 |