ملفات تنسيقات المفاتيح

تربط ملفات تنسيقات المفاتيح (ملفات .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

عند إنشاء مسار ملف يحتوي على اسم الجهاز، يتم استبدال كل الأحرف في اسم الجهاز بحرف "_"، باستثناء الأحرف من 0 إلى 9 أو من a إلى z أو من A إلى Z أو "-" أو "_".

ملف تنسيق المفاتيح العام

يقدّم النظام ملفًا خاصًا مضمّنًا لتنسيق المفتاح العام يُسمّى Generic.kl. تم تصميم مخطّط المفاتيح هذا ليتوافق مع مجموعة متنوعة من لوحات المفاتيح الخارجية وعصا التحكم الخارجية العادية. لا تعدِّل تنسيق المفتاح العميم .

بناء الجملة

ملف تنسيق المفتاح هو ملف نص عادي يتألف من تعريفات المفتاح أو المحور والرموز.

بيانات المفاتيح

تتألف بيانات المفاتيح من الكلمة الرئيسية key متبوعة برقم رمز مفتاح Linux واسم رمز مفتاح 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: المفتاح هو مفتاح افتراضي (زر شحن سعوي) بجانب الشاشة الرئيسية التي تعمل باللمس. يؤدي ذلك إلى تفعيل منطق خاص لإزالة الارتعاش (راجِع المعلومات أدناه).

بيانات المحاور

تتألّف كلّ من بيانات المحاور من الكلمة الرئيسية 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.

خيار التوسيع الأفقي

قد يُبلغ جهاز ذراع التحكم عن أحداث الإدخال حتى في حال عدم استخدام ذراع التحكم، وذلك بسبب الضوضاء. وعادةً ما يكون مصدر هذا الضجيج هو العصا اليسرى و/أو اليمنى، ما يتسبب في تسجيل قيمة موضع قريبة من 0. تحدِّد قيمة "المستوى المتوسط للضوضاء" مقدار الضوضاء المتوقَّعة من وحدة التحكّم في وضع السكون.

يقدّم بروتوكول إدخال Linux طريقة لبرامج تشغيل أجهزة الإدخال لتحديد القيمة الثابتة في منتصف محاور ذراع التحكم، ولكن لا تُبلغ بعض برامج التشغيل عن ذلك، ويقدّم بعضها قيمًا غير صحيحة. لحلّ هذه المشكلة، يمكن أن يتبع بيان المحور خيار flat يحدِّد عرض المنطقة حول محور القياس الذي يجب اعتباره محورًا متمركزًا.

على سبيل المثال، إذا أبلغ برنامج تشغيل الجهاز عن قيم AXIS_X تتراوح بين 0 و100، سيتم ربط القيمة 0 بـ -1 وسيتم ربط القيمة 100 بـ 1 من خلال نظام إدخال Android. سيكون مركز النطاق 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. إذا كانت مفاتيح الشاشة الافتراضية معروضة بشكل مرئي على الشاشة (مثل هاتف Galaxy Nexus)، يتم تنفيذها من خلال مكوّن شريط التنقّل في حزمة System UI. بما أنّ المفاتيح الافتراضية الرسومية يتم تنفيذها في خطوة متقدمة في النظام، لا يتم استخدام ملفات تنسيق المفاتيح ولا تنطبق المعلومات التالية.
  2. إذا تم تنفيذ المفاتيح الافتراضية كمنطقة قابلة للمس تشمل جزءًا من الشاشة الرئيسية التي تعمل باللمس (مثل جهاز Nexus One)، يستخدم نظام الإدخال ملف تخطيط مفاتيح افتراضيًا لترجمة إحداثيات اللمس X/Y إلى رموز مفاتيح لنظام التشغيل Linux، ثم يستخدم ملف تخطيط المفاتيح لترجمة رموز مفاتيح Linux إلى رموز مفاتيح Android (للاطّلاع على تفاصيل عن ملفات تخطيط المفاتيح الافتراضية، يُرجى الاطّلاع على الأجهزة التي تعمل باللمس). يجب أن يحدِّد ملف تنسيق المفاتيح الخاص بجهاز إدخال الشاشة التي تعمل باللمس تعيين المفاتيح المناسب وأن يتضمّن علامة VIRTUAL لكل مفتاح.
  3. إذا تم تنفيذ المفاتيح الافتراضية كأزرار سعوية منفصلة عن شاشة اللمس الرئيسية (مثل جهاز Nexus S)، يكون برنامج تشغيل جهاز kernel أو البرامج الثابتة مسؤولاً عن ترجمة اللمسات إلى رموز مفاتيح Linux التي يترجمها نظام الإدخال بعد ذلك إلى رموز مفاتيح 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>

التحقُّق

يجب التحقّق من صحة ملفات تخطيط المفاتيح باستخدام أداة التحقّق من صحة خرائط المفاتيح.