Przewodnik po integracji dla producentów OEM

Na tej stronie dowiesz się, jak przetwarzać pokrętło w VHAL, skonfigurować kompilację obrót, a także jak dostosować pokrętło we wszystkich aplikacjach. W przypadku wstępnie zainstalowanych aplikacji OEM, takich jak program uruchamiający dostarczony przez OEM, zapoznaj się z artykułem Biblioteka Car UI (car-ui-library).

VHAL,

Kontroler obrotowy umożliwia wykonywanie tych czynności:

• Posuń w górę, w dół, w lewo i w prawo.
• Obróć w prawo i w lewo.
• Naciśnij środkowy przycisk.
• Naciśnij przycisk Wróć.
• Naciśnij przycisk strony głównej.
• Naciśnij inne przyciski, np. telefon i multimedia.

Otwórz stronę hardware/interfaces/automotive/vehicle/2.0/types.hal, aby zapoznać się z dokumentacją dotyczącą właściwości systemowe i odpowiedni element int32Values.

VHAL powinien wykonywać te działania:

• Ponaglenie
• Obróć
• Środkowy przycisk
• Przycisk Wstecz
• Przycisk strony głównej
• Inne przyciski

Trącenie

Gdy użytkownik naciska kontroler pokrętły w prawo, VHAL powinien używać funkcji Właściwość HW_KEY_INPUT o następujących parametrach int32Values do wysłania to zdarzenie na Androida:

1. ACTION_DOWN
2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
3. Kierowanie na sieć reklamową.

Gdy użytkownik zwolni kontroler obrotowy, VHAL powinien użyć tej samej właściwości z kodem ACTION_UP. Ponaglenia w innych kierunkach powinny zawierać parametr z odpowiednimi klawiszami.

Nie ma kodów klawiszy dla przekątnych, ale VHAL może łączyć , aby uzyskać przekątną, jeśli sprzęt obsługuje przekątne. Na przykład ponaglenia , a po lewej powinien wygenerować:

• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

W każdej kolejności (a potem) zwolnienie kontrolera obrotowego powinno przynieść:

• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

Przed zwolnieniem użytkownik może popchnąć kontroler obrotowy w kierunku prostopadłym. Na przykład ten scenariusz:

Rysunek 1. Kierunek prostopadł

Powinno to spowodować wygenerowanie tej sekwencji zdarzeń:

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

Przy wciśniętym kontrolerze obrotowym nie powinny być generowane żadne powtarzające się zdarzenia. w jednym kierunku.

Obróć

Gdy użytkownik obraca kontroler obrotowy w prawo o jedną pozycję (kliknięcie), VHAL powinien używać właściwości HW_ROTARY_INPUT z następującymi wartościami int32Values aby wysłać zdarzenie na Androida:

1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
2. Jedno (1) punkt końcowy.
3. Kierowanie na sieć reklamową.

Jako sygnaturę czasową zdarzenia należy ustawić czas, który upłynął w nanosekundach.

Jeden (1) zapadający obrót w lewo powinien generować to samo zdarzenie, ale z -1 dla liczby punktów ustanowionych.

Jeśli w krótkim czasie występuje kilka punktów obrotu w tym samym kierunku, VHAL powinny połączyć te elementy w jedno zdarzenie, aby nie przeciążać systemu zdarzeniami. W tym przypadku sygnatura czasowa zdarzenia powinna być datą pierwszego momentu rotacji. Wartość int32Values powinna zawierać liczbę nanosekund między kolejnymi punktami składowymi lub rotacji.

Na przykład taka sekwencja rotacji:

• W momencie t0 użytkownik obrócił 1 miejsce zatrzymania w lewo.
• Przy t0 + 5 ns użytkownik obrócił 1 stóp w lewo.
• Przy t0 + 8 ns użytkownik obrócił 1 punkt zapadający w lewo.

powinno generować to zdarzenie:

• Usługa: HW_ROTARY_INPUT
• Sygnatura czasowa: t0
• int32Values:
  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. -3 (trzy punkty zatrzymania w lewo).
  3. Kierowanie na sieć reklamową.
  4. 5 ns między pierwszym i drugim punktem końcowym.
  5. 3 ns między drugą a trzecią ułamkiem.

