Файлы карты ключевых символов

Файлы сопоставления ключевых символов (файлы .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, начиная с 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 : Применяется при нажатии модификатора LEFT SHIFT.
  • rshift : Применяется при нажатии модификатора RIGHT SHIFT.
  • alt : Применяется при нажатии модификатора LEFT ALT или RIGHT ALT.
  • lalt : Применяется при нажатии модификатора LEFT ALT.
  • ralt : Применяется при нажатии модификатора RIGHT ALT.
  • ctrl : Применяется при нажатии модификатора LEFT CONTROL или RIGHT CONTROL.
  • lctrl : Применяется при нажатии модификатора LEFT CONTROL.
  • rctrl : Применяется при нажатии модификатора RIGHT CONTROL.
  • meta : применяется при нажатии модификатора LEFT META или RIGHT META.
  • lmeta : применяется при нажатии модификатора LEFT META.
  • rmeta : применяется при нажатии модификатора RIGHT META.
  • sym : Применяется при нажатии модификатора SYMBOL.
  • fn : Применяется при нажатии модификатора FUNCTION.
  • capslock : Применяется, когда модификатор CAPS LOCK заблокирован.
  • numlock : Применяется, когда модификатор NUM LOCK заблокирован.
  • scrolllock : Применяется, когда модификатор SCROLL LOCK заблокирован.

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

Следовательно, свойства, указанные позже, переопределяют свойства, указанные ранее для данного ключа.

Поведение

Каждое свойство соответствует поведению. Наиболее распространенным поведением является ввод символа, но есть и другие.

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

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

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

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

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

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

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

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

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

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

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

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

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

  • '\u0300' : серьезный акцент.
  • '\u0301' : Острый акцент.
  • '\u0302' : Циркумфлекс акцент.
  • '\u0303' : акцент тильды.
  • '\u0308' : умлаутский акцент.

Когда за мёртвой клавишей следует другой символ, мёртвая клавиша и последующие символы составляются. Например, когда пользователь набирает мертвую клавишу с серьезным акцентом, за которой следует буква «а», результатом будет «а».

Обратитесь к KeyCharacterMap.getDeadChar для получения дополнительной информации об обработке мертвых ключей.

Комментарии

Строки комментариев начинаются с «#» и продолжаются до конца строки. Как это:

# A comment!

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

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

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

Shift + А

Предположим, пользователь одновременно нажал 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 и CONTROL.

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

Таким образом, результирующее поведение комбинации клавиш CONTROL + A равно none .

ПОБЕГ

Теперь предположим, что пользователь нажал ESCAPE.

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.

Следующее объявление клавиши гарантирует, что 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
}

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

Примеры

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

# 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 не поддерживает многоязычные клавиатуры. Кроме того, встроенная общая карта символов клавиш предполагает раскладку клавиатуры на английском языке (США).

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

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

Проверка

Убедитесь, что вы проверили файлы карт ключей с помощью инструмента Validate Keymaps .