Menggambar peta

Aplikasi navigasi, lokasi menarik (POI), dan cuaca yang menggunakan template berikut dapat menggambar peta dengan mengakses Surface.

Untuk menggunakan template berikut, aplikasi Anda harus mendeklarasikan salah satu izin yang sesuai ini dalam elemen <uses-permission> di file AndroidManifest.xml.

Lihat penerapan referensi

Untuk melihat implementasi referensi lengkap, lihat Contoh Navigasi.

Mendeklarasikan izin platform

Selain izin yang diperlukan untuk template yang digunakan aplikasi Anda, aplikasi Anda harus mendeklarasikan izin androidx.car.app.ACCESS_SURFACE dalam file AndroidManifest.xml-nya untuk mendapatkan akses ke platform:

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

Mengakses platform

Untuk mengakses Surface yang disediakan host, Anda harus menerapkan SurfaceCallback dan memberikan implementasi tersebut ke layanan mobil AppManager. Surface saat ini diteruskan ke SurfaceCallback Anda dalam parameter SurfaceContainer dari callback onSurfaceAvailable() dan onSurfaceDestroyed().

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

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

Menggunakan layar virtual untuk merender konten

Selain merender langsung ke Surface menggunakan Canvas API, Anda juga dapat merender View ke Surface menggunakan VirtualDisplay dan Presentation API, seperti yang ditunjukkan contoh ini:

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()
  }
}

Menggunakan Compose untuk merender ke tampilan virtual

Anda dapat menggunakan ComposeView sebagai tampilan konten Presentation. Karena ComposeView digunakan di luar aktivitas, konfirmasi bahwa ComposeView atau tampilan induk menyebarkan LifecycleOwner dan SavedStateRegistryOwner. Untuk melakukannya, gunakan setViewTreeLifecycleOwner dan setViewTreeSavedStateRegistryOwner.

Session sudah mengimplementasikan LifecycleOwner. Untuk memenuhi kedua peran, penerapan Anda juga dapat menerapkan 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()
  }

  ...
}

Memahami area yang terlihat di permukaan

Host dapat menggambar elemen antarmuka pengguna untuk template di atas peta. Host memanggil metode SurfaceCallback.onVisibleAreaChanged untuk mengomunikasikan area permukaan yang kemungkinan besar tidak terhalang dan terlihat oleh pengguna.

Untuk meminimalkan jumlah perubahan, host memanggil metode SurfaceCallback.onStableAreaChanged dengan kotak terkecil, yang selalu terlihat sesuai dengan template saat ini.

Misalnya, saat aplikasi navigasi menggunakan NavigationTemplate dengan strip tindakan di atasnya, untuk membuat lebih banyak ruang di layar, strip tindakan dapat disembunyikan saat pengguna tidak berinteraksi dengan layar. Kasus ini menghasilkan callback ke onStableAreaChanged dan onVisibleAreaChanged dengan kotak yang sama.

Jika strip tindakan disembunyikan, hanya onVisibleAreaChanged yang dipanggil dengan area yang lebih besar. Jika pengguna berinteraksi dengan layar, hanya onVisibleAreaChanged yang dipanggil dengan kotak pertama.

Mendukung tema gelap

Aplikasi harus menggambar ulang peta ke instance Surface dengan warna gelap yang sesuai saat host menentukan bahwa kondisi menjaminnya, seperti yang dijelaskan dalam Kualitas aplikasi Android untuk mobil.

Untuk menggambar peta gelap, gunakan metode CarContext.isDarkMode. Saat status tema gelap berubah, Anda menerima panggilan ke Session.onCarConfigurationChanged.

Menggambar peta di layar cluster

Selain menggambar peta di layar utama, aplikasi navigasi juga dapat mendukung penggambaran peta di layar cluster di belakang kemudi. Untuk mempelajari lebih lanjut, lihat Menggambar ke tampilan cluster.