Dispositivos de teclado

Android es compatible con una variedad de dispositivos de teclado, incluidos teclados con funciones especiales (controles de volumen y encendido), teclados QWERTY integrados compactos y teclados externos estilo PC con todas las funciones.

Este documento describe únicamente los teclados físicos. Consulte el SDK de Android para obtener información sobre los teclados virtuales (editores de métodos de entrada).

Clasificación del teclado

Un dispositivo de entrada se clasifica como teclado si se cumple alguna de las siguientes condiciones:

• El dispositivo de entrada informa la presencia de cualquier código de tecla de Linux utilizado en los teclados, incluidos 0 a 0xff o KEY_OK a KEY_MAX .

• El dispositivo de entrada informa la presencia de cualquier código de tecla de Linux utilizado en joysticks y gamepads, incluidos BTN_0 a BTN_9 , BTN_TRIGGER a BTN_DEAD o BTN_A a BTN_THUMBR .

Actualmente, los joysticks se clasifican como teclados porque los eventos EV_KEY informan sobre los botones del joystick y del gamepad de la misma manera que se informan las teclas del teclado. Por lo tanto, los joysticks y gamepads también utilizan archivos de mapas de teclas para la configuración.

Una vez que un dispositivo de entrada ha sido clasificado como teclado, el sistema carga el archivo de configuración del dispositivo de entrada y el diseño del teclado para el teclado.

A continuación, el sistema intenta determinar características adicionales del dispositivo.

• Si el dispositivo de entrada tiene teclas asignadas a KEYCODE_Q , se considera que el dispositivo tiene un teclado alfabético (en lugar de numérico). La capacidad del teclado alfabético se informa en el objeto de Configuration del recurso como KEYBOARD_QWERTY .

• Si el dispositivo de entrada tiene teclas asignadas a KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT , KEYCODE_DPAD_RIGHT y KEYCODE_DPAD_CENTER (todas deben estar presentes), se considera que el dispositivo tiene un teclado direccional. La capacidad del teclado direccional se informa en el objeto de Configuration del recurso como NAVIGATION_DPAD .

• Si el dispositivo de entrada tiene teclas asignadas a KEYCODE_BUTTON_A u otras teclas relacionadas con el gamepad, se considera que el dispositivo tiene un gamepad.

Requisitos del controlador de teclado

1. Los controladores de teclado solo deben registrar códigos de teclas para las teclas que realmente admiten. El registro de códigos de teclas en exceso puede confundir el algoritmo de clasificación del dispositivo o hacer que el sistema detecte incorrectamente las capacidades de teclado admitidas del dispositivo.

2. Los controladores de teclado deben usar EV_KEY para informar sobre las pulsaciones de teclas, utilizando un valor de 0 para indicar que se suelta una tecla, un valor de 1 para indicar que se pulsa una tecla y un valor mayor o igual a 2 para indicar que la tecla se ha pulsado. repitiéndose automáticamente.

3. Android realiza su propia repetición de teclado. La funcionalidad de repetición automática debe estar deshabilitada en el controlador.

4. Los controladores de teclado pueden indicar opcionalmente el uso de HID o el código de escaneo de bajo nivel enviando EV_MSC con MSC_SCANCODE y un valor que indica el uso o el código de escaneo cuando se presiona la tecla. Esta información no es utilizada actualmente por Android.

5. Los controladores de teclado deben admitir la configuración de estados LED cuando se escribe EV_LED en el dispositivo. El controlador hid-input maneja esto automáticamente. En el momento de escribir este artículo, Android usa LED_CAPSLOCK , LED_SCROLLLOCK y LED_NUMLOCK . Estos LED solo necesitan ser compatibles cuando el teclado realmente tiene las luces indicadoras asociadas.

6. Los controladores de teclado para teclados integrados (por ejemplo, usando una matriz GPIO) deben asegurarse de enviar eventos EV_KEY con un valor de 0 para cualquier tecla que aún esté presionada cuando el dispositivo se vaya a dormir. De lo contrario, las teclas podrían atascarse y repetirse automáticamente para siempre.

Operación del teclado

