OEM'ler için entegrasyon kılavuzu

Bu sayfada, VHAL'deki döner girişlerin nasıl işleneceği, derlemenizin döner hizmeti içerecek şekilde nasıl yapılandırılacağı ve döner deneyiminin tüm uygulamalarda nasıl özelleştirileceği açıklanmaktadır. OEM tarafından sağlanan başlatıcı gibi önceden yüklenmiş OEM uygulamaları için Araba kullanıcı arayüzü kitaplığı (car-ui-library) başlıklı makaleyi inceleyin.

VHAL

Döner kontrol cihazı aşağıdaki işlemleri destekler:

  • Yukarı, aşağı, sola ve sağa sürükleme
  • Saat yönünde ve saat yönünün tersine döndürme
  • Merkez düğmesine basın.
  • Geri düğmesine basın.
  • Ana sayfa düğmesine basın.
  • Telefon ve Medya gibi diğer düğmelere basın.

Sistem özellikleri ve ilgili int32Values hakkında dokümanlar için hardware/interfaces/automotive/vehicle/2.0/types.hal adresini ziyaret edin.

VHAL aşağıdaki işlemleri gerçekleştirmelidir:

Dürtme

Kullanıcı döner kontrol cihazını sağa ittiğinde VHAL, Android'e etkinlik göndermek için aşağıdaki int32Values ile HW_KEY_INPUT özelliğini kullanmalıdır:

  1. ACTION_DOWN
  2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
  3. Hedef ekran.

Kullanıcı döner kontrol cihazını bıraktığında VHAL, ACTION_UP ile aynı özelliği ve tuş kodunu kullanmalıdır. Diğer yönlerdeki hatırlatıcılar için ilgili tuş kodları kullanılmalıdır.

Çaprazlar için tuş kodları yoktur ancak donanım çaprazları destekliyorsa VHAL, çapraz oluşturmak için yatay ve dikey bir olayı birleştirebilir. Örneğin, yukarı ve sola doğru itme işlemi şu sonucu vermelidir:

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

Döner kontrol cihazının serbest bırakılması, her iki sırada da (ve sonrasında) aşağıdaki sonuçları vermelidir:

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

Kullanıcı, döner kontrol cihazını bırakmadan önce dik yönde itebilir. Örneğin, aşağıdaki senaryoyu ele alalım:

Dik yön
Şekil 1. Dik yön

Bu işlem aşağıdaki etkinlik sırasını oluşturmalıdır:

  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

Döner kontrol cihazı tek yönde tutulurken tekrarlanan etkinlikler oluşturulmamalıdır.

Döndür

Kullanıcı döner kontrol cihazını bir diş (tıklama) kadar saat yönünde döndürdüğünde VHAL, Android'e etkinlik göndermek için aşağıdaki int32Values ile HW_ROTARY_INPUT özelliğini kullanmalıdır:

  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. Bir (1) durdurma noktası.
  3. Hedef ekran.

Etkinliğin zaman damgası, geçen süreye (nanosaniye cinsinden) ayarlanmalıdır.

Bir (1) tık sola döndürme işlemi aynı etkinliği oluşturmalıdır ancak tık sayısı -1 olmalıdır.

Aynı yönde birden fazla dönüşüm kilidi hızlı bir şekilde gerçekleşirse VHAL, sistemi etkinliklerle aşırı yüklememek için dönüşüm kilitlerini tek bir etkinlikte birleştirmelidir. Bu durumda, etkinliğin zaman damgası, ilk dönme çentiğinin oluştuğu zaman olmalıdır. int32Values, ardışık dönüş durakları arasındaki nanosaniye sayısını içermelidir.

Örneğin, aşağıdaki dönüş sırası:

  • t0 zamanında kullanıcı, bir dişliyi saat yönünün tersine çevirdi.
  • t0 + 5 ns zamanında kullanıcı, bir dişliyi saat yönünün tersine çevirdi.
  • t0 + 8 ns zamanında kullanıcı, bir dişliyi saat yönünün tersine çevirdi.

şu etkinliği oluşturmalıdır:

  • Tesis: HW_ROTARY_INPUT
  • Zaman damgası: t0
  • int32Values:
    1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
    2. -3 (saat yönünün tersine üç tık).
    3. Hedef ekran.
    4. Birinci ve ikinci çentik arasında 5 ns.
    5. İkinci ve üçüncü çentik arasında 3 ns.