Przycisk środkowy

Gdy użytkownik naciśnie przycisk środkowy, VHAL powinien użyć funkcji HW_KEY_INPUT właściwości z tym elementem int32Values, by wysyłać zdarzenie do Androida:

1. ACTION_DOWN
2. KEYCODE_DPAD_CENTER
3. Kierowanie na sieć reklamową.

Gdy użytkownik zwolni kontroler obrotowy, VHAL powinien użyć tej samej właściwości i kodu z kluczem ACTION_UP.

Nie generuj powtarzających zdarzeń po przytrzymaniu przycisku Środek.

Przycisk Wstecz

Gdy użytkownik naciśnie przycisk Wstecz, VHAL powinien użyć HW_KEY_INPUT właściwości z tym elementem int32Values, by wysyłać zdarzenie do Androida:

1. ACTION_DOWN
2. KEYCODE_BACK
3. Kierowanie na sieć reklamową.

Gdy użytkownik zwolni kontroler obrotowy, VHAL powinien użyć tej samej właściwości i kodu z kluczem ACTION_UP.

Przy wciśniętym przycisku środkowego nie powinny być generowane żadne powtarzające się zdarzenia.

Przycisk Ekran główny

Używaj przycisku ekranu głównego tak samo jak przycisku Wstecz, ale zamiast tego za pomocą klawisza KEYCODE_HOME z KEYCODE_BACK.

Inne przyciski

Jeśli kontroler obrotowy zawiera dodatkowe przyciski, VHAL może je jednak obsługiwać. co podoba się producentom OEM, ponieważ nie są one uważane z perspektywy Androida jako system rotacyjny. Zazwyczaj są one obsługiwane jak przyciski Wstecz i Ekran główny, ale z różnymi kodami klawiszy. na przykład KEYCODE_CALL lub KEYCODE_MUSIC.

Konfiguracja kompilacji

Nawigację pokrętną zapewnia usługa ułatwień dostępu o nazwie RotaryService. Aby uwzględnić tę usługę w obrazie systemu urządzenia, dodaj następujący wiersz do Makerfile:

PRODUCT_PACKAGES += CarRotaryController

Możesz też uwzględnić te pakiety w kompilacjach do debugowania:

• RotaryPlayground Aplikacja referencyjna dotycząca rotacji (patrz RotaryPlayground).
• RotaryIME Demonstracyjny obrotowy edytor IME (patrz Edytory metod wprowadzania).
• CarRotaryImeRRO Nakładka dla: RotaryIME.

Usługa rotacji jest włączana automatycznie po uruchomieniu urządzenia i gdy użytkownik następuje przełączenie funkcji. Dzięki temu użytkownik może korzystać z kontrolera obrotowego podczas konfiguracji.

Jeśli używasz tej samej kompilacji dla samochodów z kontrolerem obrotowym i bez niego, dodaj CarRotaryController w sposób pokazany powyżej, aby uwzględnić niezbędny kod w danej konstrukcji. Aby wyłączyć usługę obrotową w samochodach nieobrotowych, utwórz statyczne RRO do nałożenia zasobu ciągu tekstowego rotaryService w packages/services/Car/service z pustym ciągiem znaków. Użyjesz tej samej kompilacji, ale mają oddzielne konfiguracje produktów dla urządzeń obrotowych i nieobrotowych. Tylko to drugie obejmuje nakładkę.

Dostosowywanie

OEM może dostosować logikę wyszukiwania, wyróżnienie i dodatkowe produkty za pomocą nakładki zasobów w następujących lokalizacjach:

• biblioteka car-ui-library znajduje się w: packages/apps/Car/libs/car-ui-lib
• RotaryService znajduje się w: packages/apps/Car/RotaryController
• Core znajduje się w: frameworks/base/core

Historia ponagleń

OEM może określić, czy każdy z 2 typów historii ponagleń jest włączony, a jeśli tak: zasady rozmiaru i okresu ważności pamięci podręcznej. Wszystko to robi się przez zastąpienie różnych bibliotek interfejsu użytkownika i zasobami Google Cloud.

