Файлы сопоставления клавиш

Файлы раскладки клавиатуры (с расширением .kcm) отвечают за сопоставление комбинаций кодов клавиш Android с модификаторами символов 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, начиная с версии Honeycomb 3.0. Виртуальная клавиатура – это встроенное устройство ввода, которое можно использовать для передачи нажатий клавиш в приложения с помощью IME или инструментов тестирования, даже если у устройства нет встроенной клавиатуры.

Предполагается, что виртуальная клавиатура имеет полную раскладку QWERTY, одинаковую на всех устройствах. Это позволяет приложениям вводить символы с помощью виртуальной клавиатуры и всегда получать одинаковые результаты.

Не изменяйте раскладку виртуальной клавиатуры!

Синтаксис

Файл сопоставления клавиш – это файл обычного текста, состоящий из объявления типа клавиатуры и набора объявлений клавиш.

Заявление о типе клавиатуры

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

type FULL

Распознаются следующие типы клавиатур:

• NUMERIC – цифровая клавиатура (12 клавиш).

  Цифровая клавиатура поддерживает ввод текста с помощью многократного нажатия. Чтобы ввести нужную букву или символ, может потребоваться несколько раз нажать на клавишу.

  Обычно на такой клавиатуре набирают текст большими пальцами.

  Соответствует KeyCharacterMap.NUMERIC.

• PREDICTIVE – клавиатура со всеми буквами, но на каждой клавише расположено несколько букв.

  Обычно такая клавиатура предназначена для ввода текста большими пальцами.

  Соответствует KeyCharacterMap.PREDICTIVE.

• ALPHA – клавиатура со всеми буквами и, возможно, цифрами.

  Алфавитная клавиатура позволяет вводить текст напрямую, но может иметь компактную раскладку. В отличие от FULL клавиатуры, некоторые символы могут быть доступны только с помощью специальных экранных инструментов выбора символов. Кроме того, чтобы повысить скорость и точность ввода, фреймворк предоставляет специальные возможности для алфавитных клавиатур, такие как автоматическое написание заглавных букв и переключаемые / заблокированные клавиши SHIFT и ALT.

  Обычно такая клавиатура предназначена для ввода текста большими пальцами.

• FULL: полноразмерная клавиатура, как у ПК.

  Полноразмерная клавиатура работает так же, как клавиатура ПК. Все символы вводятся непосредственно с клавиатуры без поддержки на экране или таких функций, как автоматическое написание с заглавной буквы.

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

• SPECIAL_FUNCTION – клавиатура, которая используется только для управления системой, а не для ввода текста.

  Клавиатура со специальными функциями состоит только из непечатаемых клавиш, таких как HOME и POWER, которые не используются для ввода текста.

Раскладки клавиатуры Generic.kcm и Virtual.kcm – это клавиатуры FULL.

Основные заявления

Каждое объявление клавиши состоит из ключевого слова key, за которым следует название кода клавиши Android, открывающая фигурная скобка, набор свойств и действий и закрывающая фигурная скобка.

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

Свойства

Каждое ключевое свойство устанавливает соответствие между ключом и поведением. Чтобы сделать файлы раскладки клавиатуры более компактными, можно сопоставить несколько свойств с одним и тем же поведением, разделив их запятой.

В примере выше свойству label присвоено поведение 'A'. Аналогично, свойствам ctrl, alt и meta одновременно присваивается поведение none.

Распознаются следующие свойства:

• label: указывает метку, которая физически напечатана на клавише, если она состоит из одного символа. Это значение, которое возвращает метод KeyCharacterMap.getDisplayLabel.

• number: определяет поведение (символ, который должен быть введен), когда числовое текстовое поле находится в фокусе, например когда пользователь вводит номер телефона.

  На компактных клавиатурах несколько символов часто объединены в одну клавишу, поэтому одна и та же клавиша может использоваться для ввода символов '1' и 'a' или '#' и 'q'. Для таких клавиш свойство number должно указывать, какой символ должен вводиться в числовом контексте (если он есть).

  К типичным "числовым" символам относятся цифры от '0' до '9', '#', '+', '(', ')', ',' и '.'.

• base – определяет поведение (какой символ должен быть введен), когда не нажаты клавиши-модификаторы.

• <modifier> или <modifier1>+<modifier2>+…: определяет поведение (символ, который должен быть введен), когда нажата клавиша и активны все указанные модификаторы.

  Например, свойство модификатора shift определяет поведение, которое применяется при нажатии клавиши LEFT SHIFT или RIGHT SHIFT.

  Аналогично свойство модификатора rshift+ralt определяет поведение, которое применяется, когда одновременно нажаты модификаторы RIGHT SHIFT и RIGHT ALT.

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

• shift – применяется, когда нажата клавиша LEFT SHIFT или RIGHT SHIFT.
• lshift – применяется, когда нажат левый Shift.
• rshift – применяется, когда нажата клавиша Shift справа.
• alt – применяется, когда нажата клавиша-модификатор LEFT ALT или RIGHT ALT.
• lalt – применяется при нажатии левой клавиши Alt.
• ralt – применяется при нажатии клавиши-модификатора ПРАВЫЙ ALT.
• ctrl – применяется, когда нажата клавиша-модификатор LEFT CONTROL или RIGHT CONTROL.
• lctrl – применяется, когда нажата клавиша-модификатор LEFT CONTROL.
• rctrl: применяется при нажатии правой клавиши CTRL.
• meta – применяется, когда нажата клавиша-модификатор LEFT META или RIGHT META.
• lmeta – применяется при нажатии левой клавиши Meta.
• rmeta – применяется при нажатии правой клавиши META.
• sym – применяется при нажатии клавиши модификатора "Символ".
• fn – применяется при нажатии клавиши FUNCTION.
• capslock – применяется, когда модификатор CAPS LOCK заблокирован.
• numlock – применяется, когда модификатор NUM LOCK заблокирован.
• scrolllock – применяется, когда модификатор SCROLL LOCK заблокирован.

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

