קובצי מפות תווים של מפתחות

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

קבצים של מפות תווים של מפתחות (קבצים מסוג .kcm) אחראים למיפוי של שילובים של קודי מפתחות של Android עם משתני אופן ביצוע (modifiers) לתווי Unicode.

קובצי פריסה של מקשים ספציפיים למכשיר נדרשים לכל מכשירי הקלט הפנימיים (המובנים) שיש להם מקשים, גם אם רק כדי להודיע למערכת שהמכשיר מיועד למטרה מיוחדת בלבד (ולא מקלדת מלאה).

קבצים של פריסות מפתחות ספציפיות למכשיר הם אופציונליים למקלדות חיצוניות, ולרוב אין צורך בהם בכלל. המערכת מספקת מפה גנרית של תווים של מפתחות שמתאימה למקלדות חיצוניות רבות.

אם אין קובץ פריסה של מפתחות ספציפי למכשיר, המערכת תבחר ברירת מחדל במקום זאת.

מיקום

קובצי המיפוי של תווים של מפתחות נמצאים לפי ספק USB, מזהה מוצר (וגם גרסה, אם יש) או לפי שם של מכשיר קלט.

המערכת בודקת את הנתיבים הבאים לפי הסדר.

• /odm/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
• /vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
• /system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
• /data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm
• /odm/usr/keychars/DEVICE_NAME.kcm
• /vendor/usr/keychars/DEVICE_NAME.kcm
• /system/usr/keychars/DEVICE_NAME.kcm
• /data/system/devices/keychars/DEVICE_NAME.kcm
• /odm/usr/keychars/Generic.kcm
• /vendor/usr/keychars/Generic.kcm
• /system/usr/keychars/Generic.kcm
• /data/system/devices/keychars/Generic.kcm
• /odm/usr/keychars/Virtual.kcm
• /vendor/usr/keychars/Virtual.kcm
• /system/usr/keychars/Virtual.kcm
• /data/system/devices/keychars/Virtual.kcm

כשיוצרים נתיב קובץ שמכיל את שם המכשיר, כל התווים בשם המכשיר מלבד '0'-'9', 'a'-'z', 'A'-'Z', '-' או '_' מוחלפים ב-'_'.

קובץ של מפה גנרית של תווים של מפתחות

המערכת מספקת קובץ מובנה מיוחד של מפת תווים של מפתחות שנקרא Generic.kcm. מפת התווים של המפתחות הזו מיועדת לתמוך במגוון מקלדות חיצוניות רגילות.

אין לשנות את מפת התווים של המפתח הכללי!

קובץ של מפת תווים של מפתחות וירטואליים

המערכת מספקת קובץ מובנה מיוחד של מפת תווים של מפתחות שנקרא Virtual.kcm, שמכשירי המקלדת הווירטואלית משתמשים בו.

מכשיר המקלדת הווירטואלית הוא מכשיר קלט סינתטי שמזהה אותו הוא -1 (ראו KeyCharacterMap.VIRTUAL_KEYBOARD). הוא נמצא בכל מכשירי Android החל מ-Android Honeycomb 3.0. המטרה של מכשיר המקלדת הווירטואלית היא לספק מכשיר קלט מובנה ידוע שאפשר להשתמש בו להחדרת הקשות לאפליקציות על ידי ה-IME או על ידי כלי בדיקה, גם במכשירים שאין בהם מקלדות מובנות.

ההנחה היא שהמקלדת הווירטואלית כוללת פריסת QWERTY מלאה זהה בכל המכשירים. כך אפליקציות יכולות להחדיר הקשות באמצעות מכשיר המקלדת הווירטואלית ולקבל תמיד את אותן תוצאות.

אין לשנות את מפת התווים של המפתחות הווירטואליים!

תחביר

קובץ של מפת תווים של מפתח הוא קובץ טקסט פשוט שמכיל הצהרה על סוג מקלדת וקבוצה של הצהרות על מפתחות.

הצהרת סוג מקלדת

הצהרת סוג מקלדת מתארת את ההתנהגות הכוללת של המקלדת. קובץ של מפת תווים חייב להכיל הצהרה על סוג מקלדת. לצורך הבהרה, הוא ממוקם בדרך כלל בחלק העליון של הקובץ.

type FULL

סוגי המקלדת הבאים מזוהים:

