Los archivos de mapa de caracteres clave (archivos .kcm ) son responsables de asignar combinaciones de códigos de clave de Android con modificadores a caracteres Unicode.
Los archivos de diseño de teclas específicos del dispositivo son necesarios para todos los dispositivos de entrada internos (integrados) que tienen teclas, aunque solo sea para indicarle al sistema que el dispositivo tiene un propósito especial únicamente (no un teclado completo).
Los archivos de distribución de teclas específicos del dispositivo son opcionales para los teclados externos y, a menudo, no son necesarios en absoluto. El sistema proporciona un mapa de caracteres clave genérico que es adecuado para muchos teclados externos.
Si no hay disponible ningún archivo de diseño de teclas específico del dispositivo, el sistema elegirá un valor predeterminado.
Ubicación
Los archivos de mapas de caracteres clave se ubican por proveedor de USB, ID de producto (y opcionalmente versión) o por nombre de dispositivo de entrada.
Las siguientes rutas se consultan 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
Al construir una ruta de archivo que contiene el nombre del dispositivo, todos los caracteres del nombre del dispositivo que no sean '0'-'9', 'a'-'z', 'A'-'Z', '-' o '_' se reemplazan por '_'.
Archivo de mapa de caracteres clave genérico
El sistema proporciona un archivo de mapa de caracteres clave integrado especial llamado Generic.kcm . Este mapa de caracteres clave está diseñado para admitir una variedad de teclados externos estándar.
¡No modifique el mapa de caracteres clave genérico!
Archivo de mapa de caracteres clave virtual
El sistema proporciona un archivo de mapa de caracteres clave integrado especial llamado Virtual.kcm que utilizan los dispositivos de teclado virtual.
El dispositivo de teclado virtual es un dispositivo de entrada sintético cuya identificación es -1 (consulte 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 puede utilizar para inyectar pulsaciones de teclas en aplicaciones mediante el IME o mediante 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 hace posible que las aplicaciones inyecten pulsaciones de teclas utilizando el dispositivo de teclado virtual y obtengan siempre los mismos resultados.
¡No modifiques el mapa de personajes clave virtual!
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 teclas.
Declaración de 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, suele colocarse en la parte superior del archivo.
type FULL
Se reconocen los siguientes tipos de teclado:
NUMERIC: Un teclado numérico (12 teclas).Un teclado numérico admite la entrada de texto mediante un enfoque de múltiples toques. Puede que sea necesario tocar una tecla varias veces para generar la letra o símbolo deseado.
Este tipo de teclado generalmente 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.Este tipo de teclado generalmente 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 mediante selectores de caracteres especiales en pantalla. Además, para mejorar la velocidad y precisión de la escritura, el marco proporciona prestaciones especiales para teclados alfabéticos, como mayúsculas automáticas y teclas SHIFT y ALT alternadas/bloqueadas.Este tipo de teclado generalmente está diseñado para escribir con el pulgar.
FULL: Un teclado completo estilo PC.Un teclado completo se comporta como un teclado de PC. Se accede a todos los símbolos directamente presionando las teclas del teclado sin soporte en pantalla ni funciones como el uso de mayúsculas automáticas.
Este tipo de teclado generalmente está diseñado para escribir con dos manos.
SPECIAL_FUNCTION: un teclado que solo se usa para realizar funciones de control del sistema en lugar de escribir.Un teclado de función especial consta únicamente de teclas que no se imprimen, como INICIO y ENCENDIDO, que en realidad no se utilizan para escribir.
Los mapas de caracteres clave Generic.kcm y Virtual.kcm son teclados FULL .
Declaraciones clave
Cada una de las declaraciones de clave consiste en la key de palabra clave seguida de un nombre de código de clave de Android, una llave abierta, un conjunto de propiedades y comportamientos y una llave cerrada.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
Propiedades
Cada propiedad clave establece un mapeo de una clave a un comportamiento. Para que los archivos de mapas 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 está impresa físicamente en la clave, cuando consta de un solo carácter. Este es el valor que devuelve el métodoKeyCharacterMap.getDisplayLabel.number: especifica el comportamiento (carácter que se debe escribir) cuando una vista de texto numérico tiene el foco, como cuando el usuario escribe un número de teléfono.Los teclados compactos a menudo combinan varios símbolos en una sola tecla, de modo que la misma tecla podría usarse para escribir
'1'y'a'o'#'y'q', tal vez. Para estas claves, la propiedadnumberdebe configurarse para indicar qué símbolo debe escribirse 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 (carácter que se debe escribir) cuando no se presionan modificadores.<modificador> o <modificador1>
+<modificador2>+...: Especifica el comportamiento (carácter que se debe escribir) cuando se presiona la tecla y todos los modificadores especificados están activos.Por ejemplo, la propiedad del modificador
shiftespecifica un comportamiento que se aplica cuando se presiona el modificador SHIFT IZQUIERDA o SHIFT DERECHA.De manera similar, la propiedad del modificador
rshift+raltespecifica un comportamiento que se aplica cuando los modificadores SHIFT DERECHA y ALT DERECHA se presionan juntos.
Los siguientes modificadores se reconocen en las propiedades de los modificadores:
-
shift: Se aplica cuando se presiona el modificador SHIFT IZQUIERDA o SHIFT DERECHA. -
lshift: Se aplica cuando se presiona el modificador LEFT SHIFT. -
rshift: Se aplica cuando se presiona el modificador SHIFT DERECHA. -
alt: se aplica cuando se presiona el modificador ALT IZQUIERDA o ALT DERECHA. -
lalt: Se aplica cuando se presiona el modificador IZQUIERDA ALT. -
ralt: Se aplica cuando se presiona el modificador ALT DERECHA. -
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 LEFT META o RIGHT META. -
lmeta: Se aplica cuando se presiona el modificador LEFT META. -
rmeta: Se aplica cuando se presiona el modificador RIGHT META. -
sym: Se aplica cuando se presiona el modificador SYMBOL. -
fn: Se aplica cuando se presiona el modificador FUNCTION. -
capslock: se aplica cuando el modificador BLOQ MAYÚS está bloqueado. -
numlock: se aplica cuando el modificador NUM LOCK está bloqueado. -
scrolllock: Se aplica cuando el modificador SCROLL LOCK está bloqueado.
El orden en el que se enumeran las propiedades es significativo. Al asignar una clave a un comportamiento, el sistema escanea todas las propiedades relevantes en orden y devuelve el último comportamiento aplicable que encontró.
En consecuencia, las propiedades que se especifican más adelante anulan las propiedades que se especifican anteriormente para una clave determinada.
Comportamientos
Cada propiedad se asigna a un comportamiento. El comportamiento más común es escribir un carácter, pero existen otros.
Se reconocen las siguientes conductas:
none: no escriba ningún carácter.Este comportamiento es el predeterminado cuando no se especifica ningún carácter. No especificar
nonees opcional, pero mejora la claridad.'X': escriba el carácter literal especificado.Este comportamiento hace que el carácter especificado se ingrese en la vista de texto enfocado. El carácter literal puede ser cualquier carácter ASCII o una de las siguientes secuencias de escape:
-
'\\': escriba un carácter de barra invertida. -
'\n': escriba un carácter de nueva línea (úselo para ENTRAR/RETORNO). -
'\t': escriba un carácter TAB. -
'\'': Escriba un carácter de apóstrofe. -
'\"': escriba un carácter de comilla. -
'\uXXXX': escriba el carácter Unicode cuyo punto de código viene dado en hexadecimal por XXXX.
-
fallback<nombre del código de clave de Android>: realiza una acción predeterminada si la aplicación no maneja la clave.Este comportamiento hace que el sistema simule una pulsación de tecla diferente cuando una aplicación no maneja la tecla especificada de forma nativa. Se utiliza para admitir el comportamiento predeterminado de nuevas teclas que no todas las aplicaciones saben cómo manejar, como ESCAPE o las teclas del teclado numérico (cuando no se presiona el bloqueo numérico).
Cuando se realiza un comportamiento de respaldo, la aplicación recibirá dos pulsaciones de teclas: una para la clave original y otra para la tecla de respaldo que se seleccionó. Si la aplicación maneja la clave original durante la activación de la clave, entonces el evento de la clave alternativa se cancelará (
KeyEvent.isCanceleddevolverátrue).
El sistema reserva dos caracteres Unicode para realizar funciones especiales:
'\uef00': cuando se realiza este comportamiento, la vista de texto consume y elimina los cuatro caracteres que preceden al cursor, los interpreta como dígitos hexadecimales e inserta el punto de código Unicode correspondiente.'\uef01': cuando se realiza este comportamiento, la vista de texto muestra un cuadro de diálogo de selección de caracteres que contiene varios símbolos.
El sistema reconoce los siguientes caracteres Unicode como combinación de caracteres diacríticos muertos:
-
'\u0300': Acento grave. -
'\u0301': Acento agudo. -
'\u0302': Acento circunflejo. -
'\u0303': Acento tilde. -
'\u0308': Acento con diéresis.
Cuando se escribe una clave muerta seguida de otro carácter, se componen la clave muerta y los siguientes caracteres. Por ejemplo, cuando el usuario escribe una tecla muerta con acento grave seguida de la letra 'a', el resultado es 'à'.
Consulte KeyCharacterMap.getDeadChar para obtener más información sobre el manejo de claves muertas.
Comentarios
Las líneas de comentarios comienzan con '#' y continúan hasta el final de la línea. Como esto:
# 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 tecla presionada y los modificadores presionados actualmente.
MAYÚS + A
Supongamos que el usuario presionó A y SHIFT juntos. El sistema primero localiza 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 escanea las propiedades de primera a última y de izquierda a derecha, ignorando las propiedades label y number , que son especiales.
La primera propiedad encontrada es base . La propiedad base siempre se aplica a una tecla, sin importar qué modificadores se presionen. Básicamente, 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 pulsación de tecla, el sistema toma nota del hecho de que su comportamiento es 'a' (escriba el carácter a ).
Luego, el sistema continúa escaneando propiedades posteriores en caso de que alguna de ellas sea más específica que base y la anula. Encuentra shift que también se aplica al presionar la tecla SHIFT + A. Entonces, el sistema decide ignorar el comportamiento de la propiedad base y elige el comportamiento asociado con la propiedad shift , que es 'A' (escriba el carácter A ).
Luego continúa escaneando la tabla, sin embargo, no se aplican otras propiedades al presionar esta tecla (BLOQ MAYÚS no está bloqueado, no se presiona ninguna tecla CONTROL, no se presiona ninguna tecla ALT ni se presiona ninguna tecla META).
Entonces el comportamiento resultante para la combinación de teclas SHIFT + A es 'A' .
CONTROL + A
Ahora considere lo que sucedería si el usuario presionara A y CONTROL juntos.
Como antes, el sistema escanearía la tabla de propiedades. Notaría que la propiedad base se aplicó pero también continuaría escaneando hasta que finalmente alcanzara la propiedad control . Da la casualidad de que la propiedad control aparece después de base , por lo que su comportamiento anula el comportamiento base .
Entonces el comportamiento resultante para la combinación de teclas CONTROL + A es none .
ESCAPAR
Ahora supongamos que el usuario presionó ESCAPE.
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
Esta vez el sistema obtiene el comportamiento fallback BACK , un comportamiento de reserva. Como no aparece ningún carácter literal, no se escribirá ningún carácter.
Al procesar la clave, el sistema primero entregará KEYCODE_ESCAPE a la aplicación. Si la aplicación no lo maneja, el sistema lo intentará nuevamente, pero esta vez entregará KEYCODE_BACK a la aplicación según lo solicitado por el comportamiento alternativo.
Por lo tanto, las aplicaciones que reconocen y admiten KEYCODE_ESCAPE tienen la oportunidad de manejarlo tal cual, pero otras aplicaciones que no lo hacen pueden realizar la acción alternativa de tratar la clave como si fuera KEYCODE_BACK .
NUMPAD_0 con o sin BLOQ NUM
Las teclas del teclado numérico tienen interpretaciones muy diferentes dependiendo de si la tecla BLOQ NUM está bloqueada.
La siguiente declaración de clave garantiza que KEYCODE_NUMPAD_0 escriba 0 cuando se presiona BLOQ NUM. Cuando no se presiona BLOQ NUM, la clave se entrega a la aplicación como de costumbre y, si no se maneja, se entrega en su lugar la clave alternativa KEYCODE_INSERT .
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
Como podemos ver, las declaraciones de teclas alternativas mejoran en gran medida la compatibilidad con aplicaciones más antiguas que no reconocen o no admiten directamente todas las teclas que están presentes en un teclado estilo PC completo.
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'
}
Panel de juego
# 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 usando una sintaxis muy diferente y se compilaba en un formato de archivo binario ( .kcm.bin ) en el momento de la compilación.
Aunque el nuevo formato utiliza 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 mapas de caracteres clave de Android deben utilizar la nueva sintaxis y el formato de archivo de texto sin formato que se describe en este documento. La sintaxis antigua no es compatible y el sistema no reconoce los archivos .kcm.bin antiguos.
Nota de idioma
Actualmente, Android no admite teclados multilingües. Además, el mapa de caracteres clave genérico incorporado asume una distribución de teclado en inglés de EE. UU.
Se recomienda a los OEM que proporcionen mapas de caracteres clave personalizados para sus teclados si están diseñados para otros idiomas.
Las versiones futuras de Android pueden ofrecer una mejor compatibilidad con teclados multilingües o diseños de teclado seleccionables por el usuario.
Validación
Asegúrese de validar sus archivos de mapas de caracteres clave utilizando la herramienta Validar mapas de teclas .