Файлы раскладки клавиатуры

Файлы раскладки клавиатуры (файлы .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, или ключевого слова usage, за которым следует код использования 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 – клавиша должна интерпретироваться так, как если бы также была нажата функциональная клавиша.
  • 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.

Единая ставка по центру

Джойстик может сообщать о событиях ввода, даже если он не используется, из-за помех. Обычно шум исходит от левого и/или правого стика и приводит к тому, что драйвер сообщает о положении, близком к нулю. Значение "center flat" указывает, какой уровень шума можно ожидать от контроллера в состоянии покоя.

Протокол ввода 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

В примере выше значение center flat равно 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. 
    <!-- 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>

Проверка

Проверьте файлы раскладки клавиатуры с помощью инструмента Validate Keymaps (Проверка раскладки клавиатуры).