Zaznacz pamięć podręczną historii

(Android 11 QPR3, Android 11 Car, Android 12)
Ta pamięć podręczna dla FocusArea przechowuje ostatnio aktywny widok w FocusArea, aby móc ją zaznaczyć, gdy wrócisz do sekcji FocusArea. Tę pamięć podręczną można skonfigurować, nakładając na siebie te zasoby biblioteki samochodu:

• car_ui_focus_history_cache_type:
  1. Pamięć podręczna jest wyłączona.
  2. Pamięć podręczna po pewnym czasie wygaśnie (patrz poniżej).
  3. Pamięć podręczna nigdy nie wygasa.
• car_ui_focus_history_expiration_period_ms: ile milisekund przed pamięć podręczna wygasa, jeśli typ pamięci podręcznej jest ustawiony na wartość dwa (2) (patrz wyżej).

Pamięć podręczna historii obszaru fokusu

(Android 11 QPR3, Android 11 Car, Android 12)
W tej pamięci podręcznej zapisywana jest historia ponagleń, dzięki czemu ponaglenie w przeciwnym kierunku wróć do tego samego elementu (FocusArea). Tę pamięć podręczną można skonfigurować, nakładając następujące zasoby biblioteki samochodu:

• car_ui_focus_area_history_cache_type:
  1. Pamięć podręczna jest wyłączona.
  2. Pamięć podręczna wygasa po pewnym czasie (patrz poniżej).
  3. Pamięć podręczna nigdy nie wygasa.
• car_ui_focus_area_history_expiration_period_ms: ile milisekund wcześniej pamięć podręczna wygasa, jeśli jej typ jest ustawiony na 2 (patrz wyżej).
• car_ui_clear_focus_area_history_when_rotating: określa, czy opróżnić pamięć podręczną gdy użytkownik obraca kontroler.

Obrót

(Android 11 QPR3, Android 11 Car, Android 12)
OEM może zastąpić 2 zasoby całkowite w RotaryService, aby określić, występuje przyspieszenie, np. przyspieszenie myszy, dla obrotu:

• rotation_acceleration_3x_ms: przedział czasu (w milisekundach) używany do podjęcia decyzji czy Google ma przyspieszyć obrót kontrolera w chwili obrotu. Jeśli odstęp między tą zasadą a poprzednim punktem obrotu jest mniejszy od tej wartości, jest traktowany jako 3 stopnie obrotu. Ustaw jako 2147483647, aby wyłączyć 3× jego przyspieszenie.
• rotation_acceleration_2x_ms: podobny do rotation_acceleration_3x_ms. Używana do przyspieszenia 2×. Ustaw tę wartość na 2147483647, aby wyłączyć przyspieszenie 2×.

Przyspieszenie działa najlepiej, gdy dla każdego elementu docelowego ma osobne sygnatury czasowe rotacji wymagane przez VHAL. Jeśli te elementy nie są dostępne, RotaryService zakłada, że wartości funkcji są równomiernie rozmieszczone.

