Ekstensi WindowManager

Library Jetpack WindowManager memungkinkan developer aplikasi mendukung faktor bentuk perangkat dan lingkungan multi-aplikasi baru.

Ekstensi WindowManager (Ekstensi) adalah modul platform Android yang dapat diikutsertakan yang memungkinkan berbagai fitur Jetpack WindowManager. Modul ini diimplementasikan di AOSP di frameworks/base/libs/WindowManager/Jetpack dan dikirimkan di perangkat yang mendukung fitur WindowManager.

Distribusi modul ekstensi

Ekstensi dikompilasi ke dalam library .jar dan ditempatkan di partisi system_ext pada perangkat jika Extensions diaktifkan di makefile perangkat.

Untuk mengaktifkan Ekstensi di perangkat, tambahkan kode berikut ke makefile perangkat produk:

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

Tindakan ini akan mengaktifkan paket androidx.window.extensions dan androidx.window.sidecar di perangkat dan menetapkan properti persist.wm.extensions.enabled. Menyertakan paket ini dalam makefile juga menempatkan deklarasi di etc/permissions/, sehingga tersedia untuk proses aplikasi. Biasanya, modul dimuat ke dalam dan dijalankan sebagai bagian dari proses aplikasi pada runtime saat digunakan oleh library Jetpack WindowManager, yang membuat operasinya mirip dengan kode framework sisi klien, seperti yang ditunjukkan dalam gambar berikut:

Modul androidx.window.extensions adalah modul Ekstensi saat ini yang sedang dalam pengembangan aktif. Modul androidx.window.sidecar adalah modul lama yang disertakan untuk kompatibilitas dengan Jetpack WindowManager versi paling awal, tetapi file bantuan tidak lagi dikelola secara aktif.

Gambar berikut menunjukkan logika untuk menentukan penggunaan androidx.window.extensions atau androidx.window.sidecar.

Modul ekstensi

Ekstensi menyediakan fitur windowing untuk perangkat layar besar foldable dan perangkat yang mendukung windowing di layar eksternal. Area fitur meliputi:

• Penyematan aktivitas
• Informasi tata letak jendela
• Area jendela

Implementasi OEM Ekstensi dapat menyediakan komponen atau komponen null dengan implementasi default atau stub dari metode dalam antarmuka WindowExtensions jika hardware perangkat tidak mendukung fitur terkait, kecuali jika fitur tersebut diminta secara khusus dalam Compatibility Definition Document (CDD) 7.1.1.1.

Ekstensi dan Jetpack API

Modul Ekstensi WindowManager menyediakan platform API-nya sendiri selain API platform publik. Modul Ekstensi dikembangkan secara publik di library Jetpack androidx.window.extensions yang tidak ditujukan untuk developer, sehingga Jetpack WindowManager (androidx.window) dapat menautkan ke library tersebut pada waktu kompilasi. Platform Extensions API biasanya menyediakan API dengan tingkat yang lebih rendah.

API yang disediakan Ekstensi dimaksudkan untuk digunakan oleh library WindowManager Jetpack saja. Extensions API tidak dimaksudkan untuk dipanggil langsung oleh developer aplikasi. Library Ekstensi tidak boleh ditambahkan sebagai dependensi untuk aplikasi dalam file build Gradle untuk memastikan fungsi yang benar. Hindari prakompilasi library Ekstensi ke dalam aplikasi secara langsung; sebagai gantinya, andalkan pemuatan runtime untuk mencegah pemuatan campuran class Ekstensi yang dikompilasi sebelumnya dan disediakan runtime.

Jetpack WindowManager (androidx.window) dimaksudkan untuk ditambahkan sebagai dependensi aplikasi dan menyediakan API yang ditampilkan kepada developer publik, termasuk API untuk fitur Ekstensi WindowManager. Library WindowManager memuat Ekstensi secara otomatis ke dalam proses aplikasi dan menggabungkan Extensions API dengan tingkat yang lebih rendah ke dalam abstraksi tingkat yang lebih tinggi dan antarmuka yang lebih terfokus. WindowManager Jetpack API mengikuti standar pengembangan aplikasi Android modern dan dimaksudkan untuk menyediakan interoperabilitas yang mudah melalui integrasi secara baik dengan codebase yang menggunakan library AndroidX lainnya.

Versi dan update ekstensi

Modul Ekstensi dapat diupdate bersama dengan update platform Android tahunan atau kuartalan. Dengan update kuartalan, API level Ekstensi dapat ditingkatkan di antara update API platform Android, sehingga memungkinkan iterasi yang lebih cepat dan memberi OEM peluang untuk menambahkan akses API resmi ke fitur baru yang mendekati peluncuran hardware.

