Los archivos de mapas 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 necesarios para todos los dispositivos de entrada internos (integrados) que tienen teclas, aunque solo sea para indicarle al sistema que el dispositivo es solo para fines especiales (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 ningún archivo de distribución de teclas específico del dispositivo disponible, el sistema elegirá un valor predeterminado en su lugar.
Ubicación
Los archivos de mapa de caracteres clave se ubican por proveedor de USB, ID de producto (y versión opcional) 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 sustituyen por '_'.
Archivo de mapa de caracteres clave genérico
El sistema proporciona un archivo de mapa de caracteres clave incorporado 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 de clave virtual
El sistema proporciona un archivo de mapa de caracteres clave integrado especial denominado Virtual.kcm que utilizan los dispositivos de teclado virtual.
El dispositivo de teclado virtual es un dispositivo de entrada sintético cuyo id es -1 (ver 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 incorporado conocido que se puede usar para inyectar pulsaciones de teclas en aplicaciones mediante el IME o mediante instrumentación de prueba, incluso para dispositivos que no tienen teclados incorporados.
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 usando el dispositivo de teclado virtual y siempre obtengan los mismos resultados.
¡No modifique el mapa de caracteres de la tecla 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, a menudo se coloca 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 utilizando un enfoque de múltiples toques. Puede ser necesario tocar una tecla varias veces para generar la letra o el 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 la precisión de la escritura, el marco proporciona funciones especiales para teclados alfabéticos, como el uso automático de mayúsculas y las teclas SHIFT y ALT alternadas o bloqueadas.Este tipo de teclado generalmente está diseñado para escribir con el pulgar.
FULL: Un teclado estilo PC completo.Un teclado completo se comporta como un teclado de PC. Se accede a todos los símbolos directamente presionando las teclas en el teclado sin soporte en pantalla o posibilidades como el uso automático de mayúsculas.
Este tipo de teclado generalmente está diseñado para escribir con las 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 usan para escribir.
Los mapas de caracteres clave Generic.kcm y Virtual.kcm son teclados FULL .
Declaraciones clave
Cada una de las declaraciones de clave consta de la palabra key 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 de la 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 tecla, cuando consta de un solo carácter. Este es el valor que devuelve el métodoKeyCharacterMap.getDisplayLabel.number: especifica el comportamiento (carácter que debe escribirse) cuando una vista de texto numérico tiene el foco, como cuando el usuario está escribiendo un número de teléfono.Los teclados compactos a menudo combinan múltiples símbolos en una sola tecla, de modo que la misma tecla podría usarse para escribir
'1'y'a'o'#'y'q', quizás. Para estas teclas, la propiedad denumberdebe establecerse 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
'0'al'9','#','+','(',')',','y'.'.base: especifica el comportamiento (carácter que debe escribirse) cuando no se presiona ningún modificador.<modificador> o <modificador1>
+<modificador2>+...: especifica el comportamiento (carácter que debe escribirse) cuando se presiona la tecla y todos los modificadores especificados están activos.Por ejemplo, el
shiftde propiedad del modificador especifica un comportamiento que se aplica cuando se presiona el modificador MAYÚS IZQUIERDA o MAYÚS DERECHA.De manera similar, la propiedad del modificador
rshift+raltespecifica un comportamiento que se aplica cuando los modificadores RIGHT SHIFT y RIGHT ALT se presionan juntos.
Los siguientes modificadores se reconocen en las propiedades del modificador:
-
shift: Se aplica cuando se presiona el modificador LEFT SHIFT o RIGHT SHIFT. -
lshift: se aplica cuando se presiona el modificador LEFT SHIFT. -
rshift: se aplica cuando se presiona el modificador RIGHT SHIFT. -
alt: se aplica cuando se presiona el modificador ALT IZQUIERDO o ALT DERECHO. -
lalt: Se aplica cuando se presiona el modificador LEFT ALT. -
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 LEFT CONTROL. -
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 BLOQ NUM está bloqueado. -
scrolllock: se aplica cuando el modificador SCROLL LOCK está bloqueado.
El orden en 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 antes para una clave dada.
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 escriba un carácter.Este comportamiento es el predeterminado cuando no se especifica ningún carácter. 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 enfocada. 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 ENTER/RETURN). -
'\t': escriba un carácter TAB. -
'\'': Escriba un carácter de apóstrofe. -
'\"': escriba un carácter de comillas. -
'\uXXXX': escriba el carácter Unicode cuyo punto de código se proporciona en hexadecimal por XXXX.
-
fallback<nombre del código de la 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 las teclas nuevas que no todas las aplicaciones saben cómo manejar, como ESCAPE o las teclas del teclado numérico (cuando no se presiona bloq num).
Cuando se realiza un comportamiento alternativo, la aplicación recibirá dos pulsaciones de teclas: una para la tecla original y otra para la tecla alternativa que se seleccionó. Si la aplicación maneja la clave original durante la activación de la clave, se cancelará el evento de la clave alternativa (
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 una combinación de caracteres clave muertos diacríticos:
-
'\u0300': Acento grave. -
'\u0301': Acento agudo. -
'\u0302': Acento circunflejo. -
'\u0303': Acento tilde. -
'\u0308': Acento diéresis.
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 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!
Las líneas en blanco se ignoran.
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 al mismo tiempo. El sistema localiza primero 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 la primera a la última y de izquierda a derecha, ignorando las propiedades de 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 las propiedades subsiguientes 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 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 a esta tecla presionada (BLOQ MAYÚS no está bloqueado, no se presiona la tecla CONTROL, no se presiona la tecla ALT y no se presiona la 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 se aplicó la propiedad base pero también continuaría escaneando hasta que finalmente alcanzara la propiedad de control . Da la casualidad de que la propiedad de 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 suponga 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 fallback. Dado que 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 volverá a intentarlo, pero esta vez entregará KEYCODE_BACK a la aplicación según lo solicite el comportamiento de reserva.
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 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 la tecla alternativa KEYCODE_INSERT en su lugar.
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
Como podemos ver, las declaraciones de teclas de reserva mejoran en gran medida la compatibilidad con aplicaciones más antiguas que no reconocen o 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'
}
Almohadilla 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 con 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 usa la misma extensión .kcm , la sintaxis es bastante diferente (y mucho más poderosa).
A partir de Android Honeycomb 3.0, todos los archivos de mapas 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. La sintaxis anterior 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 disposición de teclado en inglés estadounidense.
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 proporcionar 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 con la herramienta Validar mapas de teclas .