O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Esta página foi traduzida pela API Cloud Translation.

Arquivos de mapa de caracteres-chave

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.

Os 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 não são necessários. O sistema fornece um mapa genérico de caracteres de teclas que é 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.

Localização

Os arquivos de mapa de caracteres de chave 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 de chave genérico

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

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

Arquivo de mapa de caracteres de chave virtual

O sistema fornece um arquivo de mapa 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ético cujo 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 pressionamentos de tecla 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 que seja o mesmo 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 de chave virtual!

Sintaxe

Um arquivo de mapa de caracteres de chave é um arquivo de texto simples que consiste em uma declaração de tipo de teclado e um conjunto de declarações de chave.

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 em uma tecla várias vezes para gerar a letra ou 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 podem ser acessados apenas usando seletores de caracteres especiais na tela. Além disso, para melhorar a velocidade e a precisão da digitação, a estrutura fornece 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 duas mãos.
SPECIAL_FUNCTION : Um teclado que é 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 imprimíveis, como HOME e POWER, que não são realmente usadas para digitar.

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

Declarações-chave

Cada declaração de chave consiste na palavra-chave key seguida por um nome de código de chave 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-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 todas atribuídas simultaneamente ao 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 que é retornado pelo método KeyCharacterMap.getDisplayLabel .
number : especifica o comportamento (caractere que deve ser digitado) quando uma exibição de texto numérico tem foco, como 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 tecla pode ser usada para digitar '1' e 'a' ou '#' e 'q' , talvez. Para essas chaves, a propriedade number deve ser configurada 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.
<modifier> ou <modifier1> + <modifier2> + ...: Especifica o comportamento (caractere que deve ser digitado) quando a tecla é pressionada e todos os modificadores especificados estão ativos.
Por exemplo, a propriedade shift do modificador especifica um comportamento que se aplica quando o modificador LEFT SHIFT ou RIGHT SHIFT é pressionado.
Da mesma forma, a propriedade do modificador 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 META DIREITO é 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.

Consequentemente, as propriedades especificadas posteriormente substituem as propriedades especificadas anteriormente para uma determinada chave.

Comportamentos

Cada propriedade mapeia 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.
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 exibiçã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 novo caractere de linha (use isso 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 é dado em hexadecimal por XXXX.
fallback <nome do código da chave Android>: execute uma ação padrão se a chave não for tratada 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 suportar o 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 tecla original e outro para a tecla de fallback que foi selecionada. Se o aplicativo manipular a chave original durante a ativação, o evento de chave de fallback será cancelado ( KeyEvent.isCanceled retornará true ).

O sistema reserva dois caracteres Unicode para executar funções especiais:

'\uef00' : quando esse comportamento é executado, a exibiçã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 este 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 combinando caracteres de teclas mortas diacríticas:

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

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

Consulte KeyCharacterMap.getDeadChar para obter mais informações sobre manipulação 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 desse pressionamento de tecla e dos modificadores pressionados no momento.

SHIFT + 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 varre as propriedades do primeiro ao último e da esquerda para a direita, ignorando as propriedades de 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. Ele essencialmente especifica o comportamento padrão para a chave, a menos que seja substituído pelas seguintes propriedades. Como a propriedade base se aplica a este pressionamento de tecla, o sistema observa o fato de que seu comportamento é 'a' (digite o caractere a ).

O sistema continua a varrer as propriedades subsequentes caso alguma delas seja mais específica que a base e a substitui. Ele encontra shift que também se aplica ao pressionamento de 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 varrer a tabela, no entanto, nenhuma outra propriedade se aplica a esta tecla pressionada (CAPS LOCK não está bloqueada, 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 varria a tabela de propriedades. Ele notaria que a propriedade base se aplicava, mas também continuaria a varredura até que finalmente chegasse à propriedade de control . Quando isso acontece, a propriedade de control aparece após a base modo que 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 de fallback. Como nenhum literal de caractere aparece, nenhum caractere será digitado.

Ao processar a chave, o sistema entregará primeiro KEYCODE_ESCAPE ao aplicativo. Se o aplicativo não lidar com isso, o sistema tentará novamente, mas desta vez ele 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 tratá-lo como está, mas outros aplicativos que não reconhecem podem 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 tecla é entregue ao aplicativo normalmente e, se não for tratada, a chave de fallback KEYCODE_INSERT é entregue.

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

Como podemos ver, as declarações de teclas de fallback melhoram muito a compatibilidade com aplicativos mais antigos que não reconhecem ou 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 de chave 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 de chave do Android devem usar a nova sintaxe e o 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 de teclas genéricos integrado assume um layout de teclado em inglês dos EUA.

Os OEMs são incentivados a fornecer mapas de caracteres de teclas personalizados para seus teclados se forem projetados para outros idiomas.

Versões futuras do Android podem oferecer 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 de chave usando a ferramenta Validar Mapas de Teclas.