Os arquivos de mapeamento de caracteres principais (arquivos .kcm) são responsáveis por combinações de mapeamento
de códigos de tecla do Android com modificadores para caracteres Unicode.
Os arquivos de layout de chave específicos do dispositivo são obrigatórios para todos os componentes internos (integrados) dispositivos de entrada com chaves, seja apenas para informar ao sistema que o dispositivo é apenas para fins especiais (não é um teclado completo).
Os arquivos de layout de tecla específicos do dispositivo são opcionais para teclados externos. muitas vezes não são necessários. O sistema fornece um mapa genérico de principais caracteres adequado para muitos teclados externos.
Se nenhum arquivo de layout de chave específico do dispositivo estiver disponível, o sistema escolha um padrão.
Local
Os arquivos de mapa de caracteres principais são localizados por fornecedor USB, produto (e, opcionalmente, 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 construir um caminho de arquivo que contém o nome do dispositivo, todos os caracteres no nome do dispositivo diferente de "0'-'9', 'a'-'z', 'A'-'Z', '-' ou "_" são substituídos por "_".
Arquivo genérico de mapeamento de caracteres de teclas
O sistema fornece um arquivo especial integrado de mapeamento de caracteres de teclas chamado Generic.kcm.
Esse mapa de caracteres chave tem o objetivo de dar suporte a várias ferramentas
teclados.
Não modifique o mapa genérico de caracteres de teclas.
Arquivo de mapeamento de caracteres de tecla virtual
O sistema fornece um arquivo especial integrado de mapeamento de caracteres de teclas chamado Virtual.kcm.
usada pelos dispositivos de teclado virtual.
O teclado virtual é um dispositivo de entrada sintético com ID -1
Consulte KeyCharacterMap.VIRTUAL_KEYBOARD. Está presente em todos os dispositivos Android
a partir do Android Honeycomb 3.0. A finalidade do dispositivo de teclado virtual
é fornecer um dispositivo de entrada integrado conhecido que pode ser usado para injetar
teclas em aplicativos pelo IME ou por instrumentação de teste, mesmo
para dispositivos que não têm teclados integrados.
O teclado virtual tem um layout QWERTY completo, que é o igual em todos os dispositivos. Isso permite que os aplicativos injetem usando o dispositivo de teclado virtual e sempre obter os mesmos resultados.
Não modifique o mapa de caracteres da chave virtual.
Sintaxe
Um arquivo-chave de mapa de caracteres é um arquivo de texto simples que consiste em um tipo de teclado e um conjunto de declarações de chaves.
Declaração do tipo de teclado
Uma declaração de tipo de teclado descreve o comportamento geral do teclado. Um arquivo de mapa de caracteres precisa conter uma declaração de tipo de teclado. Para fins de esclarecimento, ele geralmente é colocado no topo do arquivo.
type FULL
Os seguintes tipos de teclado são reconhecidos:
-
NUMERIC: um teclado numérico (de 12 teclas).Um teclado numérico oferece suporte à entrada de texto usando uma abordagem de vários toques. Pode ser necessário tocar em uma tecla várias vezes 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 permite a entrada de texto diretamente, mas pode ter uma o layout com um formato pequeno. Ao contrário de um teclado
FULL, alguns símbolos só podem ser acessíveis usando seletores de caracteres especiais na tela. Além disso, para melhorar a velocidade e a precisão da digitação, o framework oferece affordances especiais para teclados alfabéticos, como 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 no 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 affordances, como como capitalização automática.
Esse tipo de teclado geralmente é projetado para a digitação com duas mãos.
-
SPECIAL_FUNCTION: um teclado usado apenas para executar funções de controle do sistema. e não só para digitar.Um teclado de função especial consiste apenas de teclas não imprimíveis, como HOME e POWER que não são realmente usados para digitar.
Os mapas de caracteres de teclas Generic.kcm e Virtual.kcm são teclados FULL.
Declarações de chaves
Cada declaração de chave consiste na palavra-chave key seguida por um código de tecla do Android.
nome, uma chave aberta, 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 arquivos de mapeamento de caracteres mais compactos, várias propriedades podem ser mapeadas para o mesmo comportamento, separando-os 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
o comportamento none.
As seguintes propriedades são reconhecidas:
-
label: especifica o rótulo que está fisicamente impresso na chave, quando ela consiste em um único caractere. Este é o valor retornado pelo o métodoKeyCharacterMap.getDisplayLabel. -
number: especifica o comportamento (caractere que deve ser digitado) quando um valor numérico visualização de texto em foco, por exemplo, quando o usuário está digitando um número de telefone.Teclados compactos geralmente combinam vários símbolos em uma única tecla, de modo que a mesma chave pode ser usada para digitar
'1'e'a'ou'#'e'q', talvez. Para essas chaves, a propriedadenumberprecisa ser definida para indicar qual símbolo precisa ser digitado em um contexto numérico, se houver.Alguns valores "numéricos" símbolos são dígitos de
'0'a'9','#','+''(',')',','e'.'. -
base: especifica o comportamento (caractere que precisa ser digitado) quando nenhum modificador é usado. são pressionados. -
<modificador> ou <modifier1>
+<modifier2>+...: especifica o comportamento (caractere que deve ser digitado) quando a tecla é pressionada, e todas as os modificadores especificados estiverem ativos.Por exemplo, a propriedade modificadora
shiftespecifica um comportamento que se aplica quando se o modificador LEFT SHIFT ou RIGHT SHIFT for pressionado.Da mesma forma, a propriedade modificadora
rshift+raltespecifica um comportamento que se aplica quando os modificadores RIGHT SHIFT e RIGHT ALT são pressionados juntos.
Os seguintes modificadores são reconhecidos nas propriedades deles:
shift: aplica-se quando o modificador LEFT SHIFT ou RIGHT SHIFT é pressionado.lshift: é aplicado quando o modificador LEFT SHIFT é pressionado.rshift: é aplicado quando o modificador RIGHT SHIFT é pressionado.alt: aplica-se quando o modificador LEFT ALT ou RIGHT ALT é pressionado.lalt: é aplicado quando o modificador LEFT ALT é pressionado.ralt: é aplicado quando o modificador RIGHT ALT é pressionado.ctrl: aplica-se quando o modificador LEFT CONTROL ou RIGHT CONTROL é pressionado.lctrl: aplica-se quando o modificador LEFT CONTROL é pressionado.rctrl: é aplicado quando o modificador RIGHT CONTROL é pressionado.meta: aplica-se quando o modificador LEFT META ou RIGHT META é pressionado.lmeta: é aplicado quando o modificador LEFT META é pressionado.rmeta: é aplicado quando o modificador RIGHT META é pressionado.sym: aplica-se 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 é importante. Ao mapear uma chave para um comportamento, o sistema verifica todas as propriedades relevantes em ordem e retorna a última o comportamento aplicável encontrado.
Consequentemente, as propriedades especificadas posteriormente substituem aquelas que são especificado 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 nenhum caractere.Esse é o comportamento padrão quando nenhum caractere é especificado. Como especificar
noneé opcional, mas melhora a clareza. -
'X': digite o literal de caractere especificado.Esse comportamento faz com que o caractere especificado seja inserido no campo em foco visualização de texto. O caractere literal 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 apóstrofo.'\"': digite um caractere de aspas.'\uXXXX': digite o caractere Unicode cujo ponto de código é fornecido em hexadecimal por XXXX.
-
fallback<Nome do código da tecla do Android>: realiza uma ação padrão se a tecla não estiver gerenciados pelo aplicativo.Esse comportamento faz com que o sistema simule um pressionamento de tecla diferente quando um aplicativo não processa a chave especificada nativamente. Ele é usado para oferecer suporte ao comportamento padrão novas chaves que nem todos os aplicativos sabem lidar, como ESCAPE ou teclas numéricas (quando o numlock não é pressionado).
Quando um comportamento de substituição é executado, o aplicativo recebe dois pressionamentos de tecla: uma para a chave original e outra para a chave substituta selecionada. Se o aplicativo manipular a chave original durante o pressionamento da tecla, a chave substituta o evento será cancelado (
KeyEvent.isCanceledretornarátrue).
O sistema reserva dois caracteres Unicode para executar funções especiais:
-
'\uef00': quando esse comportamento é executado, a visualização de texto consome e remove o quatro caracteres anteriores ao cursor, interpreta-os como dígitos hexadecimais e insere o ponto de código Unicode correspondente. -
'\uef01': quando esse comportamento é executado, 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 combinações diacríticas mortas caracteres-chave:
'\u0300': acento grave.'\u0301': acento agudo.'\u0302': acento circunflexo.'\u0303': acento til.'\u0308': acento trema.
Quando uma chave inativa é digitada seguida por outro caractere, a chave inativa e o seguinte são compostos. Por exemplo, quando o usuário digita um acento grave morto seguida pela letra 'a', o resultado é 'à'.
Consulte KeyCharacterMap.getDeadChar para mais informações sobre como processar teclas inativas.
Comentários
As linhas de comentários começam com "'#'" e continuar até o fim 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 ao combinando essa tecla e os modificadores pressionados no momento.
SHIFT + A
Suponha que o usuário pressionou A e SHIFT ao mesmo tempo. Primeiro, o sistema 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 tecla, independentemente de quais modificadores forem pressionados. Ele especifica o padrão
comportamento da chave, a menos que ela seja substituída pelas seguintes propriedades.
Como a propriedade base se aplica a esse pressionamento de tecla, o sistema anota
de que o comportamento dele é 'a' (digite o caractere a).
O sistema continua a verificar as propriedades subsequentes para verificar se alguma delas
são mais específicas do que base e vão substitui-las. Ela encontra shift, que
também se aplica ao pressionar SHIFT + A. Então, o sistema decide ignorar
o comportamento da propriedade base e escolhe o comportamento associado à
a propriedade shift, que é 'A' (digite o caractere A).
Em seguida, ele continua verificando a tabela, mas nenhuma outra propriedade se aplica a isso. pressionamento de tecla (CAPS LOCK não bloqueado, nenhuma tecla CONTROL está pressionada, nenhuma delas a tecla ALT é pressionada e nenhuma tecla META é pressionada).
Assim, o comportamento resultante para a combinação de teclas SHIFT + A será 'A'.
CONTROLE + A
Agora, considere o que aconteceria se o usuário pressionasse A e CONTROL ao mesmo tempo.
Como antes, o sistema verifica a tabela de propriedades. Ele notaria
que a propriedade base aplicou, mas também continuaria verificando até
por fim, ele chegou à propriedade control. Nesse caso, o control
aparece depois de base, então seu comportamento substitui o comportamento de base.
Assim, o comportamento resultante para a 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
}
Desta vez, o sistema recebe o comportamento fallback BACK, um comportamento substituto.
Como nenhum literal de caractere aparece, nenhum caractere será digitado.
Ao processar a chave, o sistema primeiro vai entregar KEYCODE_ESCAPE para o
para o aplicativo. Se o aplicativo não lidar com isso, o sistema tentará
novamente, mas desta vez entregará KEYCODE_BACK ao aplicativo como
solicitado pelo comportamento substituto.
Portanto, os aplicativos que reconhecem e oferecem suporte a KEYCODE_ESCAPE têm o
oportunidade de lidar com ele como está, mas outros aplicativos que não conseguem
execute a ação substituta de tratar a chave como se ela fosse KEYCODE_BACK.
NUMPAD_0 com ou sem NUM LOCK
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 é pressionada. Quando NUM LOCK não é pressionada, a tecla é entregue.
para o aplicativo como de costume e, se não for tratado, o substituto
a chave KEYCODE_INSERT será entregue.
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
Como podemos ver, as declarações de chaves substitutas melhoram muito a compatibilidade com aplicativos mais antigos que não reconhecem ou não dão suporte direto a todas as chaves que estão presentes em um teclado estilo PC completo.
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 chave do Android era especificado
usando uma sintaxe muito diferente e foi compilado em um formato de arquivo binário
(.kcm.bin) no tempo de build.
Embora o novo formato use a mesma extensão .kcm, a sintaxe é bem parecida
diferente (e muito mais eficiente).
A partir do Android Honeycomb 3.0, todos os arquivos principais de mapeamento de caracteres do Android precisarão 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
Atualmente, o Android não oferece suporte a teclados multilíngues. Além disso, o um mapa genérico de caracteres de teclas integrado adota um layout de teclado em inglês americano.
Recomendamos que OEMs ofereçam mapas de caracteres de teclas personalizados para os teclados caso tenham sido projetados para outros idiomas.
Versões futuras do Android poderão oferecer melhor suporte a teclados multilíngues ou layouts de teclado selecionáveis pelo usuário.
Validação
Valide seus arquivos de mapeamento de caracteres principais usando o Ferramenta Validate Keymaps.