קובצי פריסת מקשים

קובצי פריסת מקשים (.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 מיוצג באמצעות מספר שלם, כאשר הערך הגבוה של 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 ואחריה מספר הקוד של הציר והפרמטרים שקובעים את ההתנהגות של הציר כולל שם קוד אחד לפחות של ציר 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, מערכת הקלט של Android ממופה את המספר 0 לערך -1, ואת המספר 100 לערך 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. אם המקשים הרכים הווירטואליים מוצגים בצורה גרפית על המסך (למשל, 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 של framework. 
    <!-- 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>

אימות

צריך לאמת את קובצי פריסת המפתח באמצעות אימות מפות המקשים.