/**
     * 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),

Wyróżnij wyróżnione

OEM może zastąpić domyślne wyróżnienie na platformie Androida oraz w ramach biblioteki Car-ui-library.

Domyślne wyróżnienie

Platforma Androida zapewnia domyślne wyróżnienie za pomocą atrybutu selectableItemBackground Theme.DeviceDefault: odnosi się do item_background.xml w Core. OEM może nakładać item_background.xml, aby zmienić domyślny rysowalny element zaznaczenia.

Ten obiekt rysowalny powinien zwykle być obiektem StateListDrawable, który dostosowuje tło. na podstawie różnych kombinacji stanów, w tym android:state_focused i android:state_pressed. Gdy użytkownik używa kontrolera obrotowego do zaznacz widok, android:state_focused będzie wynosić true, ale android:state_pressed będzie false. Jeśli użytkownik naciśnie przycisk przycisk środkowy na kontrolerze obrotowym, zarówno android:state_focused, jak i Gdy użytkownik przytrzymuje przycisk, android:state_pressed będzie mieć wartość true. Gdy użytkownik zwolni przycisk, pozostanie tylko android:state_focused true

car-ui-library, wykorzystuje motyw Theme.DeviceDefault. W rezultacie wpływa na aplikacje, które używają tej biblioteki, oraz aplikacje korzystające z dowolnego motywu Theme.DeviceDefault Nie będzie to miało wpływu na aplikacje, które wykorzystują niepowiązane motywy, na przykład Theme.Material.

Wyróżnianie materiałów w bibliotece UI samochodu

OEM może zastąpić kilka zasobów biblioteki samochodu, aby kontrolować sposób wyróżnienia analizuje widoki z nieprostokątnym (np. okrągłym lub w kształcie pigułki) z wyróżnieniem oraz aplikacje korzystające z motywu, który nie pochodzi od Theme.DeviceDefault. Te zasobów w taki sposób, aby wyróżniony element był zgodny z domyślne wyróżnienie z możliwością rysowania.

(Android 11 QPR3, Android 11 Car, Android 12)
Te zasoby służą do wskazywania, kiedy widok jest aktywny, ale nie naciśnięty:

• car_ui_rotary_focus_fill_color: kolor wypełnienia.
• car_ui_rotary_focus_stroke_color: kolor konturu.
• car_ui_rotary_focus_stroke_width: grubość obrysu.

(Android 11 QPR3, Android 11 Car, Android 12)
Te zasoby służą do wskazywania, kiedy widok jest aktywny i wciśnięty:

• car_ui_rotary_focus_pressed_fill_color: kolor wypełnienia.
• car_ui_rotary_focus_pressed_stroke_color: kolor konturu.
• car_ui_rotary_focus_pressed_stroke_width: grubość obrysu.

Czasami przycisk ma jednolity kolor tła, aby zwrócić na niego uwagę użytkownika. jak w przykładzie poniżej. Może to sprawić, że wyróżnienie będzie słabo widoczne.

Rysunek 2. Przycisk z jednolitym tłem

W takiej sytuacji deweloper może określić niestandardowe wyróżnienie za pomocą kolory dodatkowe:

• (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

Każdy kolor może być przezroczysty, a dowolny wymiar może wynosić zero, jeśli na przykład z chwilą wypełnienia lub tylko konspektu.

Wyróżnienie FocusArea

(Android 11 QPR3, Android 11 Car, Android 12)
FocusArea może narysować 2 typy wyróżnień, gdy jednym z elementów podrzędnych skupieni. Jeśli zajdzie taka potrzeba, można łączyć obie opcje. Ta funkcja jest domyślnie wyłączona w AOSP, ale można je włączyć, zastępując zasoby biblioteki interfejsu samochodu:

• car_ui_enable_focus_area_foreground_highlight: narysuj wyróżnienie na FocusArea i jego elementy podrzędne. W AOSP ten obiekt rysowalny to kontur w okolicy: FocusArea. OEM może zastąpić Element car_ui_focus_area_foreground_highlight, który można rysować.
• car_ui_enable_focus_area_background_highlight: narysuj wyróżnienie na FocusArea, ale za elementami potomnymi. W AOSP ten element rysowalny to pełne wypełnienie. OEM może zastąpić element rysowalny car_ui_focus_area_background_highlight.

Edytory metody wprowadzania

Edytor metody wprowadzania (IME) to metoda wprowadzania. Może to być na przykład klawiatura ekranowa.

(Android 11 QPR3, Android 11 Car, Android 12)
OEM musi nałożyć zasób ciągu znaków default_touch_input_method w RotaryService, aby określić ComponentName dotykowy edytor IME. Jeśli na przykład producent OEM używa edytora IME dostarczonego z Androidem Automotive, powinni określić com.google.android.apps.automotive.inputmethod/.InputMethodService

(Android 11 QPR3, Android 11 Car, Android 12)
Jeśli producent OEM utworzył edytor IME specjalnie dla rotatorów, powinien podać ComponentName w zasobie rotary_input_method. Jeśli ten zasób i nakładany, określony edytor IME jest używany za każdym razem, gdy użytkownik wchodzi w interakcję z głośnikiem za pomocą ponaglenia, obrotu i przycisku środkowego. Gdy użytkownik dotknie ekranu ekranu, zostanie użyty poprzedni edytor IME. Przycisk Wstecz (i inne przyciski na pokrętle kontroler) nie mają wpływu na wybór IME. Jeśli ten zasób nie jest nakładany, przełączanie IME nie jest możliwe ma miejsce. Karta Carboard nie obsługuje pokrętła, więc użytkownik nie może wpisywać tekstu za pomocą pokrętła. jeśli producent OEM nie dostarczył obrotowego edytora IME.

RotaryIME to demonstracyjny obrotowy edytor IME. Choć ta funkcja wystarczy, wypróbuj opisane powyżej automatyczne przełączanie IME. Kod źródłowy elementu RotaryIME znaleźć w: packages/apps/Car/tests/RotaryIME/.

ponaglenia poza ekranem,

Domyślnie, gdy użytkownik próbuje odsunąć ekran od krawędzi ekranu, nic się nie dzieje. Dostawca OEM może skonfigurować, co powinno się stać w każdym z czterech kierunków, podając dowolny kombinacja:

1. Działanie globalne zdefiniowane przez funkcję AccessibilityService. Przykład: GLOBAL_ACTION_BACK
2. Kod klucza, np. KEYCODE_BACK.
3. Zamiar uruchomienia działania reprezentowanego jako adres URL.

(Android 11 QPR3, Android 11 Car, Android 12)
Określa się je przez nałożenie następujących zasobów tablicowych w RotaryService:

• off_screen_nudge_global_actions: tablica globalnych działań, które mają zostać wykonane, gdy użytkownik przesuwa palcem w górę, w dół, w lewo lub w prawo poza krawędź ekranu. Brak działania globalnego jest wykonywana, jeśli odpowiednim elementem tej tablicy jest -1.
• off_screen_nudge_key_codes: tablica kodów kluczy zdarzeń kliknięcia do wstawienia gdy użytkownik przesuwa palcem w górę, w dół, w lewo lub w prawo poza krawędź ekranu. Brak zdarzeń wstrzyknięta, jeśli odpowiednim elementem tej tablicy jest 0 (KEYCODE_UNKNOWN).
• off_screen_nudge_intents: tablica intencji uruchomienia działania, gdy użytkownik przesuwa palcem w górę, w dół, w lewo lub w prawo poza krawędź ekranu. Brak aktywności uruchamiana, jeśli odpowiedni element tej tablicy jest pusty.

Inne konfiguracje

Nakładkę należy zastosować do tych RotaryService zasobów:

• (Android 11 QPR3, Android 11 Car, Android 12)
  config_showHeadsUpNotificationOnBottom: wartość logiczna wskazująca, czy powiadomienia HUD powinny być wyświetlane u dołu, a nie u góry. Musi to być mają tę samą wartość co config_showHeadsUpNotificationOnBottom Zasób wartości logicznej w frameworks/base/packages/CarSystemUI/res/values/config.xml
• (Android 11 QPR3, Android 11 Car, Android 12)
  notification_headsup_card_margin_horizontal: lewy i prawy margines dla: w oknie powiadomienia HUD. Musi mieć taką samą wartość jak notification_headsup_card_margin_horizontal zmniejsz rozmiar zasobu w packages/apps/Car/Notification/res/values/dimens.xml
• (Android 12)
  excluded_application_overlay_window_titles: tablica z nazw okien, których nie należy uważać za okna nakładane. Powinny one obejmować tytuły okien aplikacji reprezentujących TaskViews lub TaskDisplayAreas. Domyślnie lista zawiera tylko pozycję „Mapy”.

Możesz nałożyć na siebie ten zasób RotaryService:

• (Android 11 QPR3, Android 11 Car, Android 12)
  long_press_ms: liczba całkowita określająca liczbę milisekund Aby aktywować naciśnięcie i przytrzymanie, musisz przytrzymać przycisk środkowy. 0 wskazuje system. określ domyślny czas oczekiwania przy długim naciśnięciu. jest to wartość domyślna