این صفحه نحوه پردازش ورودی های چرخشی در 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 استفاده کند:
-
ACTION_DOWN
-
KEYCODE_SYSTEM_NAVIGATION_RIGHT
- نمایش هدف.
هنگامی که کاربر کنترل کننده چرخشی را آزاد می کند، 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
کاربر ممکن است کنترل کننده چرخشی را قبل از رها کردن آن در جهت عمود فشار دهد. به عنوان مثال، سناریوی زیر:
![جهت عمود بر](https://source.android.com/static/docs/automotive/images/rotary_06.png?authuser=0&hl=fa)
این باید دنباله ای از رویدادها را ایجاد کند:
-
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
در حالی که کنترل کننده چرخشی در یک جهت نگه داشته شده است، هیچ رویداد تکراری نباید ایجاد شود.
چرخش
هنگامی که کاربر کنترلر چرخشی را در جهت عقربههای ساعت میچرخاند (کلیک کنید)، VHAL باید از ویژگی HW_ROTARY_INPUT
با int32Values
زیر برای ارسال یک رویداد به Android استفاده کند:
-
ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
- یک (1) بازدارنده.
- نمایش هدف.
مهر زمانی رویداد باید روی زمان سپری شده بر حسب نانوثانیه تنظیم شود.
یک (1) چرخش در خلاف جهت عقربههای ساعت باید همان رویداد را ایجاد کند، اما برای تعداد گیرهها -1 را ایجاد کند.
اگر چرخش های متعدد در یک جهت به صورت متوالی اتفاق بیفتد، VHAL باید آن ها را در یک رویداد واحد ترکیب کند تا سیستم را با حوادث بیش از حد بارگیری نکند. در این مورد، مهر زمانی رویداد باید زمانی باشد که اولین بازدارنده چرخش اتفاق افتاده باشد. int32Values
باید شامل تعداد نانوثانیههای بین چرخشهای متوالی باشد.
به عنوان مثال، دنباله چرخش زیر:
- در زمان t0، کاربر یک دتنت را در خلاف جهت عقربه های ساعت چرخاند.
- در زمان t0 + 5 ns، کاربر یک دتنت را در خلاف جهت عقربههای ساعت چرخاند.
- در زمان t0 + 8 ns، کاربر یک دتنت را در خلاف جهت عقربههای ساعت چرخاند.
باید این رویداد را ایجاد کند:
- ویژگی:
HW_ROTARY_INPUT
- مهر زمانی:
t0
-
int32Values
:-
ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
- -3 (سه سوراخ در خلاف جهت عقربه های ساعت).
- نمایش هدف.
- 5 ns بین اولین و دومین بازدارنده.
- 3 ns بین دود دوم و سوم.
-
دکمه مرکزی
هنگامی که کاربر دکمه مرکز را فشار می دهد، VHAL باید از ویژگی HW_KEY_INPUT
با int32Values
زیر برای ارسال یک رویداد به Android استفاده کند:
-
ACTION_DOWN
-
KEYCODE_DPAD_CENTER
- نمایش هدف.
هنگامی که کاربر کنترل کننده چرخشی را آزاد می کند، VHAL باید از همان ویژگی و کد کلید با ACTION_UP
استفاده کند.
هنگامی که دکمه مرکز را پایین نگه دارید، رویدادهای تکراری ایجاد نکنید.
دکمه برگشت
هنگامی که کاربر دکمه برگشت را فشار می دهد، VHAL باید از ویژگی HW_KEY_INPUT
با int32Values
زیر برای ارسال یک رویداد به Android استفاده کند:
-
ACTION_DOWN
-
KEYCODE_BACK
- نمایش هدف.
هنگامی که کاربر کنترل کننده چرخشی را آزاد می کند، 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
:- کش غیرفعال است.
- کش پس از مدتی منقضی می شود (به زیر مراجعه کنید).
- کش هرگز منقضی نمی شود.
-
car_ui_focus_history_expiration_period_ms
: چند میلی ثانیه قبل از انقضای حافظه نهان اگر نوع کش روی دو (2) تنظیم شود (به بالا مراجعه کنید).
حافظه پنهان تاریخچه FocusArea
( اندروید 11 QPR3، اندروید 11 ماشین، اندروید 12 )
این حافظه پنهان تاریخچه ای از اشاره ها را ذخیره می کند تا حرکت دادن در جهت مخالف بتواند فوکوس را به همان FocusArea
برگرداند. این کش را می توان با همپوشانی منابع car-ui-library زیر پیکربندی کرد:
-
car_ui_focus_area_history_cache_type
:- کش غیرفعال است.
- کش پس از مدتی منقضی می شود (به زیر مراجعه کنید).
- کش هرگز منقضی نمی شود.
-
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
: ضخامت طرح کلی.
گاهی اوقات به یک دکمه رنگ پس زمینه ثابت داده می شود تا مورد توجه کاربر قرار گیرد، همانطور که در مثال نشان داده شده است. این ممکن است برجسته کردن فوکوس را دشوار کند.
![دکمه با پس زمینه جامد](https://source.android.com/static/docs/automotive/images/rotary_05.png?authuser=0&hl=fa)
- ( اندروید 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 می تواند با تعیین هر ترکیبی از موارد زیر، آنچه را که باید برای هر یک از چهار جهت رخ دهد پیکربندی کند:
- یک اقدام جهانی که توسط
AccessibilityService
تعریف شده است. به عنوان مثال،GLOBAL_ACTION_BACK
. - یک کد کلید، مانند
KEYCODE_BACK
. - قصدی برای راه اندازی فعالیتی که به صورت 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
: مقدار صحیح برای نشان دادن چند میلی ثانیه دکمه مرکزی باید نگه داشته شود تا فشار طولانی را راه اندازی کند. صفر نشان می دهد که باید از مهلت زمانی فشار طولانی مدت پیش فرض سیستم استفاده شود. این مقدار پیش فرض است.