Файлы карты ключевых персонажей

Файлы сопоставления ключевых символов (файлы .kcm ) отвечают за сопоставление комбинаций кодов клавиш Android с модификаторами с символами Юникода.

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

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

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

Расположение

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

    Специальная функциональная клавиатура состоит только из непечатаемых клавиш, таких как ДОМОЙ и ПИТАНИЕ, которые фактически не используются для набора текста.

Карты ключевых символов 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 : определяет поведение (символ, который следует ввести), когда модификаторы не нажимаются.

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

    Например, свойство модификатора 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' : введите символ табуляции.
    • '\'' : введите символ апострофа.
    • '\"' : введите символ кавычки.
    • '\uXXXX' : введите символ Юникода, код которого задается в шестнадцатеричном формате XXXX.

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

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

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

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

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

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

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

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

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

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

Комментарии

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

# A comment!

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

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

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

Шифт + А

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