فایل های چیدمان کلید

فایل‌های چیدمان کلید (فایل‌های .kl ) کدهای کلید لینوکس و کدهای محور را به کدهای کلید 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

هنگام ساخت یک مسیر فایل که حاوی نام دستگاه است، همه کاراکترهای نام دستگاه به غیر از '0'-'9'، 'a'-'z'، 'A'-'Z'، '-' یا '_' با '_' جایگزین می شوند.

فایل طرح بندی کلید عمومی

این سیستم یک فایل طرح بندی کلید عمومی داخلی به نام Generic.kl را فراهم می کند. این طرح کلید برای پشتیبانی از انواع کیبوردهای خارجی استاندارد و جوی استیک در نظر گرفته شده است. طرح کلی کلید را تغییر ندهید!

نحو

فایل طرح بندی کلید یک فایل متنی ساده است که از اعلان های کلید یا محور و پرچم ها تشکیل شده است.

اعلامیه های کلیدی

اعلان‌های کلیدی شامل key کلمه کلیدی به دنبال شماره کد کلید لینوکس و نام کد کلید Android یا استفاده از کلمه کلیدی به دنبال استفاده از HID و نام کد کلید Android است. استفاده از HID به عنوان یک عدد صحیح 32 بیتی نشان داده می شود که در آن 16 بیت بالا نشان دهنده صفحه استفاده HID و 16 بیت پایین نشان دهنده شناسه استفاده HID است. هر یک از اعلان‌ها را می‌توان با مجموعه‌ای اختیاری از پرچم‌های خط‌مشی محدود شده با فضای خالی دنبال کرد.

key 1     ESCAPE
key 114   VOLUME_DOWN
key 16    Q                 VIRTUAL
key usage 0x0c006F          BRIGHTNESS_UP

پرچم های خط مشی زیر شناسایی می شوند:

  • FUNCTION : کلید باید طوری تفسیر شود که گویی کلید FUNCTION نیز فشار داده شده است.
  • GESTURE : کلید ایجاد شده توسط یک حرکت کاربر، مانند دست زدن به صفحه لمسی.
  • VIRTUAL : کلید یک کلید نرم افزار مجازی (دکمه خازنی) در مجاورت صفحه لمسی اصلی است. این باعث می‌شود که منطق debouncing ویژه فعال شود (به زیر مراجعه کنید).

اعلامیه های محور

اعلان‌های محور هر کدام از axis کلمه کلیدی و به دنبال آن یک شماره کد محور لینوکس و واجد شرایطی است که رفتار محور را کنترل می‌کند که شامل حداقل یک نام کد محور Android است.

محورهای اساسی

یک محور اصلی به سادگی یک کد محور لینوکس را به نام کد محور اندروید نگاشت می کند. اعلان زیر ABS_X (نشان داده شده با 0x00 ) را به AXIS_X (نشان داده شده با X ) نشان می دهد.

axis 0x00 X

در مثال بالا، اگر مقدار ABS_X 5 باشد، AXIS_X روی 5 تنظیم شده است.

محورهای شکاف

یک محور تقسیم یک کد محور لینوکس را به دو نام کد محور اندروید نگاشت می‌کند، به طوری که مقادیر کمتر یا بیشتر از یک آستانه در دو محور مختلف تقسیم می‌شوند. این نگاشت زمانی مفید است که یک محور فیزیکی گزارش شده توسط دستگاه، دو محور منطقی متقابل متفاوت را رمزگذاری کند.

اعلان زیر مقادیر محور 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 تنظیم شده است.

گزینه تخت وسط

یک دستگاه جوی استیک ممکن است رویدادهای ورودی را حتی زمانی که از جوی استیک استفاده نمی شود، به دلیل نویز گزارش کند. این نویز معمولاً از سمت چپ و/یا راست می‌آید و باعث می‌شود راننده مقدار موقعیت نزدیک به 0 را گزارش کند.

پروتکل ورودی لینوکس راهی را برای درایورهای دستگاه ورودی فراهم می کند تا مقدار مسطح مرکز محورهای جوی استیک را مشخص کنند، اما همه درایورها آن را گزارش نمی کنند و برخی از آنها مقادیر نادرستی ارائه می دهند. برای حل این مشکل، یک اعلان محور ممکن است با یک گزینه flat دنبال شود که عرض ناحیه اطراف موقعیت مرکزی محور را که باید به عنوان مرکز در نظر گرفته شود، مشخص می کند.

