Disegna mappe

Le app di navigazione, punti d'interesse (POI) e meteo che utilizzano i seguenti modelli possono disegnare mappe accedendo a un Surface.

Per utilizzare i seguenti modelli, l'app deve dichiarare una di queste autorizzazioni corrispondenti in un <uses-permission> elemento nel AndroidManifest.xml file.

Consulta l'implementazione dei riferimenti

Per visualizzare un'implementazione dei riferimenti completa, consulta l'esempio di navigazione .

Dichiara l'autorizzazione per la superficie

Oltre all'autorizzazione richiesta per il modello utilizzato dall'app, quest'ultima deve dichiarare l'autorizzazione androidx.car.app.ACCESS_SURFACE nel file AndroidManifest.xml per accedere alla superficie:

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.ACCESS_SURFACE" />
  ...
</manifest>

Accedi alla superficie

Per accedere a Surface fornito dall'host, devi implementare un SurfaceCallback e fornire l'implementazione al servizio auto AppManager. La Surface corrente viene passata al SurfaceCallback nel SurfaceContainer parametro dei onSurfaceAvailable() e onSurfaceDestroyed() callback.

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

Utilizza un display virtuale per il rendering dei contenuti

Oltre al rendering direttamente nella Surface utilizzando l'API Canvas, puoi anche eseguire il rendering delle visualizzazioni nella Surface utilizzando le API VirtualDisplay e Presentation, come mostrato in questo esempio:

class HelloWorldSurfaceCallback(context: Context) : SurfaceCallback {
  lateinit var virtualDisplay: VirtualDisplay
  lateinit var presentation: Presentation

  override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
      virtualDisplay = context
          .getSystemService(DisplayManager::class.java)
          .createVirtualDisplay(
              VIRTUAL_DISPLAY_NAME ,
              surfaceContainer.width,
              surfaceContainer.height,
              surfaceContainer.dpi,
              surfaceContainer.surface,
              0
          )

      presentation = Presentation(context, virtualDisplay.display)

      // Instantiate the view to be used as the content view
      val view = ...

      presentation.setContentView(view)
      presentation.show()
  }

  override fun onSurfaceDestroyed(surfaceContainer: SurfaceContainer) {
    presentation.dismiss()
    // This handles releasing the Surface provided when creating the VirtualDisplay
    virtualDisplay.release()
  }
}

Utilizza Compose per il rendering sul display virtuale

Puoi utilizzare un ComposeView come visualizzazione dei contenuti di Presentation. Poiché ComposeView viene utilizzato al di fuori di un'attività, verifica che propaghi un LifecycleOwner e un SavedStateRegistryOwner o una vista genitore. Per farlo, utilizza setViewTreeLifecycleOwner e setViewTreeSavedStateRegistryOwner.

Session implementa già LifecycleOwner. Per svolgere entrambi i ruoli, l'implementazione può anche implementare SavedStateRegistryOwner.

class HelloWorldSession() : Session(), SavedStateRegistryOwner { ... }

class HelloWorldSurfaceCallback(session: HelloWorldSession) : SurfaceCallback {
  ...

  override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
    ...
    val view = ComposeView(session.carContext)
    view.setViewTreeLifecycleOwner(session)
    view.setViewTreeSavedStateRegistryOwner(session)
    view.setContent {
      // Composable content
    }

    presentation.setContentView(view)
    presentation.show()
  }

  ...
}

Informazioni sull'area visibile della superficie

L'host può disegnare elementi dell'interfaccia utente per i modelli sopra la mappa. L'host chiama il metodo SurfaceCallback.onVisibleAreaChanged per comunicare l'area della superficie che ha maggiori probabilità di essere libera e visibile all'utente.

Per ridurre al minimo il numero di modifiche, l'host chiama il SurfaceCallback.onStableAreaChanged metodo con il rettangolo più piccolo, che è sempre visibile in base al modello corrente.

Ad esempio, quando un'app di navigazione utilizza NavigationTemplate con una barra delle azioni in alto, per aumentare lo spazio sullo schermo la barra delle azioni può essere nascosta quando l'utente non interagisce con lo schermo. In questo caso, viene eseguito un callback a onStableAreaChanged e onVisibleAreaChanged con lo stesso rettangolo.

Quando la barra delle azioni è nascosta, viene chiamato solo onVisibleAreaChanged con l'area più grande. Se l'utente interagisce con lo schermo, viene chiamato solo onVisibleAreaChanged con il primo rettangolo.

Supporta il tema scuro

Le app devono ridisegnare la mappa sull'istanza Surface con i colori scuri appropriati quando l'host determina che le condizioni lo giustificano, come descritto in Qualità delle app per Android per le auto.

Per disegnare una mappa scura, utilizza il CarContext.isDarkMode metodo. Quando lo stato del tema scuro cambia, ricevi una chiamata a Session.onCarConfigurationChanged.

Disegna mappe sul display del quadro strumenti

Oltre a disegnare mappe sul display principale, le app di navigazione possono anche supportare il disegno di mappe sul display del quadro strumenti dietro il volante. Per saperne di più, consulta Disegnare sul display del quadro strumenti.