OEM'ler için entegrasyon kılavuzu

Bu sayfada, VHAL'de döner girişlerin nasıl işleneceği, derlemenizi döner hizmeti içerecek şekilde yapılandırma ve döner deneyimini tüm uygulamalarda nasıl özelleştireceğiniz 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ükleyin.
  • Saat yönünde ve saat yönünün tersine döndürün.
  • Orta 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 ile ilgili dokümanlar için hardware/interfaces/automotive/vehicle/2.0/types.hal bölümüne bakın.

VHAL aşağıdaki işlemleri yapmalıdır:

Hatırlatma

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 mülkünü kullanmalıdır:

  1. ACTION_DOWN
  2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
  3. Görüntülü reklamları hedefleyin.

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

Dikeyler için anahtar kodları yoktur ancak donanım dikeyleri destekliyorsa VHAL, yatay ve dikey bir etkinliği birleştirerek dikey oluşturabilir. Örneğin, yukarı ve sola doğru hareket ettirdiğinizde şunu görürsünüz:

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

Her iki sırada da (ve sonrasında) döner kumandayı bıraktığınızda aşağıdakiler gerçekleşir:

  • 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 senaryo:

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

Bu işlem aşağıdaki sırayla gerçekleşir:

  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 bir yönde tutulurken tekrar etkinliği oluşturulmamalıdır.

Döndür

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

  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. Bir (1) kilitleme noktası.
  3. Görüntülü reklamları hedefleyin.

Etkinliğin zaman damgası, geçen sürenin nanosaniye cinsinden değerine ayarlanmalıdır.

Bir (1) mandalın saat yönünün tersine döndürülmesi, aynı etkinliği oluşturmalıdır ancak mandal sayısı için -1 değeri kullanılır.

Aynı yönde hızlıca art arda birden fazla kilitlenme meydana gelirse VHAL, sistemi etkinlikle aşırı yüklememek için kilitlenmeleri tek bir etkinlikte birleştirmelidir. Bu durumda, etkinliğin zaman damgası, ilk dönme aralığının gerçekleştiği zaman olmalıdır. int32Values, art arda gelen dönme durakları arasındaki nanosaniye sayısını içermelidir.

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

  • t0 zamanında kullanıcı, bir kilitleme noktasını saat yönünün tersine çevirdi.
  • t0 + 5 ns zamanında kullanıcı, bir kilitleme noktasını saat yönünün tersine çevirdi.
  • t0 + 8 ns zamanında kullanıcı, bir kilitleme noktasını 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 üç kademeli).
    3. Görüntülü reklamları hedefleyin.
    4. Birinci ve ikinci durma noktası arasında 5 ns.
    5. İkinci ve üçüncü durma noktası 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 int32Values ile HW_KEY_INPUT mülkünü kullanmalıdır:

  1. ACTION_DOWN
  2. KEYCODE_DPAD_CENTER
  3. Görüntülü reklamları hedefleyin.

Kullanıcı döner kontrol cihazını bıraktığında VHAL, ACTION_UP ile aynı mülkü ve anahtar kodunu kullanmalıdır.

Orta düğme basılıyken 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 int32Values ile HW_KEY_INPUT mülkünü kullanmalıdır:

  1. ACTION_DOWN
  2. KEYCODE_BACK
  3. Görüntülü reklamları hedefleyin.

Kullanıcı döner kontrol cihazını bıraktığında VHAL, ACTION_UP ile aynı mülkü ve anahtar kodunu kullanmalıdır.

Orta düğme basılıyken tekrar etkinliği oluşturulmaz.

Ana ekran düğmesi

Ana ekran düğmesini, Geri düğmesi gibi kullanın ancak KEYCODE_BACK yerine KEYCODE_HOME tuşuna basın.

Diğer düğmeler

Döner kontrol cihazında ek düğmeler varsa Android açısından döner kontrol cihazının bir parçası olarak kabul edilmediklerinden VHAL bunları OEM'nin istediği şekilde işleyebilir. Bunlar genellikle Geri ve Ana Sayfa düğmeleri gibi ele alınır ancak farklı tuş kodlarına sahiptir. Örneğin, KEYCODE_CALL veya KEYCODE_MUSIC.

Derleme yapılandırması

Döner gezinme, RotaryService adlı bir erişilebilirlik hizmeti tarafından sağlanır. Bu hizmeti cihazınızın sistem resmine dahil etmek için makefile dosyanıza aşağıdaki satırı ekleyin:

PRODUCT_PACKAGES += CarRotaryController

