راهنمای یکپارچه سازی برای OEM ها

این صفحه نحوه پردازش ورودی های چرخشی در VHAL، پیکربندی ساخت خود را برای گنجاندن سرویس چرخشی و نحوه سفارشی کردن تجربه چرخشی در همه برنامه ها شرح می دهد. برای برنامه‌های OEM از پیش نصب‌شده، مانند راه‌اندازی که OEM ارائه می‌کند، به کتابخانه UI Car (car-ui-library) مراجعه کنید.

VHAL

یک کنترلر چرخشی از اقدامات زیر پشتیبانی می کند:

• به بالا، پایین، چپ و راست تکان دهید.
• در جهت عقربه های ساعت و خلاف جهت عقربه های ساعت بچرخانید.
• دکمه مرکز را فشار دهید.
• دکمه برگشت را فشار دهید.
• دکمه Home را فشار دهید.
• دکمه های دیگر مانند تلفن و رسانه را فشار دهید.

برای مستندات مربوط به خصوصیات سیستم و int32Values مربوطه به hardware/interfaces/automotive/vehicle/2.0/types.hal مراجعه کنید.

VHAL باید این اقدامات را انجام دهد:

• تکان دادن
• چرخش
• دکمه مرکزی
• دکمه برگشت
• دکمه صفحه اصلی
• دکمه های دیگر

تکان دادن

هنگامی که کاربر کنترل کننده چرخشی را به سمت راست فشار می دهد، VHAL باید از ویژگی HW_KEY_INPUT با int32Values زیر برای ارسال یک رویداد به Android استفاده کند:

1. ACTION_DOWN
2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
3. نمایش هدف.

هنگامی که کاربر کنترل کننده چرخشی را آزاد می کند، VHAL باید از همان ویژگی و کد کلید با ACTION_UP استفاده کند. تلنگرها در جهات دیگر باید از کدهای کلید مربوطه استفاده کنند.

هیچ کد کلیدی برای مورب ها وجود ندارد، اما VHAL می تواند یک رویداد افقی و عمودی را برای تولید یک مورب ترکیب کند، اگر سخت افزار از مورب ها پشتیبانی کند. برای مثال، تکان دادن به سمت چپ و بالا باید تولید کند:

• 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

کاربر ممکن است کنترل کننده چرخشی را قبل از رها کردن آن در جهت عمود فشار دهد. به عنوان مثال، سناریوی زیر:

این باید دنباله ای از رویدادها را ایجاد کند:

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

در حالی که کنترل کننده چرخشی در یک جهت نگه داشته شده است، هیچ رویداد تکراری نباید ایجاد شود.

چرخش

هنگامی که کاربر کنترلر چرخشی را در جهت عقربه‌های ساعت می‌چرخاند (کلیک کنید)، VHAL باید از ویژگی HW_ROTARY_INPUT با int32Values ​​زیر برای ارسال یک رویداد به Android استفاده کند:

1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
2. یک (1) بازدارنده.
3. نمایش هدف.

مهر زمانی رویداد باید روی زمان سپری شده بر حسب نانوثانیه تنظیم شود.

یک (1) چرخش در خلاف جهت عقربه‌های ساعت باید همان رویداد را ایجاد کند، اما برای تعداد گیره‌ها -1 را ایجاد کند.

اگر چرخش های متعدد در یک جهت به صورت متوالی اتفاق بیفتد، VHAL باید آن ها را در یک رویداد واحد ترکیب کند تا سیستم را با حوادث بیش از حد بارگیری نکند. در این مورد، مهر زمانی رویداد باید زمانی باشد که اولین بازدارنده چرخش اتفاق افتاده باشد. int32Values باید شامل تعداد نانوثانیه‌های بین چرخش‌های متوالی باشد.

به عنوان مثال، دنباله چرخش زیر:

• در زمان t0، کاربر یک دتنت را در خلاف جهت عقربه های ساعت چرخاند.
• در زمان t0 + 5 ns، کاربر یک دتنت را در خلاف جهت عقربه‌های ساعت چرخاند.
• در زمان t0 + 8 ns، کاربر یک دتنت را در خلاف جهت عقربه‌های ساعت چرخاند.

باید این رویداد را ایجاد کند:

• ویژگی: HW_ROTARY_INPUT
• مهر زمانی: t0
• int32Values :
  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. -3 (سه سوراخ در خلاف جهت عقربه های ساعت).
  3. نمایش هدف.
  4. 5 ns بین اولین و دومین بازدارنده.
  5. 3 ns بین دود دوم و سوم.

