מכשירים עם מקלדת

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

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

במסמך הזה מתוארות רק מקלדות פיזיות. מידע על מקלדות וירטואליות (עורכי שיטות קלט) זמין ב-Android SDK.

סיווג מקלדות

מכשיר קלט מסווג כמקלדת אם מתקיים אחד מהתנאים הבאים:

• מכשיר הקלט מדווח על נוכחות של קודי מפתחות של Linux שמשמשים במקלדות, כולל 0 עד 0xff או KEY_OK עד KEY_MAX.

• מכשיר הקלט מדווח על נוכחות של קודי מפתחות של Linux שמשמשים ב-joysticks וב-gamepads, כולל BTN_0 עד BTN_9, BTN_TRIGGER עד BTN_DEAD או BTN_A עד BTN_THUMBR.

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

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

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

• אם במכשיר הקלט יש מקשים שממופים ל-KEYCODE_Q, נחשב שהמכשיר כולל מקלדת אלפביתית (לעומת מקלדת נומרית). היכולת של מקלדת האלפבית מדווחת באובייקט המשאב Configuration בתור KEYBOARD_QWERTY.

• אם במכשיר הקלט יש מקשים שממופים ל-KEYCODE_DPAD_UP,‏ KEYCODE_DPAD_DOWN,‏ KEYCODE_DPAD_LEFT,‏ KEYCODE_DPAD_RIGHT ו-KEYCODE_DPAD_CENTER (כולם חייבים להיות נוכחים), המכשיר נחשב כמכשיר עם מקלדת כיוונים. היכולת של מקלדת הכיוונים מדווחת באובייקט המשאב Configuration בתור NAVIGATION_DPAD.

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

דרישות למנהלי מקלדות

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

2. מנהלי מקלדות צריכים להשתמש ב-EV_KEY כדי לדווח על הקשות, ולהשתמש בערך 0 כדי לציין שהמקש שוחרר, בערך 1 כדי לציין שהמקש נלחץ, ובערך שגדול מ-2 או שווה לו כדי לציין שהמקש חוזר על עצמו באופן אוטומטי.

3. Android מבצעת חזרה על מקש משלה. צריך להשבית את הפונקציונליות של החזרה אוטומטית בתוכנה.

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

5. מנהלי ההתקנים של המקלדת צריכים לתמוך בהגדרת מצבי ה-LED כשהערך EV_LED נכתב במכשיר. הנהג hid-input מטפל בכך באופן אוטומטי. נכון למועד כתיבת המאמר, ב-Android נעשה שימוש ב-LED_CAPSLOCK, ב-LED_SCROLLLOCK וב-LED_NUMLOCK. צריך לתמוך בנורות ה-LED האלה רק אם למקלדת יש בפועל את נוריות החיווי המשויכות.

6. מנהלי מקלדות למקלדות מוטמעות (למשל, באמצעות מטריצה של GPIO) צריכים לוודא שהם שולחים אירועי EV_KEY עם ערך 0 לכל המפתחות שעדיין לוחצים עליהם כשהמכשיר עובר למצב שינה. אחרת, יכול להיות שהמפתחות יידבקו וימשיכו לחזור על עצמם באופן אוטומטי לנצח.

הפעלת המקלדת

בהמשך מופיע סיכום קצר של פעולת המקלדת ב-Android.

1. ה-EventHub קורא אירועים גולמיים מהדרייבר evdev וממפה את קודי המפתחות של Linux (שנקראים לפעמים קודי סריקה) לקודי מפתחות של Android באמצעות המפה של פריסת המפתחות של המקלדת.

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

3. ה-InputReader מודיע ל-InputDispatcher על האירוע המרכזי.

4. ה-InputDispatcher שואל את ה-WindowManagerPolicy מה לעשות עם האירוע המרכזי, באמצעות קריאה ל-WindowManagerPolicy.interceptKeyBeforeQueueing. השיטה הזו היא חלק מנתיב קריטי שאחראי להעיר את המכשיר כשלוחצים על מקשים מסוימים. ה-EventHub מחזיק למעשה את נעילת ההפעלה (wake lock) לאורך הנתיב הקריטי הזה כדי להבטיח שהפעולה תתבצע עד הסוף.

5. אם InputFilter נמצא כרגע בשימוש, ה-InputDispatcher נותן לו הזדמנות לצרוך או לשנות את המפתח. אפשר להשתמש ב-InputFilter כדי להטמיע מדיניות נגישות ברמה נמוכה ברמת המערכת.

6. InputDispatcher מציב את המפתח בתור לעיבוד בשרשור ההעברה.