• NUMERIC: מקלדת נומרית (12 מקשים).

  מקלדת מספרית תומכת בהזנת טקסט באמצעות מספר הקשות. יכול להיות שתצטרכו להקיש על מקש כמה פעמים כדי ליצור את האות או את הסמל הרצויים.

  בדרך כלל, מקלדות מהסוג הזה מיועדות להקלדה באמצעות האגודל.

  תואם ל-KeyCharacterMap.NUMERIC.

• PREDICTIVE: מקלדת עם כל האותיות, אבל עם יותר מאות אחת לכל מקש.

  בדרך כלל, מקלדות מהסוג הזה מיועדות להקלדה באמצעות האגודל.

  תואם ל-KeyCharacterMap.PREDICTIVE.

• ALPHA: מקלדת עם כל האותיות, ואולי גם מספרים מסוימים.

  מקלדת אלפביתית תומכת בהזנת טקסט ישירות, אבל יכול להיות שהיא תהיה בעלת פריסה מרוכזת עם גורם צורה קטן. בניגוד למקלדת FULL, יכול להיות שסמלים מסוימים יהיו נגישים רק באמצעות בוררי תווים מיוחדים במסך. בנוסף, כדי לשפר את מהירות ההקלדה ואת הדיוק שלה, המסגרת מספקת תכונות מיוחדות למקלדות אלפביתיות, כמו שימוש אוטומטי באותיות רישיות והפעלה אוטומטית או נעילה של מקשי SHIFT ו-ALT.

  בדרך כלל, סוג המקלדת הזה מיועד להקלדה באמצעות האגודל.

• FULL: מקלדת מלאה בסגנון PC.

  מקלדת מלאה פועלת כמו מקלדת של מחשב. כדי לגשת לכל הסמלים, לוחצים ישירות על המקשים במקלדת בלי תמיכה במסך או תכונות כמו הוספת אותיות רישיות באופן אוטומטי.

  בדרך כלל, סוג המקלדת הזה מיועד להקלדה מלאה בשתי ידיים.

• SPECIAL_FUNCTION: מקלדת שמשמשת רק לביצוע פעולות בקרה על המערכת, ולא להקלדה.

  מקלדת פונקציות מיוחדת מורכבת רק ממקשות שלא מודפסות, כמו 'דף הבית' ו'הפעלה', שלא משמשות בפועל להקלדה.

מפות התווים של המקש Generic.kcm ושל המקש Virtual.kcm הן מקלדות FULL.

הצהרות על מפתחות

כל הצהרת מפתח מורכבת ממילת המפתח key, ואחריה שם של קוד מפתח ל-Android, סוגריים מסולסלים פתוחים, קבוצה של מאפיינים והתנהגויות וסוגרים מסולסלים סגורים.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

מאפיינים

כל מאפיין מפתח יוצר מיפוי ממפתח להתנהגות. כדי שהקבצים של מפות התווים של המפתחות יהיו קומפקטיים יותר, אפשר למפות כמה מאפיינים לאותו התנהגות על ידי הפרדה ביניהם באמצעות פסיק.

בדוגמה שלמעלה, ההתנהגות 'A' מוקצית לנכס label. באופן דומה, למאפיינים ctrl, ‏ alt ו-meta מוקצה בו-זמנית ההתנהגות none.

המערכת מזהה את המאפיינים הבאים:

• label: מציין את התווית שמודפסת פיזית על המפתח, כשהיא מורכבת מתו אחד. זהו הערך שמוחזר על ידי השיטה KeyCharacterMap.getDisplayLabel.

• number: מציין את ההתנהגות (התו שצריך להקליד) כשהתצוגה של הטקסט המספרי נמצאת בחזית, למשל כשהמשתמש מקלידים מספר טלפון.

  במקלדות קומפקטיות, לרוב משלבים כמה סמלים במפתח אחד, כך שאותו מפתח יכול לשמש להקלדה של '1' ו-'a' או של '#' ו-'q'. במפתחות האלה, צריך להגדיר את המאפיין number כדי לציין איזה סמל צריך להקליד בהקשר מספרי, אם יש כזה.

  דוגמאות לסמלים 'מספריים' אופייניים: הספרות '0' עד '9', '#', '+', '(', ')', ',' ו-'.'.

• base: מציין את ההתנהגות (התו שצריך להקליד) כשלא לוחצים על לחצני שינוי.