Orta düğme

Kullanıcı Merkez düğmesine bastığında VHAL, Android'e etkinlik göndermek için aşağıdaki HW_KEY_INPUT özelliğini kullanmalıdır: int32Values

  1. ACTION_DOWN
  2. KEYCODE_DPAD_CENTER
  3. Hedef ekran.

Kullanıcı döner kontrol cihazını bıraktığında VHAL, ACTION_UP ile aynı özelliği ve tuş kodunu kullanmalıdır.

Merkez düğmesi basılı tutulduğunda tekrar etkinlikleri oluşturmayın.

Geri düğmesi

Kullanıcı Geri düğmesine bastığında VHAL, Android'e etkinlik göndermek için aşağıdaki HW_KEY_INPUT özelliğini kullanmalıdır: int32Values

  1. ACTION_DOWN
  2. KEYCODE_BACK
  3. Hedef ekran.

Kullanıcı döner kontrol cihazını bıraktığında VHAL, ACTION_UP ile aynı özelliği ve tuş kodunu kullanmalıdır.

Merkez düğmesi basılı tutulurken tekrarlanan etkinlikler oluşturulmamalıdır.

Ana sayfa düğmesi

Ana sayfa düğmesini, geri düğmesi gibi kullanın ancak KEYCODE_BACK yerine KEYCODE_HOME simgesini kullanın.

Diğer düğmeler

Döner multimedya kontrol düğmesinde ek düğmeler varsa VHAL, bunları OEM'in istediği şekilde işleyebilir. Çünkü bu düğmeler, Android açısından döner multimedya kontrol düğmesinin bir parçası olarak kabul edilmez. Bunlar genellikle Geri ve Ana Sayfa düğmeleri gibi ele alınır ancak farklı tuş kodları kullanılır. Örneğin, KEYCODE_CALL veya KEYCODE_MUSIC.

Derleme yapılandırması

Döner düğme navigasyonu, RotaryService adlı bir erişilebilirlik hizmeti tarafından sağlanır. Bu hizmeti cihazınızın sistem görüntüsüne dahil etmek için makefile'ınıza aşağıdaki satırı ekleyin:

PRODUCT_PACKAGES += CarRotaryController

Hata ayıklama derlemelerine aşağıdaki paketleri de eklemek isteyebilirsiniz:

Döner servis, cihaz başlatıldığında ve kullanıcı geçişi yapıldığında otomatik olarak etkinleştirilir. Bu sayede kullanıcı, kurulum sırasında döner kontrolü kullanabilir.

Döner kontrol cihazı olan ve olmayan arabalar için aynı derlemeyi kullanıyorsanız gerekli kodun derlemeye dahil edilmesi için yukarıda gösterildiği gibi CarRotaryController ekleyin. Döner olmayan arabalarda döner hizmetinin etkinleştirilmesini önlemek için rotaryService dize kaynağını packages/services/Car/service içinde boş bir dizeyle kaplayan statik bir RRO oluşturun. Aynı derlemeyi kullanırsınız ancak döner ve döner olmayan cihazlar için ayrı ürün yapılandırmaları vardır. Yalnızca ikincisinde yer paylaşımı bulunur.

Özelleştirme

OEM'ler, aşağıdaki konumlardaki kaynak yer paylaşımları aracılığıyla odak bulma mantığını, odak vurgusunu ve bazı ek öğeleri özelleştirebilir:

  • car-ui-library, packages/apps/Car/libs/car-ui-lib konumunda bulunur.
  • RotaryService, packages/apps/Car/RotaryController konumunda bulunuyor
  • Core, frameworks/base/core konumunda bulunuyor

Otomatik hatırlatma geçmişi

OEM, iki tür hatırlatma geçmişinden her birinin etkinleştirilip etkinleştirilmeyeceğini ve etkinleştirilirse önbellek boyutunu ve geçerlilik bitimi politikasını yapılandırabilir. Bu işlemlerin tümü, çeşitli car-ui-library kaynakları geçersiz kılınarak yapılır.

Odaklanma geçmişi önbelleği

