Esta página foi traduzida pela API Cloud Translation.

Arquivos de mapa de caracteres principais

Os arquivos de mapa de caracteres-chave (arquivos .kcm ) são responsáveis por mapear combinações de códigos-chave do Android com modificadores para caracteres Unicode.

Arquivos de layout de teclas específicos do dispositivo são necessários para todos os dispositivos de entrada internos (integrados) que possuem teclas, 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 geralmente nem são necessários. O sistema fornece um mapa de caracteres de teclas genérico adequado para muitos teclados externos.

Se nenhum arquivo de layout de teclas específico do dispositivo estiver disponível, o sistema escolherá um padrão.

Localização

Os arquivos de mapa de caracteres principais estão localizados por fornecedor USB, ID do produto (e opcionalmente versão) ou pelo nome do dispositivo de entrada.

Os seguintes caminhos 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 diferentes de '0'-'9', 'a'-'z', 'A'-'Z', '-' ou '_' são substituídos por '_'.

Arquivo de mapa de caracteres chave genérico

O sistema fornece um arquivo especial de mapa de caracteres-chave integrado chamado Generic.kcm . Este mapa de caracteres principais destina-se a oferecer suporte a uma variedade de teclados externos padrão.

Não modifique o mapa genérico de caracteres-chave!

Arquivo de mapa de caracteres-chave virtual

O sistema fornece um arquivo de mapa de caracteres de teclas integrado especial chamado Virtual.kcm que é usado pelos dispositivos de teclado virtual.

O dispositivo de teclado virtual é um dispositivo de entrada sintético cujo id é -1 (consulte KeyCharacterMap.VIRTUAL_KEYBOARD ). Está presente em todos os dispositivos Android começando com Android Honeycomb 3.0. O objetivo do dispositivo de teclado virtual é fornecer um dispositivo de entrada integrado conhecido que possa ser usado para injetar pressionamentos de teclas em aplicativos pelo IME ou por instrumentação de teste, mesmo para dispositivos que não possuem teclados integrados.

Presume-se que o teclado virtual tenha um layout QWERTY completo, igual em todos os dispositivos. Isso possibilita que os aplicativos injetem pressionamentos de tecla usando o dispositivo de teclado virtual e sempre obtenham os mesmos resultados.

Não modifique o mapa de caracteres-chave virtual!

Sintaxe

Um arquivo de mapa de caracteres principais é 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 de tipo de teclado

Uma declaração de tipo de teclado descreve o comportamento geral do teclado. Um arquivo de mapa de caracteres deve conter uma declaração de tipo de teclado. Para maior clareza, geralmente é colocado no topo 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 multitoque. Pode ser 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 suporta 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 acessíveis usando seletores de caracteres especiais na tela. Além disso, para melhorar a velocidade e a precisão da digitação, a estrutura oferece recursos especiais para teclados alfabéticos, como capitalização automática e teclas SHIFT e ALT alternadas/bloqueadas.
Esse tipo de teclado geralmente é projetado para digitação com o polegar.
FULL : Um teclado estilo PC completo.
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 capitalização automática.
Esse tipo de teclado geralmente é projetado para digitação completa com as duas mãos.
SPECIAL_FUNCTION : Um teclado usado apenas para executar funções de controle do sistema, e não para digitação.
Um teclado de função especial consiste apenas em teclas não imprimíveis, como HOME e POWER, que não são realmente usadas para digitação.

Os mapas de caracteres-chave Generic.kcm e Virtual.kcm são ambos teclados FULL .

Declarações principais

Cada declaração de chave consiste na palavra-chave key seguida por um nome de código de chave Android, uma chave aberta, um conjunto de propriedades e comportamentos e uma chave fechada.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Propriedades

Cada propriedade chave estabelece um mapeamento de uma chave para um comportamento. Para tornar os arquivos de mapeamento de caracteres principais mais compactos, diversas 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 recebem simultaneamente o comportamento none .

As seguintes propriedades são reconhecidas:

label : especifica o rótulo que é impresso fisicamente na chave, quando consiste em um único caractere. Este é o valor retornado pelo método KeyCharacterMap.getDisplayLabel .
number : especifica o comportamento (caractere que deve ser digitado) quando uma visualização de texto numérico tem 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 pode ser usada para digitar '1' e 'a' ou '#' e 'q' , talvez. Para essas chaves, a propriedade number deve ser definida para indicar qual símbolo deve ser digitado em um contexto numérico, se houver.
Alguns símbolos "numéricos" típicos são dígitos '0' a '9' , '#' , '+' , '(' , ')' , ',' , e '.' .
base : Especifica o comportamento (caractere que deve ser digitado) quando nenhum modificador é pressionado.
<modificador> ou <modificador1> + <modificador2> + ...: Especifica o comportamento (caractere que deve ser digitado) quando a tecla é pressionada e todos os modificadores especificados estão ativos.
Por exemplo, a propriedade do modificador shift especifica um comportamento que se aplica quando o modificador LEFT SHIFT ou RIGHT SHIFT é pressionado.
Da mesma forma, a propriedade modificadora rshift+ralt especifica 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 do modificador:

shift : Aplica-se quando o modificador LEFT SHIFT ou RIGHT SHIFT é pressionado.
lshift : Aplica-se quando o modificador LEFT SHIFT é pressionado.
rshift : Aplica-se quando o modificador RIGHT SHIFT é pressionado.
alt : Aplica-se quando o modificador LEFT ALT ou RIGHT ALT é pressionado.
lalt : Aplica-se quando o modificador LEFT ALT é pressionado.
ralt : Aplica-se 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 : Aplica-se quando o modificador RIGHT CONTROL é pressionado.
meta : Aplica-se quando o modificador LEFT META ou RIGHT META é pressionado.
lmeta : Aplica-se quando o modificador LEFT META é pressionado.
rmeta : Aplica-se quando o modificador RIGHT META é pressionado.
sym : Aplica-se quando o modificador SYMBOL é pressionado.
fn : Aplica-se quando o modificador FUNCTION é pressionado.
capslock : Aplica-se quando o modificador CAPS LOCK está bloqueado.
numlock : Aplica-se quando o modificador NUM LOCK está bloqueado.
scrolllock : Aplica-se 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 em ordem e retorna o último comportamento aplicável encontrado.

Conseqüentemente, as propriedades especificadas posteriormente substituem as propriedades especificadas anteriormente para uma determinada chave.

Comportamentos

Cada propriedade é mapeada para um comportamento. O comportamento mais comum é digitar um caractere, mas existem outros.

Os seguintes comportamentos são reconhecidos:

none : não digite um caractere.
Este 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 exibição de texto em foco. 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-o 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 <nome do código da chave Android>: execute uma ação padrão se a chave não for manipulada pelo aplicativo.
Esse comportamento faz com que o sistema simule um pressionamento de tecla diferente quando um aplicativo não manipula a tecla especificada nativamente. Ele é usado para oferecer suporte ao comportamento padrão de novas teclas que nem todos os aplicativos sabem como manipular, como ESCAPE ou teclas do teclado numérico (quando numlock não é pressionado).
Quando um comportamento de fallback é executado, o aplicativo receberá dois pressionamentos de tecla: um para a chave original e outro para a tecla de fallback que foi selecionada. Se o aplicativo manipular a chave original durante a ativação, o evento da chave substituta será cancelado ( KeyEvent.isCanceled retornará 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 os quatro caracteres que precedem o 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 exibe uma caixa de diálogo de seleção de caracteres que contém símbolos diversos.

O sistema reconhece os seguintes caracteres Unicode como uma combinação de caracteres diacríticos de chave morta:

'\u0300' : sotaque grave.
'\u0301' : sotaque agudo.
'\u0302' : Acento circunflexo.
'\u0303' : acento til.
'\u0308' : sotaque trema.

Quando uma chave morta é digitada seguida por outro caractere, a chave morta e os caracteres seguintes são compostos. Por exemplo, quando o usuário digita uma tecla morta com acento grave seguida pela letra 'a', o resultado é 'à'.

Consulte KeyCharacterMap.getDeadChar para obter mais informações sobre o tratamento de chaves inativas.

Comentários

As linhas de comentários começam com '#' e continuam até o final da linha. Assim:

# 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 daquela tecla pressionada e dos modificadores pressionados no momento.

MUDANÇA + A

Suponha que o usuário pressionou A e SHIFT juntos. 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 para a ú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, não importa quais modificadores sejam pressionados. Essencialmente, especifica o comportamento padrão da chave, a menos que seja substituído pelas seguintes propriedades. Como a propriedade base se aplica a esse pressionamento de tecla, o sistema anota o fato de que seu comportamento é 'a' (digite o caractere a ).

O sistema então 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 ao pressionamento da tecla SHIFT + A. Assim, 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 varredura da tabela, porém nenhuma outra propriedade se aplica a esse pressionamento de tecla (CAPS LOCK não está bloqueado, nenhuma tecla CONTROL é pressionada, nenhuma tecla ALT é pressionada e nenhuma tecla META é pressionada).

Portanto, o comportamento resultante para a combinação de teclas SHIFT + A é 'A' .

CONTROLE + A

Agora considere o que aconteceria se o usuário pressionasse A e CONTROL juntos.

Como antes, o sistema verificaria a tabela de propriedades. Ele notaria que a propriedade base era aplicada, mas também continuaria a varredura até atingir a propriedade control . Acontece que a propriedade control aparece depois de base , portanto seu comportamento substitui o comportamento base .

Portanto, o comportamento resultante para a combinação de teclas CONTROL + A é none .

ESCAPAR

Agora suponha que o usuário pressionou ESCAPE.

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

Desta vez o sistema obtém o comportamento fallback BACK , um comportamento fallback. Como nenhum caractere literal aparece, nenhum caractere será digitado.

Ao processar a chave, o sistema primeiro entregará KEYCODE_ESCAPE à aplicação. Se o aplicativo não lidar com isso, o sistema tentará novamente, mas desta vez entregará KEYCODE_BACK ao aplicativo conforme solicitado pelo comportamento de fallback.

Portanto, os aplicativos que reconhecem e suportam KEYCODE_ESCAPE têm a oportunidade de lidar com isso como está, mas outros aplicativos que não o fazem podem, em vez disso, executar a ação de fallback de tratar a chave como se 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 for pressionado. Quando NUM LOCK não é pressionado, a chave é entregue ao aplicativo normalmente e, se não for tratada, a chave substituta 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 teclas substitutas melhoram muito a compatibilidade com aplicativos mais antigos que não reconhecem ou não suportam diretamente todas as teclas 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'
}

Controle

# 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 compatibilidade

Antes do Android Honeycomb 3.0, o mapa de caracteres principais do Android era especificado usando uma sintaxe muito diferente e compilado em um formato de arquivo binário ( .kcm.bin ) no momento da compilação.

Embora o novo formato use a mesma extensão .kcm , a sintaxe é bem diferente (e muito mais poderosa).

A partir do Android Honeycomb 3.0, todos os arquivos de mapa de caracteres principais do Android devem usar a nova sintaxe e o novo formato de arquivo de texto simples descrito neste documento. A sintaxe antiga não é suportada e os arquivos .kcm.bin antigos não são reconhecidos pelo sistema.

Nota de linguagem

Atualmente, o Android não oferece suporte a teclados multilíngues. Além disso, o mapa de caracteres-chave genérico integrado assume um layout de teclado em inglês dos EUA.

Os OEMs são incentivados a fornecer mapas de caracteres-chave personalizados para seus teclados, caso sejam projetados para outros idiomas.

Versões futuras do Android poderão fornecer melhor suporte para teclados multilíngues ou layouts de teclado selecionáveis pelo usuário.

Validação

Certifique-se de validar seus arquivos de mapa de caracteres principais usando a ferramenta Validar mapas de teclas .