Halaman ini menjelaskan cara memproses input rotasi di VHAL, mengonfigurasi build Anda untuk menyertakan layanan rotasi, dan cara menyesuaikan pengalaman rotasi di semua aplikasi. Untuk aplikasi OEM yang sudah diinstal sebelumnya, seperti peluncur yang disediakan OEM, lihat Car UI Library (car-ui-library) .
VHAL
Pengontrol putar mendukung tindakan berikut:
- Dorongan ke atas, bawah, kiri, dan kanan.
- Putar searah jarum jam dan berlawanan arah jarum jam.
- Tekan tombol Tengah.
- Tekan tombol Kembali.
- Tekan tombol Beranda.
- 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:
Dorongan
Saat pengguna menekan pengontrol putar ke kanan, VHAL harus menggunakan properti HW_KEY_INPUT
dengan int32Values
berikut untuk mengirim peristiwa ke Android:
-
ACTION_DOWN
-
KEYCODE_SYSTEM_NAVIGATION_RIGHT
- Tampilan sasaran.
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 kejadian horizontal dan vertikal untuk menghasilkan diagonal jika perangkat keras mendukung diagonal. Misalnya, menyenggol 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 putar 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:
![Arah tegak lurus](https://source.android.com/static/docs/automotive/images/rotary_06.png?authuser=19&hl=id)
Ini harus menghasilkan urutan kejadian berikut:
-
HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
-
HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN
-
HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
-
HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP
Tidak ada peristiwa berulang yang dihasilkan saat pengontrol putar ditahan dalam satu arah.
Memutar
Saat pengguna memutar pengontrol putar searah jarum jam sebanyak satu kali penahan (klik), VHAL harus menggunakan properti HW_ROTARY_INPUT
dengan int32Values
berikut untuk mengirim peristiwa ke Android:
-
ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
- Satu (1) penahanan.
- Tampilan sasaran.
Stempel waktu acara harus disetel ke waktu yang telah berlalu dalam nanodetik.
Rotasi satu (1) penahan berlawanan arah jarum jam akan menghasilkan kejadian yang sama tetapi dengan -1 untuk jumlah penahan.
Jika beberapa penahan rotasi dalam arah yang sama terjadi secara berurutan, VHAL harus menggabungkan penahan tersebut menjadi satu kejadian sehingga tidak membebani sistem dengan kejadian yang berlebihan. Dalam hal ini, stempel waktu kejadian haruslah saat penahanan rotasi pertama kali terjadi. int32Values
harus mencakup jumlah nanodetik antara penahanan rotasi berturut-turut.
Misalnya urutan putaran berikut:
- Pada waktu t0, pengguna memutar satu penahan berlawanan arah jarum jam.
- Pada waktu t0 + 5 ns, pengguna memutar satu penahan berlawanan arah jarum jam.
- Pada waktu t0 + 8 ns, pengguna memutar satu penahan berlawanan arah jarum jam.
harus menghasilkan acara ini:
- Properti:
HW_ROTARY_INPUT
- Stempel waktu:
t0
-
int32Values
:-
ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
- -3 (tiga penahan berlawanan arah jarum jam).
- Tampilan sasaran.
- 5 ns antara penahan pertama dan kedua.
- 3 ns antara penahan kedua dan ketiga.
-
Tombol tengah
Saat pengguna menekan tombol Tengah, VHAL harus menggunakan properti HW_KEY_INPUT
dengan int32Values
berikut untuk mengirim acara ke Android:
-
ACTION_DOWN
-
KEYCODE_DPAD_CENTER
- Tampilan sasaran.
Saat pengguna melepaskan pengontrol putar, VHAL harus menggunakan properti dan kode kunci yang sama dengan ACTION_UP
.
Jangan membuat kejadian berulang saat tombol Tengah ditekan.
Tombol kembali
Saat pengguna menekan tombol Kembali, VHAL harus menggunakan properti HW_KEY_INPUT
dengan int32Values
berikut untuk mengirim acara ke Android:
-
ACTION_DOWN
-
KEYCODE_BACK
- Tampilan sasaran.
Saat pengguna melepaskan pengontrol putar, VHAL harus menggunakan properti dan kode kunci yang sama dengan ACTION_UP
.
Tidak ada kejadian berulang yang dihasilkan saat tombol Tengah ditekan.
Tombol Home
Tangani tombol Beranda seperti yang Anda lakukan pada tombol Kembali tetapi dengan KEYCODE_HOME
alih-alih KEYCODE_BACK
.
Tombol lainnya
Jika pengontrol putar menyertakan tombol tambahan, VHAL dapat menanganinya sesuka OEM karena tombol tersebut tidak dianggap sebagai bagian dari putar dari perspektif Android. Ini biasanya ditangani seperti tombol Kembali dan Beranda tetapi dengan kode kunci yang berbeda. Misalnya, KEYCODE_CALL
atau KEYCODE_MUSIC
.
Bangun konfigurasi
Navigasi putar disediakan oleh layanan aksesibilitas yang disebut RotaryService
. Untuk menyertakan layanan ini dalam image sistem perangkat Anda, tambahkan baris berikut ke makefile Anda:
PRODUCT_PACKAGES += CarRotaryController
Anda mungkin juga ingin menyertakan paket berikut dalam debug build:
-
RotaryPlayground
Aplikasi referensi untuk rotary (lihat RotaryPlayground ). -
RotaryIME
IME putar demo (lihat Editor Metode Input ). -
CarRotaryImeRRO
Hamparan untukRotaryIME
.
Layanan putar diaktifkan secara otomatis saat perangkat melakukan booting dan saat terjadi peralihan pengguna. Hal ini memastikan bahwa pengguna dapat menggunakan pengontrol putar selama pengaturan.
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 putar diaktifkan pada mobil non-rotasi, buat RRO statis untuk melapisi sumber daya string rotaryService
di packages/services/Car/service
dengan string kosong. Anda akan menggunakan build yang sama, namun memiliki konfigurasi produk terpisah, untuk perangkat putar dan non-putar. Hanya yang terakhir yang menyertakan overlay.
Kustomisasi
OEM dapat menyesuaikan logika pencarian fokus, sorotan fokus, dan beberapa item tambahan melalui hamparan sumber daya di lokasi berikut:
- perpustakaan car-ui terletak di
packages/apps/Car/libs/car-ui-lib
-
RotaryService
terletak dipackages/apps/Car/RotaryController
-
Core
terletak diframeworks/base/core
Menyenggol sejarah
OEM dapat mengonfigurasi apakah masing-masing dari dua jenis riwayat dorongan diaktifkan atau tidak dan, jika demikian, ukuran cache dan kebijakan kedaluwarsa. Ini semua dilakukan dengan mengganti berbagai sumber daya car-ui-library.
Fokuskan cache riwayat
( Android 11 QPR3, Android 11 Mobil, Android 12 )
Cache per- FocusArea
ini menyimpan tampilan fokus terbaru dalam FocusArea
sehingga dapat difokus ketika kembali ke FocusArea
. Cache ini dapat dikonfigurasi dengan menghamparkan sumber daya car-ui-library berikut:
-
car_ui_focus_history_cache_type
:- Tembolok dinonaktifkan.
- Cache akan kedaluwarsa setelah beberapa waktu (lihat di bawah).
- Cache tidak akan pernah kadaluwarsa.
-
car_ui_focus_history_expiration_period_ms
: Berapa milidetik sebelum cache kedaluwarsa jika jenis cache diatur ke dua (2) (lihat di atas).
Cache riwayat FocusArea
( Android 11 QPR3, Android 11 Mobil, Android 12 )
Cache ini menyimpan riwayat dorongan sehingga dorongan ke arah berlawanan dapat mengembalikan fokus ke FocusArea
yang sama. Cache ini dapat dikonfigurasi dengan menghamparkan sumber daya car-ui-library berikut:
-
car_ui_focus_area_history_cache_type
:- Tembolok dinonaktifkan.
- Cache kedaluwarsa setelah beberapa waktu (lihat di bawah).
- Cache tidak pernah kedaluwarsa.
-
car_ui_focus_area_history_expiration_period_ms
: Berapa milidetik sebelum cache kedaluwarsa jika jenis cache disetel 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 Mobil, Android 12 )
OEM dapat mengambil alih dua sumber daya bilangan bulat di RotaryService
untuk menentukan apakah ada akselerasi, misalnya akselerasi mouse, untuk rotasi:
-
rotation_acceleration_3x_ms
: Interval waktu (dalam milidetik) yang digunakan untuk memutuskan apakah Google harus mempercepat rotasi pengontrol untuk menahan rotasi. Jika interval antara penahan ini dan penahan rotasi sebelumnya lebih kecil dari nilai ini, maka akan dianggap sebagai tiga penahan rotasi. Setel ini ke 2147483647 untuk menonaktifkan akselerasi 3×. -
rotation_acceleration_2x_ms
: Mirip denganrotation_acceleration_3x_ms
. Digunakan untuk akselerasi 2×. Setel ini ke2147483647
untuk menonaktifkan akselerasi 2×.
Akselerasi bekerja paling baik bila ada stempel waktu individual untuk setiap penahan rotasi, seperti yang disyaratkan oleh VHAL. Jika hal ini tidak tersedia, RotaryService
mengasumsikan bahwa penahan rotasi mempunyai 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 dalam kerangka Android dan beberapa sumber daya sorotan fokus di perpustakaan car-ui.
Sorotan fokus default
Kerangka kerja Android menyediakan sorotan fokus default melalui atribut selectableItemBackground
. Di Theme.DeviceDefault
, atribut ini merujuk ke item_background.xml
di Core
. OEM dapat melapisi item_background.xml
untuk mengubah drawable sorotan fokus default.
Sumber daya dapat digambar ini biasanya 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 bernilai true
, namun android:state_pressed
akan bernilai false
. Jika pengguna kemudian menekan tombol Tengah pada pengontrol putar, android:state_focused
dan android:state_pressed
akan true
saat pengguna menahan tombolnya. Saat pengguna melepas tombol, hanya android:state_focused
yang akan tetap true
.
car-ui-library menggunakan tema yang berasal dari Theme.DeviceDefault
. Akibatnya, hamparan ini memengaruhi aplikasi yang menggunakan perpustakaan ini dan aplikasi yang menggunakan tema apa pun yang berasal dari Theme.DeviceDefault
. Ini tidak akan memengaruhi aplikasi yang menggunakan tema yang tidak terkait, seperti Theme.Material
.
Fokus menyorot sumber daya di perpustakaan car-ui
OEM dapat mengganti beberapa sumber daya car-ui-library untuk mengontrol tampilan sorotan fokus pada tampilan dengan sorotan fokus non-persegi panjang (seperti bulat atau berbentuk pil) dan dalam aplikasi yang menggunakan tema yang tidak berasal dari Theme.DeviceDefault
. Sumber daya ini harus di-overlay sehingga sorotan fokus konsisten dengan sumber daya sorotan fokus default yang dapat digambar.
( Android 11 QPR3, Android 11 Mobil, Android 12 )
Sumber daya berikut digunakan untuk menunjukkan kapan tampilan difokuskan namun tidak ditekan:
-
car_ui_rotary_focus_fill_color
: Warna isian. -
car_ui_rotary_focus_stroke_color
: Warna garis luar. -
car_ui_rotary_focus_stroke_width
: Ketebalan garis luar.
( Android 11 QPR3, Android 11 Mobil, Android 12 )
Sumber daya 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 luar. -
car_ui_rotary_focus_pressed_stroke_width
: Ketebalan garis luar.
Terkadang sebuah tombol diberi warna latar belakang solid untuk menarik perhatian pengguna, seperti pada contoh yang ditunjukkan. Hal ini mungkin membuat sorotan fokus sulit dilihat.
![Tombol dengan latar belakang padat](https://source.android.com/static/docs/automotive/images/rotary_05.png?authuser=19&hl=id)
- ( Android 11 QPR3, Android 11 Mobil, 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
Warna apa pun bisa transparan dan dimensi mana pun bisa nol jika, misalnya, Anda hanya menginginkan isian atau kerangka saja.
Sorotan Area Fokus
( Android 11 QPR3, Android 11 Mobil, Android 12 )
FocusArea
dapat menggambar dua jenis sorotan ketika salah satu turunannya terfokus. Keduanya dapat digunakan bersamaan, jika diinginkan. Fitur ini dinonaktifkan secara default di AOSP, namun dapat diaktifkan dengan mengganti sumber daya car-ui-library:
-
car_ui_enable_focus_area_foreground_highlight
: Gambarkan sorotan di atasFocusArea
dan turunannya. Di AOSP, sumber daya dapat digambar ini adalah garis besar di sekitarFocusArea
. OEM dapat mengganti drawablecar_ui_focus_area_foreground_highlight
. -
car_ui_enable_focus_area_background_highlight
: Menggambar sorotan di atasFocusArea
tetapi di belakang turunannya. Di AOSP, drawable ini merupakan isian yang solid. OEM dapat mengganti drawablecar_ui_focus_area_background_highlight
.
Editor Metode Masukan
Editor Metode Masukan (IME) adalah metode masukan. Misalnya, keyboard di layar.
( Android 11 QPR3, Android 11 Mobil, Android 12 )
OEM harus melapisi sumber daya string default_touch_input_method
di RotaryService
untuk menentukan ComponentName
dari IME berbasis sentuhan. Misalnya, jika OEM menggunakan IME yang disediakan dengan Android Automotive, mereka harus menentukan com.google.android.apps.automotive.inputmethod/.InputMethodService
.
( Android 11 QPR3, Android 11 Mobil, Android 12 )
Jika OEM telah membuat IME khusus untuk mesin putar, mereka harus menentukan ComponentName
Komponennya di sumber daya rotary_input_method
. Jika sumber daya ini dilapis, IME yang ditentukan akan digunakan setiap kali pengguna berinteraksi dengan unit kepala melalui dorongan, putaran, dan tombol Tengah pengontrol putar. Saat pengguna menyentuh layar, IME sebelumnya akan digunakan. Tombol Kembali (dan tombol lain pada pengontrol putar) tidak berpengaruh pada pemilihan IME. Jika sumber daya ini tidak dihamparkan, peralihan IME tidak akan terjadi. Carboard tidak mendukung rotari sehingga pengguna tidak dapat memasukkan teks melalui pengontrol putar jika OEM belum menyediakan IME putar.
RotaryIME
adalah demo IME putar. Meskipun sederhana, cukup mencoba peralihan IME otomatis yang dijelaskan di atas. Kode sumber untuk RotaryIME
dapat ditemukan di packages/apps/Car/tests/RotaryIME/
.
Dorongan di luar layar
Secara default, saat pengguna mencoba menggeser tepi layar, tidak terjadi apa-apa. OEM dapat mengonfigurasi apa yang harus terjadi untuk masing-masing dari empat arah dengan menentukan kombinasi apa pun dari:
- Tindakan global yang ditentukan oleh
AccessibilityService
. Misalnya,GLOBAL_ACTION_BACK
. - Kode kunci, seperti
KEYCODE_BACK
. - Niat untuk meluncurkan aktivitas yang direpresentasikan sebagai URL.
( Android 11 QPR3, Android 11 Mobil, Android 12 )
Ini ditentukan dengan menghamparkan sumber daya array berikut di RotaryService
:
-
off_screen_nudge_global_actions
: Rangkaian tindakan global yang dilakukan saat pengguna mendorong ke atas, bawah, kiri, atau kanan dari tepi layar. Tidak ada tindakan global yang dilakukan jika elemen relevan dari array ini adalah -1. -
off_screen_nudge_key_codes
: Kumpulan kode kunci peristiwa klik yang akan dimasukkan saat pengguna mendorong ke atas, bawah, kiri, atau kanan dari tepi layar. Tidak ada peristiwa yang dimasukkan jika elemen relevan dari array ini adalah 0 (KEYCODE_UNKNOWN
). -
off_screen_nudge_intents
: Rangkaian maksud untuk meluncurkan aktivitas saat pengguna mendorong ke atas, bawah, kiri, atau kanan dari tepi layar. Tidak ada aktivitas yang diluncurkan jika elemen relevan dari array ini kosong.
Konfigurasi lainnya
Anda harus melapisi sumber daya RotaryService
berikut:
- ( Android 11 QPR3, Android 11 Mobil, Android 12 )
config_showHeadsUpNotificationOnBottom
: Nilai Boolean untuk menunjukkan apakah notifikasi pendahuluan harus ditampilkan di bagian bawah dan bukan di atas. Ini harus memiliki nilai yang sama dengan sumber daya Booleanconfig_showHeadsUpNotificationOnBottom
diframeworks/base/packages/CarSystemUI/res/values/config.xml
- ( Android 11 QPR3, Android 11 Mobil, Android 12 )
notification_headsup_card_margin_horizontal
: Margin kiri dan kanan untuk jendela notifikasi pendahuluan. Ini harus memiliki nilai yang sama dengan sumber daya dimennotification_headsup_card_margin_horizontal
dipackages/apps/Car/Notification/res/values/dimens.xml
- ( Android 12 )
excluded_application_overlay_window_titles
: Serangkaian judul jendela yang tidak boleh dianggap sebagai jendela overlay. Ini harus mencakup judul jendela aplikasi yang mewakiliTaskViews
atauTaskDisplayAreas
. Secara default, daftar ini hanya berisi "Peta".
Anda dapat menghamparkan sumber daya RotaryService
berikut:
- ( Android 11 QPR3, Android 11 Mobil, Android 12 )
long_press_ms
: Nilai bilangan bulat untuk menunjukkan berapa milidetik tombol Tengah harus ditahan untuk memicu penekanan yang lama. Nol menunjukkan batas waktu tekan lama default sistem harus digunakan. Ini adalah nilai default.