• <modifier> או <modifier1>+<modifier2>+…: מציין את ההתנהגות (הדמות שצריך להקליד) כשמקישים על המקש וכל המקשי המשתנים שצוינו פעילים.

  לדוגמה, מאפיין המשתנה shift מציין התנהגות שחלה כשלוחצים על המקש SHIFT שמימין או על המקש SHIFT שמשמאל.

  באופן דומה, מאפיין המשתנה rshift+ralt מציין התנהגות שחלה כשלוחצים בו-זמנית על מקשי ה-SHIFT הימני וה-ALT הימני.

המאפיינים הבאים של המשתנים מוכרים במאפייני המשתנים:

• shift: האפשרות הזו חלה כאשר לוחצים על מקש ה-SHIFT הימני או על מקש ה-SHIFT השמאלי.
• lshift: חלה כשמקשי ה-SHIFT הימני מופעל.
• rshift: חלה כשמקשי ה-SHIFT הימני מולחצים.
• alt: האפשרות הזו חלה כשלוחצים על מקש ה-ALT הימני או על מקש ה-ALT השמאלי.
• lalt: חלה כשלוחצים על מקש השינוי ALT הימני.
• ralt: האפשרות הזו חלה כשלוחצים על מקש המקשי ALT הימני.
• ctrl: חל כשלוחצים על מקש השינוי LEFT CONTROL או RIGHT CONTROL.
• lctrl: האפשרות הזו חלה כשמקישים על מקש ה-CTRL הימני.
• rctrl: האפשרות הזו חלה כשמקישים על המקש 'CTRL' הימני.
• meta: האפשרות הזו חלה כשמקישים על המקש המשנה META שמאלי או META ימני.
• lmeta: חלה כשמקישים על מקש השינוי META הימני.
• rmeta: חל כאשר מקישים על המקש המשנה META שמימין.
• sym: האפשרות הזו חלה כשמקישים על מקש השינוי SYMBOL.
• fn: רלוונטי כשלוחצים על לחצן השינוי FUNCTION.
• capslock: חלה כשמקש CAPS LOCK נעול.
• numlock: חל כאשר המקש המשנה NUM LOCK נעול.
• scrolllock: המשמעות היא שהמקש SCROLL LOCK נעול.

הסדר שבו הנכסים מפורטים חשוב. כשממפים מפתח להתנהגות, המערכת סורקת את כל המאפיינים הרלוונטיים לפי הסדר ומחזירה את ההתנהגות הרלוונטית האחרונה שמצאה.

כתוצאה מכך, מאפיינים שצוינו מאוחר יותר מבטלים את המאפיינים שצוינו קודם למפתח נתון.

Behaviors

כל נכס ממופה להתנהגות. ההתנהגות הנפוצה ביותר היא הקלדה של תו, אבל יש התנהגויות אחרות.

המערכת מזהה את ההתנהגויות הבאות:

• none: לא מקלידים תו.

  זוהי התנהגות ברירת המחדל כשלא מציינים תו. אפשר לציין את none, אבל זה לא חובה.

• 'X': מקלידים את ליצ'ר התווים שצוין.

  כתוצאה מהתנהגות הזו, התו שצוין מופיע בתצוגת הטקסט שבה מתמקדים. ליטרל התו יכול להיות כל תו ASCII, או אחת מרצפי הבריחה הבאים:

  • '\\': מקלידים תו קו נטוי לאחור.
  • '\n': מקלידים תו של שורה חדשה (משתמשים בזה כדי להקיש על Enter או על Return).
  • '\t': מקלידים תו Tab.
  • '\'': מקלידים תו גרש.
  • '\"': מקלידים תו מירכאות.
  • '\uXXXX': מקלידים את תו ה-Unicode שמיקום התו (code point) שלו מצוין בספרות הקסדצימליות XXXX.

• fallback <Android key code name>: ביצוע פעולת ברירת מחדל אם האפליקציה לא מטפלת במפתח.

  ההתנהגות הזו גורמת למערכת לדמות הקשה על מקש אחר כשאפליקציה לא מטפלת במקש שצוין באופן מקורי. הוא משמש לתמיכה בהתנהגות ברירת המחדל של מקשים חדשים שלא כל האפליקציות יודעות לטפל בהם, כמו מקש ה-ESCAPE או מקשים בלוח החיוג המספרי (כשמקש Numlock לא לחוץ).

  כשמתבצעת התנהגות חלופית, האפליקציה תקבל שתי לחיצות על מקש: אחת על המקש המקורי ואחת על מקש החלופי שנבחר. אם האפליקציה מטפלת במפתח המקורי במהלך key up, האירוע של מפתח החלופי יבוטל (KeyEvent.isCanceled יחזיר את הערך true).