Tabel berikut mencantumkan versi API androidx.window.extensions untuk berbagai rilis Android.

Level Extensions API (kolom tengah) ditingkatkan setiap kali ada penambahan ke platform API stabil yang ada (kolom kanan).

Kompatibilitas mundur dan maju

Jetpack WindowManager menangani kompleksitas dalam menangani update level API yang sering terjadi, evolusi API yang cepat, dan kompatibilitas mundur. Saat kode library dieksekusi dalam proses aplikasi, library akan memeriksa level API Ekstensi yang dideklarasikan dan memberikan akses ke fitur sesuai dengan level yang dideklarasikan.

Untuk melindungi aplikasi agar tidak error saat runtime, WindowManager juga melakukan pemeriksaan refleksi Java runtime dari Extensions API yang tersedia sesuai dengan level API Extensions yang dideklarasikan. Jika ada ketidakcocokan, WindowManager dapat menonaktifkan penggunaan Ekstensi (sebagian atau sepenuhnya) dan melaporkan fitur yang relevan sebagai tidak tersedia untuk aplikasi.

Ekstensi WindowManager diimplementasikan sebagai modul system_ext yang menggunakan API platform pribadi untuk memanggil core WindowManager, DeviceStateManager, dan layanan sistem lainnya dalam penerapan fitur Ekstensi.

Kompatibilitas mungkin tidak dapat dipertahankan dengan Ekstensi versi pra-rilis sebelum rilis platform Android per kuartal atau tahunan yang terkait ketika versi tersebut telah diselesaikan. Histori lengkap Extensions API dapat ditemukan di cabang rilis file teks window:extensions:extensions API.

Ekstensi versi yang lebih baru harus terus berfungsi dengan WindowManager versi lama yang dikompilasi ke dalam aplikasi untuk mempertahankan kompatibilitas ke depan. Untuk memastikan hal ini, setiap versi baru Extensions API hanya menambahkan API baru dan tidak menghapus API yang lebih lama. Akibatnya, aplikasi dengan versi WindowManager lama dapat terus menggunakan API Ekstensi lama yang dikompilasi oleh aplikasi.

Verifikasi CTS memastikan bahwa untuk setiap versi Extensions API yang dideklarasikan di perangkat, semua API untuk versi tersebut dan versi sebelumnya ada dan berfungsi.

Performa

Modul Ekstensi di-cache di loader class sistem non-bootclasspath secara default mulai Android 14 (API level 34), sehingga tidak ada dampak performa karena memuat modul ke dalam memori saat aplikasi dimulai. Menggunakan fitur modul individual mungkin memiliki sedikit pengaruh terhadap karakteristik kinerja aplikasi saat panggilan IPC tambahan dilakukan antara klien dan server.

Modul

Penyematan aktivitas

Komponen Penyematan aktivitas menyediakan sekumpulan fitur yang memungkinkan aplikasi mengatur presentasi jendela aktivitas dalam batas-batas aplikasi induk. Hal ini termasuk menampilkan dua aktivitas secara bersamaan dalam tata letak multi-panel, yang memfasilitasi pengoptimalan perangkat layar besar untuk aplikasi lama.

Komponen penyematan aktivitas harus tersedia di semua perangkat yang memiliki layar bawaan berukuran sama dengan atau lebih besar dari sw600 dp. Penyematan aktivitas juga harus diaktifkan di perangkat yang mendukung koneksi layar eksternal, karena aplikasi mungkin ditampilkan dalam ukuran yang lebih besar ketika layar eksternal terhubung saat runtime.

Konfigurasi perangkat

Tidak ada konfigurasi perangkat khusus yang diperlukan selain mengaktifkan modul Ekstensi seperti yang dijelaskan di bagian Distribusi modul ekstensi. Masuk akal untuk mengaktifkan Ekstensi di semua perangkat yang mendukung mode multi-aplikasi. Versi Android mendatang kemungkinan akan membuat Ekstensi diperlukan pada konfigurasi perangkat genggam dan layar besar yang umum.

Informasi tata letak jendela

Komponen informasi tata letak jendela mengidentifikasi posisi dan status engsel pada perangkat foldable saat engsel melintasi jendela aplikasi. Informasi tata letak jendela memungkinkan aplikasi merespons dan menampilkan tata letak yang dioptimalkan dalam mode di atas meja di perangkat foldable. Lihat Membuat aplikasi Anda fold aware untuk mengetahui detail penggunaan.