دکمه مرکزی

هنگامی که کاربر دکمه مرکز را فشار می دهد، VHAL باید از ویژگی HW_KEY_INPUT با int32Values زیر برای ارسال یک رویداد به Android استفاده کند:

1. ACTION_DOWN
2. KEYCODE_DPAD_CENTER
3. نمایش هدف.

هنگامی که کاربر کنترل کننده چرخشی را آزاد می کند، VHAL باید از همان ویژگی و کد کلید با ACTION_UP استفاده کند.

هنگامی که دکمه مرکز را پایین نگه دارید، رویدادهای تکراری ایجاد نکنید.

دکمه برگشت

هنگامی که کاربر دکمه بازگشت را فشار می دهد، VHAL باید از ویژگی HW_KEY_INPUT با int32Values زیر برای ارسال یک رویداد به Android استفاده کند:

1. ACTION_DOWN
2. KEYCODE_BACK
3. نمایش هدف.

هنگامی که کاربر کنترل کننده چرخشی را آزاد می کند، VHAL باید از همان ویژگی و کد کلید با ACTION_UP استفاده کند.

در حالی که دکمه مرکز را پایین نگه داشته اید، هیچ رویداد تکراری نباید ایجاد شود.

دکمه صفحه اصلی

دکمه صفحه اصلی را مانند دکمه بازگشت استفاده کنید اما به جای KEYCODE_HOME KEYCODE_BACK

دکمه های دیگر

اگر کنترل‌کننده چرخشی شامل دکمه‌های اضافی باشد، VHAL می‌تواند آن‌ها را هر طور که OEM دوست دارد کنترل کند، زیرا از دیدگاه اندروید بخشی از چرخش محسوب نمی‌شوند. این‌ها معمولاً مانند دکمه‌های بازگشت و صفحه اصلی اما با کدهای کلید متفاوتی کار می‌کنند. برای مثال، KEYCODE_CALL یا KEYCODE_MUSIC .

پیکربندی ساخت

ناوبری چرخشی توسط یک سرویس دسترسی به نام RotaryService ارائه می شود. برای گنجاندن این سرویس در تصویر سیستم برای دستگاه خود، خط زیر را به makefile خود اضافه کنید:

PRODUCT_PACKAGES += CarRotaryController

همچنین ممکن است بخواهید بسته های زیر را در بیلدهای اشکال زدایی قرار دهید:

• RotaryPlayground یک برنامه مرجع برای چرخش (به RotaryPlayground مراجعه کنید).
• RotaryIME یک IME روتاری دمو (به ویرایشگرهای روش ورودی مراجعه کنید).
• CarRotaryImeRRO پوشش RotaryIME .

هنگامی که دستگاه بوت می شود و هنگامی که سوئیچ کاربر رخ می دهد، سرویس چرخشی به طور خودکار فعال می شود. این تضمین می کند که کاربر می تواند در حین راه اندازی از کنترلر چرخشی استفاده کند.

اگر از همان بیلد برای خودروهای دارای کنترلر چرخشی و بدون کنترلر چرخشی استفاده می کنید، CarRotaryController را مانند تصویر بالا اضافه کنید تا کد لازم در بیلد گنجانده شود. برای جلوگیری از فعال شدن سرویس چرخشی در خودروهای غیر چرخشی، یک RRO ایستا ایجاد کنید تا منبع رشته rotaryService را در packages/services/Car/service با یک رشته خالی پوشش دهد. شما از همان ساخت استفاده خواهید کرد، اما تنظیمات محصول جداگانه ای برای دستگاه های چرخشی و غیر چرخشی دارید. فقط مورد دوم شامل پوشش است.

سفارشی سازی

OEM ها می توانند منطق یافتن فوکوس، برجسته سازی فوکوس و برخی موارد اضافی را از طریق همپوشانی منابع در مکان های زیر سفارشی کنند:

• car-ui-library در packages/apps/Car/libs/car-ui-lib قرار دارد
• RotaryService در packages/apps/Car/RotaryController قرار دارد
• Core در frameworks/base/core قرار دارد

سوق دادن به تاریخ

OEM می‌تواند فعال بودن یا نبودن هر یک از دو نوع سوابق حرکتی و در این صورت، اندازه کش و خط‌مشی انقضا را پیکربندی کند. این همه با نادیده گرفتن منابع مختلف car-ui-library انجام می شود.