המערכת שומרת שני תווי Unicode לביצוע פונקציות מיוחדות:

• '\uef00': כשההתנהגות הזו מתבצעת, תצוגת הטקסט צורכת ומסירה את ארבעת התווים שמקדימים את הסמן, מפרשת אותם כספרות הקסדצימליות ומוסיפה את נקודת הקוד המתאימה ב-Unicode.

• '\uef01': כשההתנהגות הזו מתבצעת, בתצוגת הטקסט מוצגת תיבת דו-שיח לבחירת תווים שמכילה סמלים שונים.

המערכת מזהה את תווי ה-Unicode הבאים כתוים משולבים של תווים מותנים:

• '\u0300': הטעמה משנית.
• '\u0301': הטעמה ראשית.
• '\u0302': הטעמת גג.
• '\u0303': סימן הטעמה ~.
• '\u0308': סימן הטעמה Umlaut.

כשמקלידים מקש נטול תו ואחריו תו אחר, המקש הנטול התו והתווים הבאים משולבבים. לדוגמה, כשהמשתמש מקליד הטעמה משנית מסוג הטעמה משנית ואחריו האות 'a', התוצאה היא 'à'.

מידע נוסף על טיפול במפתחות לא תקינים זמין במאמר KeyCharacterMap.getDeadChar.

תגובות

שורות התגובה מתחילות ב-'#' וממשיכות עד לסוף השורה. תוכל לעשות זאת כך:

# A comment!

המערכת מתעלמת משורות ריקות.

איך שילובי מקשים ממופים להתנהגויות

כשהמשתמש לוחץ על מקש, המערכת מחפשת את ההתנהגות שמשויכת לשילוב של לחיצת המקש הזו והמקשיות לשינוי ההגדרות (modifiers) שנלחצו כרגע.

Shift + A

נניח שהמשתמש לחץ על A ו-SHIFT בו-זמנית. המערכת מאתרת קודם את קבוצת המאפיינים וההתנהגויות שמשויכים ל-KEYCODE_A.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

המערכת סורקת את המאפיינים מהראשון לאחרון ומשמאל לימין, ומתעלמת מהמאפיינים label ו-number, שהם מיוחדים.

המאפיין הראשון שנמצא הוא base. המאפיין base תמיד חל על מפתח, ללא קשר למקשות השינוי שנלחצו. הוא קובע את התנהגות ברירת המחדל של המפתח, אלא אם המאפיינים הבאים מבטלים אותה. מכיוון שהמאפיין base חל על הלחיצה על המקש, המערכת מתעדת את העובדה שההתנהגות שלו היא 'a' (הקלדה של התו a).

לאחר מכן, המערכת ממשיכה לסרוק את הנכסים הבאים, למקרה שאחד מהם יהיה ספציפי יותר מ-base וישנה אותו. הוא נתקל ב-shift, שחלה גם על הקשה על המקש SHIFT + A. לכן המערכת מחליטה להתעלם מההתנהגות של המאפיין base ובוחרת את ההתנהגות שמשויכת למאפיין shift, שהיא 'A' (מקלידים את התו A).

לאחר מכן הוא ממשיך לסרוק את הטבלה, אבל לא חלים מאפיינים אחרים על ההקשה הזו (מקש CAPS LOCK לא נעול, לא מקישים על מקש CONTROL, לא מקישים על מקש ALT ולא מקישים על מקש META).

לכן, ההתנהגות שמתקבלת לשילוב המקשים SHIFT + A היא 'A'.

Ctrl + A

עכשיו נבחן מה יקרה אם המשתמש ילחץ על A ו-CTRL בו-זמנית.

כמו בעבר, המערכת תסרוק את טבלת המאפיינים. המערכת תבחין שהנכס base חל, אבל תמשיך לסרוק עד שתגיע בסופו של דבר לנכס control. במקרה הזה, המאפיין control מופיע אחרי base, כך שההתנהגות שלו מבטלת את ההתנהגות של base.

לכן, ההתנהגות שמתקבלת משילוב המקשים CONTROL + A היא none.

ESCAPE

עכשיו נניח שהמשתמש לחץ על ESCAPE.

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

הפעם המערכת מקבלת את ההתנהגות fallback BACK, התנהגות חלופית. מכיוון שלא מופיע ליטרל של תו, לא יתבצע הקלדה של תו.

