Integrationsleitfaden für OEMs

Auf dieser Seite wird beschrieben, wie Sie Drehknopfeingaben in der VHAL verarbeiten, Ihren Build konfigurieren um den Rotationsdienst einzubinden und die Nutzung für alle Apps anzupassen. Informationen zu vorinstallierten OEM-Apps, z. B. einem vom OEM bereitgestellten Launcher, finden Sie unter Car UI Library (car-ui-library):

VHAL

Ein Drehregler unterstützt folgende Aktionen:

• Schrittweise nach oben, unten, links und rechts bewegen
• Drehen Sie das Gerät im und gegen den Uhrzeigersinn.
• Drücke die Taste in der Mitte.
• Drücke die Zurück-Taste.
• Drücken Sie die Startbildschirmtaste.
• Drücken Sie andere Tasten, z. B. Telefon und Medien.

Unter hardware/interfaces/automotive/vehicle/2.0/types.hal finden Sie eine Dokumentation zu Systemeigenschaften und dem entsprechenden int32Values.

Die VHAL sollte die folgenden Aktionen ausführen:

• Automatische Erinnerung
• Drehen
• Schaltfläche in der Mitte
• Schaltfläche „Zurück“
• Schaltfläche „Startseite“
• Andere Schaltflächen

Anstupsen

Wenn der Benutzer den Drehregler nach rechts drückt, sollte der VHAL die Funktion Property HW_KEY_INPUT mit dem folgenden int32Values zum Senden eines an Android senden:

1. ACTION_DOWN
2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
3. Zieldisplay.

Wenn der Nutzer den Drehregler loslässt, sollte die VHAL dieselbe Eigenschaft und Keycode mit ACTION_UP. Für automatische Erinnerungen in andere Richtungen sollte die entsprechenden Keycodes.

Es gibt keine Keycodes für Diagonalen, aber die VHAL kann eine horizontale und eine vertikale -Ereignis, um eine Diagonale zu erzeugen, wenn die Hardware Diagonalen unterstützt. Zum Beispiel können Sie und links erhalten Sie Folgendes:

• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

In beiden Schritten (und anschließend) sollte der Drehregler Folgendes erzeugen:

• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
• HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

Der Nutzer kann die Drehsteuerung in einer senkrechten Richtung drücken, bevor er sie loslässt. Beispiel:

<ph type="x-smartling-placeholder">

</ph>

Dadurch sollte die folgende Ereignissequenz generiert werden:

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

Während der Drehregler gedrückt wird, sollten keine Repeat-Ereignisse generiert werden. in eine Richtung zu lenken.

Drehen

Wenn der Nutzer den Drehregler im Uhrzeigersinn um eine Stellung (Klicken) dreht, wird die VHAL sollte das Attribut HW_ROTARY_INPUT mit dem folgenden int32Values verwenden So senden Sie ein Ereignis an Android:

1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
2. Eine (1) Haft.
3. Zieldisplay.

Der Zeitstempel des Ereignisses sollte auf die verstrichene Zeit in Nanosekunden festgelegt werden.

Eine Drehung um eine (1) Verriegelung gegen den Uhrzeigersinn sollte dasselbe Ereignis generieren, jedoch mit -1 für die Anzahl der Verhaftungen.

Wenn mehrere Rotationssperre in dieselbe Richtung schnell hintereinander auftreten, kann die VHAL die Sperren zu einem einzigen Ereignis kombinieren, um das System nicht mit Ereignissen zu überlasten. In diesem Fall sollte der Zeitstempel des Ereignisses das Datum angeben, an dem die erste Rotationssperre stattgefunden hat. int32Values sollte die Anzahl der Nanosekunden zwischen aufeinanderfolgenden Verweileinheiten enthalten der Drehung.

Zum Beispiel die folgende Rotationssequenz:

• Zum Zeitpunkt t0 drehte der Nutzer eine Verteidigung gegen den Uhrzeigersinn.
• Zum Zeitpunkt t0 + 5 ns drehte der Nutzer eine Haftsperre gegen den Uhrzeigersinn.
• Zum Zeitpunkt t0 + 8 ns drehte der Nutzer eine Haftsperre gegen den Uhrzeigersinn.

sollte folgendes Ereignis generieren:

• Unterkunft: HW_ROTARY_INPUT
• Zeitstempel: t0
• int32Values: <ph type="x-smartling-placeholder">
  </ph>
  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. -3 (drei Verriegelungen gegen den Uhrzeigersinn)
  3. Zieldisplay.
  4. 5 ns zwischen der ersten und zweiten Verweildauer.
  5. 3 ns zwischen der zweiten und dritten Verweildauer.

Schaltfläche in der Mitte

Wenn der Nutzer auf die mittlere Taste drückt, sollte der VHAL die Methode HW_KEY_INPUT verwenden. mit dem folgenden int32Values, um ein Ereignis an Android zu senden:

1. ACTION_DOWN
2. KEYCODE_DPAD_CENTER
3. Zieldisplay.

Wenn der Nutzer den Drehregler loslässt, sollte die VHAL dieselbe Eigenschaft verwenden. und Keycode mit ACTION_UP.

Es werden keine Repeat-Ereignisse generiert, wenn die mittlere Taste gedrückt gehalten wird.

Schaltfläche „Zurück“

Wenn der Nutzer auf die Schaltfläche „Zurück“ drückt, sollte der VHAL die Methode HW_KEY_INPUT verwenden. mit dem folgenden int32Values, um ein Ereignis an Android zu senden:

1. ACTION_DOWN
2. KEYCODE_BACK
3. Zieldisplay.

Wenn der Nutzer den Drehregler loslässt, sollte die VHAL dieselbe Eigenschaft verwenden. und Keycode mit ACTION_UP.

Wenn die mittlere Taste gedrückt wird, sollten keine Repeat-Ereignisse generiert werden.

Startbildschirmtaste

Behandele die Startbildschirmtaste wie die Schaltfläche „Zurück“, aber verwende stattdessen KEYCODE_HOME von KEYCODE_BACK.

Andere Schaltflächen

Wenn der Drehregler zusätzliche Tasten enthält, kann der VHAL diese jedoch handhaben. den OEMs gefallen, da sie aus der Perspektive von Android nicht als Teil des Rotary betrachtet werden. Diese werden normalerweise wie die Zurück- und Home-Tasten gehandhabt, jedoch mit unterschiedlichen Tastencodes. Beispiel: KEYCODE_CALL oder KEYCODE_MUSIC.

Build-Konfiguration

Die Rotation wird von der Bedienungshilfe RotaryService bereitgestellt. Um diesen Dienst in das System-Image Ihres Geräts aufzunehmen, fügen Sie die folgende Zeile zu Ihrem Makefile:

PRODUCT_PACKAGES += CarRotaryController

Sie können auch die folgenden Pakete in Debug-Builds einbinden:

• RotaryPlayground Eine Referenz-App für Drehknopf (siehe RotaryPlayground.
• RotaryIME Ein Demo-IME mit Rotations-IME (siehe Eingabemethoden-Editoren).
• CarRotaryImeRRO Das Overlay für RotaryIME.

Der Rotationsdienst wird automatisch aktiviert, wenn das Gerät hochfährt und ein Nutzer erfolgt. Dadurch wird sichergestellt, dass der Nutzer den Drehregler während der Einrichtung verwenden kann.

Wenn Sie für Autos mit und ohne Drehsteuerung denselben Build verwenden, Fügen Sie CarRotaryController wie oben gezeigt hinzu, damit der erforderliche Code eingefügt wird. im Build. Um zu verhindern, dass der Rotationsdienst bei nicht drehbaren Autos aktiviert wird, erstellen Sie eine statische RRO zum Einblenden der Stringressource rotaryService in packages/services/Car/service mit einem leeren String. Sie verwenden denselben Build, haben jedoch unterschiedliche Produktkonfigurationen für dreh- und nicht drehbare Geräte. Nur Letzteres enthält das Overlay.

Personalisierung

OEMs können die Logik zur Fokussuche, das Hervorheben des Fokus und einige zusätzliche Elemente Ressourcen-Overlays an den folgenden Speicherorten:

• Die Car-UI-Bibliothek befindet sich in packages/apps/Car/libs/car-ui-lib
• RotaryService befindet sich in packages/apps/Car/RotaryController.
• Core befindet sich in frameworks/base/core.

Anstupser-Verlauf

Der OEM kann konfigurieren, ob jeder der beiden Arten von Anstupser-Verlauf aktiviert ist, und falls ja, die Cache-Größe und die Ablaufrichtlinie. Hierzu werden verschiedene Auto-UI-Bibliotheken Ressourcen.

Verlaufs-Cache fokussieren

(Android 11 QPR3, Android 11 Car, Android 12)
In diesem FocusArea-Cache wird die zuletzt fokussierte Ansicht im FocusArea, damit es fokussiert werden kann, wenn zurück zu FocusArea zurückgekehrt wird. Dieser Cache kann durch Überlagerung der folgenden Ressourcen vom Typ „car-ui-library“ konfiguriert werden:

• car_ui_focus_history_cache_type: <ph type="x-smartling-placeholder">
  </ph>
  1. Cache ist deaktiviert.
  2. Der Cache läuft nach einiger Zeit ab (siehe unten).
  3. Der Cache läuft niemals ab.
• car_ui_focus_history_expiration_period_ms: gibt an, wie viele Millisekunden vor dem Der Cache läuft ab, wenn der Cache-Typ auf zwei (2) eingestellt ist (siehe oben).

FocusArea-Verlaufs-Cache

(Android 11 QPR3, Android 11 Car, Android 12)
Dieser Cache speichert einen Verlauf der Anstupser, sodass Anstupser in die entgegengesetzte Richtung Fokus wieder auf denselben FocusArea verschieben. Dieser Cache kann konfiguriert werden, indem die folgende Ressourcen für die Auto-UI-Bibliothek:

• car_ui_focus_area_history_cache_type: <ph type="x-smartling-placeholder">
  </ph>
  1. Cache ist deaktiviert.
  2. Der Cache läuft nach einiger Zeit ab (siehe unten).
  3. Der Cache läuft niemals ab.
• car_ui_focus_area_history_expiration_period_ms: wie viele Millisekunden vorher Der Cache läuft ab, wenn der Cache-Typ auf 2 eingestellt ist (siehe oben).
• car_ui_clear_focus_area_history_when_rotating: Gibt an, ob der Cache geleert werden soll wenn der Nutzer den Controller dreht.

Ausrichtung

(Android 11 QPR3, Android 11 Car, Android 12)
Der OEM kann zwei ganzzahlige Ressourcen in der RotaryService überschreiben, um anzugeben, ob Es gibt eine Beschleunigung, z. B. Mausbeschleunigung, für die Drehung:

• rotation_acceleration_3x_ms: Zeitintervall (in Millisekunden), das für die Entscheidung verwendet wird Legt fest, ob Google die Controller-Rotation für eine Rotationssperre beschleunigen soll. Wenn die zwischen dieser Verzögerung und der vorherigen Rotationssperre kleiner ist als dieser Wert, wird dies als drei Drehbewegungen behandelt. Setzen Sie dies auf 2147483647, um 3× zu deaktivieren. von Beschleunigungen.
• rotation_acceleration_2x_ms: Ähnlich wie rotation_acceleration_3x_ms. Wird für die 2‐fache Beschleunigung verwendet. Setzen Sie diesen Wert auf 2147483647, um die 2-fache Beschleunigung zu deaktivieren.

Die Beschleunigung funktioniert am besten, wenn für jede Detent von Rotation, wie erforderlich von VHAL. Sind diese nicht verfügbar, geht das RotaryService davon aus, dass die Rotation gleichmäßige Abstände.

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

Hervorhebung hervorheben

Der OEM kann die standardmäßige Fokushervorhebung im Android-Framework überschreiben und mehrere Ressourcen in der Auto-UI-Bibliothek hervorheben.

Standardeinstellung „Fokus hervorheben“

Das Android-Framework bietet eine standardmäßige Fokussierung durch das Attribut selectableItemBackground In Theme.DeviceDefault: Attribut bezieht sich auf item_background.xml in Core. Der OEM kann Mit item_background.xml ändern Sie das standardmäßige Drawable für Fokus-Hervorhebung.

Dieses Drawable sollte in der Regel ein StateListDrawable sein, das den Hintergrund anpasst auf Basis verschiedener Statuskombinationen, darunter android:state_focused und android:state_pressed. Wenn der Nutzer mit dem Drehregler fokussieren Sie eine Ansicht, android:state_focused ist true, aber android:state_pressed wird false. Wenn die Nutzenden dann die Taste in der Mitte des Drehreglers android:state_focused und android:state_pressed wird true, während der Nutzer die Taste gedrückt hält. Wenn der Nutzer die Schaltfläche loslässt, bleibt nur android:state_focused übrig true.

In der Auto-UI-Bibliothek wird ein Design verwendet, das von Theme.DeviceDefault abgeleitet ist. Daher Dieses Overlay betrifft Apps, die diese Bibliothek verwenden, sowie Apps, die ein Design verwenden, das aus Theme.DeviceDefault Apps mit einem anderen Thema sind davon nicht betroffen. wie Theme.Material.

Fokus auf Ressourcen in der Auto-UI-Bibliothek

Der OEM kann mehrere Ressourcen der Auto-UI-Bibliothek überschreiben, um zu steuern, wie der Fokus hervorgehoben wird. stellt Ansichten mit einer nicht rechteckigen (z. B. runden oder pillenförmigen) Hervorhebung dar Apps, die ein Design verwenden, das nicht von Theme.DeviceDefault abgeleitet ist Diese Ressourcen sollten so überlagert werden, dass der Fokus mit dem Standardfokus-Hervorhebung.

(Android 11 QPR3, Android 11 Car, Android 12)
Die folgenden Ressourcen werden verwendet, um anzuzeigen, wenn eine Ansicht hervorgehoben, aber nicht gedrückt wird:

• car_ui_rotary_focus_fill_color: Füllfarbe.
• car_ui_rotary_focus_stroke_color: Umrissfarbe.
• car_ui_rotary_focus_stroke_width: Stärke der Kontur.

(Android 11 QPR3, Android 11 Car, Android 12)
Die folgenden Ressourcen werden verwendet, um anzuzeigen, wann eine Ansicht hervorgehoben und gedrückt wird:

• car_ui_rotary_focus_pressed_fill_color: Füllfarbe.
• car_ui_rotary_focus_pressed_stroke_color: Umrissfarbe.
• car_ui_rotary_focus_pressed_stroke_width: Stärke der Kontur.

Manchmal erhält eine Schaltfläche eine einfarbige Hintergrundfarbe, um die Aufmerksamkeit der Nutzenden wie im Beispiel gezeigt. Dadurch ist die Hervorhebung möglicherweise schwer zu erkennen.

<ph type="x-smartling-placeholder">

</ph>

In diesem Fall kann der Entwickler mithilfe von sekundäre Farben: <ph type="x-smartling-placeholder">

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

Alle Farben können transparent sein und beide Dimensionen können null sein, wenn Sie beispielsweise nur eine Füllung oder nur einen Umriss wollten.

Fokusbereich-Hervorhebung

(Android 11 QPR3, Android 11 Car, Android 12)
Mit FocusArea können zwei Arten von Markierungen gezeichnet werden, wenn eines der Nachfolgerelemente fokussiert sind. Beide können bei Bedarf in Kombination verwendet werden. Diese Funktion ist in AOSP, kann aber durch Überschreiben der Ressourcen der Auto-UI-Bibliothek aktiviert werden:

• car_ui_enable_focus_area_foreground_highlight: Hervorhebung über dem das FocusArea und seine Nachfolgerelemente. In AOSP ist dieses Drawable ein Umriss. um den FocusArea. OEMs können die Drawable „car_ui_focus_area_foreground_highlight“.
• car_ui_enable_focus_area_background_highlight: Hervorhebung über dem FocusArea, aber hinter seinen Nachfolgern. In AOSP ist dieses Drawable eine durchgehende Füllung. OEMs können das Drawable car_ui_focus_area_background_highlight überschreiben.

Eingabemethoden-Editoren

Input Method Editors (IMEs) sind Eingabemethoden. Zum Beispiel eine Bildschirmtastatur.

(Android 11 QPR3, Android 11 Car, Android 12)
Der OEM muss die String-Ressource default_touch_input_method überlagern in der RotaryService, um den ComponentName des Touch-basierten IMEs. Wenn der OEM beispielsweise den bei Android Automotive bereitgestellten IME verwendet, sollten sie angeben, com.google.android.apps.automotive.inputmethod/.InputMethodService

(Android 11 QPR3, Android 11 Car, Android 12)
Wenn der OEM einen IME speziell für Rotary erstellt hat, sollte er seinen ComponentName in der Ressource rotary_input_method. Wenn diese Ressource eingeblendet wird, wird der angegebene IME immer dann verwendet, wenn der Nutzer mit dem Infotainmentsystem interagiert. über die Anstoß-, Rotations- und Mitteltaste des Drehreglers bewegen. Wenn der Nutzer die angezeigt wird, wird der vorherige IME verwendet. Die Zurück-Taste (und andere Tasten am Drehknopf) Controller) haben keine Auswirkungen auf die IME-Auswahl. Wenn diese Ressource nicht überlagert ist, kann der IME nicht gewechselt werden. erfolgt. Carboard unterstützt keinen Drehknopf, daher können Nutzende keinen Text über den Drehknopf eingeben. Controller, wenn der OEM keinen IME mit Drehknopf angegeben hat.

