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

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

عندما تتوفّر مفاتيح التحكّم الافتراضية في مكان قريب من الشاشة التي تعمل باللمس، من السهل على المستخدمين الضغط عن طريق الخطأ على الزر عند عند لمس الجزء السفلي من الشاشة أو عند تمرير الإصبع من أعلى إلى أسفل أو من أسفل إلى أعلى الشاشة. لمنع حدوث ذلك، يُطبق نظام الإدخال قليلاً مرة أخرى بحيث يتم تجاهل ضغطات المفاتيح الافتراضية لفترة قصيرة من الوقت بعد آخر لمسة على شاشة اللمس (يسمى هذا التأخير وقت سكون المفتاح الافتراضي).

لتفعيل ميزة "ارتداد المفتاح الأساسي" الافتراضي، اتّبِع الخطوات التالية:

  1. توفير ملف تنسيق مفتاح لشاشة اللمس أو زر السعة الكهربائية جهاز إدخال تم ضبط العلامة VIRTUAL لكل مفتاح عليه. 
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. قم بتعيين قيمة وقت الهدوء للمفتاح الافتراضي في تراكب الموارد إطار العمل 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>

التحقُّق

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