7. כשה-InputDispatcher מסיר את המפתח מהתור, הוא נותן ל-WindowManagerPolicy הזדמנות שנייה ליירט את האירוע המרכזי באמצעות קריאה ל-WindowManagerPolicy.interceptKeyBeforeDispatching. השיטה הזו מטפלת בקיצור דרך למערכת ובפונקציות אחרות.

8. לאחר מכן, InputDispatcher מזהה את היעד של האירוע המרכזי (החלון הממוקד) וממתין עד שהוא יהיה מוכן. לאחר מכן, ה-InputDispatcher מעביר את האירוע המרכזי לאפליקציה.

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

10. אם האירוע המרכזי לא מטופל בהעברה לפני ה-IME ויש שימוש ב-IME, האירוע המרכזי מועבר ל-IME.

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

12. האפליקציה מדווחת בחזרה ל-InputDispatcher אם האירוע המרכזי נוצל. אם האירוע לא נצרך, האירוע InputDispatcher קורא ל-WindowManagerPolicy.dispatchUnhandledKey כדי להחיל התנהגות 'חלופית'. בהתאם לפעולה החלופית, יכול להיות שמחזור השליחה של האירועים המרכזיים יופעל מחדש באמצעות קוד מפתח אחר. לדוגמה, אם אפליקציה לא מטפלת ב-KEYCODE_ESCAPE, המערכת עשויה לשלוח מחדש את האירוע המרכזי בתור KEYCODE_BACK.

הגדרת המקלדת

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

בקטעים הבאים מפורטים פרטים נוספים על הקבצים שמשתתפים בהגדרת המקלדת:

• קבצי פריסה של מפתחות
• קבצים של מפות של תווים מרכזיים
• הזנת קובצי תצורה של המכשיר

מאפיינים

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

keyboard.layout

הגדרה: keyboard.layout = <name>

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

הרווחים בשם הופכים לקווים תחתונים במהלך החיפוש.

פרטים נוספים זמינים במסמכים בנושא קובץ פריסת המפתח.

keyboard.characterMap

הגדרה: keyboard.characterMap = <name>

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

הרווחים בשם הופכים לקווים תחתונים במהלך החיפוש.

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

keyboard.orientationAware

הגדרה: keyboard.orientationAware = 0 | 1

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

• אם הערך הוא 1, המקשים של לוח המקשים לכיוונים מסתובבים כשכיוון המסך המשויך משתנה.

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

ערך ברירת המחדל הוא 0.

התכונה 'זיהוי כיוון' משמשת לתמיכה ברוטציה של מקשי מקלדת כיוונים, כמו ב-Motorola Droid. לדוגמה, כשמסובבים את המכשיר ב-90 מעלות בכיוון השעון מהכיוון הטבעי שלו, המיפוי של KEYCODE_DPAD_UP משתנה כדי ליצור את KEYCODE_DPAD_RIGHT, כי המקש 'למעלה' מצביע בסופו של דבר ל'ימין' כשהמכשיר מוחזק בכיוון הזה.

keyboard.builtIn

הגדרה: keyboard.builtIn = 0 | 1

מציין אם המקלדת היא המקלדת המובנית (המצורפת פיזית).

ערך ברירת המחדל הוא 1 אם שם המכשיר מסתיים ב--keypad, ו-0 במקרים אחרים.

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

חשוב להשתמש במזהה 0 למקלדת המובנית כדי לשמור על תאימות לשדה KeyCharacterMap.BUILT_IN_KEYBOARD, שמציין את המזהה של המקלדת המובנית ויש לו ערך 0. השדה הזה הוצא משימוש ב-API, אבל יכול להיות שאפליקציות ישנות עדיין משתמשות בו.

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

הגדרות לדוגמה

# This is an example input device configuration file for a built-in
# keyboard that has a DPad.

# The keyboard is internal because it is part of the device.
device.internal = 1

# The keyboard is the default built-in keyboard so it should be assigned
# an id of 0.
keyboard.builtIn = 1

# The keyboard includes a DPad which is mounted on the device.  As the device
# is rotated the orientation of the DPad rotates along with it, so the DPad must
# be aware of the display orientation.  This ensures that pressing 'up' on the
# DPad always means 'up' from the perspective of the user, even when the entire
# device has been rotated.
keyboard.orientationAware = 1

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

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

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

שימושים ב-HID, קודי מפתחות ל-Linux וקודי מפתחות ל-Android

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

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

כשמערכת Android קוראת אירועי EV_KEY מליבת Linux, היא מתרגמת כל קוד מפתח של Linux לקוד המפתח התואם ב-Android בהתאם לקובץ הפריסה של המפתחות במכשיר.

כשאירוע המפתח נשלח לאפליקציה, המכונה android.view.KeyEvent מדווחת על קוד המפתח של Linux כערך של getScanCode() ועל קוד המפתח של Android כערך של getKeyCode(). לצורכי המסגרת, רק הערך של getKeyCode() חשוב.