El siguiente es un breve resumen del funcionamiento del teclado en Android.

1. EventHub lee eventos sin procesar del controlador evdev y asigna códigos de teclas de Linux (a veces denominados códigos de escaneo) en códigos de teclas de Android utilizando el mapa de diseño de teclas del teclado.

2. InputReader consume los eventos sin procesar y actualiza el estado de la clave meta. Por ejemplo, si se presiona o suelta la tecla de mayúsculas a la izquierda, el lector establecerá o restablecerá los bits META_SHIFT_LEFT_ON y META_SHIFT_ON según corresponda.

3. InputReader notifica a InputDispatcher sobre el evento clave.

4. InputDispatcher le pregunta a WindowManagerPolicy qué hacer con el evento clave llamando a WindowManagerPolicy.interceptKeyBeforeQueueing . Este método es parte de una ruta crítica que se encarga de activar el dispositivo cuando se presionan ciertas teclas. EventHub mantiene efectivamente un bloqueo de activación a lo largo de esta ruta crítica para garantizar que se ejecute hasta su finalización.

5. Si un InputFilter está actualmente en uso, InputDispatcher le da la oportunidad de consumir o transformar la clave. El InputFilter se puede usar para implementar políticas de accesibilidad de todo el sistema de bajo nivel.

6. InputDispatcher pone en cola la clave para su procesamiento en el subproceso de envío.

7. Cuando InputDispatcher quita la cola de la clave, le da a WindowManagerPolicy una segunda oportunidad de interceptar el evento clave llamando a WindowManagerPolicy.interceptKeyBeforeDispatching . Este método maneja accesos directos del sistema y otras funciones.

8. Luego, InputDispatcher identifica el objetivo del evento clave (la ventana enfocada) y espera a que esté listo. Luego, InputDispatcher entrega el evento clave a la aplicación.

9. Dentro de la aplicación, el evento clave se propaga por la jerarquía de vistas hasta la vista enfocada para el envío de claves previo al IME.

10. Si el evento clave no se maneja en el envío previo al IME y se está utilizando un IME, el evento clave se envía al IME.

11. Si el evento clave no fue consumido por el IME, entonces el evento clave se propaga hacia abajo en la jerarquía de vistas a la vista enfocada para el envío de claves estándar.

12. La aplicación informa al InputDispatcher si se consumió el evento clave. Si el evento no se consumió, InputDispatcher llama a WindowManagerPolicy.dispatchUnhandledKey para aplicar el comportamiento de "retroceso". Dependiendo de la acción de reserva, el ciclo de despacho de eventos clave puede reiniciarse utilizando un código de clave diferente. Por ejemplo, si una aplicación no maneja KEYCODE_ESCAPE , el sistema puede volver a enviar el evento clave como KEYCODE_BACK en su lugar.

Configuración del teclado

El comportamiento del teclado está determinado por la disposición de las teclas del teclado, el mapa de caracteres de las teclas y la configuración del dispositivo de entrada.

Consulte las siguientes secciones para obtener más detalles sobre los archivos que participan en la configuración del teclado:

• Archivos de distribución de teclas
• Archivos de mapas de caracteres clave
• Archivos de configuración de dispositivos de entrada

Propiedades

Las siguientes propiedades de configuración del dispositivo de entrada se utilizan para los teclados.

keyboard.layout

Definición: keyboard.layout = <nombre>

Especifica el nombre del archivo de diseño de teclas asociado con el dispositivo de entrada, sin incluir la extensión .kl . Si no se encuentra este archivo, el sistema de entrada utilizará el diseño de teclas predeterminado en su lugar.

Los espacios en el nombre se convierten en guiones bajos durante la búsqueda.

Consulte la documentación del archivo de distribución de teclas para obtener más detalles.

keyboard.characterMap

Definición: keyboard.characterMap = <nombre>

Especifica el nombre del archivo de mapa de caracteres clave asociado con el dispositivo de entrada, sin incluir la extensión .kcm . Si no se encuentra este archivo, el sistema de entrada utilizará el mapa de caracteres clave predeterminado en su lugar.