כשהמערכת מעבדת את המפתח, היא שולחת קודם את KEYCODE_ESCAPE לאפליקציה. אם האפליקציה לא מטפלת בבקשה, המערכת תנסה שוב, אבל הפעם היא תעביר את KEYCODE_BACK לאפליקציה כפי שמבקש התנהגות החלופות.

כך, אפליקציות שמזהות את KEYCODE_ESCAPE ותומכות בה יכולות לטפל בה כפי שהיא, אבל אפליקציות אחרות שלא תומכות בה יכולות לבצע במקום זאת את פעולת החזרה למצב הקודם (fallback) ולטפל במפתח כאילו הוא KEYCODE_BACK.

NUMPAD_0 עם או בלי NUM LOCK

למקשים במקלדת הנומרית יש פרשנויות שונות מאוד בהתאם למצב של מקש NUM LOCK.

הצהרת המפתח הבאה מבטיחה שהלחיצה על KEYCODE_NUMPAD_0 תגרום להקלדה של 0 כשהלחצן NUM LOCK מופעל. כשלא לוחצים על NUM LOCK, המקש מועבר לאפליקציה כרגיל, ואם הוא לא מטופל, מפתח החלופי KEYCODE_INSERT מועבר במקום זאת.

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

כפי שאפשר לראות, הצהרות על מפתחות חלופיים משפרות מאוד את התאימות לאפליקציות ישנות שלא מזהות את כל המקשים שמופיעים במקלדת מלאה בסגנון PC או לא תומכות בהם ישירות.

דוגמאות

מקלדת מלאה

# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.

type FULL

key C {
    label:                              'C'
    base:                               'c'
    shift, capslock:                    'C'
    alt:                                '\u00e7'
    shift+alt:                          '\u00c7'
    ctrl, meta:                         none
}

key SPACE {
    label:                              ' '
    base:                               ' '
    ctrl:                               none
    alt, meta:                          fallback SEARCH
}

key NUMPAD_9 {
    label, number:                      '9'
    base:                               fallback PAGE_UP
    numlock:                            '9'
    ctrl, alt, meta:                    none
}

מקלדת אלפאנומרית

# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard.  Some keys are combined, such as `A` and `2`.  Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.

type ALPHA

key A {
    label:                              'A'
    number:                             '2'
    base:                               'a'
    shift, capslock:                    'A'
    alt:                                '#'
    shift+alt, capslock+alt:            none
}

key SPACE {
    label:                              ' '
    number:                             ' '
    base:                               ' '
    shift:                              ' '
    alt:                                '\uef01'
    shift+alt:                          '\uef01'
}

משטח משחק

# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.

type SPECIAL_FUNCTION

key BUTTON_A {
    base:                               fallback BACK
}

key BUTTON_X {
    base:                               fallback DPAD_CENTER
}

key BUTTON_START {
    base:                               fallback HOME
}

key BUTTON_SELECT {
    base:                               fallback MENU
}

הערה לגבי תאימות

לפני Android Honeycomb 3.0, מפת התווים של מפתחות Android צוינה באמצעות תחביר שונה מאוד, והיא קומפלרה לפורמט קובץ בינארי (.kcm.bin) בזמן ה-build.

למרות שבפורמט החדש נעשה שימוש באותה סיומת .kcm, התחביר שונה למדי (והוא הרבה יותר חזק).

החל מ-Android Honeycomb 3.0, כל קובצי המפות של תווים של מפתחות Android חייבים להשתמש בתחביר החדש ובפורמט הקובץ של טקסט פשוט שמתואר במסמך הזה. אין תמיכה בתחביר הישן, והמערכת לא מזהה את קובצי .kcm.bin הישנים.

הערה לגבי שפה

מערכת Android לא תומכת כרגע במקלדות בכמה שפות. בנוסף, המפה המובנית של תווים כלליים של מפתחות מבוססת על פריסת מקלדת באנגלית ארה"ב.

אנחנו ממליצים ליצרני ציוד מקורי לספק מפות של תווים מותאמים אישית למקלדות שלהם, אם הן מיועדות לשפות אחרות.

גרסאות עתידיות של Android עשויות לספק תמיכה טובה יותר במקלדות בכמה שפות או במיקומי מקשים שניתנים לבחירת המשתמש.

אימות

חשוב לאמת את קובצי המיפוי של תווים של מפתחות באמצעות הכלי Validate Keymaps.