Клавиатурные устройства

Android поддерживает различные клавиатурные устройства, включая клавиатуры со специальными функциями (регулятор громкости и питания), компактные встроенные клавиатуры QWERTY и полнофункциональные внешние клавиатуры в стиле ПК.

В этом документе описываются только физические клавиатуры. Сведения о программных клавиатурах (редакторах методов ввода) см. в Android SDK.

Классификация клавиатуры

Устройство ввода классифицируется как клавиатура, если выполняется одно из следующих условий:

• Устройство ввода сообщает о наличии любых кодов клавиш Linux, используемых на клавиатурах, включая от 0 до 0xff или KEY_OK до KEY_MAX .

• Устройство ввода сообщает о наличии любых кодов клавиш Linux, используемых на джойстиках и геймпадах, в том числе BTN_0 до BTN_9 , BTN_TRIGGER до BTN_DEAD или BTN_A до BTN_THUMBR .

Джойстики в настоящее время классифицируются как клавиатуры, потому что кнопки джойстика и геймпада сообщаются событиями EV_KEY так же, как сообщаются клавиши клавиатуры. Таким образом, джойстики и геймпады также используют файлы карты клавиш для настройки.

Как только устройство ввода классифицируется как клавиатура, система загружает файл конфигурации устройства ввода и раскладку клавиатуры для клавиатуры.

Затем система пытается определить дополнительные характеристики устройства.

• Если на устройстве ввода есть какие-либо клавиши, сопоставленные с 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. Драйверы клавиатуры могут опционально указывать использование HID или низкоуровневый код сканирования, отправляя EV_MSC с MSC_SCANCODE и значением, указывающим использование или код сканирования при нажатии клавиши. Эта информация в настоящее время не используется Android.

5. Драйверы клавиатуры должны поддерживать установку состояний светодиодов, когда EV_LED записывается в устройство. Драйвер скрытого hid-input обрабатывает это автоматически. На момент написания этой статьи Android использует LED_CAPSLOCK , LED_SCROLLLOCK и LED_NUMLOCK . Эти светодиоды должны поддерживаться только тогда, когда на клавиатуре действительно есть соответствующие индикаторы.

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 эффективно удерживает блокировку пробуждения на этом критическом пути, чтобы гарантировать его завершение.

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 = <имя>

Задает имя файла раскладки клавиш, связанного с устройством ввода, за исключением расширения .kl . Если этот файл не найден, система ввода вместо этого будет использовать раскладку клавиш по умолчанию.

Пробелы в имени при поиске преобразуются в символы подчеркивания.

Дополнительные сведения см. в документации по файлу раскладки клавиш.

keyboard.characterMap

Определение: keyboard.characterMap = <имя>

Указывает имя файла сопоставления ключевых символов, связанного с устройством ввода, за исключением расширения .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 . Формат карты ключевых символов также сильно отличался, и платформа не поддерживала полные клавиатуры в стиле ПК или внешние клавиатуры.

При обновлении устройств до 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() .

Обратите внимание, что информация об использовании HID не используется самим Android и не передается приложениям.

Кодовые таблицы

В следующих таблицах показано, как использование HID, коды клавиш Linux и коды клавиш Android связаны друг с другом.

Столбец LKC указывает код ключа Linux в шестнадцатеричном формате.

Столбец AKC указывает код ключа Android в шестнадцатеричном формате.

Столбец «Примечания» относится к примечаниям, размещенным после таблицы.

Столбец «Версия» указывает первую версию платформы Android, которая включила этот ключ в карту ключей по умолчанию. Несколько строк отображаются в случаях, когда карта ключей по умолчанию изменилась между версиями. Указана самая старая версия 1.6.

• В Gingerbread (2.3) и более ранних версиях картой ключей по умолчанию была qwerty.kl . Эта карта клавиш предназначена только для использования с эмулятором Android и не предназначена для поддержки произвольных внешних клавиатур. Тем не менее, несколько OEM-производителей добавили в платформу поддержку клавиатуры Bluetooth и полагались на qwerty.kl для обеспечения необходимых сопоставлений клавиатуры. Следовательно, эти старые сопоставления могут представлять интерес для OEM-производителей, которые создают периферийные устройства для этих конкретных устройств. Обратите внимание, что сопоставления существенно отличаются от текущих, особенно в отношении обработки клавиши HOME . Рекомендуется, чтобы все новые периферийные устройства разрабатывались в соответствии с Honeycomb или более поздними картами клавиш (т. е. стандартными HID).

• Начиная с Honeycomb (3.0), картой ключей по умолчанию является Generic.kl . Эта карта клавиш была разработана для поддержки полнофункциональных клавиатур в стиле ПК. Большая часть функций стандартных HID-клавиатур должна работать «из коробки».

Сопоставление кода клавиш может различаться в разных версиях ядра Linux и Android. Когда известно, что в сопоставлении клавиш Android по умолчанию произошли изменения, они указываются в столбце версии.

Драйверы HID и карты клавиш для конкретных устройств могут применять сопоставления, отличные от указанных здесь.

Клавиатура HID и страница клавиатуры (0x07)

Общая страница рабочего стола HID (0x01)

HID потребительская страница (0x0c)

Additional non-HID Mappings

These mappings describe functions that do not appear in HID but for which Linux key codes exist.

Legacy Unsupported Keys

These mappings appeared in previous versions of Android but were inconsistent with HID or used non-standard Linux key codes. They are no longer supported.

Заметки

1. The Android key code associated with common alphanumeric and symbolic keys may vary based on the keyboard layout and language. For historical reasons, the physical scan codes and HID usages associated with keys on a keyboard are often defined positionally even though the labels printed on those keys may vary from one language to another.

   On a US English (QWERTY) keyboard, the top-left alphabetic key is labeled Q. On a French (AZERTY) keyboard, the key in the same position is labeled A. Despite the label, on both keyboards the top-left alphabetic key is referred to using the HID usage 0x07 0x0014 which is mapped to the Linux key code KEY_Q.

   When Android is configured with a US English keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_Q and will produce the characters 'Q' and 'q'. However, when Android is configured with a French keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_A and will produce the characters 'A' and 'a'.

   The Android key code typically reflects the language-specific interpretation of the key, so a different Android key code may be used for different languages.

2. 0x0c 0x022f AC Zoom is defined in the HID as a linear control but the kernel maps it as a key, which is probably incorrect.

3. The Linux function keys KEY_FN_* are mapped to simpler key codes but are dispatched with the META_FUNCTION meta state bit set to true.

4. Prior to Android Ice Cream Sandwich 4.0, the default key layout contained mappings for some extra key codes that were not defined in the mainline Linux kernel headers. These mappings have since been removed because these previously undefined key codes have since been assigned different meanings in more recent versions of the Linux kernel.

Sources

1. USB HID Usage Tables v1.12
2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java