RotaryIME ist ein Demo-Rotary-IME. Obwohl es einfach ist, reicht es aus, können Sie den oben beschriebenen automatischen IME-Wechsel ausprobieren. Der Quellcode für RotaryIME finden Sie unter packages/apps/Car/tests/RotaryIME/.

Automatische Erinnerungen außerhalb des Bildschirms

Wenn der Nutzer versucht, den Bildschirm vom Rand weg zu bewegen, passiert nichts. Der OEM kann konfigurieren, was für jede der vier Richtungen geschehen soll, indem er eine beliebige Kombination aus:

1. Eine durch AccessibilityService definierte globale Aktion. Beispiel: GLOBAL_ACTION_BACK
2. Ein Schlüsselcode wie KEYCODE_BACK.
3. Intent zum Starten einer als URL dargestellten Aktivität.

(Android 11 QPR3, Android 11 Car, Android 12)
Diese werden angegeben, indem die folgenden Array-Ressourcen in der RotaryService:

• off_screen_nudge_global_actions: Array globaler Aktionen, die ausgeführt werden sollen, wenn die Nutzenden bewegen sich vom Bildschirmrand nach oben, unten, links oder rechts weg. Keine globale Aktion ist wird ausgeführt, wenn das relevante Element dieses Arrays -1 ist.
• off_screen_nudge_key_codes: Array der Schlüsselcodes der einzufügenden Klickereignisse wenn die Nutzenden vom Bildschirmrand nach oben, unten, links oder rechts wegfahren. Es sind keine Ereignisse wird eingefügt, wenn das relevante Element dieses Arrays 0 ist (KEYCODE_UNKNOWN).
• off_screen_nudge_intents: Array von Intents zum Starten einer Aktivität, wenn die Nutzenden bewegen sich vom Bildschirmrand nach oben, unten, links oder rechts weg. Keine Aktivität ist gestartet, wenn das relevante Element dieses Arrays leer ist.