Los espacios en el nombre se convierten en guiones bajos durante la búsqueda.

Consulte la documentación del archivo de mapa de caracteres clave para obtener más detalles.

keyboard.orientationAware

Definición: keyboard.orientationAware = 0 | 1

Especifica si el teclado debe reaccionar a los cambios de orientación de la pantalla.

• Si el valor es 1 , las teclas del teclado direccional giran cuando cambia la orientación de la pantalla asociada.

• Si el valor es 0 , el teclado es inmune a los cambios de orientación de la pantalla.

El valor predeterminado es 0 .

El conocimiento de la orientación se utiliza para respaldar la rotación de las teclas del teclado direccional, como en el Motorola Droid. Por ejemplo, cuando el dispositivo se gira 90 grados en el sentido de las agujas del reloj desde su orientación natural, KEYCODE_DPAD_UP se reasigna para producir KEYCODE_DPAD_RIGHT ya que la tecla 'arriba' termina apuntando a la 'derecha' cuando el dispositivo se mantiene en esa orientación.

keyboard.builtIn

Definición: keyboard.builtIn = 0 | 1

Especifica si el teclado es el teclado integrado (conectado físicamente).

El valor predeterminado es 1 si el nombre del dispositivo termina con -keypad , 0 en caso contrario.

Al teclado incorporado siempre se le asigna una identificación de dispositivo de 0 . A otros teclados que no están integrados se les asignan identificadores de dispositivo únicos distintos de cero.

El uso de una identificación de 0 para el teclado integrado es importante para mantener la compatibilidad con el campo KeyCharacterMap.BUILT_IN_KEYBOARD , que especifica la identificación del teclado integrado y tiene un valor de 0 . Este campo ha quedado obsoleto en la API, pero es posible que las aplicaciones más antiguas aún lo utilicen.

Un teclado de función especial (uno cuyo mapa de caracteres de teclas especifica un tipo de SPECIAL_FUNCTION ) nunca se registrará como teclado incorporado, independientemente de la configuración de esta propiedad. Esto se debe a que, por definición, un teclado de funciones especiales no está destinado a ser utilizado para escribir con fines generales.

Configuraciones de ejemplo

# This is an example input device configuration file for a built-in
# keyboard that has a DPad.

# The keyboard is internal because it is part of the device.
device.internal = 1

# The keyboard is the default built-in keyboard so it should be assigned
# an id of 0.
keyboard.builtIn = 1

# The keyboard includes a DPad which is mounted on the device.  As the device
# is rotated the orientation of the DPad rotates along with it, so the DPad must
# be aware of the display orientation.  This ensures that pressing 'up' on the
# DPad always means 'up' from the perspective of the user, even when the entire
# device has been rotated.
keyboard.orientationAware = 1

Notas de compatibilidad

Antes de Honeycomb, el mapeador de entrada de teclado no usaba ninguna propiedad de configuración. Se asumió que todos los teclados estaban conectados físicamente y conscientes de la orientación. El diseño de teclas predeterminado y el mapa de caracteres clave se llamaron qwerty en lugar de Generic . El formato del mapa de caracteres clave también era muy diferente y el marco no admitía teclados completos estilo PC o teclados externos.

Al actualizar dispositivos a Honeycomb, asegúrese de crear o actualizar la configuración necesaria y los archivos de asignación de claves.

Usos de HID, códigos clave de Linux y códigos clave de Android

El sistema se refiere a claves usando varios identificadores diferentes, dependiendo de la capa de abstracción.

Para dispositivos HID, cada clave tiene un uso HID asociado. El controlador hid-input Linux y los controladores HID específicos del dispositivo y del proveedor relacionado son responsables de analizar los informes de HID y asignar los usos de HID a los códigos clave de Linux.

A medida que Android lee los eventos EV_KEY del kernel de Linux, traduce cada código de tecla de Linux a su correspondiente código de tecla de Android de acuerdo con el archivo de diseño de teclas del dispositivo.

Cuando el evento clave se envía a una aplicación, la instancia android.view.KeyEvent informa el código clave de Linux como el valor de getScanCode() y el código clave de Android como el valor de getKeyCode() . A los efectos del marco, solo es importante el valor de getKeyCode() .

