Los archivos de mapa de caracteres clave (archivos .kcm) son responsables de asignar combinaciones de códigos de teclas de Android con modificadores a caracteres Unicode.
Los archivos de diseño de teclas específicos del dispositivo son obligatorios para todos los dispositivos de entrada internos (integrados) que tengan teclas, aunque solo sea para indicarle al sistema que el dispositivo es solo para fines especiales (no un teclado completo).
Los archivos de diseño de teclas específicos del dispositivo son opcionales para los teclados externos y, a menudo, no son necesarios. El sistema proporciona un mapa de caracteres de teclas genérico que es adecuado para muchos teclados externos.
Si no hay un archivo de diseño de teclas específico del dispositivo disponible, el sistema elegirá uno predeterminado.
Ubicación
Los archivos de mapa de caracteres clave 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/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
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 el guion bajo.
Archivo de mapa de caracteres de clave genérico
El sistema proporciona un archivo de mapa de caracteres clave integrado especial llamado Generic.kcm.
Este mapa de caracteres de teclas está diseñado para admitir una variedad de teclados externos estándar.
No modifiques el mapa de caracteres de clave genérico.
Archivo de mapa de caracteres de teclas virtuales
El sistema proporciona un archivo de mapa de caracteres clave integrado especial llamado Virtual.kcm que usan los dispositivos de teclado virtual.
El dispositivo de teclado virtual es un dispositivo de entrada sintético cuyo ID es -1 (consulta KeyCharacterMap.VIRTUAL_KEYBOARD). Está presente en todos los dispositivos Android a partir de Android Honeycomb 3.0. El propósito del dispositivo de teclado virtual es proporcionar un dispositivo de entrada integrado conocido que se pueda usar para insertar pulsaciones de teclas en aplicaciones a través del IME o la instrumentación de prueba, incluso para dispositivos que no tienen teclados integrados.
Se supone que el teclado virtual tiene un diseño QWERTY completo que es el mismo en todos los dispositivos. Esto permite que las aplicaciones inserten pulsaciones de teclas con el dispositivo de teclado virtual y siempre obtengan los mismos resultados.
No modifiques el mapa de caracteres de teclas virtuales.
Sintaxis
Un archivo de mapa de caracteres clave es un archivo de texto sin formato que consta de una declaración de tipo de teclado y un conjunto de declaraciones de claves.
Declaración del tipo de teclado
Una declaración de tipo de teclado describe el comportamiento general del teclado. Un archivo de mapa de caracteres debe contener una declaración de tipo de teclado. Para mayor claridad, a menudo se coloca en la parte superior del archivo.
type FULL
Se reconocen los siguientes tipos de teclados:
-
NUMERIC: Un teclado numérico (12 teclas).Un teclado numérico admite la entrada de texto con un enfoque de varios toques. Es posible que debas presionar una tecla varias veces para generar la letra o el símbolo deseado.
Por lo general, este tipo de teclado está diseñado para escribir con el pulgar.
Corresponde a
KeyCharacterMap.NUMERIC. -
PREDICTIVE: Un teclado con todas las letras, pero con más de una letra por tecla.Por lo general, este tipo de teclado está diseñado para escribir con el pulgar.
Corresponde a
KeyCharacterMap.PREDICTIVE. -
ALPHA: Un teclado con todas las letras y, tal vez, algunos números.Un teclado alfabético admite la entrada de texto directamente, pero puede tener un diseño condensado con un factor de forma pequeño. A diferencia de un teclado
FULL, es posible que solo se pueda acceder a algunos símbolos con selectores de caracteres en pantalla especiales. Además, para mejorar la velocidad y precisión de escritura, el framework proporciona indicaciones especiales para teclados alfabéticos, como la mayúscula automática y las teclas SHIFT y ALT activadas o bloqueadas.Por lo general, este tipo de teclado está diseñado para escribir con el pulgar.
-
FULL: Un teclado completo al estilo de PC.Un teclado completo se comporta como un teclado de PC. Para acceder a todos los símbolos, presiona las teclas del teclado directamente, sin compatibilidad en pantalla ni indicaciones visuales, como la mayúscula automática.
Por lo general, este tipo de teclado está diseñado para escribir con las dos manos.
-
SPECIAL_FUNCTION: Es un teclado que solo se usa para realizar funciones de control del sistema en lugar de escribir.Un teclado de funciones especiales solo consta de teclas que no imprimen, como HOME y POWER, que no se usan para escribir.
Los mapas de caracteres de teclas Generic.kcm y Virtual.kcm son teclados FULL.
Declaraciones de claves
Cada declaración de clave consta de la palabra clave key seguida de un nombre de código de clave de Android, una llave de apertura, un conjunto de propiedades y comportamientos, y una llave de cierre.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
Propiedades
Cada propiedad clave establece una asignación de una clave a un comportamiento. Para que los archivos de mapa de caracteres clave sean más compactos, se pueden asignar varias propiedades al mismo comportamiento separándolas con una coma.
En el ejemplo anterior, a la propiedad label se le asigna el comportamiento 'A'.
Del mismo modo, a las propiedades ctrl, alt y meta se les asigna simultáneamente el comportamiento none.
Se reconocen las siguientes propiedades:
-
label: Especifica la etiqueta que se imprime físicamente en la clave, cuando consta de un solo carácter. Este es el valor que muestra el métodoKeyCharacterMap.getDisplayLabel. -
number: Especifica el comportamiento (el carácter que se debe escribir) cuando una vista de texto numérico tiene el enfoque, como cuando el usuario escribe un número de teléfono.Los teclados compactos suelen combinar varios símbolos en una sola tecla, de modo que se pueda usar la misma tecla para escribir
'1'y'a', o'#'y'q'. Para estas claves, se debe establecer la propiedadnumberpara indicar qué símbolo se debe escribir en un contexto numérico, si corresponde.Algunos símbolos "numéricos" típicos son los dígitos del
'0'al'9','#','+','(',')',','y'.'. -
base: Especifica el comportamiento (el carácter que se debe escribir) cuando no se presionan modificadores. -
<modifier> o <modifier1>
+<modifier2>+…: Especifica el comportamiento (el carácter que se debe escribir) cuando se presiona la tecla y todos los modificadores especificados están activos.Por ejemplo, la propiedad modificador
shiftespecifica un comportamiento que se aplica cuando se presiona el modificador MAYÚS izquierda o derecha.De manera similar, la propiedad modificador
rshift+raltespecifica un comportamiento que se aplica cuando se presionan los modificadores MAYÚSCULAS DERECHA y ALT DERECHA juntos.
Los siguientes modificadores se reconocen en las propiedades de modificadores:
shift: Se aplica cuando se presiona el modificador MAYÚSCULAS IZQUIERDA o MAYÚSCULAS DERECHA.lshift: Se aplica cuando se presiona el modificador MAYÚSAGACHA.rshift: Se aplica cuando se presiona el modificador MAYÚSCULAS DERECHA.alt: Se aplica cuando se presiona el modificador ALT IZQUIERDO o ALT DERECHO.lalt: Se aplica cuando se presiona el modificador ALT IZQUIERDO.ralt: Se aplica cuando se presiona el modificador ALT DERECHO.ctrl: Se aplica cuando se presiona el modificador CONTROL IZQUIERDO o CONTROL DERECHO.lctrl: Se aplica cuando se presiona el modificador CONTROL IZQUIERDO.rctrl: Se aplica cuando se presiona el modificador CONTROL DERECHO.meta: Se aplica cuando se presiona el modificador META IZQUIERDO o META DERECHO.lmeta: Se aplica cuando se presiona el modificador META IZQUIERDO.rmeta: Se aplica cuando se presiona el modificador META DERECHA.sym: Se aplica cuando se presiona el modificador SYMBOL.fn: Se aplica cuando se presiona el modificador FUNCTION.capslock: Se aplica cuando el modificador CAPS LOCK está bloqueado.numlock: Se aplica cuando el modificador NUM LOCK está bloqueado.scrolllock: Se aplica cuando el modificador de bloqueo de desplazamiento está bloqueado.
El orden en que se enumeran las propiedades es importante. Cuando se asigna una clave a un comportamiento, el sistema analiza todas las propiedades relevantes en orden y muestra el último comportamiento aplicable que encontró.
En consecuencia, las propiedades que se especifican más adelante anula las que se especifican antes para una clave determinada.
Comportamientos
Cada propiedad se asigna a un comportamiento. El comportamiento más común es escribir un carácter, pero hay otros.
Se reconocen los siguientes comportamientos:
-
none: No escribas ningún carácter.Este comportamiento es el predeterminado cuando no se especifica ningún carácter. Especificar
nonees opcional, pero mejora la claridad. -
'X': Escribe el literal de carácter especificado.Este comportamiento hace que se ingrese el carácter especificado en la vista de texto enfocada. El literal de carácter puede ser cualquier carácter ASCII o una de las siguientes secuencias de escape:
'\\': Escribe un carácter de barra diagonal inversa.'\n': Escribe un carácter de línea nueva (usa esto para INTRO o RETORNO).'\t': Escribe un carácter TAB.'\'': Escribe un carácter de apóstrofo.'\"': Escribe un carácter de comillas.'\uXXXX': Escribe el carácter Unicode cuyo punto de código se proporciona en hexadecimal con XXXX.
-
fallback<Nombre de código de clave de Android>: Realiza una acción predeterminada si la aplicación no controla la clave.Este comportamiento hace que el sistema simule una pulsación de tecla diferente cuando una aplicación no controla la clave especificada de forma nativa. Se usa para admitir el comportamiento predeterminado de las teclas nuevas que no todas las aplicaciones saben controlar, como ESCAPE o las teclas del teclado numérico (cuando no se presiona Num Lock).
Cuando se realiza un comportamiento de resguardo, la aplicación recibirá dos presiones de teclas: una para la tecla original y otra para la tecla de resguardo que se seleccionó. Si la aplicación controla la clave original durante el evento de tecla arriba, se cancelará el evento de tecla de resguardo (
KeyEvent.isCanceledmostrarátrue).
El sistema reserva dos caracteres Unicode para realizar funciones especiales:
-
'\uef00': Cuando se realiza este comportamiento, la vista de texto consume y quita los cuatro caracteres que preceden al cursor, los interpreta como dígitos hexadecimales y, luego, inserta el punto de código Unicode correspondiente. -
'\uef01': Cuando se realiza este comportamiento, la vista de texto muestra un diálogo del selector de caracteres que contiene símbolos varios.
El sistema reconoce los siguientes caracteres Unicode como combinaciones de caracteres de teclas muertas diacríticas:
'\u0300': Acento grave.'\u0301': Acento agudo.'\u0302': Acento circunflejo.'\u0303': Acento grave.'\u0308': Acento umlaut.
Cuando se escribe una tecla muerta seguida de otro carácter, se componen la tecla muerta y los siguientes caracteres. Por ejemplo, cuando el usuario escribe una tecla muerta de acento grave seguida de la letra "a", el resultado es "à".
Consulta KeyCharacterMap.getDeadChar para obtener más información sobre el manejo de teclas inactivas.
Comentarios
Las líneas de comentarios comienzan con "#" y continúan hasta el final de la línea. Me gusta:
# A comment!
Se ignoran las líneas en blanco.
Cómo se asignan las combinaciones de teclas a los comportamientos
Cuando el usuario presiona una tecla, el sistema busca el comportamiento asociado con la combinación de esa presión de tecla y los modificadores que se presionaron actualmente.
MAYÚSCULAS + A
Supongamos que el usuario presionó A y MAYÚSCULAS al mismo tiempo. Primero, el sistema ubica el conjunto de propiedades y comportamientos asociados con KEYCODE_A.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
El sistema analiza las propiedades de la primera a la última y de izquierda a derecha, y omite las propiedades label y number, que son especiales.
La primera propiedad que se encuentra es base. La propiedad base siempre se aplica a una tecla, sin importar qué modificadores se presionen. En esencia, especifica el comportamiento predeterminado de la clave, a menos que se anule con las siguientes propiedades.
Dado que la propiedad base se aplica a esta presión de tecla, el sistema toma nota de que su comportamiento es 'a' (escribe el carácter a).
Luego, el sistema continúa analizando las propiedades posteriores en caso de que alguna de ellas sea más específica que base y la anule. Encuentra shift, que también se aplica a la combinación de teclas MAYÚS + A. Por lo tanto, el sistema decide ignorar el comportamiento de la propiedad base y elige el comportamiento asociado con la propiedad shift, que es 'A' (escribe el carácter A).
Luego, continúa analizando la tabla. Sin embargo, no se aplican otras propiedades a esta pulsación de tecla (no está bloqueada la tecla MAYÚSCULAS, no se presiona la tecla CONTROL, no se presiona la tecla ALT ni se presiona la tecla META).
Por lo tanto, el comportamiento resultante de la combinación de teclas MAYÚS + A es 'A'.
CONTROL + A
Ahora, considera lo que sucedería si el usuario presionara A y CONTROL al mismo tiempo.
Al igual que antes, el sistema analizaría la tabla de propiedades. Notaría que se aplicó la propiedad base, pero también seguiría escaneando hasta que finalmente llegara a la propiedad control. Como sucede, la propiedad control aparece después de base, por lo que su comportamiento anula el comportamiento de base.
Por lo tanto, el comportamiento resultante de la combinación de teclas CONTROL + A es none.
Escape
Ahora supongamos que el usuario presionó ESC.
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
Esta vez, el sistema obtiene el comportamiento fallback BACK, un comportamiento de resguardo.
Como no aparece ningún carácter literal, no se escribirá ningún carácter.
Cuando se procese la clave, el sistema primero entregará KEYCODE_ESCAPE a la aplicación. Si la aplicación no lo controla, el sistema lo intentará de nuevo, pero esta vez entregará KEYCODE_BACK a la aplicación como lo solicite el comportamiento de resguardo.
Por lo tanto, las aplicaciones que reconocen y admiten KEYCODE_ESCAPE tienen la oportunidad de controlarla tal como está, pero otras aplicaciones que no lo hacen pueden realizar la acción de resguardo de tratar la clave como si fuera KEYCODE_BACK.
NUMPAD_0 con o sin NUM LOCK
Las teclas del teclado numérico tienen interpretaciones muy diferentes según si la tecla NUM LOCK está bloqueada.
La siguiente declaración de clave garantiza que KEYCODE_NUMPAD_0 escriba 0 cuando se presione NUM LOCK. Cuando no se presiona NUM LOCK, la clave se entrega a la aplicación como de costumbre y, si no se controla, se entrega la clave de resguardo KEYCODE_INSERT.
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
Como podemos ver, las declaraciones de claves de resguardo mejoran en gran medida la compatibilidad con aplicaciones más antiguas que no reconocen o no admiten directamente todas las teclas presentes en un teclado completo al estilo de PC.
Ejemplos
Teclado completo
# 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
}
Teclado alfanumérico
# 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'
}
Game pad
# 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
}
Nota de compatibilidad
Antes de Android Honeycomb 3.0, el mapa de caracteres clave de Android se especificaba con una sintaxis muy diferente y se compilaba en un formato de archivo binario (.kcm.bin) durante el tiempo de compilación.
Aunque el nuevo formato usa la misma extensión .kcm, la sintaxis es bastante diferente (y mucho más potente).
A partir de Android Honeycomb 3.0, todos los archivos de mapa de caracteres clave de Android deben usar la nueva sintaxis y el formato de archivo de texto sin formato que se describe en este documento.
No se admite la sintaxis anterior, y el sistema no reconoce los archivos .kcm.bin anteriores.
Nota sobre el idioma
Actualmente, Android no admite teclados multilingües. Además, el mapa de caracteres de teclas genérico integrado supone un diseño de teclado en inglés de EE.UU.
Se recomienda a los OEMs que proporcionen mapas de caracteres de teclas personalizados para sus teclados si están diseñados para otros idiomas.
Es posible que las versiones futuras de Android proporcionen una mejor compatibilidad con teclados multilingües o diseños de teclado que el usuario pueda seleccionar.
Validación
Asegúrate de validar tus archivos de mapa de caracteres clave con la herramienta Validate Keymaps.