Screen

public abstract class Screen
extends Object implements LifecycleOwner

java.lang.Object
   ↳ androidx.car.app.Screen


A Screen has a Lifecycle and provides the mechanism for the app to send Templates to display when the Screen is visible. Screen instances can also be pushed and popped to and from a Screen stack, which ensures they adhere to the template flow restrictions (see onGetTemplate() for more details on template flow).

The Screen class can be used to manage individual units of business logic within a car app. A Screen is closely tied to the CarAppService it is a part of, and cannot be used without it. Though Screen defines its own lifecycle (see getLifecycle()), that lifecycle is dependent on its CarAppService: if the car app service is stopped, no screens inside of it can be started; when the car app service is destroyed, all screens will be destroyed.

Screen objects are not thread safe and all calls should be made from the same thread.

Summary

Protected constructors

Screen(CarContext carContext)

Public methods

final void finish()

Removes this screen from the stack, which will move its lifecycle state down to Lifecycle.State.DESTROYED.

final CarContext getCarContext()

Returns the CarContext of the CarAppService.

final Lifecycle getLifecycle()

Returns this screen's lifecycle.

String getMarker()

Retrieves the marker that has been set for this screen, or null if one has not been set.

final ScreenManager getScreenManager()

Returns the ScreenManager to use for pushing/removing screens.

final void invalidate()

Requests the current template to be invalidated, which eventually triggers a call to onGetTemplate() to get the new template to display.

abstract Template onGetTemplate()

Returns the Template to present in the car screen.

void setMarker(String marker)

Updates the marker for this screen.

void setResult(Object result)

Sets the result that will be sent to the OnScreenResultListener that was given when pushing this screen onto the stack using ScreenManager.pushForResult(Screen, OnScreenResultListener).

Inherited methods

Protected constructors

Screen

protected Screen (CarContext carContext)

Parameters
carContext CarContext

Public methods

finish

public final void finish ()

Removes this screen from the stack, which will move its lifecycle state down to Lifecycle.State.DESTROYED.

Call when your screen is done and should be removed from the stack.

If this screen is the only one in the stack, it will not be finished.

getCarContext

public final CarContext getCarContext ()

Returns the CarContext of the CarAppService.

Returns
CarContext

getLifecycle

public final Lifecycle getLifecycle ()

Returns this screen's lifecycle.

Here are some ways you can use a Screen's Lifecycle:

What each Lifecycle.Event means for a screen:

Lifecycle.Event.ON_CREATE
The screen is in the process of being pushed to the screen stack, it is valid, but contents from it are not yet visible in the car screen. You should get a callback to onGetTemplate() at a point after this call. This is where you can make decision on whether this Screen is still relevant, and if you choose to not return a Template from this Screen call finish().
Lifecycle.Event.ON_START
The template returned from this screen is visible in the car screen.
Lifecycle.Event.ON_RESUME
The user can now interact with the template returned from this screen.
Lifecycle.Event.ON_PAUSE
The user can no longer interact with this screen's template.
Lifecycle.Event.ON_STOP
The template returned from this screen is no longer visible.
Lifecycle.Event.ON_DESTROY
This screen is no longer valid and is removed from the screen stack.

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

Similarly, listeners that are added in Lifecycle.Event.ON_CREATE should be removed in Lifecycle.Event.ON_DESTROY<