Os arquivos de mapa de caracteres de teclas (arquivos .kcm) são responsáveis por mapear combinações
de códigos de teclas do Android com modificadores para caracteres Unicode.
Os arquivos de layout de teclas específicos do dispositivo são obrigatórios para todos os dispositivos de entrada internos (integrados) que têm teclas, mesmo que apenas para informar ao sistema que o dispositivo é apenas para fins especiais (não um teclado completo).
Os arquivos de layout de teclas específicos do dispositivo são opcionais para teclados externos e muitas vezes não são necessários. O sistema fornece um mapa de caracteres de tecla genérico adequado para muitos teclados externos.
Se nenhum arquivo de layout de chave específico do dispositivo estiver disponível, o sistema escolherá um padrão.
Local
Os arquivos de mapeamento de caracteres de teclas são localizados pelo fornecedor USB, pelo ID do produto (e, opcionalmente, da versão) ou pelo nome do dispositivo de entrada.
Os caminhos a seguir são consultados em ordem.
/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
Ao criar um caminho de arquivo que contém o nome do dispositivo, todos os caracteres no nome do dispositivo, exceto "0"-"9", "a"-"z", "A"-"Z", "-" ou "_", são substituídos por "_".
Arquivo de mapa de caracteres de chave genérica
O sistema fornece um arquivo de mapeamento de caracteres de tecla integrado especial chamado Generic.kcm.
Esse mapa de caracteres de tecla tem como objetivo oferecer suporte a vários teclados externos
padrão.
Não modifique o mapa de caracteres de chave genérica.
Arquivo de mapa de caracteres de chave virtual
O sistema fornece um arquivo de mapeamento de caracteres de tecla integrado especial chamado Virtual.kcm
que é usado pelos dispositivos de teclado virtual.
O dispositivo de teclado virtual é um dispositivo de entrada sintética cujo ID é -1
(consulte KeyCharacterMap.VIRTUAL_KEYBOARD). Ele está presente em todos os dispositivos Android
a partir do Android Honeycomb 3.0. O objetivo do dispositivo de teclado virtual
é fornecer um dispositivo de entrada integrado conhecido que possa ser usado para injetar
teclados em aplicativos pelo IME ou pela instrumentação de teste, mesmo
para dispositivos que não têm teclados integrados.
O teclado virtual tem um layout QWERTY completo idêntico em todos os dispositivos. Isso permite que os aplicativos injetem teclas usando o dispositivo de teclado virtual e sempre recebam os mesmos resultados.
Não modifique o mapa de caracteres do teclado virtual.
Sintaxe
Um arquivo de mapeamento de caracteres de tecla é um arquivo de texto simples que consiste em uma declaração de tipo de teclado e um conjunto de declarações de teclas.
Declaração do tipo de teclado
Uma declaração de tipo de teclado descreve o comportamento geral do teclado. Um arquivo de mapeamento de caracteres precisa conter uma declaração de tipo de teclado. Para maior clareza, ele geralmente é colocado na parte de cima do arquivo.
type FULL
Os seguintes tipos de teclado são reconhecidos:
-
NUMERIC: um teclado numérico (12 teclas).Um teclado numérico oferece suporte à entrada de texto usando uma abordagem de vários toques. Talvez seja necessário tocar várias vezes em uma tecla para gerar a letra ou o símbolo desejado.
Esse tipo de teclado geralmente é projetado para digitação com o polegar.
Corresponde a
KeyCharacterMap.NUMERIC. -
PREDICTIVE: um teclado com todas as letras, mas com mais de uma letra por tecla.Esse tipo de teclado geralmente é projetado para digitação com o polegar.
Corresponde a
KeyCharacterMap.PREDICTIVE. -
ALPHA: um teclado com todas as letras e talvez alguns números.Um teclado alfabético oferece suporte à entrada de texto diretamente, mas pode ter um layout condensado com um formato pequeno. Ao contrário de um teclado
FULL, alguns símbolos só podem ser acessados usando seletores de caracteres especiais na tela. Além disso, para melhorar a velocidade e a precisão da digitação, o framework oferece recursos especiais para teclados alfabéticos, como a capitalização automática e as teclas SHIFT e ALT alternadas / bloqueadas.Esse tipo de teclado geralmente é projetado para digitação com o polegar.
-
FULL: um teclado completo de estilo PC.Um teclado completo se comporta como um teclado de PC. Todos os símbolos são acessados diretamente pressionando teclas no teclado sem suporte na tela ou recursos, como a capitalização automática.
Esse tipo de teclado geralmente é projetado para digitação com as duas mãos.
-
SPECIAL_FUNCTION: um teclado usado apenas para executar funções de controle do sistema em vez de digitar.Um teclado de função especial consiste apenas em teclas não de impressão, como HOME e POWER, que não são usadas para digitação.
Os mapas de caracteres das teclas Generic.kcm e Virtual.kcm são teclados FULL.
Declarações de chave
Cada declaração de chave consiste na palavra-chave key seguida por um nome de código de chave do Android, uma chave de abertura, um conjunto de propriedades e comportamentos e uma chave de fechamento.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
Propriedades
Cada propriedade de chave estabelece um mapeamento de uma chave para um comportamento. Para tornar os arquivos de mapa de caracteres de chave mais compactos, várias propriedades podem ser mapeadas para o mesmo comportamento separando-as com uma vírgula.
No exemplo acima, a propriedade label recebe o comportamento 'A'.
Da mesma forma, as propriedades ctrl, alt e meta são atribuídas simultaneamente
ao comportamento none.
As seguintes propriedades são reconhecidas:
-
label: especifica o rótulo impresso fisicamente na chave, quando ele consiste em um único caractere. Esse é o valor retornado pelo métodoKeyCharacterMap.getDisplayLabel. -
number: especifica o comportamento (caractere que precisa ser digitado) quando uma visualização de texto numérico tem o foco, como quando o usuário está digitando um número de telefone.Os teclados compactos geralmente combinam vários símbolos em uma única tecla, de modo que a mesma tecla possa ser usada para digitar
'1'e'a'ou'#'e'q'. Para essas chaves, a propriedadenumberprecisa ser definida para indicar qual símbolo precisa ser digitado em um contexto numérico, se houver.Alguns símbolos "numéricos" típicos são os dígitos
'0'a'9','#','+','(',')',','e'.'. -
base: especifica o comportamento (caractere que precisa ser digitado) quando nenhum modificador é pressionado. -
<modifier> ou <modifier1>
+<modifier2>+...: especifica o comportamento (caractere que precisa ser digitado) quando a tecla é pressionada e todos os modificadores especificados estão ativos.Por exemplo, a propriedade modificadora
shiftespecifica um comportamento que é aplicado quando o modificador SHIFT ESQUERDO ou SHIFT DIREITO é pressionado.Da mesma forma, a propriedade modificadora
rshift+raltespecifica um comportamento que é aplicado quando os modificadores SHIFT DIREITO e ALT DIREITO são pressionados juntos.
Os seguintes modificadores são reconhecidos nas propriedades de modificador:
shift: é aplicado quando o modificador SHIFT ESQUERDO ou SHIFT DIREITO é pressionado.lshift: é aplicado quando o modificador SHIFT ESQUERDO é pressionado.rshift: é aplicado quando o modificador SHIFT DIREITO é pressionado.alt: é aplicado quando o modificador ALT ESQUERDO ou ALT DIREITO é pressionado.lalt: é aplicado quando o modificador ALT ESQUERDO é pressionado.ralt: é aplicado quando o modificador ALT DIREITO é pressionado.ctrl: é aplicado quando o modificador CTRL ESQUERDO ou CTRL DIREITO é pressionado.lctrl: é aplicado quando o modificador CTRL ESQUERDO é pressionado.rctrl: é aplicado quando o modificador CONTROLE DIREITO é pressionado.meta: é aplicado quando o modificador META ESQUERDO ou META DIREITO é pressionado.lmeta: é aplicado quando o modificador META ESQUERDO é pressionado.rmeta: é aplicado quando o modificador META DIREITO é pressionado.sym: é aplicado quando o modificador SYMBOL é pressionado.fn: é aplicado quando o modificador FUNCTION é pressionado.capslock: é aplicado quando o modificador CAPS LOCK está bloqueado.numlock: é aplicado quando o modificador NUM LOCK está bloqueado.scrolllock: é aplicado quando o modificador SCROLL LOCK está bloqueado.
A ordem em que as propriedades são listadas é significativa. Ao mapear uma chave para um comportamento, o sistema verifica todas as propriedades relevantes na ordem e retorna o último comportamento aplicável encontrado.
Consequentemente, as propriedades especificadas mais tarde substituem as especificadas anteriormente para uma determinada chave.
Comportamentos
Cada propriedade é mapeada para um comportamento. O comportamento mais comum é digitar um caractere, mas há outros.
Os seguintes comportamentos são reconhecidos:
-
none: não digite um caractere.Esse comportamento é o padrão quando nenhum caractere é especificado. Especificar
noneé opcional, mas melhora a clareza. -
'X': digite o literal de caractere especificado.Esse comportamento faz com que o caractere especificado seja inserido na visualização de texto em foco. O literal de caractere pode ser qualquer caractere ASCII ou uma das seguintes sequências de escape:
'\\': digite um caractere de barra invertida.'\n': digite um caractere de nova linha (use para ENTER / RETURN).'\t': digite um caractere TAB.'\'': digite um caractere de apóstrofo.'\"': digite um caractere de aspas.'\uXXXX': digite o caractere Unicode cujo ponto de código é fornecido em hexadecimal por XXXX.
-
fallback<Android key code name>: realiza uma ação padrão se a chave não for processada pelo aplicativo.Esse comportamento faz com que o sistema simule uma tecla diferente quando um aplicativo não processa a tecla especificada de forma nativa. Ele é usado para oferecer suporte ao comportamento padrão para novas teclas que nem todos os aplicativos sabem como processar, como ESCAPE ou teclas do teclado numérico (quando o NumLock não está pressionado).
Quando um comportamento alternativo é executado, o aplicativo recebe duas pressões de tecla: uma para a tecla original e outra para a tecla alternativa selecionada. Se o aplicativo processar a chave original durante a ativação da chave, o evento de chave de fallback será cancelado (
KeyEvent.isCanceledvai retornartrue).
O sistema reserva dois caracteres Unicode para executar funções especiais:
-
'\uef00': quando esse comportamento é realizado, a visualização de texto consome e remove os quatro caracteres que precedem o cursor, os interpreta como dígitos hexadecimais e insere o ponto de código Unicode correspondente. -
'\uef01': quando esse comportamento é realizado, a visualização de texto mostra uma caixa de diálogo do seletor de caracteres que contém símbolos diversos.
O sistema reconhece os seguintes caracteres Unicode como caracteres de tecla diacríticos diacríticos:
'\u0300': acento grave.'\u0301': acento agudo.'\u0302': acento circunflexo.'\u0303': acento til.'\u0308': acento umlaut.
Quando uma tecla morta é digitada seguida por outro caractere, a tecla morta e os caracteres seguintes são compostos. Por exemplo, quando o usuário digita uma tecla morta de acento grave seguida da letra "a", o resultado é "à".
Consulte KeyCharacterMap.getDeadChar para mais informações sobre o tratamento de teclas inativas.
Comentários
As linhas de comentário começam com '#' e continuam até o final da linha. Curta:
# A comment!
As linhas em branco são ignoradas.
Como as combinações de teclas são mapeadas para comportamentos
Quando o usuário pressiona uma tecla, o sistema procura o comportamento associado à combinação dessa tecla e dos modificadores pressionados no momento.
SHIFT + A
Suponha que o usuário tenha pressionado A e SHIFT ao mesmo tempo. O sistema primeiro localiza
o conjunto de propriedades e comportamentos associados a KEYCODE_A.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
O sistema verifica as propriedades da primeira à última e da esquerda para a direita, ignorando
as propriedades label e number, que são especiais.
A primeira propriedade encontrada é base. A propriedade base sempre se aplica a
uma chave, não importa quais modificadores sejam pressionados. Ele especifica o comportamento padrão
da chave, a menos que seja substituído pelas propriedades a seguir.
Como a propriedade base se aplica a essa tecla pressionada, o sistema registra
que o comportamento dela é 'a' (digite o caractere a).
O sistema continua a verificar as propriedades subsequentes, caso alguma delas
seja mais específica que base e a substitua. Ele encontra shift, que
também se aplica à tecla SHIFT + A. Então, o sistema decide ignorar
o comportamento da propriedade base e escolhe o comportamento associado à
propriedade shift, que é 'A' (digite o caractere A).
Em seguida, ele continua a verificar a tabela, mas nenhuma outra propriedade se aplica a essa pressão de tecla (o CAPS LOCK não está ativado, nem a tecla CONTROL, nem a tecla ALT e nem a tecla META).
Portanto, o comportamento resultante da combinação de teclas SHIFT + A é 'A'.
CTRL + A
Agora considere o que aconteceria se o usuário pressionasse A e CONTROL juntos.
Como antes, o sistema vai verificar a tabela de propriedades. Ele notaria
que a propriedade base foi aplicada, mas também continuaria a verificar até
chegar à propriedade control. A propriedade control
aparece depois de base, então o comportamento dela substitui o comportamento de base.
O comportamento resultante da combinação de teclas CONTROL + A é none.
ESCAPE
Agora, suponha que o usuário tenha pressionado ESCAPE.
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
Dessa vez, o sistema recebe o comportamento fallback BACK, um comportamento alternativo.
Como nenhum caractere literal aparece, nenhum caractere será digitado.
Ao processar a chave, o sistema vai primeiro entregar KEYCODE_ESCAPE ao
app. Se o aplicativo não o processar, o sistema tentará
de novo, mas dessa vez ele vai enviar KEYCODE_BACK para o aplicativo, conforme
solicitado pelo comportamento alternativo.
Assim, os aplicativos que reconhecem e oferecem suporte a KEYCODE_ESCAPE têm a
oportunidade de processá-la como está, mas outros aplicativos que não oferecem suporte a ela podem
realizar a ação de fallback de tratar a chave como se fosse KEYCODE_BACK.
NUMPAD_0 com ou sem BLOQUEIO NUM
As teclas do teclado numérico têm interpretações muito diferentes, dependendo se a tecla NUM LOCK está bloqueada.
A declaração de chave a seguir garante que KEYCODE_NUMPAD_0 digite 0
quando NUM LOCK for pressionado. Quando o NUM LOCK não é pressionado, a tecla é enviada
ao aplicativo normalmente. Se ela não for processada, a tecla
KEYCODE_INSERT será enviada.
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
Como podemos ver, as declarações de chave de fallback melhoram muito a compatibilidade com aplicativos mais antigos que não reconhecem ou oferecem suporte direto a todas as teclas presentes em um teclado completo estilo PC.
Exemplos
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
}
Observação sobre compatibilidade
Antes do Android Honeycomb 3.0, o mapa de caracteres de chave do Android era especificado
usando uma sintaxe muito diferente e era compilado em um formato de arquivo binário
(.kcm.bin) no momento do build.
Embora o novo formato use a mesma extensão .kcm, a sintaxe é bastante
diferente (e muito mais poderosa).
A partir do Android Honeycomb 3.0, todos os arquivos de mapa de caracteres de chave do Android precisam usar
a nova sintaxe e o formato de arquivo de texto simples descritos neste documento.
A sintaxe antiga não é compatível, e os arquivos .kcm.bin antigos não são reconhecidos
pelo sistema.
Observação sobre o idioma
No momento, o Android não oferece suporte a teclados multilíngues. Além disso, o mapa de caracteres de tecla genérico integrado assume um layout de teclado em inglês dos EUA.
Recomendamos que os OEMs forneçam mapas de caracteres personalizados para os teclados se eles forem projetados para outros idiomas.
Versões futuras do Android podem oferecer suporte melhor para teclados multilíngues ou layouts de teclado selecionáveis pelo usuário.
Validação
Valide seus arquivos de mapa de caracteres usando a ferramenta Validar mapas de teclado.