KeyEvent Code

Коды событий и устройства ввода

В документе KeyEvent описаны константы для кодов событий от клавиш и кнопок Key Event. Константы имеют имена с префиксом KEYCODE_, за которым следует имя кнопки, клавиши или другого управляющего элемента клавиатуры или манипулятора, например KEYCODE_7, KEYCODE_BUTTON_3, KEYCODE_DEL

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

Например, константа для центральной кнопки крестовины описана так:

KEYCODE_DPAD_CENTER (Added in API level 1)
public static final int KEYCODE_DPAD_CENTER
Key code constant: Directional Pad Center key.
May also be synthesized from trackball motions.
Constant Value: 23 (0x00000017)

Константа для клавиши ENTER на клавиатуре описана так:

KEYCODE_ENTER (Added in API level 1)
public static final int KEYCODE_ENTER
Key code constant: Enter key.
Constant Value: 66 (0x00000042)

На основе приведенного в данном документе списка описаний констант создана таблица БД, содержащая названия кнопок, их функции и значения кодов (десятичные и шестнадцатеричные). Для удобства поиска нужного кода используется выбор по имени, а также по dec- и hex-значениям событий для этих кнопок.

Кроме того, на основе документа InputDevice подготовлена таблица устройств ввода, содержащая их классификацию с соответствующими комментариями (26 классов).

Ниже приведен краткий перевод обоих документов.

Key Event и Device Input

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

Нажатие клавиши начинается с события клавиши, содержащего ACTION_DOWN. Если клавиша удерживается достаточно долго для повторения, то за начальным нажатием следуют дополнительные события клавиши с ACTION_DOWN и ненулевым значением для getRepeatCount().

Последнее событие кнопки — это ACTION_UP, которое возникает при отпускании клавиши. Если нажатие клавиши отменено, событие нажатия клавиши будет иметь установленный флаг FLAG_CANCELED.

Например, нажатие и отпускание кнопки '8' на клавиатуре вызывает события
(здесь 0x25 - сканкод кнопки, 0x0700 - PID клавиатуры):

   MSC_SCAN    00070025
   KEY_8       DOWN   - нажата (вниз)
   SYN_REPORT  00000000
   MSC_SCAN    00070025
   KEY_8       UP     - отпущена (вверх)
   SYN_REPORT  00000000

События от кнопок и клавиш обычно сопровождаются:

кодом кнопки getKeyCode()

кодом сканирования getScanCode()

кодом метасостояния getMetaState()

Константы кода кнопки определены в представленной здесь таблице, созданной на основе класса констант.

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

Константы кода метасостояния описывают нажатое состояние клавиш-модификаторов , таких как META_SHIFT_ON или META_ALT_ON.

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

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

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

Никогда не нужно полагаться на получение KeyEvents для любой клавиши в методе программного ввода. В частности, программная клавиатура по умолчанию никогда не будет отправлять какие-либо события клавиш любому приложению, предназначенному для Jelly Bean или более поздней версии, и будет отправлять события только для некоторых нажатий клавиш удаления и возврата приложениям, предназначенным для Ice Cream Sandwich или более ранней версии.

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

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

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

Реализация представления должна быть готова к обработке FLAG_CANCELED и должна допускать аномальные ситуации, такие как получение нового ACTION_DOWN без предварительного получения ACTION_UP для предыдущего нажатия клавиши.

В кокументе InputDevice приведена дополнительная информация о том, как различные типы устройств ввода и источников представляют клавиши и кнопки.

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

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

Поэтому нужно использовать комментарии к константам устройств ввода для соответствующей интерпретации.