Perangkat Android foldable yang menyertakan engsel yang menghubungkan area panel layar terpisah atau berkelanjutan harus menyediakan informasi tentang engsel untuk aplikasi melalui WindowLayoutComponent.

Posisi dan batas engsel harus dilaporkan relatif terhadap jendela aplikasi yang diidentifikasi oleh Context yang diteruskan ke API. Jika batas jendela aplikasi tidak bersinggungan dengan batas engsel, DisplayFeature engsel tidak boleh dilaporkan. Anda juga dapat tidak melaporkan fitur tampilan saat posisinya mungkin tidak dilaporkan dengan andal, seperti saat jendela aplikasi dapat dipindahkan secara bebas oleh pengguna dalam mode multi-aplikasi atau mode tampilan lebar kompatibilitas.

Untuk fitur lipat, update status harus dilaporkan saat posisi engsel berubah antar status stabil. Secara default dalam status tampilan datar, API harus melaporkan FoldingFeature.State.FLAT. Jika hardware perangkat dapat dibiarkan dalam mode setengah dilipat dalam status stabil, API harus melaporkan FoldingFeature.State.HALF_OPENED. Tidak ada status tertutup di API, karena dalam kasus seperti itu, jendela aplikasi tidak akan terlihat atau tidak akan melintasi batas engsel.

Konfigurasi perangkat

Untuk mendukung penerapan fitur lipat, OEM harus melakukan hal berikut:

• Konfigurasi status perangkat di device_state_configuration.xml yang akan digunakan oleh DeviceStateManagerService. Lihat DeviceStateProviderImpl.java untuk referensi.

  Jika implementasi default DeviceStateProvider atau DeviceStatePolicy tidak cocok untuk perangkat, implementasi kustom dapat digunakan.

• Aktifkan modul Ekstensi seperti yang dijelaskan di bagian Distribusi modul ekstensi.

• Tentukan lokasi fitur tampilan dalam resource string com.android.internal.R.string.config_display_features (biasanya di frameworks/base/core/res/res/values/config.xml dalam overlay perangkat).

  Format yang diharapkan untuk string adalah:

  <type>-[<left>,<top>,<right>,<bottom>]

  type dapat berupa fold atau hinge. Nilai untuk left, top, right, dan bottom adalah koordinat piksel bilangan bulat dalam ruang koordinat tampilan dalam orientasi tampilan alami. String konfigurasi dapat berisi beberapa fitur tampilan yang dipisahkan dengan titik koma.

  Contoh:

  <!-- Jetpack WindowManager display features -->
  <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
  

• Tentukan pemetaan antara ID status perangkat internal yang digunakan di DeviceStateManager dan konstanta status publik yang dikirim ke developer di com.android.internal.R.array.config_device_state_postures.

  Format yang diharapkan untuk setiap entri adalah:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  ID status yang didukung adalah:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: Status tidak memiliki fitur lipat untuk dilaporkan. Misalnya, status tertutup dari perangkat lipat biasa dengan layar utama di sisi dalam.
  • COMMON_STATE_HALF_OPENED = 2: Fitur lipat setengah terbuka.
  • COMMON_STATE_FLAT = 3: Fitur lipat datar. Misalnya, status ini dapat berupa status terbuka dari perangkat lipat standar dengan layar utama di sisi dalam.
  • COMMON_STATE_USE_BASE_STATE = 1000: Di Android 14, nilai yang dapat digunakan untuk status yang diemulasi dengan status engsel yang berasal dari status dasar, seperti yang ditentukan dalam CommonFoldingFeature.java

  Lihat DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) untuk mengetahui informasi selengkapnya.

  Contoh:

  <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
  <string-array name="config_device_state_postures" translatable="false">
      <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
      <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
      <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
  </string-array>
  

Area jendela

Komponen area jendela menyediakan serangkaian fitur yang memberi aplikasi akses ke tampilan dan area tampilan tambahan di beberapa perangkat foldable dan multi-tampilan.

Mode tampilan belakang memungkinkan aplikasi menampilkan UI pratinjau kamera di layar penutup perangkat foldable untuk memungkinkan penggunaan kamera perangkat utama untuk selfie dan video. Perangkat yang memiliki tampilan penutup yang kompatibel dengan Android (sebagaimana ditentukan oleh CDD Android dalam hal atribut seperti ukuran, kepadatan, dan fitur navigasi yang tersedia) yang sejajar dengan kamera perangkat belakang harus memberikan akses ke mode tampilan belakang.