حافظه پنهان تاریخچه را متمرکز کنید

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
این حافظه پنهان برای هر FocusArea جدیدترین نمای متمرکز شده را در FocusArea ذخیره می کند تا بتوان هنگام بازگشت به FocusArea فوکوس کرد. این کش را می توان با همپوشانی منابع car-ui-library زیر پیکربندی کرد:

• car_ui_focus_history_cache_type :
  1. کش غیرفعال است.
  2. کش پس از مدتی منقضی می شود (به زیر مراجعه کنید).
  3. کش هرگز منقضی نمی شود.
• car_ui_focus_history_expiration_period_ms : چند میلی ثانیه قبل از انقضای حافظه نهان اگر نوع کش روی دو (2) تنظیم شود (به بالا مراجعه کنید).

حافظه پنهان تاریخچه FocusArea

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
این حافظه پنهان تاریخچه ای از اشاره ها را ذخیره می کند تا حرکت دادن در جهت مخالف بتواند فوکوس را به همان FocusArea برگرداند. این کش را می توان با همپوشانی منابع car-ui-library زیر پیکربندی کرد:

• car_ui_focus_area_history_cache_type :
  1. کش غیرفعال است.
  2. کش پس از مدتی منقضی می شود (به زیر مراجعه کنید).
  3. کش هرگز منقضی نمی شود.
• car_ui_focus_area_history_expiration_period_ms : چند میلی ثانیه قبل از انقضای حافظه پنهان اگر نوع کش روی 2 تنظیم شود (به بالا مراجعه کنید).
• car_ui_clear_focus_area_history_when_rotating : زمانی که کاربر کنترلر را می چرخاند، حافظه پنهان پاک شود یا نه.

چرخش

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
OEM می تواند دو منبع صحیح را در RotaryService لغو کند تا مشخص کند که آیا شتابی مانند شتاب ماوس برای چرخش وجود دارد یا خیر:

• rotation_acceleration_3x_ms : فاصله زمانی (بر حسب میلی ثانیه) مورد استفاده برای تصمیم گیری در مورد اینکه آیا Google باید چرخش کنترلر را برای کاهش چرخش تسریع کند یا خیر. اگر فاصله بین این دتنت و عقب‌نشینی چرخش قبلی کمتر از این مقدار باشد، به‌عنوان سه فرورفتگی چرخش تلقی می‌شود. این را روی 2147483647 تنظیم کنید تا شتاب 3× غیرفعال شود.
• rotation_acceleration_2x_ms : مشابه rotation_acceleration_3x_ms . برای شتاب 2× استفاده می شود. این را روی 2147483647 تنظیم کنید تا شتاب 2× غیرفعال شود.

شتاب زمانی بهتر عمل می کند که برای هر بازدارنده چرخش مهرهای زمانی جداگانه وجود داشته باشد، همانطور که VHAL لازم است . اگر این‌ها در دسترس نباشند، RotaryService فرض می‌کند که گیره‌های چرخش به طور مساوی فاصله دارند.

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

برجسته تمرکز

OEM می‌تواند برجسته‌سازی پیش‌فرض تمرکز در چارچوب Android و چندین منبع برجسته تمرکز در car-ui-library را لغو کند.

برجسته کردن فوکوس پیش‌فرض

چارچوب Android از طریق ویژگی selectableItemBackground یک برجسته‌سازی پیش‌فرض فوکوس ارائه می‌کند. در Theme.DeviceDefault ، این ویژگی به item_background.xml در Core اشاره دارد. OEM می تواند item_background.xml را برای تغییر برجسته کردن فوکوس پیش فرض قابل ترسیم پوشش دهد.

این رسم معمولاً باید StateListDrawable باشد که پس‌زمینه را بر اساس ترکیب‌های مختلف حالت‌ها، از جمله android:state_focused و android:state_pressed تنظیم می‌کند. هنگامی که کاربر از کنترلر چرخشی برای فوکوس کردن یک نما استفاده می کند، android:state_focused true است، اما android:state_pressed false خواهد بود. اگر کاربر سپس دکمه مرکز روی کنترلر چرخشی را فشار دهد، هر دو android:state_focused و android:state_pressed true خواهند بود در حالی که کاربر دکمه را پایین نگه داشته است. وقتی کاربر دکمه را رها می کند، فقط android:state_focused true باقی می ماند.