Tenga en cuenta que Android no usa la información de uso de HID ni la pasa a las aplicaciones.

Tablas de códigos

Las siguientes tablas muestran cómo se relacionan entre sí los usos de HID, los códigos de clave de Linux y los códigos de clave de Android.

La columna LKC especifica el código clave de Linux en hexadecimal.

La columna AKC especifica el código clave de Android en hexadecimal.

La columna Notas hace referencia a las notas que se publican después de la tabla.

La columna Versión especifica la primera versión de la plataforma Android que ha incluido esta clave en su mapa de claves predeterminado. Se muestran varias filas en los casos en que el mapa de teclas predeterminado ha cambiado entre versiones. La versión más antigua indicada es la 1.6.

• En Gingerbread (2.3) y versiones anteriores, el mapa de teclas predeterminado era qwerty.kl . Este mapa de teclas solo estaba diseñado para usarse con el emulador de Android y no para admitir teclados externos arbitrarios. Sin embargo, algunos OEM agregaron soporte de teclado Bluetooth a la plataforma y confiaron en qwerty.kl para proporcionar las asignaciones de teclado necesarias. En consecuencia, estas asignaciones más antiguas pueden ser de interés para los OEM que están construyendo periféricos para estos dispositivos en particular. Tenga en cuenta que las asignaciones son sustancialmente diferentes de las actuales, particularmente con respecto al tratamiento de la tecla HOME . Se recomienda que todos los periféricos nuevos se desarrollen de acuerdo con Honeycomb o mapas de teclas más recientes (es decir, HID estándar).

• A partir de Honeycomb (3.0), el mapa de teclas predeterminado es Generic.kl . Este mapa de teclas se diseñó para admitir teclados completos de estilo PC. La mayoría de las funciones de los teclados HID estándar deberían funcionar de inmediato.

La asignación de códigos clave puede variar según las versiones del kernel de Linux y Android. Cuando se sabe que se han producido cambios en los mapas de teclas predeterminados de Android, se indican en la columna de versión.

Los controladores HID específicos del dispositivo y los mapas de teclas pueden aplicar mapas diferentes a los que se indican aquí.

Teclado HID y página de teclado numérico (0x07)

Página de escritorio genérica de HID (0x01)

Página de consumidor HID (0x0c)

Additional non-HID Mappings

These mappings describe functions that do not appear in HID but for which Linux key codes exist.

Legacy Unsupported Keys

These mappings appeared in previous versions of Android but were inconsistent with HID or used non-standard Linux key codes. They are no longer supported.

notas

1. The Android key code associated with common alphanumeric and symbolic keys may vary based on the keyboard layout and language. For historical reasons, the physical scan codes and HID usages associated with keys on a keyboard are often defined positionally even though the labels printed on those keys may vary from one language to another.

   On a US English (QWERTY) keyboard, the top-left alphabetic key is labeled Q. On a French (AZERTY) keyboard, the key in the same position is labeled A. Despite the label, on both keyboards the top-left alphabetic key is referred to using the HID usage 0x07 0x0014 which is mapped to the Linux key code KEY_Q.

   When Android is configured with a US English keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_Q and will produce the characters 'Q' and 'q'. However, when Android is configured with a French keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_A and will produce the characters 'A' and 'a'.

   The Android key code typically reflects the language-specific interpretation of the key, so a different Android key code may be used for different languages.

2. 0x0c 0x022f AC Zoom is defined in the HID as a linear control but the kernel maps it as a key, which is probably incorrect.

3. The Linux function keys KEY_FN_* are mapped to simpler key codes but are dispatched with the META_FUNCTION meta state bit set to true.

4. Prior to Android Ice Cream Sandwich 4.0, the default key layout contained mappings for some extra key codes that were not defined in the mainline Linux kernel headers. These mappings have since been removed because these previously undefined key codes have since been assigned different meanings in more recent versions of the Linux kernel.

Sources

1. USB HID Usage Tables v1.12
2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java