# Interface CarBridge

public interface CarBridge

Internal service-provider interface implemented by each platform port to render the portable `com.codename1.car` template tree onto the native in-car UI (Apple CarPlay's `CPTemplate` hierarchy or Google Android Auto's `androidx.car.app` templates).

Application code never touches this interface -- it is obtained by the `com.codename1.car` framework classes from `com.codename1.ui.Display#getCarBridge()` and driven through the public `com.codename1.car.CarContext` / `com.codename1.car.CarScreen` API. The base implementation returns `null`, which is why the public API degrades to a harmless no-op on the simulator and on ports without an in-car projection (so application code needs no platform `if` statements).

A bridge renders a screen by pulling its template through `CarScreen.createTemplate()` (the framework calls `CarScreen#dispatchCreateTemplate()` on its behalf) and is responsible for invoking the relevant `com.codename1.car.CarActionListener` when the user activates a row, grid item or action -- the bridge identifies the activated element by the indices it assigned while rendering.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `finish()`
  Tears down the in-car experience, dismissing the app from the head unit.
  `int`
  `getGridItemLimit()`
  Returns the maximum number of items the head unit will display in a single grid, or `0` when the limit is unknown.
  `int`
  `getListRowLimit()`
  Returns the maximum number of rows the head unit will display in a single list, or `0` when the limit is unknown.
  `void`
  `invalidate(CarScreen screen)`
  Re-pulls and re-renders the template for the supplied screen (call after mutating the model behind a screen, mirroring `androidx.car.app.Screen#invalidate()`). No effect if the screen is not currently on the stack.
  `boolean`
  `isConnected()`
  Returns true while a head unit (CarPlay / Android Auto) is currently connected and the projected UI is live.
  `void`
  `popScreen()`
  Pops the top screen off the in-car back stack, returning to the previous screen.
  `void`
  `pushScreen(CarScreen screen)`
  Pushes a screen onto the in-car back stack and renders its template.
  `void`
  `showToast(String message, int durationSeconds)`
  Shows a short transient message on the head unit (CarPlay banner / Android Auto toast).

- ## Method Details

  - ### pushScreen

    void pushScreen(CarScreen screen)

    Pushes a screen onto the in-car back stack and renders its template. The pushed screen becomes the visible top of stack.

    ###### Parameters

    - `screen`: the screen to push and render

  - ### popScreen

    void popScreen()
    Pops the top screen off the in-car back stack, returning to the previous screen. Has no effect when only the root screen remains.

  - ### invalidate

    void invalidate(CarScreen screen)

    Re-pulls and re-renders the template for the supplied screen (call after mutating the model behind a screen, mirroring `androidx.car.app.Screen#invalidate()`). No effect if the screen is not currently on the stack.

    ###### Parameters

    - `screen`: the screen whose template should be rebuilt

  - ### finish

    void finish()
    Tears down the in-car experience, dismissing the app from the head unit.

  - ### isConnected

    boolean isConnected()

    Returns true while a head unit (CarPlay / Android Auto) is currently connected and the projected UI is live.

    ###### Returns

    true if a car is connected

  - ### showToast

    void showToast(String message, int durationSeconds)

    Shows a short transient message on the head unit (CarPlay banner / Android Auto toast).

    ###### Parameters

    - `message`: the text to display

    - `durationSeconds`: requested display duration in seconds; the head unit may clamp it

  - ### getListRowLimit

    int getListRowLimit()

    Returns the maximum number of rows the head unit will display in a single list, or `0` when the limit is unknown. Driver-distraction rules cap this aggressively (often 6-12); honour it when populating a `com.codename1.car.CarListTemplate`.

    ###### Returns

    the row limit, or 0 if unknown

  - ### getGridItemLimit

    int getGridItemLimit()

    Returns the maximum number of items the head unit will display in a single grid, or `0` when the limit is unknown.

    ###### Returns

    the grid item limit, or 0 if unknown