Los archivos de diseño de teclas (archivos .kl) asignan códigos de teclas y ejes de Linux a códigos de teclas y ejes de Android, y especifican marcas de políticas asociadas.
Los archivos de diseño de teclas específicos del dispositivo son los siguientes:
- Obligatorio para dispositivos de entrada internos (integrados) con teclas, incluidas las teclas especiales, como las de volumen, encendido y multimedia de auriculares.
- Opcional para otros dispositivos de entrada, pero recomendado para teclados y joysticks de uso especial.
Si no hay un archivo de diseño de teclas específico del dispositivo disponible, el sistema elige uno predeterminado.
Ubicación
Los archivos de diseño de claves se encuentran por proveedor USB, ID de producto (y, de manera opcional, versión) o por nombre del dispositivo de entrada. Se consultan las siguientes rutas de acceso en orden:
/odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl/odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl/odm/usr/keylayout/DEVICE_NAME.kl/vendor/usr/keylayout/DEVICE_NAME.kl/system/usr/keylayout/DEVICE_NAME.kl/data/system/devices/keylayout/DEVICE_NAME.kl/odm/usr/keylayout/Generic.kl/vendor/usr/keylayout/Generic.kl/system/usr/keylayout/Generic.kl/data/system/devices/keylayout/Generic.kl
Cuando se construye una ruta de acceso de archivo que contiene el nombre del dispositivo, todos los caracteres del nombre del dispositivo, excepto los números del 0 al 9, las letras del a al z, las letras del A al Z, el guion o el guion bajo, se reemplazan por _.
Archivo de diseño de teclas genérico
El sistema proporciona un archivo de diseño de claves genérico integrado especial llamado Generic.kl. Este diseño de teclas está diseñado para admitir una variedad de joysticks y teclados externos estándar. No modifiques el diseño de la clave genérica.
Sintaxis
Un archivo de diseño de claves es un archivo de texto sin formato que consta de declaraciones y marcas de claves o ejes.
Declaraciones de claves
Las declaraciones de claves consisten en la palabra clave key seguida de un número de código de clave de Linux y un nombre de código de clave de Android, o el uso de la palabra clave seguido de un uso de HID y un nombre de código de clave de Android. El uso de HID se representa como un número entero de 32 bits, en el que los 16 bits superiores representan la página de uso de HID y los 16 bits inferiores representan el ID de uso de HID. Cualquier declaración puede ir seguida de un conjunto opcional de marcas de políticas delimitadas por espacios en blanco.
key 1 ESCAPE key 114 VOLUME_DOWN key 16 Q VIRTUAL key usage 0x0c006F BRIGHTNESS_UP
Se reconocen las siguientes marcas de políticas:
FUNCTION: La clave se debe interpretar como si también se presionara la tecla FUNCTION.GESTURE: Es la clave que genera un gesto del usuario, como colocar la palma de la mano sobre la pantalla táctil.VIRTUAL: La tecla es una tecla virtual (botón capacitivo) junto a la pantalla táctil principal. Esto hace que se habilite una lógica de anulación de rebote especial (consulta a continuación).
Declaraciones de ejes
Cada declaración de eje consta de la palabra clave axis seguida de un número de código de eje de Linux y calificadores que controlan el comportamiento del eje, incluido al menos un nombre de código de eje de Android.
Ejes básicos
Un eje básico simplemente asigna un código de eje de Linux a un nombre de código de eje de Android. La siguiente declaración asigna ABS_X (indicado por 0x00) a AXIS_X (indicado por X).
axis 0x00 X
En el ejemplo anterior, si el valor de ABS_X es 5, entonces AXIS_X se establece en 5.
Ejes divididos
Un eje dividido asigna un código de eje de Linux a dos nombres de código de eje de Android, de modo que los valores inferiores o superiores a un umbral se dividan en dos ejes diferentes cuando se asignan. Esta asignación es útil cuando un solo eje físico que informa el dispositivo codifica dos ejes lógicos diferentes y mutuamente excluyentes.
La siguiente declaración asigna los valores del eje ABS_Y (indicados por 0x01) a AXIS_GAS cuando son menores que 0x7f o a AXIS_BRAKE cuando son mayores que 0x7f.
axis 0x01 split 0x7f GAS BRAKE
En el ejemplo anterior, si el valor de ABS_Y es 0x7d, entonces AXIS_GAS se establece en 2 (0x7f - 0x7d) y AXIS_BRAKE se establece en 0. Por el contrario, si el valor de ABS_Y es 0x83, AXIS_GAS se establece en 0 y AXIS_BRAKE se establece en 4 (0x83 - 0x7f). Por último, si el valor de ABS_Y es igual al valor dividido de 0x7f, AXIS_GAS y AXIS_BRAKE se establecen en 0.
Ejes invertidos
Un eje invertido invierte el signo del valor del eje. La siguiente declaración asigna ABS_RZ (indicado por 0x05) a AXIS_BRAKE (indicado por BRAKE) y lo niega para invertir el resultado.
axis 0x05 invert BRAKE
En el ejemplo anterior, si el valor de ABS_RZ es 2, entonces AXIS_BRAKE se establece en -2.
Opción de centro plano
Debido al ruido, un dispositivo de joystick puede informar eventos de entrada incluso cuando no se está usando. Por lo general, este ruido proviene de los joysticks izquierdo o derecho y hace que el controlador informe un valor de posición cercano a 0. El valor "center flat" especifica la cantidad de ruido que se espera del controlador en reposo.
El protocolo de entrada de Linux proporciona una forma para que los controladores de dispositivos de entrada especifiquen el valor plano central de los ejes del joystick, pero no todos los controladores lo informan y algunos proporcionan valores incorrectos. Para resolver este problema, una declaración de eje puede ir seguida de una opción flat que especifique el ancho de la región alrededor de la posición central del eje que se debe considerar como centrado.
Por ejemplo, si un controlador de dispositivo informa valores de AXIS_X entre 0 y 100, el sistema de entrada de Android asignará 0 a -1 y 100 a 1.
El centro del rango será 50 en las coordenadas sin escala y 0 en las coordenadas con escala.
Si un valor plano es igual a 10, los desarrolladores deben suponer que cualquier valor de AXIS_X informado entre -0.1 y 0.1 (entre 40 y 60 en coordenadas sin escala) es ruido y tratar esos valores que provienen del joystick como cero.
Nota: Si bien el archivo de diseño de claves especifica el valor para el espacio de coordenadas del controlador, el valor que informa android.view.InputDevice.MotionRange#getFlat() está en el espacio de coordenadas de Android.
axis 0x03 Z flat 4096
En el ejemplo anterior, el valor plano central se establece en 4096.
Comentarios
Las líneas de comentarios comienzan con # y continúan hasta el final de la línea:
# A comment!
Se ignoran las líneas en blanco.
Ejemplos
Teclado
# This is an example of a key layout file for a keyboard. key 1 ESCAPE key 2 1 key 3 2 key 4 3 key 5 4 key 6 5 key 7 6 key 8 7 key 9 8 key 10 9 key 11 0 key 12 MINUS key 13 EQUALS key 14 DEL # etc...
Controles del sistema
# This is an example of a key layout file for basic system controls, # such as volume and power keys which are typically implemented as GPIO pins # the device decodes into key presses. key 114 VOLUME_DOWN key 115 VOLUME_UP key 116 POWER
Botones capacitivos
# This is an example of a key layout file for a touch device with capacitive buttons. key 139 MENU VIRTUAL key 172 HOME VIRTUAL key 158 BACK VIRTUAL key 217 SEARCH VIRTUAL
Controles multimedia del conector para auriculares
# This is an example of a key layout file for headset mounted media controls. # A typical headset jack interface might have special control wires or detect known # resistive loads as corresponding to media functions or volume controls. # This file assumes that the driver decodes these signals and reports media # controls as key presses. key 163 MEDIA_NEXT key 165 MEDIA_PREVIOUS key 226 HEADSETHOOK
Joystick
# This is an example of a key layout file for a joystick. # These are the buttons that the joystick supports, represented as keys. key 304 BUTTON_A key 305 BUTTON_B key 307 BUTTON_X key 308 BUTTON_Y key 310 BUTTON_L1 key 311 BUTTON_R1 key 314 BUTTON_SELECT key 315 BUTTON_START key 316 BUTTON_MODE key 317 BUTTON_THUMBL key 318 BUTTON_THUMBR # Left and right stick. # The reported value for flat is 128 in a range of -32767 to 32768, which is absurd. # This confuses applications that rely on the flat value because the joystick # actually settles in a flat range of +/- 4096 or so. We override it here. axis 0x00 X flat 4096 axis 0x01 Y flat 4096 axis 0x03 Z flat 4096 axis 0x04 RZ flat 4096 # Triggers. axis 0x02 LTRIGGER axis 0x05 RTRIGGER # Hat. axis 0x10 HAT_X axis 0x11 HAT_Y
Teclas virtuales en pantalla
El sistema de entrada proporciona funciones especiales para implementar teclas virtuales en los siguientes casos de uso:
- Si las teclas virtuales en pantalla se muestran gráficamente en la pantalla (como en el Galaxy Nexus), el componente de la barra de navegación las implementa en el paquete de la IU del sistema. Debido a que las teclas virtuales gráficas se implementan en una capa alta del sistema, no se incluyen los archivos de diseño de teclas y no se aplica la siguiente información.
- Si las teclas virtuales en pantalla se implementan como una región táctil extendida que forma parte de la pantalla táctil principal (como en el Nexus One), el sistema de entrada usa un archivo de mapa de teclas virtual para traducir las coordenadas táctiles X/Y en códigos de teclas de Linux y, luego, usa el archivo de diseño de teclas para traducir los códigos de teclas de Linux en códigos de teclas de Android (para obtener detalles sobre los archivos de mapa de teclas virtuales, consulta Dispositivos táctiles). El archivo de diseño de teclas del dispositivo de entrada de pantalla táctil debe especificar la asignación de teclas adecuada y, además, incluir la marca
VIRTUALpara cada tecla. - Si las teclas virtuales en pantalla se implementan como botones capacitivos separados de la pantalla táctil principal (como en el Nexus S), el controlador de dispositivo del kernel o el firmware es responsable de traducir los toques en códigos de teclas de Linux, que el sistema de entrada luego traduce en códigos de teclas de Android con el archivo de diseño de teclas.
El archivo de diseño de teclas del dispositivo de entrada de botones capacitivos debe especificar la asignación de teclas adecuada y debe incluir la marca
VIRTUALpara cada tecla.
Cuando las teclas virtuales se encuentran dentro o en estrecha proximidad física de la pantalla táctil, es fácil que los usuarios presionen accidentalmente un botón cuando tocan cerca de la parte inferior de la pantalla o cuando deslizan un dedo de arriba abajo o de abajo hacia arriba en la pantalla. Para evitar esto, el sistema de entrada aplica un pequeño desbloqueo de rebote de modo que se ignoren las presiones de teclas virtuales durante un breve período después del toque más reciente en la pantalla táctil (esta demora se denomina tiempo de inactividad de la tecla virtual).
Para habilitar el desbloqueo de teclas virtuales, haz lo siguiente:
- Proporciona un archivo de diseño de teclas para la pantalla táctil o el dispositivo de entrada de botones capacitivos con la marca
VIRTUALestablecida para cada tecla.key 139 MENU VIRTUAL key 172 HOME VIRTUAL key 158 BACK VIRTUAL key 217 SEARCH VIRTUAL
- Establece el valor del tiempo de inactividad de la clave virtual en una superposición de recursos para el recurso
config.xmldel framework.<!-- Specifies the amount of time to disable virtual keys after the screen is touched to filter out accidental virtual key presses due to swiping gestures or taps near the edge of the display. May be 0 to disable the feature. It is recommended that this value be no more than 250 ms. This feature should be disabled for most devices. --> <integer name="config_virtualKeyQuietTimeMillis">250</integer>
Validación
Debes validar tus archivos de diseño de teclas con la herramienta Validate Keymaps.