(Android 11 QPR3, Android 11 Car, Android 12)
Bu FocusArea önbelleği, FocusArea'e geri dönüldüğünde odaklanılabilmesi için FocusArea içindeki en son odaklanılan görünümü depolar. Bu önbellek, aşağıdaki car-ui-library kaynakları yerleştirilerek yapılandırılabilir:

  • car_ui_focus_history_cache_type:
    1. Önbellek devre dışı bırakıldı.
    2. Önbelleğin süresi bir süre sonra dolar (aşağıya bakın).
    3. Önbelleğin süresi asla dolmaz.
  • car_ui_focus_history_expiration_period_ms: Önbellek türü iki (2) olarak ayarlanmışsa önbelleğin süresi dolmadan kaç milisaniye önce (yukarıya bakın)

FocusArea geçmiş önbelleği

(Android 11 QPR3, Android 11 Car, Android 12)
Bu önbellek, dürtmelerin geçmişini saklar. Böylece ters yönde dürtme işlemi yapıldığında odak aynı FocusArea'ye dönebilir. Bu önbellek, aşağıdaki car-ui-library kaynakları yerleştirilerek yapılandırılabilir:

  • car_ui_focus_area_history_cache_type:
    1. Önbellek devre dışı bırakıldı.
    2. Önbelleğin süresi bir süre sonra dolar (aşağıya bakın).
    3. Önbelleğin süresi asla dolmaz.
  • car_ui_focus_area_history_expiration_period_ms: Önbellek türü 2 olarak ayarlanmışsa (yukarıya bakın) önbelleğin süresi dolmadan kaç milisaniye önce.
  • car_ui_clear_focus_area_history_when_rotating: Kullanıcı kontrol cihazını döndürdüğünde önbelleğin geçersiz kılınıp kılınmayacağı.

Döndürme

(Android 11 QPR3, Android 11 Car, Android 12)
OEM, RotaryService içinde iki tam sayı kaynağını geçersiz kılarak döndürme için fare hızlandırma gibi bir hızlandırma olup olmadığını belirtebilir:

  • rotation_acceleration_3x_ms: Google'ın, dönüş durdurma noktası için kontrol cihazı dönüşünü hızlandırıp hızlandırmaması gerektiğine karar vermek üzere kullanılan zaman aralığı (milisaniye cinsinden). Bu çentik ile önceki dönme çentiği arasındaki aralık bu değerden küçükse üç dönme çentiği olarak kabul edilir. 3× hızlandırmayı devre dışı bırakmak için bu değeri 2147483647 olarak ayarlayın.
  • rotation_acceleration_2x_ms: rotation_acceleration_3x_ms ile benzer. 2 kat hızlandırma için kullanılır. 2 kat hızlandırmayı devre dışı bırakmak için bu değeri 2147483647 olarak ayarlayın.

Hızlanma, VHAL'nin gerektirdiği gibi, her dönüş çentiği için ayrı zaman damgaları olduğunda en iyi şekilde çalışır. Bunlar kullanılamıyorsa RotaryService, dönme duraklarının eşit aralıklı olduğunu varsayar.

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

Odak vurgusu

OEM, Android çerçevesindeki varsayılan odak vurgusunu ve car-ui-library'deki çeşitli odak vurgusu kaynaklarını geçersiz kılabilir.

Varsayılan odak vurgusu

Android çerçevesi, selectableItemBackground özelliği aracılığıyla varsayılan bir odak vurgusu sağlar. Theme.DeviceDefault içinde bu özellik, Core içindeki item_background.xml öğesini ifade eder. OEM, varsayılan odak vurgusu çizilebilir öğesini değiştirmek için item_background.xml öğesini yerleştirebilir.

Bu çizilebilir öğe genellikle StateListDrawable olmalıdır. Bu öğe, android:state_focused ve android:state_pressed dahil olmak üzere farklı durum kombinasyonlarına göre arka planı ayarlar. Kullanıcı, görünümü odaklamak için döner kontrol cihazını kullandığında android:state_focused true olur ancak android:state_pressed false olur. Kullanıcı daha sonra döner kontrol cihazındaki orta düğmeye basarsa düğmeyi basılı tuttuğu sürece hem android:state_focused hem de android:state_pressed true olur. Kullanıcı düğmeyi bıraktığında yalnızca android:state_focused kalır true.