לתשומת ליבכם: מערכת Android עצמה לא משתמשת בנתוני השימוש ב-HID, והם לא מועברים לאפליקציות.

טבלאות קוד

בטבלאות הבאות אפשר לראות איך שימושים ב-HID, קודי מפתחות של Linux וקודי מפתחות של Android קשורים זה לזה.

בעמודה LKC מצוין קוד המפתח של Linux בפורמט הקסדצימלי.

בעמודה AKC מצוין קוד המפתח של Android בפורמט הקסדצימלי.

העמודה 'הערות' מתייחסת להערות שפורסמו אחרי הטבלה.

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

• בגרסאות Gingerbread‏ (2.3) וגרסאות קודמות, מפת המפתחות שמוגדרת כברירת מחדל היא qwerty.kl. מפת המפתחות הזו מיועדת לשימוש רק עם Android Emulator, ולא לשימוש לתמיכה במקלדות חיצוניות שרירותיות. עם זאת, כמה יצרני ציוד מקורי הוסיפו לתמיכה בפלטפורמה תמיכה במקלדת Bluetooth, והסתמכו על qwerty.kl כדי לספק את המיפויים הנדרשים של המקלדת. לכן, המיפויים הישנים האלה עשויים לעניין יצרני ציוד מקורי (OEM) שמפתחים ציוד היקפי למכשירים הספציפיים האלה. חשוב לזכור שהמיפויים שונים באופן משמעותי מהמיפויים הנוכחיים, במיוחד בנוגע לטיפול במפתח HOME. מומלץ לפתח את כל הפריטים ההיקפיים החדשים בהתאם למפות המפתחות של Honeycomb או למפות מפתחות עדכניות יותר (למשל, HID סטנדרטי).

• החל מגרסה Honeycomb ‏ (3.0), מפת המפתחות שמוגדרת כברירת מחדל היא Generic.kl. מפת המפתחות הזו תוכננה לתמוך במקלדות מלאות בסגנון PC. רוב הפונקציונליות של מקלדות HID רגילות אמורה לפעול 'מהקופסה'.

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

במנהלי HID ספציפיים למכשיר ובמפות מפתחות עשויות להיות מיפויים שונים מאלה שצוינו כאן.

דף של מקלדת HID ומקלדת צדדית (0x07)

דף כללי של HID למחשב (0x01)

דף הצרכן של HID‏ (0x0c)

מיפויים נוספים שאינם HID

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

מפתחות מדור קודם שלא נתמכים

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

הערות

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

   במקלדת QWERTY באנגלית (ארה"ב), המקש האלפביתי הימני העליון מסומן באות Q. במקלדת בצרפתית (AZERTY), המקש באותה מיקום מסומן באות A. למרות התווית, בשתי המקלדות המפתח האלפביתי הימני העליון מתייחס לשימוש HID‏ 0x07 0x0014 שממופה לקוד המפתח KEY_Q ב-Linux.

   כשמערכת Android מוגדרת עם פריסה של מקלדת באנגלית (ארה"ב), קוד המקש KEY_Q ב-Linux ממופה לקוד המקש KEYCODE_Q ב-Android ויוצר את התווים Q ו-q. עם זאת, כשמערכת Android מוגדרת עם פריסה של מקלדת צרפתית, קוד המקש KEY_Q ב-Linux ממופה לקוד המקש KEYCODE_A ב-Android ויוצר את התווים 'A' ו-'a'.

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

2. 0x0c 0x022f AC Zoom מוגדר ב-HID כפקד לינארי, אבל הליבה ממפה אותו כמפתח, וכנראה שזו טעות.

3. מקשי הפונקציה של Linux‏ KEY_FN_* ממופים למפתחות קוד פשוטים יותר, אבל הם נשלחים עם הביט של מצב המטא META_FUNCTION מוגדר כ-true.

4. לפני Android Ice Cream Sandwich 4.0, פריסת המקשים שמוגדרת כברירת מחדל הכילה מיפויים של קודי מפתחות נוספים שלא הוגדרו בכותרות הליבה הראשיות של Linux. המיפויים האלה הוסרו מאז כי קודי המפתחות האלה, שלא הוגדרו בעבר, קיבלו מאז משמעויות שונות בגרסאות חדשות יותר של ליבה של Linux.

מקורות

1. טבלאות שימוש ב-USB HID v1.12
2. ליבה של Linux 2.6.39: include/linux/input.h, ‏ drivers/hid/hid-input.c
3. Android ICS: ‏ qwerty.kl, ‏ Generic.kl, ‏ KeyEvent.java