فایل‌های چیدمان کلید (فایل‌های .kl) کدهای کلید و کدهای محور Linux را به کدهای کلید و کدهای محور Android نگاشت می‌کنند و پرچم‌های خط‌مشی مرتبط را مشخص می‌کنند.
فایل‌های چیدمان کلید ویژه دستگاه عبارتند از:
- برای دستگاه‌های ورودی داخلی (توکار) دارای کلید، ازجمله کلیدهای ویژه مانند میزان صدا، روشن/خاموش، و کلیدهای رسانه هدست الزامی است.
- برای دیگر دستگاه‌های ورودی اختیاری است اما برای صفحه‌کلیدهای خاص‌منظوره و دسته‌های بازی توصیه می‌شود.
اگر فایل چیدمان کلید مختص دستگاه دردسترس نباشد، سیستم به‌جای آن چیدمان پیش‌فرضی را انتخاب می‌کند.
مکان
فایل‌های چیدمان کلید براساس فروشنده USB، محصول (و به‌طور اختیاری نسخه) شناسه یا براساس نام دستگاه ورودی قرار می‌گیرند. مسیرهای زیر به‌ترتیب بررسی می‌شوند:
/odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl/odm/usr/keylayout/DEVICE_NAME.kl/vendor/usr/keylayout/DEVICE_NAME.kl/system/usr/keylayout/DEVICE_NAME.kl/data/system/devices/keylayout/DEVICE_NAME.kl/odm/usr/keylayout/Generic.kl/vendor/usr/keylayout/Generic.kl/system/usr/keylayout/Generic.kl/data/system/devices/keylayout/Generic.kl
هنگام ساختن مسیر فایل که حاوی نام دستگاه است، همه نویسه‌های نام دستگاه به‌غیراز «۰» تا «۹»، «a» تا «z»، «A» تا «Z»، «-» یا «_» با «_» جایگزین می‌شوند.
فایل چیدمان کلید عمومی
سیستم فایل جانمایی کلید عمومی توکار ویژه‌ای به‌نام
Generic.kl ارائه می‌دهد. این چیدمان کلید برای پشتیبانی از انواع
صفحه کلیدهای خارجی استاندارد و دسته‌های بازی طراحی شده است. جانمایی کلید عمومی را
تغییر ندهید!
نحو
فایل چیدمان کلید یک فایل نوشتاری ساده است که شامل اعلامیه‌های کلید یا محور و پرچم‌ها است.
بیانیه‌های کلیدی
اعلامیه‌های کلید شامل کلیدواژه key و به‌دنبال آن شماره کد کلید Linux و نام کد کلید Android، یا استفاده از کلیدواژه و به‌دنبال آن استفاده از HID و نام کد کلید Android است. استفاده از HID به‌صورت عدد صحیح ۳۲ بیتی نشان داده می‌شود که ۱۶ بیت بالا نشان‌دهنده صفحه استفاده از HID و ۱۶ بیت پایین نشان‌دهنده شناسه استفاده از HID است. هریک از این اظهارنامه‌ها می‌تواند با مجموعه‌ای اختیاری از پرچم‌های خط‌مشی که با فاصله از هم جدا شده‌اند دنبال شود.
key 1 ESCAPE key 114 VOLUME_DOWN key 16 Q VIRTUAL key usage 0x0c006F BRIGHTNESS_UP
پرچم‌های خط‌مشی زیر شناسایی شده‌اند:
FUNCTION: کلید باید به‌گونه‌ای تفسیر شود که گویی کلید FUNCTION نیز فشار داده شده است.-
GESTURE: کلید تولیدشده با اشاره کاربر، مثل لمس کردن صفحه لمسی با کف دست. VIRTUAL: کلید یک کلید نرم مجازی (دکمه خازنی) در مجاورت صفحه لمسی اصلی است. این کار باعث می‌شود منطق خاصی برای حذف پرش فعال شود (به بخش زیر مراجعه کنید).
اظهارنامه‌های محور
هریک از بیانیه‌های محور از کلیدواژه axis و به‌دنبال آن
عدد کد محور Linux و مشخص‌کننده‌هایی که رفتار محور را کنترل می‌کنند
ازجمله حداقل یک نام کد محور Android تشکیل شده است.
محورهای اصلی
محور پایه به‌سادگی کد محور Linux را به نام کد محور Android تخصیص می‌دهد. بیانیه زیر ABS_X (نشان‌داده‌شده با 0x00) را
به AXIS_X (نشان‌داده‌شده با X)
تخصیص می‌دهد.
axis 0x00 X
در مثال بالا، اگر مقدار ABS_X برابر با 5 باشد،
AXIS_X روی 5 تنظیم می‌شود.
محورهای تقسیم
محور تقسیم‌شده یک کد محور Linux را به دو نام کد محور Android نگاشت می‌کند، به‌طوری‌که مقادیر کمتر یا بیشتر از یک آستانه هنگام نگاشت شدن در دو محور مختلف تقسیم می‌شوند. این نگاشت زمانی مفید است که یک محور فیزیکی که توسط دستگاه گزارش می‌شود، دو محور منطقی مختلف و متقابلاً انحصاری را کدبندی می‌کند.
اظهارنامه زیر مقادیر محور ABS_Y (نشان‌داده‌شده با 0x01) را به AXIS_GAS وقتی کمتر از 0x7f است یا به AXIS_BRAKE وقتی بیشتر از 0x7f است نگاشت می‌کند.
axis 0x01 split 0x7f GAS BRAKE
در مثال بالا، اگر مقدار ABS_Y برابر با 0x7d
باشد، AXIS_GAS روی 2 (0x7f - 0x7d)
تنظیم می‌شود و AXIS_BRAKE روی 0 تنظیم می‌شود. برعکس، اگر مقدار
ABS_Y برابر با 0x83 باشد، AXIS_GAS روی
0 و AXIS_BRAKE روی 4
(0x83 - 0x7f) تنظیم می‌شود. درنهایت، اگر مقدار ABS_Y برابر با
مقدار تقسیم 0x7f باشد، هم AXIS_GAS و هم
AXIS_BRAKE روی 0 تنظیم می‌شود.
محورهای معکوس
محور وارونه علامت مقدار محور را وارونه می‌کند. اعلامیه زیر
ABS_RZ (با 0x05 نشان داده شده است) را به
AXIS_BRAKE (با BRAKE نشان داده شده است) نگاشت می‌کند و
خروجی را با منفی کردن آن معکوس می‌کند.
axis 0x05 invert BRAKE
در مثال بالا، اگر مقدار ABS_RZ برابر با 2 باشد،
AXIS_BRAKE روی -2 تنظیم می‌شود.
گزینه تخت مرکزی
دستگاه دسته فرمان ممکن است به‌دلیل نویز، رویدادهای ورودی را حتی زمانی که از دسته فرمان استفاده نمی‌شود گزارش کند. این صدا معمولاً از چوب‌های چپ و/یا راست می‌آید و باعث می‌شود راننده مقدار موقعیتی نزدیک به ۰ را گزارش کند. مقدار «مرکز ثابت» میزان نویزی را که باید از کنترل‌کننده در حالت استراحت انتظار داشت مشخص می‌کند.
پروتکل ورودی Linux روشی را برای درایورهای دستگاه ورودی فراهم می‌کند تا مقدار تخت مرکزی محورهای جوی‌استیک را مشخص کنند، اما همه درایورها آن را گزارش نمی‌کنند و برخی‌از آن‌ها مقادیر نادرستی ارائه می‌دهند. برای حل این مشکل، ممکن است پس‌از بیانیه محور، گزینه
flat بیاید که پهنای ناحیه اطراف موقعیت مرکزی محور را که باید به‌عنوان مرکز درنظر گرفته شود مشخص می‌کند.
برای مثال، اگر درایور دستگاه مقادیر AXIS_X را بین ۰ و ۱۰۰ گزارش کند،
سیستم ورودی Android مقدار ۰ را به ۱- و مقدار ۱۰۰ را به ۱ نگاشت می‌کند.
مرکز این محدوده در مختصات بدون مقیاس ۵۰ و در مختصات با مقیاس ۰ خواهد بود.
اگر مقدار تخت برابر با ۱۰ باشد،
توسعه‌دهندگان باید فرض کنند که هر مقدار AXIS_X گزارش‌شده بین
-۰٫۱ و ۰٫۱ (بین ۴۰ و ۶۰ در مختصات بدون مقیاس) نویز است و آن مقادیر دریافتی
از دسته فرمان را صفر درنظر بگیرند.
توجه: درحالی‌که فایل چیدمان کلید مقدار را برای فضای مختصات درایور مشخص می‌کند، مقدار گزارش‌شده توسط android.view.InputDevice.MotionRange#getFlat() در فضای مختصات Android است.
axis 0x03 Z flat 4096
در مثال بالا، مقدار تخت مرکزی روی 4096 تنظیم شده است.
نظرات
خطوط نظر با # شروع می‌شوند و تا انتهای خط ادامه می‌یابند:
# A comment!
خطوط خالی نادیده گرفته می‌شوند.
مثال‌ها
صفحه‌کلید
# This is an example of a key layout file for a keyboard. key 1 ESCAPE key 2 1 key 3 2 key 4 3 key 5 4 key 6 5 key 7 6 key 8 7 key 9 8 key 10 9 key 11 0 key 12 MINUS key 13 EQUALS key 14 DEL # etc...
کنترل‌های سیستم
# This is an example of a key layout file for basic system controls, # such as volume and power keys which are typically implemented as GPIO pins # the device decodes into key presses. key 114 VOLUME_DOWN key 115 VOLUME_UP key 116 POWER
دکمه‌های لمسی
# This is an example of a key layout file for a touch device with capacitive buttons. key 139 MENU VIRTUAL key 172 HOME VIRTUAL key 158 BACK VIRTUAL key 217 SEARCH VIRTUAL
کنترل‌های رسانه فیش هدست
# This is an example of a key layout file for headset mounted media controls. # A typical headset jack interface might have special control wires or detect known # resistive loads as corresponding to media functions or volume controls. # This file assumes that the driver decodes these signals and reports media # controls as key presses. key 163 MEDIA_NEXT key 165 MEDIA_PREVIOUS key 226 HEADSETHOOK
دسته کنترل
# This is an example of a key layout file for a joystick. # These are the buttons that the joystick supports, represented as keys. key 304 BUTTON_A key 305 BUTTON_B key 307 BUTTON_X key 308 BUTTON_Y key 310 BUTTON_L1 key 311 BUTTON_R1 key 314 BUTTON_SELECT key 315 BUTTON_START key 316 BUTTON_MODE key 317 BUTTON_THUMBL key 318 BUTTON_THUMBR # Left and right stick. # The reported value for flat is 128 in a range of -32767 to 32768, which is absurd. # This confuses applications that rely on the flat value because the joystick # actually settles in a flat range of +/- 4096 or so. We override it here. axis 0x00 X flat 4096 axis 0x01 Y flat 4096 axis 0x03 Z flat 4096 axis 0x04 RZ flat 4096 # Triggers. axis 0x02 LTRIGGER axis 0x05 RTRIGGER # Hat. axis 0x10 HAT_X axis 0x11 HAT_Y
کلیدهای نرم‌افزاری مجازی
سیستم ورودی ویژگی‌های خاصی را برای پیاده‌سازی کلیدهای نرم مجازی در موارد استفاده زیر ارائه می‌دهد:
- اگر کلیدهای نرم مجازی به‌صورت گرافیکی روی صفحه نمایش داده شوند (مثل Galaxy Nexus)، توسط عنصر «نوار پیمایش» در بسته «واسط کاربر سیستم» پیاده‌سازی می‌شوند. ازآنجایی‌که کلیدهای نرم‌افزاری مجازی گرافیکی در لایه بالایی سیستم پیاده‌سازی می‌شوند، فایل‌های چیدمان کلید درگیر نمی‌شوند و اطلاعات زیر اعمال نمی‌شود.
- اگر کلیدهای نرم مجازی به‌عنوان ناحیه لمسی گسترده‌ای که بخشی از صفحه لمسی اصلی است پیاده‌سازی شده باشند (مثل Nexus One)، سیستم ورودی از فایل نقشه کلید مجازی برای تبدیل مختصات لمسی X/Y به کدهای کلید Linux استفاده می‌کند، سپس از فایل چیدمان کلید برای تبدیل کدهای کلید Linux به کدهای کلید Android استفاده می‌کند (برای جزئیات بیشتر درباره فایل‌های نقشه کلید مجازی، به دستگاه‌های لمسی مراجعه کنید). فایل چیدمان کلید برای دستگاه ورودی صفحه‌لمسی باید نگاشت کلید مناسب را مشخص کند و برای هر کلید، پرچم
VIRTUALرا داشته باشد. - اگر کلیدهای نرم مجازی به‌عنوان دکمه‌های خازنی جدا از
صفحه لمسی اصلی (مانند Nexus S) پیاده‌سازی شده باشند، درایور دستگاه هسته یا
سفت‌افزار مسئول ترجمه لمس‌ها به کدهای کلید لینوکس است که
سیستم ورودی سپس آن‌ها را بااستفاده از فایل چیدمان کلید به کدهای کلید Android ترجمه می‌کند.
فایل چیدمان کلید برای دستگاه ورودی دکمه خازنی باید نگاشت کلید مناسب را مشخص کند و شامل پرچم
VIRTUALبرای هر کلید باشد.
وقتی کلیدهای نرم مجازی در داخل یا در مجاورت فیزیکی صفحه لمسی قرار دارند، کاربران به‌راحتی می‌توانند هنگام لمس کردن نزدیک پایین صفحه یا هنگام کشیدن انگشت از بالا به پایین یا از پایین به بالای صفحه، به‌طور تصادفی دکمه‌ای را فشار دهند. برای جلوگیری از این اتفاق، سیستم ورودی کمی ضدجهش اعمال می‌کند تا فشار دادن کلیدهای نرم‌افزاری مجازی برای مدت کوتاهی پس‌از آخرین لمس صفحه‌نمایش لمسی نادیده گرفته شود (این تأخیر زمان سکوت کلید مجازی نامیده می‌شود).
برای فعال کردن لرزش‌گیری کلید مجازی:
- فایل چیدمان کلید را برای صفحه لمسی یا دستگاه ورودی دکمه خازنی
با پرچم
VIRTUALتنظیم‌شده برای هر کلید ارائه دهید.key 139 MENU VIRTUAL key 172 HOME VIRTUAL key 158 BACK VIRTUAL key 217 SEARCH VIRTUAL
- مقدار زمان بی‌صدا بودن کلید مجازی را در رونهاد منبع برای منبع
config.xmlچارچوب تنظیم کنید.<!-- Specifies the amount of time to disable virtual keys after the screen is touched to filter out accidental virtual key presses due to swiping gestures or taps near the edge of the display. May be 0 to disable the feature. It is recommended that this value be no more than 250 ms. This feature should be disabled for most devices. --> <integer name="config_virtualKeyQuietTimeMillis">250</integer>
اعتبارسنجی
باید فایل‌های چیدمان کلید را بااستفاده از ابزار اعتبارسنجی نقشه کلید اعتبارسنجی کنید.