به عنوان مثال، اگر یک درایور دستگاه مقادیر AXIS_X را بین 0 تا 100 گزارش کند، 0 به -1 و 100 توسط سیستم ورودی Android به 1 نگاشت می شود. مرکز محدوده در مختصات بدون مقیاس 50 و در مختصات مقیاس شده 0 خواهد بود. اگر یک مقدار مسطح برابر با 10 باشد، توسعه دهندگان باید فرض کنند که هر مقدار AXIS_X که بین 0.1- و 0.1 گزارش شده است (بین 40 تا 60 در مختصات بدون مقیاس) نویز است و آن مقادیری که از جوی استیک به دست می‌آید را صفر در نظر بگیرند.

توجه : در حالی که فایل طرح بندی کلید مقدار فضای مختصات درایور را مشخص می کند، مقدار گزارش شده توسط 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

کلیدهای نرم افزاری مجازی

سیستم ورودی ویژگی های خاصی را برای پیاده سازی کلیدهای نرم افزار مجازی در موارد استفاده زیر فراهم می کند:

  1. اگر کلیدهای نرم افزار مجازی به صورت گرافیکی روی صفحه نمایش داده شوند (مانند گلکسی نکسوس)، توسط مؤلفه نوار ناوبری در بسته رابط کاربری سیستم پیاده سازی می شوند. از آنجایی که کلیدهای نرم افزار مجازی گرافیکی در لایه بالایی در سیستم پیاده سازی می شوند، فایل های چیدمان کلید درگیر نیستند و اطلاعات زیر اعمال نمی شود.
  2. اگر کلیدهای نرم افزار مجازی به عنوان یک منطقه قابل لمس گسترده که بخشی از صفحه لمسی اصلی است (مانند Nexus One) پیاده سازی شوند، سیستم ورودی از یک فایل نقشه کلید مجازی برای ترجمه مختصات لمسی X/Y به کدهای کلید لینوکس استفاده می کند. سپس از فایل طرح بندی کلید برای ترجمه کدهای کلید لینوکس به کدهای کلید اندروید استفاده می کند (برای جزئیات بیشتر در مورد فایل های نقشه کلید مجازی، به دستگاه های لمسی مراجعه کنید). فایل چیدمان کلید برای دستگاه ورودی صفحه لمسی باید نگاشت کلید مناسب را مشخص کند و پرچم VIRTUAL را برای هر کلید درج کند.
  3. اگر کلیدهای نرم‌افزار مجازی به‌عنوان دکمه‌های خازنی جدا از صفحه لمسی اصلی (مانند نکسوس S) پیاده‌سازی شوند، درایور دستگاه هسته یا میان‌افزار مسئول ترجمه لمس‌ها به کدهای کلید لینوکس است که سپس سیستم ورودی به کدهای کلید Android ترجمه می‌شود. با استفاده از فایل طرح بندی کلید فایل طرح بندی کلید برای دستگاه ورودی دکمه خازنی باید نگاشت کلید مناسب را مشخص کند و برای هر کلید پرچم VIRTUAL را شامل شود.

هنگامی که کلیدهای نرم افزار مجازی در داخل یا در مجاورت فیزیکی صفحه لمسی قرار دارند، برای کاربران آسان است که به طور تصادفی یک دکمه را هنگام لمس کردن نزدیک به پایین صفحه یا هنگام کشیدن انگشت از بالا به پایین یا از پایین به پایین فشار دهند. بالای صفحه نمایش برای جلوگیری از این امر، سیستم ورودی کمی انحراف را اعمال می کند به طوری که فشار دادن کلیدهای نرم مجازی برای مدت کوتاهی پس از آخرین لمس روی صفحه لمسی نادیده گرفته می شود (به این تاخیر زمان خاموشی کلید مجازی می گویند).

برای فعال کردن بازگرداندن کلید نرم افزار مجازی:

  1. یک فایل طرح بندی کلید برای صفحه لمسی یا دستگاه ورودی دکمه خازنی با پرچم VIRTUAL تنظیم شده برای هر کلید ارائه دهید.
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. مقدار زمان خاموشی کلید مجازی را در یک پوشش منبع برای منبع Framework 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>

اعتبار سنجی

شما باید فایل های طرح بندی کلید خود را با استفاده از ابزار Validate Keymaps تأیید کنید.