Di Android 14, mode layar ganda memungkinkan aplikasi yang berjalan di layar dalam perangkat foldable untuk menampilkan konten tambahan di layar penutup yang menghadap pengguna lain; misalnya, layar penutup dapat menampilkan pratinjau kamera kepada orang yang difoto atau direkam.

Konfigurasi perangkat

Untuk mendukung penerapan fitur lipat, OEM harus melakukan hal berikut:

• Konfigurasi status perangkat di device_state_configuration.xml yang akan digunakan oleh DeviceStateManagerService. Lihat DeviceStateProviderImpl.java untuk mengetahui informasi selengkapnya.

  Jika penerapan default DeviceStateProvider atau DeviceStatePolicy tidak sesuai untuk perangkat, penerapan kustom dapat digunakan.

• Untuk perangkat foldable yang mendukung mode terbuka atau datar, tentukan ID status yang sesuai di com.android.internal.R.array.config_openDeviceStates.

• Untuk perangkat dalam lipatan yang mendukung status terlipat, cantumkan ID status yang sesuai di com.android.internal.R.array.config_foldedDeviceStates.

• Untuk perangkat foldable yang mendukung status setengah terlipat (engsel terbuka setengah seperti laptop), cantumkan status yang sesuai di com.android.internal.R.array.config_halfFoldedDeviceStates.

• Untuk perangkat yang mendukung mode tampilan belakang:

  • Cantumkan status yang sesuai di com.android.internal.R.array.config_rearDisplayDeviceStates untuk DeviceStateManager.
  • Tentukan alamat tampilan fisik layar belakang di com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Tentukan ID status di com.android.internal.R.integer.config_deviceStateRearDisplay yang akan digunakan oleh Ekstensi.
  • Tambahkan ID status di com.android.internal.R.array.config_deviceStatesAvailableForAppRequests agar tersedia untuk aplikasi.

• Di Android 14, untuk perangkat yang mendukung mode tampilan ganda (serentak):

  • Setel com.android.internal.R.bool.config_supportsConcurrentInternalDisplays ke true.
  • Tentukan alamat tampilan fisik layar belakang di com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Tentukan ID status di com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay yang akan digunakan oleh Ekstensi jika ID tersebut dimaksudkan untuk disediakan untuk aplikasi.
  • Tambahkan ID status di com.android.internal.R.array.config_deviceStatesAvailableForAppRequests agar tersedia untuk aplikasi.

Verifikasi

OEM harus memverifikasi penerapannya untuk memastikan perilaku yang diharapkan dalam skenario umum. Pengujian CTS dan pengujian menggunakan Jetpack WindowManager tersedia untuk OEM untuk menguji implementasi.

Uji CTS

Untuk menjalankan pengujian CTS, lihat Menjalankan pengujian CTS. Pengujian CTS yang terkait dengan Jetpack WindowManager berada di cts/tests/framework/base/windowmanager/jetpack/. Nama modul pengujian adalah CtsWindowManagerJetpackTestCases.

Pengujian WindowManager

Untuk mendownload pengujian Jetpack WindowManager, ikuti Petunjuk Android Jetpack. Pengujian terletak di library jendela pada modul window:window: window/window/src/androidTest/.

Untuk menjalankan pengujian perangkat untuk modul window:window dari command line, lakukan hal berikut:

1. Colokkan perangkat yang mengaktifkan opsi developer dan Proses debug USB.
2. Mengizinkan komputer men-debug perangkat.
3. Buka shell di direktori utama repositori androidx.
4. Ubah direktori ke framework/support.
5. Jalankan perintah berikut: ./gradlew window:window:connectedAndroidTest.
6. Menganalisis hasilnya.

Untuk menjalankan pengujian dari Android Studio, lakukan hal berikut:

1. Buka Android Studio.
2. Colokkan perangkat yang telah mengaktifkan opsi developer dan proses debug USB.
3. Izinkan komputer untuk men-debug perangkat.
4. Buka pengujian dalam library jendela modul jendela.
5. Buka class pengujian dan jalankan menggunakan panah hijau di sisi kanan editor.

Atau, Anda dapat membuat konfigurasi di Android Studio untuk menjalankan metode pengujian, class pengujian, atau semua pengujian dalam modul.

Hasil dapat dianalisis secara manual dengan melihat output shell. Beberapa pengujian akan dilewati jika perangkat tidak memenuhi asumsi tertentu. Hasil disimpan di lokasi standar, dan analis dapat menulis skrip untuk mengotomatiskan analisis hasil.