car-ui-library, Theme.DeviceDefault öğesinden türetilmiş bir tema kullanır. Sonuç olarak bu yer paylaşımı, bu kitaplığı kullanan uygulamaları ve Theme.DeviceDefault'dan türetilen temaları kullanan uygulamaları etkiler. Theme.Material gibi alakasız bir tema kullanan uygulamaları etkilemez.

Focus highlight kaynaklarını car-ui-library'de kullanma

OEM, odak vurgusunun dikdörtgen olmayan (ör. yuvarlak veya hap şeklinde) odak vurgusuna sahip görünümlerde ve Theme.DeviceDefault'dan türetilmeyen bir tema kullanan uygulamalarda nasıl görüneceğini kontrol etmek için çeşitli car-ui-library kaynaklarını geçersiz kılabilir. Bu kaynaklar, odak vurgusunun varsayılan odak vurgusu çizilebilir öğesiyle tutarlı olması için yerleştirilmelidir.

(Android 11 QPR3, Android 11 Car, Android 12)
Bir görünümün odaklandığı ancak basılmadığı zamanı belirtmek için aşağıdaki kaynaklar kullanılır:

  • car_ui_rotary_focus_fill_color: Dolgu rengi.
  • car_ui_rotary_focus_stroke_color: Dış çizgi rengi.
  • car_ui_rotary_focus_stroke_width: Anahat kalınlığı.

(Android 11 QPR3, Android 11 Car, Android 12)
Bir görünümün odaklandığı ve basıldığı zamanı belirtmek için aşağıdaki kaynaklar kullanılır:

  • car_ui_rotary_focus_pressed_fill_color: Dolgu rengi.
  • car_ui_rotary_focus_pressed_stroke_color: Dış çizgi rengi.
  • car_ui_rotary_focus_pressed_stroke_width: Anahat kalınlığı.

Bazen, gösterilen örnekte olduğu gibi, kullanıcının dikkatini çekmek için düğmeye düz bir arka plan rengi verilir. Bu durum, odak vurgusunun görülmesini zorlaştırabilir.

Düz arka planlı düğme
Şekil 2. Düz arka planlı düğme

