Panduan integrasi untuk OEM

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Halaman ini menjelaskan cara memproses input dari alat rotasi di VHAL, mengonfigurasi build untuk menyertakan layanan alat rotasi, dan cara menyesuaikan pengalaman alat rotasi di semua aplikasi. Untuk aplikasi OEM yang diprainstal, seperti peluncur yang disediakan OEM, lihat Library UI Mobil (car-ui-library).

VHAL

Pengontrol rotari mendukung tindakan berikut:

• Geser ke atas, bawah, kiri, dan kanan.
• Putar searah jarum jam dan berlawanan arah jarum jam.
• Tekan tombol Tengah.
• Tekan tombol Kembali.
• Tekan tombol Layar utama.
• Tekan tombol lain, seperti Telepon dan Media.

Lihat hardware/interfaces/automotive/vehicle/2.0/types.hal untuk dokumentasi tentang properti sistem dan int32Values yang sesuai.

VHAL harus menangani tindakan berikut:

• Senggol
• Putar
• Tombol tengah
• Tombol kembali
• Tombol layar utama
• Tombol lainnya

Senggol

Saat pengguna mendorong pengontrol putar ke kanan, VHAL harus menggunakan properti HW_KEY_INPUT dengan int32Values berikut untuk mengirim peristiwa ke Android:

1. ACTION_DOWN
2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
3. Tampilan target.

Saat pengguna melepaskan pengontrol putar, VHAL harus menggunakan properti dan kode kunci yang sama dengan ACTION_UP. Dorongan ke arah lain harus menggunakan kode kunci yang sesuai.

Tidak ada kode kunci untuk diagonal, tetapi VHAL dapat menggabungkan peristiwa horizontal dan vertikal untuk menghasilkan diagonal jika hardware mendukung diagonal. Misalnya, mendorong ke atas dan ke kiri akan menghasilkan:

• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

Dalam urutan mana pun (dan selanjutnya), melepaskan pengontrol rotasi akan menghasilkan:

• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

Pengguna dapat mendorong pengontrol putar ke arah tegak lurus sebelum melepaskannya. Misalnya, skenario berikut:

Tindakan ini akan menghasilkan urutan peristiwa berikut:

1. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
2. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN
3. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
4. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

Tidak ada peristiwa repeat yang akan dihasilkan saat pengontrol putar dipegang dalam satu arah.

Putar

Saat pengguna memutar pengontrol putar searah jarum jam dengan satu detent (klik), VHAL harus menggunakan properti HW_ROTARY_INPUT dengan int32Values berikut untuk mengirim peristiwa ke Android:

1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
2. Satu (1) detent.
3. Tampilan target.

Stempel waktu peristiwa harus ditetapkan ke waktu yang berlalu dalam nanodetik.

Rotasi satu (1) detent berlawanan arah jarum jam akan menghasilkan peristiwa yang sama, tetapi dengan -1 untuk jumlah detent.

Jika beberapa detent rotasi dalam arah yang sama terjadi secara berurutan dengan cepat, VHAL harus menggabungkan detent menjadi satu peristiwa agar tidak membebani sistem dengan peristiwa. Dalam hal ini, stempel waktu peristiwa harus saat detent rotasi pertama terjadi. int32Values harus menyertakan jumlah nanodetik di antara detent berturut-turut rotasi.

Misalnya, urutan rotasi berikut:

• Pada waktu t0, pengguna memutar satu detent berlawanan arah jarum jam.
• Pada waktu t0 + 5 ns, pengguna memutar satu detent berlawanan arah jarum jam.
• Pada waktu t0 + 8 ns, pengguna memutar satu detent berlawanan arah jarum jam.

akan menghasilkan peristiwa ini:

• Properti: HW_ROTARY_INPUT
• Stempel waktu: t0
• int32Values:
  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. -3 (tiga detent berlawanan arah jarum jam).
  3. Tampilan target.
  4. 5 ns antara detent pertama dan kedua.
  5. 3 ns antara detent kedua dan ketiga.

Tombol tengah

Saat pengguna menekan tombol Tengah, VHAL harus menggunakan properti HW_KEY_INPUT dengan int32Values berikut untuk mengirim peristiwa ke Android:

1. ACTION_DOWN
2. KEYCODE_DPAD_CENTER
3. Tampilan target.

Saat pengguna melepaskan pengontrol rotasi, VHAL harus menggunakan properti dan kode kunci yang sama dengan ACTION_UP.

Jangan buat peristiwa ulang saat tombol Tengah ditekan.

Tombol kembali

Saat pengguna menekan tombol Kembali, VHAL harus menggunakan properti HW_KEY_INPUT dengan int32Values berikut untuk mengirim peristiwa ke Android:

1. ACTION_DOWN
2. KEYCODE_BACK
3. Tampilan target.

Saat pengguna melepaskan pengontrol rotasi, VHAL harus menggunakan properti dan kode kunci yang sama dengan ACTION_UP.

Tidak ada peristiwa ulang yang akan dihasilkan saat tombol Tengah ditekan.

Tombol beranda

Tangani tombol Layar utama seperti yang Anda lakukan pada tombol Kembali, tetapi dengan KEYCODE_HOME, bukan KEYCODE_BACK.

Tombol lainnya

Jika pengontrol dari alat rotasi menyertakan tombol tambahan, VHAL dapat menanganinya sesuai keinginan OEM karena tidak dianggap sebagai bagian dari alat rotasi dari perspektif Android. Tombol ini biasanya ditangani seperti tombol Kembali dan Beranda, tetapi dengan kode tombol yang berbeda. Misalnya, KEYCODE_CALL atau KEYCODE_MUSIC.

Konfigurasi build

Navigasi dari alat rotasi disediakan oleh layanan aksesibilitas yang disebut RotaryService. Untuk menyertakan layanan ini dalam image sistem untuk perangkat Anda, tambahkan baris berikut ke makefile Anda:

PRODUCT_PACKAGES += CarRotaryController

Anda juga dapat menyertakan paket berikut dalam build debug:

• RotaryPlayground Aplikasi referensi untuk alat rotasi (lihat RotaryPlayground).
• RotaryIME IME dari alat rotasi demo (lihat Editor Metode Input).
• CarRotaryImeRRO Overlay untuk RotaryIME.

Layanan rotasi diaktifkan secara otomatis saat perangkat melakukan booting dan saat terjadi pergantian pengguna. Tindakan ini memastikan bahwa pengguna dapat menggunakan pengontrol putar selama penyiapan.

Jika Anda menggunakan build yang sama untuk mobil dengan dan tanpa pengontrol putar, tambahkan CarRotaryController seperti yang ditunjukkan di atas sehingga kode yang diperlukan disertakan dalam build. Untuk mencegah layanan rotari diaktifkan pada mobil non-rotasi, buat RRO statis untuk menempatkan resource string rotaryService di packages/services/Car/service dengan string kosong. Anda akan menggunakan build yang sama, tetapi memiliki konfigurasi produk terpisah, untuk perangkat rotari dan non-rotary. Hanya yang kedua yang menyertakan overlay.

Penyesuaian

OEM dapat menyesuaikan logika penemuan fokus, sorotan fokus, dan beberapa item tambahan melalui overlay resource di lokasi berikut:

• car-ui-library terletak di packages/apps/Car/libs/car-ui-lib
• RotaryService terletak di packages/apps/Car/RotaryController
• Core terletak di frameworks/base/core

Histori senggol

OEM dapat mengonfigurasi apakah setiap dua jenis histori nudge diaktifkan atau tidak, dan jika ya, ukuran cache dan kebijakan masa berlaku. Semua ini dilakukan dengan mengganti berbagai resource car-ui-library.

Cache histori fokus

(Android 11 QPR3, Android 11 Car, Android 12)
Cache per FocusArea ini menyimpan tampilan yang terakhir difokuskan dalam FocusArea sehingga dapat difokuskan saat mendorong kembali ke FocusArea. Cache ini dapat dikonfigurasi dengan menempatkan resource library UI mobil berikut:

• car_ui_focus_history_cache_type:
  1. Cache dinonaktifkan.
  2. Cache akan berakhir masa berlakunya setelah beberapa waktu (lihat di bawah).
  3. Cache tidak akan pernah habis masa berlakunya.