Таким образом, свойства, указанные позже, переопределяют свойства, указанные ранее для определенного ключа.

Поведение при прокрутке

Каждое свойство сопоставляется с определенным поведением. Чаще всего это ввод символа, но есть и другие варианты.

Распознаются следующие действия:

• none – не вводите символ.

  Это поведение по умолчанию, если символ не указан. Указывать noneнеобязательно, но это помогает избежать путаницы.

• 'X' – введите указанный символьный литерал.

  В результате указанный символ будет введен в элемент TextView, находящийся в фокусе. В качестве литерала можно использовать любой символ ASCII или одну из следующих управляющих последовательностей:

  • '\\' – введите обратную косую черту.
  • '\n': введите символ новой строки (используйте для клавиш ВВОД и RETURN).
  • '\t' – введите символ табуляции.
  • '\'' – введите апостроф.
  • '\"' – введите кавычки.
  • '\uXXXX' – введите символ Unicode, кодовая точка которого задана в шестнадцатеричном формате как XXXX.

• fallback <Кодовое название ключа Android>: выполнить действие по умолчанию, если приложение не обрабатывает ключ.

  В этом случае система имитирует нажатие другой клавиши, если приложение не поддерживает указанную клавишу. Он используется для поддержки поведения по умолчанию для новых клавиш, которые не все приложения умеют обрабатывать, например ESCAPE или клавиши цифровой клавиатуры (когда Num Lock не нажат).

  Когда выполняется резервное действие, приложение получает два нажатия клавиш: одно для исходной клавиши и другое для выбранной резервной клавиши. Если приложение обрабатывает исходный ключ при отпускании клавиши, то событие резервного ключа будет отменено (KeyEvent.isCanceled вернет true).

Система резервирует два символа Unicode для выполнения специальных функций:

• '\uef00' – при выполнении этого действия элемент TextView удаляет четыре символа перед курсором, интерпретирует их как шестнадцатеричные цифры и вставляет соответствующую кодовую точку Unicode.

• '\uef01' – при выполнении этого действия элемент TextView показывает диалоговое окно выбора символов, содержащее различные символы.

Система распознает следующие символы Unicode как сочетания диакритических знаков и мертвых клавиш:

• '\u0300' – гравис.
• '\u0301' – акут.
• '\u0302' – циркумфлекс.
• '\u0303' – тильда.
• '\u0308' – умлаут.

Если нажать немую клавишу, а затем другую, то они будут объединены. Например, если пользователь нажмет клавишу с мертвой клавишей grave accent, а затем букву "a", то в результате получится "à".

Подробнее KeyCharacterMap.getDeadChar…

Комментарии

Строки комментариев начинаются с символа "#" и продолжаются до конца строки. Пример:

# A comment!

Пустые строки игнорируются.

Как сочетания клавиш сопоставляются с действиями

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

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'.

КОНТРОЛЬНАЯ КАМПАНИЯ – A

Теперь подумайте, что произойдет, если пользователь одновременно нажмет клавиши A и CONTROL.

Как и раньше, система будет сканировать таблицу свойств. Он заметит, что применено свойство base, но продолжит сканирование, пока не дойдет до свойства control. Поскольку свойство control указано после base, его поведение переопределяет поведение base.

В результате сочетание клавиш Ctrl + A будет выполнять действие "none".

ESCAPE

Теперь предположим, что пользователь нажал клавишу ESC.

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

В этот раз система получает поведение fallback BACK, которое является резервным. Поскольку литерал символа не указан, символ не будет введен.

При обработке ключа система сначала передаст KEYCODE_ESCAPE приложению. Если приложение не обработает его, система попытается снова, но на этот раз передаст приложению значение KEYCODE_BACK, как указано в резервном поведении.

Поэтому приложения, которые распознают и поддерживают KEYCODE_ESCAPE, могут обрабатывать его как есть, а другие приложения, которые этого не делают, могут вместо этого выполнить резервное действие, рассматривая ключ как KEYCODE_BACK.

NUMPAD_0 с NUM LOCK или без него

Значение клавиш на цифровой клавиатуре зависит от того, включен ли режим Num Lock.

Следующая декларация клавиш гарантирует, что при нажатии клавиши Num Lock будут вводиться символы KEYCODE_NUMPAD_0 типа 0. Если клавиша NUM LOCK не нажата, клавиша передается приложению как обычно, а если оно не обрабатывает ее, то вместо нее передается резервная клавиша KEYCODE_INSERT.

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

Как видите, объявления запасных ключей значительно повышают совместимость с более старыми приложениями, которые не распознают или не поддерживают все клавиши, присутствующие на полноразмерной клавиатуре ПК.

Примеры

Полная клавиатура

# 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) во время сборки.

Хотя новый формат использует то же расширение .kcm, синтаксис у него совсем другой (и гораздо более мощный).

Начиная с Android Honeycomb 3.0, все файлы раскладки клавиатуры Android должны использовать новый синтаксис и формат обычного текста, описанный в этом документе. Старый синтаксис не поддерживается, а файлы .kcm.bin старого формата не распознаются системой.

Примечание о языке

В настоящее время Android не поддерживает многоязычные клавиатуры. Кроме того, встроенная карта символов для универсальных клавиш предполагает раскладку клавиатуры США.

Если клавиатура предназначена для другого языка, производителям рекомендуется предоставлять для нее собственные карты символов.

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

Проверка

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