ملفات التخطيط الرئيسية

تقوم ملفات تخطيط المفاتيح (ملفات .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. قم بتعيين قيمة وقت هدوء المفتاح الظاهري في تراكب الموارد لمورد إطار العمل 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>

تصديق

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