• car_ui_focus_history_expiration_period_ms: Berapa milidetik sebelum cache berakhir jika jenis cache ditetapkan ke dua (2) (lihat di atas).

Cache histori FocusArea

(Android 11 QPR3, Android 11 Car, Android 12)
Cache ini menyimpan histori dorongan sehingga dorongan ke arah yang berlawanan dapat mengembalikan fokus ke FocusArea yang sama. Cache ini dapat dikonfigurasi dengan menempatkan resource car-ui-library berikut:

• car_ui_focus_area_history_cache_type:
  1. Cache dinonaktifkan.
  2. Masa berlaku cache akan berakhir setelah beberapa saat (lihat di bawah).
  3. Cache tidak memiliki batas waktu.
• car_ui_focus_area_history_expiration_period_ms: Berapa milidetik sebelum cache berakhir masa berlakunya jika jenis cache ditetapkan ke 2 (lihat di atas).
• car_ui_clear_focus_area_history_when_rotating: Apakah akan membatalkan cache saat pengguna memutar pengontrol.

Rotasi

(Android 11 QPR3, Android 11 Car, Android 12)
OEM dapat mengganti dua resource bilangan bulat di RotaryService untuk menentukan apakah ada akselerasi, seperti akselerasi mouse, untuk rotasi:

• rotation_acceleration_3x_ms: Interval waktu (dalam milidetik) yang digunakan untuk memutuskan apakah Google harus mempercepat rotasi pengontrol untuk detent rotasi. Jika interval antara detent ini dan detent rotasi sebelumnya lebih kecil dari nilai ini, detent ini akan diperlakukan sebagai tiga detent rotasi. Tetapkan ke 2147483647 untuk menonaktifkan akselerasi 3x.
• rotation_acceleration_2x_ms: Mirip dengan rotation_acceleration_3x_ms. Digunakan untuk akselerasi 2x. Tetapkan ke 2147483647 untuk menonaktifkan akselerasi 2x.

Akselerasi berfungsi paling baik jika ada stempel waktu individual untuk setiap detent rotasi, seperti diperlukan oleh VHAL. Jika tidak tersedia, RotaryService akan mengasumsikan bahwa detent rotasi memiliki jarak yang sama.

/**
     * Property to feed H/W rotary events to android
     *
     * int32Values[0] : RotaryInputType identifying which rotary knob rotated
     * int32Values[1] : number of detents (clicks), positive for clockwise,
     *                  negative for counterclockwise
     * int32Values[2] : target display defined in VehicleDisplay. Events not
     *                  tied to specific display must be sent to
     *                  VehicleDisplay#MAIN.
     * int32values[3 .. 3 + abs(number of detents) - 2]:
     *                  nanosecond deltas between pairs of consecutive detents,
     *                  if the number of detents is > 1 or < -1
     *
     * VehiclePropValue.timestamp: when the rotation occurred. If the number of
     *                             detents is > 1 or < -1, this is when the
     *                             first detent of rotation occurred.
     *
     * @change_mode VehiclePropertyChangeMode:ON_CHANGE
     * @data_enum RotaryInputType
     * @access VehiclePropertyAccess:READ
     */
    HW_ROTARY_INPUT = (
        0x0A20
        | VehiclePropertyGroup:SYSTEM
        | VehiclePropertyType:INT32_VEC
        | VehicleArea:GLOBAL),

Sorotan fokus

OEM dapat mengganti sorotan fokus default di framework Android dan beberapa resource sorotan fokus di car-ui-library.

Sorotan fokus default

Framework Android menyediakan sorotan fokus default melalui atribut selectableItemBackground. Di Theme.DeviceDefault, atribut ini mengacu pada item_background.xml di Core. OEM dapat menempatkan item_background.xml untuk mengubah drawable sorotan fokus default.