Andere Konfigurationen

Sie sollten die folgenden RotaryService-Ressourcen überlagern:

• (Android 11 QPR3, Android 11 Car, Android 12)
  config_showHeadsUpNotificationOnBottom: Boolescher Wert, der angibt, ob Vorabbenachrichtigungen sollten unten, nicht oben, angezeigt werden. Dies muss haben denselben Wert wie config_showHeadsUpNotificationOnBottom. Boolesche Ressource in frameworks/base/packages/CarSystemUI/res/values/config.xml
• (Android 11 QPR3, Android 11 Car, Android 12)
  notification_headsup_card_margin_horizontal: linker und rechter Rand für Vorabbenachrichtigungsfenster. Dieser muss denselben Wert haben wie der notification_headsup_card_margin_horizontal Dimension-Ressource in packages/apps/Car/Notification/res/values/dimens.xml
• (Android 12)
  excluded_application_overlay_window_titles: ein Array von Titel von Fenstern, die nicht als Overlay-Fenster betrachtet werden sollen. Dazu sollten auch Titel gehören. von App-Fenstern, die TaskViews oder TaskDisplayAreas darstellen. Standardmäßig enthält diese Liste nur „Karten“.

Sie können die folgende RotaryService-Ressource überlagern:

• (Android 11 QPR3, Android 11 Car, Android 12)
  long_press_ms: Ganzzahlwert, der angibt, wie viele Millisekunden der Zum langen Drücken muss die mittlere Taste gedrückt werden. Null gibt an, dass das System Standardzeitlimit für langes Drücken verwendet werden. Dies ist der Standardwert.