Bu durumda geliştirici, ikincil renkleri kullanarak özel bir odak vurgusu belirtebilir:
  • (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

Örneğin, yalnızca dolgu veya yalnızca ana hat istiyorsanız renklerden herhangi biri şeffaf olabilir ve boyutlardan biri sıfır olabilir.

FocusArea vurgusu

(Android 11 QPR3, Android 11 Car, Android 12)
FocusArea, alt öğelerinden biri odaklandığında iki tür vurgu çizebilir. İstenirse her ikisi de birlikte kullanılabilir. Bu özellik, AOSP'de varsayılan olarak devre dışıdır ancak car-ui-library kaynakları geçersiz kılınarak etkinleştirilebilir:

  • car_ui_enable_focus_area_foreground_highlight: FocusArea ve alt öğelerinin üzerine vurgu çizin. AOSP'de bu çizilebilir öğe, FocusArea öğesinin etrafındaki bir ana hattır. OEM'ler, car_ui_focus_area_foreground_highlight çizilebilir öğesini geçersiz kılabilir.
  • car_ui_enable_focus_area_background_highlight: FocusArea öğesinin üzerinde ancak alt öğelerinin arkasında bir vurgu çizin. AOSP'de bu çizilebilir öğe, düz bir dolgudur. OEM'ler car_ui_focus_area_background_highlight çizilebilir öğesini geçersiz kılabilir.

Giriş Yöntemi Düzenleyiciler

Giriş yöntemi düzenleyiciler (IME), giriş yöntemleridir. Örneğin, dokunmatik klavye.

(Android 11 QPR3, Android 11 Car, Android 12)
OEM, dokunmaya dayalı IME'nin ComponentName değerini belirtmek için RotaryService içinde default_touch_input_method dize kaynağını yerleştirmelidir. Örneğin, OEM, Android Automotive ile birlikte sağlanan IME'yi kullanıyorsa com.google.android.apps.automotive.inputmethod/.InputMethodService değerini belirtmelidir.

(Android 11 QPR3, Android 11 Car, Android 12)
OEM, döner düğme için özel bir IME oluşturduysa rotary_input_method kaynağında ComponentName değerini belirtmelidir. Bu kaynak yerleştirilmişse kullanıcı, döner kontrol cihazının dürtme, döndürme ve merkez düğmesi aracılığıyla ana üniteyle etkileşimde bulunduğunda belirtilen IME kullanılır. Kullanıcı ekrana dokunduğunda önceki IME kullanılır. Geri düğmesi (ve döner kontrol cihazındaki diğer düğmeler), IME seçimini etkilemez. Bu kaynak yerleştirilmezse IME değiştirme işlemi gerçekleşmez. Cardboard, çevirmeli girişi desteklemediği için OEM tarafından çevirmeli IME sağlanmamışsa kullanıcı, çevirmeli kontrol cihazı aracılığıyla metin giremez.

RotaryIME, demo bir çevirmeli IME'dir. Temel bir yöntem olsa da yukarıda açıklanan otomatik IME geçişini denemek için yeterlidir. RotaryIME kaynak kodunu packages/apps/Car/tests/RotaryIME/ adresinde bulabilirsiniz.

Ekran dışı hatırlatıcılar

Varsayılan olarak, kullanıcı ekranın kenarından çıkmaya çalıştığında hiçbir şey olmaz. OEM, aşağıdaki kombinasyonlardan herhangi birini belirterek dört yönün her birinde ne olacağını yapılandırabilir:

  1. AccessibilityService tarafından tanımlanan genel bir işlem. Örneğin, GLOBAL_ACTION_BACK.
  2. KEYCODE_BACK gibi bir anahtar kodu.
  3. Bir URL olarak temsil edilen etkinliği başlatma amaçlı bir intent.

(Android 11 QPR3, Android 11 Car, Android 12)
Bunlar, RotaryService içinde aşağıdaki dizi kaynakları yerleştirilerek belirtilir:

  • off_screen_nudge_global_actions: Kullanıcı ekranın kenarından yukarı, aşağı, sola veya sağa kaydırdığında gerçekleştirilecek genel işlemler dizisi. Bu dizinin ilgili öğesi -1 ise herhangi bir genel işlem yapılmaz.
  • off_screen_nudge_key_codes: Kullanıcı ekranın kenarından yukarı, aşağı, sola veya sağa doğru kaydırdığında yerleştirilecek tıklama etkinliklerinin tuş kodları dizisi. Bu dizinin ilgili öğesi 0 (KEYCODE_UNKNOWN) ise etkinlik eklenmez.
  • off_screen_nudge_intents: Kullanıcı ekranın kenarından yukarı, aşağı, sola veya sağa kaydırdığında bir etkinliği başlatacak intent dizisi. Bu dizinin ilgili öğesi boşsa hiçbir etkinlik başlatılmaz.

Diğer yapılandırmalar

Aşağıdaki RotaryService kaynakları yerleştirmeniz gerekir:

  • (Android 11 QPR3, Android 11 Car, Android 12)
    config_showHeadsUpNotificationOnBottom: Anlık bildirimlerin üstte değil altta gösterilip gösterilmeyeceğini belirten Boole değeri. Bu, config_showHeadsUpNotificationOnBottom Boole kaynağı ile aynı değere sahip olmalıdır frameworks/base/packages/CarSystemUI/res/values/config.xml
  • (Android 11 QPR3, Android 11 Car, Android 12)
    notification_headsup_card_margin_horizontal: Anlık bildirim penceresinin sol ve sağ kenar boşluğu. Bu, packages/apps/Car/Notification/res/values/dimens.xml içindeki notification_headsup_card_margin_horizontal dimen kaynağıyla aynı değere sahip olmalıdır.
  • (Android 12)
    excluded_application_overlay_window_titles: Yer paylaşımı pencereleri olarak kabul edilmemesi gereken pencerelerin başlık dizisi. Bu, TaskViews veya TaskDisplayAreas'yi temsil eden uygulama pencerelerinin başlıklarını içermelidir. Varsayılan olarak bu listede yalnızca "Haritalar" bulunur.

Aşağıdaki RotaryService kaynağı yerleştirebilirsiniz:

  • (Android 11 QPR3, Android 11 Car, Android 12)
    long_press_ms: Orta düğmenin uzun basma işlemini tetiklemek için kaç milisaniye basılı tutulması gerektiğini gösteren tam sayı değeri. Sıfır, sistemin varsayılan uzun basma zaman aşımının kullanılması gerektiğini belirtir. Bu, varsayılan değerdir.