Drawable ini biasanya harus berupa StateListDrawable, yang menyesuaikan latar belakang berdasarkan berbagai kombinasi status, termasuk android:state_focused dan android:state_pressed. Saat pengguna menggunakan pengontrol putar untuk memfokuskan tampilan, android:state_focused akan menjadi true, tetapi android:state_pressed akan menjadi false. Jika pengguna kemudian menekan tombol Tengah pada pengontrol putar, android:state_focused dan android:state_pressed akan menjadi true saat pengguna menahan tombol. Saat pengguna melepaskan tombol, hanya android:state_focused yang akan tetap true.

car-ui-library menggunakan tema yang berasal dari Theme.DeviceDefault. Akibatnya, overlay ini memengaruhi aplikasi yang menggunakan library ini dan aplikasi yang menggunakan tema apa pun yang berasal dari Theme.DeviceDefault. Hal ini tidak akan memengaruhi aplikasi yang menggunakan tema yang tidak terkait, seperti Theme.Material.

Memfokuskan resource sorotan di car-ui-library

OEM dapat mengganti beberapa resource library UI mobil untuk mengontrol tampilan penanda fokus pada tampilan dengan penanda fokus non-persegi panjang (seperti bulat atau berbentuk pil) dan di aplikasi yang menggunakan tema yang tidak berasal dari Theme.DeviceDefault. Resource ini harus ditempatkan sehingga sorotan fokus konsisten dengan drawable sorotan fokus default.

(Android 11 QPR3, Android 11 Car, Android 12)
Resource berikut digunakan untuk menunjukkan kapan tampilan difokuskan, tetapi tidak ditekan:

• car_ui_rotary_focus_fill_color: Warna isian.
• car_ui_rotary_focus_stroke_color: Warna garis batas.
• car_ui_rotary_focus_stroke_width: Ketebalan garis batas.

(Android 11 QPR3, Android 11 Car, Android 12)
Resource berikut digunakan untuk menunjukkan kapan tampilan difokuskan dan ditekan:

• car_ui_rotary_focus_pressed_fill_color: Warna isian.
• car_ui_rotary_focus_pressed_stroke_color: Warna garis batas.
• car_ui_rotary_focus_pressed_stroke_width: Ketebalan garis batas.

Terkadang tombol diberi warna latar belakang solid untuk menarik perhatian pengguna, seperti dalam contoh yang ditampilkan. Hal ini dapat membuat sorotan fokus sulit dilihat.

• (Android 11 QPR3, Android 11 Car, Android 12)
  car_ui_rotary_focus_fill_secondary_color
car_ui_rotary_focus_stroke_secondary_color
• (Android 12)
  car_ui_rotary_focus_pressed_fill_secondary_color
car_ui_rotary_focus_pressed_stroke_secondary_color

Semua warna dapat transparan dan salah satu dimensi dapat nol jika, misalnya, Anda hanya menginginkan isi atau hanya garis batas.

Sorotan FocusArea

(Android 11 QPR3, Android 11 Car, Android 12)
FocusArea dapat menggambar dua jenis sorotan saat salah satu turunannya difokuskan. Keduanya dapat digunakan bersama-sama, jika diinginkan. Fitur ini dinonaktifkan secara default di AOSP, tetapi dapat diaktifkan dengan mengganti resource library UI mobil:

• car_ui_enable_focus_area_foreground_highlight: Menggambar sorotan di atas FocusArea dan turunannya. Di AOSP, drawable ini adalah garis batas di sekitar FocusArea. OEM dapat mengganti drawable car_ui_focus_area_foreground_highlight.
• car_ui_enable_focus_area_background_highlight: Menggambar sorotan di atas FocusArea, tetapi di belakang turunannya. Di AOSP, drawable ini adalah isian solid. OEM dapat mengganti drawable car_ui_focus_area_background_highlight.

Editor Metode Masukan

Editor Metode Input (IME) adalah metode input. Misalnya, keyboard virtual.

(Android 11 QPR3, Android 11 Car, Android 12)
OEM harus menempatkan ulang resource string default_touch_input_method di RotaryService untuk menentukan ComponentName IME berbasis sentuh. Misalnya, jika OEM menggunakan IME yang disediakan dengan Android Automotive, OEM harus menentukan com.google.android.apps.automotive.inputmethod/.InputMethodService.