Aşağıdaki paketleri de hata ayıklama derlemelerine ekleyebilirsiniz:

  • RotaryPlayground Döner kontrol için referans uygulama (RotaryPlayground'a bakın).
  • RotaryIME Demo olarak kullanılan bir döner IME (Giriş Yöntemi Düzenleyiciler bölümüne bakın).
  • CarRotaryImeRRO RotaryIME için yer paylaşımlı resim.

Döner hizmet, cihaz açıldığında ve kullanıcı geçişi olduğunda otomatik olarak etkinleştirilir. Bu sayede kullanıcı, kurulum sırasında döner kontrol cihazını kullanabilir.

Döner kontrol düğmesi olan ve olmayan araçlar için aynı derlemeyi kullanıyorsanız gerekli kodun derlemeye eklenmesi için yukarıda gösterildiği gibi CarRotaryController ekleyin. Döner hizmetin döner olmayan araçlarda etkinleştirilmesini önlemek için packages/services/Car/service içindeki rotaryService dize kaynağını boş bir dizeyle örtüşecek şekilde statik bir RRO oluşturun. Aynı derlemeyi kullanırsınız ancak döner ve dönmeyen cihazlar için ayrı ürün yapılandırmalarınız olur. Yalnızca ikincisi yer paylaşımını içerir.

Ö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 konumundadır.
  • RotaryService, packages/apps/Car/RotaryController bölgesinde bulunuyor
  • Core, frameworks/base/core bölgesinde bulunuyor

Hatırlatma geçmişi

OEM, iki tür hatırlatma geçmişinin etkin olup olmadığını ve etkinse önbelleğe alma boyutunu ve geçerlilik bitiş tarihini yapılandırabilir. Tüm bunlar, çeşitli car-ui-library kaynaklarının geçersiz kılınmasıyla yapılır.

Odak geçmişi önbelleği

(Android 11 QPR3, Android 11 Car, Android 12)
Bu FocusArea başına önbelleğe alma özelliği, FocusArea'a geri döndürüldüğünde odaklanabilmesi için FocusArea içinde en son odaklanan görünümü depolar. Bu önbellek, aşağıdaki car-ui-library kaynaklarının yer paylaşımı yapılarak yapılandırılabilir:

  • car_ui_focus_history_cache_type:
    1. Önbelleğe alma 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 hiçbir zaman dolmaz.
  • car_ui_focus_history_expiration_period_ms: Önbelleğe alma türü iki (2) olarak ayarlanmışsa önbelleğin süresinin dolmasına kaç milisaniye kaldığını belirtir (yukarıya bakın).

FocusArea geçmişi önbelleği

(Android 11 QPR3, Android 11 Car, Android 12)
Bu önbellekte, zıt yönde itme işleminin odağın aynı FocusArea öğesine dönmesini sağlamak için itme geçmişi saklanır. Bu önbellek, aşağıdaki car-ui-library kaynaklarının yer paylaşımı yapılarak yapılandırılabilir:

  • car_ui_focus_area_history_cache_type:
    1. Önbelleğe alma 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: Önbelleğe alma türü 2 olarak ayarlanmışsa önbelleğin geçerlilik süresinin dolmasına kaç milisaniye kaldığını belirtir (yukarıya bakın).
  • car_ui_clear_focus_area_history_when_rotating: Kullanıcı kontrol cihazını döndürdüğünde önbelleğin iptal edilip edilmeyeceği.

Döndürme

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

  • rotation_acceleration_3x_ms: Google'ın bir kilitleme noktası için kontrolör dönüşünü hızlandırması gerekip gerekmediğine karar vermek amacıyla kullanılan zaman aralığı (milisaniye cinsinden). Bu durma noktası ile önceki durma noktası arasındaki aralık bu değerden azsa üç durma noktası olarak değerlendirilir. 3 kat hızlandırmayı devre dışı bırakmak için bu değeri 2147483647 olarak ayarlayın.
  • rotation_acceleration_2x_ms: rotation_acceleration_3x_ms'a benzer. 2 kat hızlandırma için kullanılır. 2 kat hızlandırmayı devre dışı bırakmak için bu ayarı 2147483647 olarak ayarlayın.

Hızlanma, VHAL tarafından zorunludur olduğu için her bir dönme aralığı için ayrı zaman damgaları olduğunda en iyi şekilde çalışır. Bunlar mevcut değilse RotaryService, dönme durma noktalarının eşit aralıklarla yerleştirilmiş 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'te bu özellik, Core'deki item_background.xml'yi ifade eder. OEM, varsayılan odak vurgusu çizilebilir öğesini değiştirmek için item_background.xml öğesini yer paylaşımı olarak kullanabilir.

Bu çizilebilir öğe genellikle android:state_focused ve android:state_pressed dahil olmak üzere farklı durum kombinasyonlarına göre arka planı ayarlayan bir StateListDrawable olmalıdır. Kullanıcı, bir görünüme odaklanmak için döner kumandayı 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üğme basılı tutulurken hem android:state_focused hem de android:state_pressed true olur. Kullanıcı düğmeyi bıraktığında yalnızca android:state_focused kalırtrue.

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

car-ui-library'de vurgu kaynaklarına odaklanma

OEM, dikdörtgen olmayan (yuvarlak veya hap şeklinde) bir odak vurgusuna sahip görünümlerde ve Theme.DeviceDefault'ten türetilmiş olmayan bir tema kullanan uygulamalarda odak vurgusunun 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 yer paylaşımına tabi tutulmalıdır.

(Android 11 QPR3, Android 11 Car, Android 12)
Bir görünüme odaklanıldığında ancak basılmadığında 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: Ana hat kalınlığı.

(Android 11 QPR3, Android 11 Car, Android 12)
Bir görünümün ne zaman odağa alındığını ve basıldığını 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: Ana hat kalınlığı.

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

Katı arka plana sahip 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

Renklerden herhangi biri saydam olabilir ve boyutlardan biri sıfır olabilir (ör. yalnızca dolgu veya yalnızca dış çizgi isterseniz).

FocusArea vurgusu

(Android 11 QPR3, Android 11 Car, Android 12)
FocusArea, alt öğelerinden biri odaklandığında iki tür vurgu çizebilir. Dilerseniz her ikisini birlikte kullanabilirsiniz. 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 bir vurgu çizin. AOSP'de bu çizilebilir öğe, FocusArea etrafındaki bir dış çizgidir. OEM'ler car_ui_focus_area_foreground_highlight çizilebilir öğesini geçersiz kılabilir.
  • car_ui_enable_focus_area_background_highlight: FocusArea öğesinin üstüne ancak alt öğelerinin arkasına vurgu çizin. AOSP'de bu çizilebilir öğe, doldurulmuş bir alan olarak görünür. 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, dokunmatik tabanlı IME'nin ComponentName değerini belirtmek için default_touch_input_method dize kaynağını RotaryService üzerine yerleştirmelidir. Örneğin, OEM Android Automotive ile 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 olarak bir IME oluşturduysa ComponentName değerini rotary_input_method kaynağında belirtmelidir. Bu kaynak örtüşürse kullanıcı, döner kontrol cihazının itme, döndürme ve orta düğmesi aracılığıyla ana üniteyle etkileşim kurduğunda belirtilen IME kullanılır. Kullanıcı ekrana dokunduğunda önceki IME kullanılır. Geri düğmesinin (ve döner kontrol cihazındaki diğer düğmelerin) IME seçimi üzerinde hiçbir etkisi yoktur. Bu kaynak örtüşmüyorsa IME geçişi gerçekleşmez. Carboard, çevirmeli girişleri desteklemez. Bu nedenle, OEM çevirmeli bir IME sağlamadıysa kullanıcı çevirmeli kontrol cihazı aracılığıyla metin giremez.

RotaryIME, demo olarak kullanılan bir çevirmeli IME'dir. Temel olsa da yukarıda açıklanan otomatik IME geçişini denemek yeterlidir. RotaryIME için kaynak kodu packages/apps/Car/tests/RotaryIME/'da bulunabilir.

Ekran dışı hatırlatmalar

Varsayılan olarak, kullanıcı ekranın kenarından uzaklaşmaya çalıştığında hiçbir şey olmaz. OEM, aşağıdakilerin herhangi bir kombinasyonunu belirterek dört yönün her biri için ne olması gerektiğini 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. URL olarak temsil edilen bir etkinliği başlatma intent'i.

(Android 11 QPR3, Android 11 Car, Android 12)
Bunlar, RotaryService içinde aşağıdaki dizi kaynaklarının yer paylaşımıyla belirtilir:

  • off_screen_nudge_global_actions: Kullanıcı ekranın kenarından yukarı, aşağı, sola veya sağa doğru hareket ettiğinde gerçekleştirilecek genel işlemler dizisi. Bu dizinin ilgili öğesi -1 ise 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 hareket ettiğinde eklenecek tıklama etkinliklerinin anahtar kodları dizisi. Bu dizideki ilgili öğe 0 (KEYCODE_UNKNOWN) ise etkinlik eklenmez.
  • off_screen_nudge_intents: Kullanıcı ekranın kenarından yukarı, aşağı, sola veya sağa doğru kaydırdığında bir etkinlik başlatmak için intent dizisi. Bu dizinin ilgili öğesi boşsa etkinlik başlatılmaz.

Diğer yapılandırmalar

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

  • (Android 11 QPR3, Android 11 Car, Android 12)
    config_showHeadsUpNotificationOnBottom: Uyarı bildirimlerinin üstte değil de altta gösterilip gösterilmeyeceğini belirten boole değeri. Bu, frameworks/base/packages/CarSystemUI/res/values/config.xml'daki config_showHeadsUpNotificationOnBottom Boole kaynağıyla aynı değere sahip olmalıdır.
  • (Android 11 QPR3, Android 11 Car, Android 12)
    notification_headsup_card_margin_horizontal: Bildirim penceresi için 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şımlı pencere olarak değerlendirilmemesi gereken pencere başlıklarının dizisi. Bu, TaskViews veya TaskDisplayAreas'ü temsil eden uygulama pencerelerinin başlıklarını içermelidir. Bu liste varsayılan olarak yalnızca "Haritalar"ı içerir.

Aşağıdaki RotaryService kaynağını yer paylaşımı olarak kullanabilirsiniz:

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