car-ui-library از یک تم مشتق شده از Theme.DeviceDefault استفاده می کند. در نتیجه، این پوشش روی برنامه‌هایی که از این کتابخانه استفاده می‌کنند و برنامه‌هایی که از هر طرح زمینه برگرفته از Theme.DeviceDefault استفاده می‌کنند، تأثیر می‌گذارد. روی برنامه‌هایی که از طرح زمینه نامرتبط استفاده می‌کنند، مانند Theme.Material ، تأثیری نمی‌گذارد.

تمرکز بر منابع برجسته در car-ui-library

OEM می‌تواند چندین منبع car-ui-library را نادیده بگیرد تا نحوه برجسته‌سازی فوکوس را روی نماهایی با برجسته‌سازی غیرمستطیلی (مانند گرد یا قرص‌شکل) و در برنامه‌هایی که از طرح زمینه استفاده می‌کنند استفاده کند که از Theme.DeviceDefault استفاده نمی‌کند، نادیده بگیرد. Theme.DeviceDefault . این منابع باید به گونه‌ای روی هم قرار گیرند که برجسته‌سازی فوکوس با برجسته‌سازی تمرکز پیش‌فرض قابل ترسیم مطابقت داشته باشد.

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
منابع زیر برای نشان دادن زمانی که یک نما فوکوس شده است اما فشرده نشده است استفاده می شود:

• car_ui_rotary_focus_fill_color : رنگ پر کنید.
• car_ui_rotary_focus_stroke_color : رنگ طرح کلی.
• car_ui_rotary_focus_stroke_width : ضخامت طرح کلی.

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
منابع زیر برای نشان دادن زمان فوکوس و فشار دادن یک نما استفاده می شود:

• car_ui_rotary_focus_pressed_fill_color : رنگ را پر کنید.
• car_ui_rotary_focus_pressed_stroke_color : رنگ طرح کلی.
• car_ui_rotary_focus_pressed_stroke_width : ضخامت طرح کلی.

گاهی اوقات به یک دکمه رنگ پس زمینه ثابت داده می شود تا مورد توجه کاربر قرار گیرد، همانطور که در مثال نشان داده شده است. این ممکن است برجسته کردن فوکوس را دشوار کند.

در این شرایط، توسعه‌دهنده می‌تواند با استفاده از رنگ‌های ثانویه ، برجسته‌سازی تمرکز سفارشی را مشخص کند:

• ( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
  car_ui_rotary_focus_fill_secondary_color
car_ui_rotary_focus_stroke_secondary_color
• ( اندروید 12 )
  car_ui_rotary_focus_pressed_fill_secondary_color
car_ui_rotary_focus_pressed_stroke_secondary_color

هر یک از رنگ‌ها می‌تواند شفاف باشد و هر کدام از ابعاد می‌تواند صفر باشد، برای مثال، اگر فقط یک پر شده یا فقط یک طرح کلی بخواهید.

برجسته FocusArea

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
FocusArea می تواند دو نوع برجسته را در زمانی که یکی از فرزندانش فوکوس می کند ترسیم کند. در صورت تمایل می توان از هر دو به همراه استفاده کرد. این ویژگی به طور پیش‌فرض در AOSP غیرفعال است، اما می‌توان آن را با نادیده گرفتن منابع car-ui-library فعال کرد:

• car_ui_enable_focus_area_foreground_highlight : یک برجسته در بالای FocusArea و فرزندان آن بکشید. در AOSP، این قابل ترسیم یک طرح کلی در اطراف FocusArea است. OEM ها می توانند car_ui_focus_area_foreground_highlight قابل ترسیم را لغو کنند.
• car_ui_enable_focus_area_background_highlight : یک برجسته در بالای FocusArea اما پشت نوادگان آن بکشید. در AOSP، این قابل کشیدن یک پر جامد است. OEM ها می توانند car_ui_focus_area_background_highlight قابل ترسیم را لغو کنند.

ویرایشگرهای روش ورودی

ویرایشگرهای روش ورودی (IME) روش های ورودی هستند. به عنوان مثال، یک صفحه کلید روی صفحه.

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
OEM باید منبع رشته default_touch_input_method را در RotaryService قرار دهد تا ComponentName IME مبتنی بر لمس را مشخص کند. برای مثال، اگر OEM از IME ارائه شده با Android Automotive استفاده کند، باید com.google.android.apps.automotive.inputmethod/.InputMethodService را مشخص کند.

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
اگر OEM یک IME خاص برای چرخش ایجاد کرده است، باید ComponentName آن را در منبع rotary_input_method مشخص کند. اگر این منبع روی هم قرار گیرد، هر زمان که کاربر از طریق فشار دادن، چرخش، و دکمه مرکزی کنترلر چرخشی با واحد اصلی تعامل داشته باشد، از IME مشخص شده استفاده می شود. هنگامی که کاربر صفحه را لمس می کند، IME قبلی استفاده می شود. دکمه برگشت (و سایر دکمه های روی کنترلر چرخشی) هیچ تاثیری در انتخاب IME ندارد. اگر این منبع روی هم قرار نگیرد، هیچ تغییر IME رخ نمی دهد. Carboard از چرخش پشتیبانی نمی کند، بنابراین اگر OEM یک IME چرخشی ارائه نکرده باشد، کاربر نمی تواند متن را از طریق کنترل کننده چرخشی وارد کند.

RotaryIME یک IME چرخشی آزمایشی است. در حالی که ساده است، کافی است سوئیچینگ خودکار IME که در بالا توضیح داده شد را امتحان کنید. کد منبع RotaryIME را می توان در packages/apps/Car/tests/RotaryIME/ یافت.

تکان دادن خارج از صفحه نمایش

به‌طور پیش‌فرض، وقتی کاربر سعی می‌کند از لبه صفحه خارج شود، هیچ اتفاقی نمی‌افتد. OEM می تواند با تعیین هر ترکیبی از موارد زیر، آنچه را که باید برای هر یک از چهار جهت رخ دهد پیکربندی کند:

1. یک اقدام جهانی که توسط AccessibilityService تعریف شده است. به عنوان مثال، GLOBAL_ACTION_BACK .
2. یک کد کلید، مانند KEYCODE_BACK .
3. قصدی برای راه اندازی فعالیتی که به صورت URL نشان داده می شود.

( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
اینها با همپوشانی منابع آرایه زیر در RotaryService مشخص می شوند:

• off_screen_nudge_global_actions : آرایه ای از کنش های سراسری برای انجام زمانی که کاربر از لبه صفحه به بالا، پایین، چپ یا راست تکان می دهد. اگر عنصر مربوطه این آرایه -1 باشد، هیچ اقدام سراسری انجام نمی شود.
• off_screen_nudge_key_codes : آرایه ای از کدهای کلیدی رویدادهای کلیک برای تزریق هنگامی که کاربر از لبه صفحه به بالا، پایین، چپ یا راست حرکت می کند. اگر عنصر مربوطه این آرایه 0 باشد ( KEYCODE_UNKNOWN ) هیچ رویدادی تزریق نمی شود.
• off_screen_nudge_intents : آرایه ای از اهداف برای راه اندازی یک فعالیت زمانی که کاربر از لبه صفحه به بالا، پایین، چپ یا راست تکان می دهد. اگر عنصر مربوطه این آرایه خالی باشد هیچ فعالیتی راه اندازی نمی شود.

تنظیمات دیگر

شما باید منابع RotaryService زیر را پوشش دهید:

• ( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
  config_showHeadsUpNotificationOnBottom : مقدار بولی برای نشان دادن اینکه آیا اعلان‌های heads-up باید در پایین به جای بالا نشان داده شوند یا خیر. این باید همان مقدار منبع بولی config_showHeadsUpNotificationOnBottom در frameworks/base/packages/CarSystemUI/res/values/config.xml داشته باشد.
• ( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
  notification_headsup_card_margin_horizontal : حاشیه چپ و راست برای پنجره اعلان heads-up. این باید همان مقداری باشد که notification_headsup_card_margin_horizontal dimen resource در packages/apps/Car/Notification/res/values/dimens.xml
• ( اندروید 12 )
  excluded_application_overlay_window_titles : آرایه ای از عناوین پنجره ها که نباید پنجره های همپوشانی در نظر گرفته شوند. این باید شامل عناوین پنجره های برنامه باشد که نمایانگر TaskViews یا TaskDisplayAreas هستند. به‌طور پیش‌فرض، این فهرست فقط حاوی «نقشه‌ها» است.

می توانید منبع RotaryService زیر را همپوشانی کنید:

• ( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
  long_press_ms : مقدار صحیح برای نشان دادن چند میلی ثانیه دکمه مرکزی باید نگه داشته شود تا فشار طولانی را راه اندازی کند. صفر نشان می دهد که باید از مهلت زمانی فشار طولانی مدت پیش فرض سیستم استفاده شود. این مقدار پیش فرض است.