(Android 11 QPR3, Android 11 Car, Android 12)
Jika OEM telah membuat IME khusus untuk perangkat putar, OEM harus menentukan ComponentName-nya di resource rotary_input_method. Jika resource ini ditumpangkan, IME yang ditentukan akan digunakan setiap kali pengguna berinteraksi dengan head unit melalui tombol dorong, putar, dan Tengah pengontrol rotasi. Saat pengguna menyentuh layar, IME sebelumnya akan digunakan. Tombol Kembali (dan tombol lain di pengontrol putar) tidak memengaruhi pemilihan IME. Jika resource ini tidak ditempatkan, tidak akan terjadi pengalihan IME. Cardboard tidak mendukung alat rotasi sehingga pengguna tidak dapat memasukkan teks melalui pengontrol alat rotasi jika OEM belum menyediakan IME alat rotasi.

RotaryIME adalah IME putar demo. Meskipun dasar, ini cukup untuk mencoba pengalihan IME otomatis yang dijelaskan di atas. Kode sumber untuk RotaryIME dapat ditemukan di packages/apps/Car/tests/RotaryIME/.

Saran tindak lanjut di luar layar

Secara default, saat pengguna mencoba mendorong dari tepi layar, tidak ada yang terjadi. OEM dapat mengonfigurasi hal yang akan terjadi untuk masing-masing dari empat arah dengan menentukan kombinasi dari:

1. Tindakan global yang ditentukan oleh AccessibilityService. Contoh: GLOBAL_ACTION_BACK.
2. Kode kunci, seperti KEYCODE_BACK.
3. Intent untuk meluncurkan aktivitas yang direpresentasikan sebagai URL.

(Android 11 QPR3, Android 11 Car, Android 12)
Ini ditentukan dengan menempatkan ulang resource array berikut di RotaryService:

• off_screen_nudge_global_actions: Array tindakan global yang akan dilakukan saat pengguna mendorong ke atas, bawah, kiri, atau kanan dari tepi layar. Tidak ada tindakan global yang dilakukan jika elemen yang relevan dari array ini adalah -1.
• off_screen_nudge_key_codes: Array kode kunci peristiwa klik untuk dimasukkan saat pengguna mendorong ke atas, bawah, kiri, atau kanan dari tepi layar. Tidak ada peristiwa yang dimasukkan jika elemen yang relevan dari array ini adalah 0 (KEYCODE_UNKNOWN).
• off_screen_nudge_intents: Array intent untuk meluncurkan aktivitas saat pengguna mendorong ke atas, bawah, kiri, atau kanan dari tepi layar. Tidak ada aktivitas yang diluncurkan jika elemen yang relevan dari array ini kosong.

Konfigurasi lainnya

Anda harus menempatkan resource RotaryService berikut:

• (Android 11 QPR3, Android 11 Car, Android 12)
  config_showHeadsUpNotificationOnBottom: Nilai boolean untuk menunjukkan apakah notifikasi pemberitahuan harus ditampilkan di bagian bawah, bukan di bagian atas. Nilai ini harus memiliki nilai yang sama dengan resource Boolean config_showHeadsUpNotificationOnBottom di frameworks/base/packages/CarSystemUI/res/values/config.xml
• (Android 11 QPR3, Android 11 Car, Android 12)
  notification_headsup_card_margin_horizontal: Margin kiri dan kanan untuk jendela notifikasi heads-up. Nilai ini harus sama dengan resource dimen notification_headsup_card_margin_horizontal di packages/apps/Car/Notification/res/values/dimens.xml
• (Android 12)
  excluded_application_overlay_window_titles: Array judul jendela yang tidak boleh dianggap sebagai jendela overlay. Ini harus mencakup judul jendela aplikasi yang mewakili TaskViews atau TaskDisplayAreas. Secara default, daftar ini hanya berisi "Maps".

Anda dapat menempatkan resource RotaryService berikut:

• (Android 11 QPR3, Android 11 Car, Android 12)
  long_press_ms: Nilai bilangan bulat untuk merepresentasikan berapa milidetik Tombol tengah harus ditekan untuk memicu penekanan lama. Nol menunjukkan waktu tunggu default tekan lama sistem harus digunakan. Nilai ini merupakan default.