Dispositivos de teclado

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Android oferece suporte a vários dispositivos de teclado, incluindo teclados de função especial (controles de volume e energia), teclados QWERTY compactos incorporados e teclados externos completos no estilo de PC.

Este documento descreve apenas teclados físicos. Consulte o SDK do Android para informações sobre teclados virtuais (editores de método de entrada).

Classificação do teclado

Um dispositivo de entrada é classificado como um teclado se uma das seguintes condições for verdadeira:

• O dispositivo de entrada informa a presença de qualquer código de tecla do Linux usado em teclados, incluindo 0 a 0xff ou KEY_OK a KEY_MAX.

• O dispositivo de entrada informa a presença de qualquer código de tecla do Linux usado em joysticks e gamepads, incluindo BTN_0 a BTN_9, BTN_TRIGGER a BTN_DEAD ou BTN_A a BTN_THUMBR.

Atualmente, os joysticks são classificados como teclados porque os botões de joystick e gamepad são informados por eventos EV_KEY da mesma forma que as teclas do teclado. Assim, joysticks e gamepads também usam arquivos de mapeamento de teclas para configuração.

Depois que um dispositivo de entrada é classificado como um teclado, o sistema carrega o arquivo de configuração do dispositivo de entrada e o layout do teclado.

Em seguida, o sistema tenta determinar outras características do dispositivo.

• Se o dispositivo de entrada tiver teclas mapeadas para KEYCODE_Q, ele será considerado como tendo um teclado alfabético (em vez de numérico). O recurso de teclado alfabético é informado no objeto Configuration do recurso como KEYBOARD_QWERTY.

• Se o dispositivo de entrada tiver teclas mapeadas para KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT, KEYCODE_DPAD_RIGHT e KEYCODE_DPAD_CENTER (todas precisam estar presentes), o dispositivo será considerado como tendo um teclado direcional. O recurso do teclado direcional é informado no objeto Configuration do recurso como NAVIGATION_DPAD.

• Se o dispositivo de entrada tiver teclas mapeadas para KEYCODE_BUTTON_A ou outras teclas relacionadas ao gamepad, ele será considerado como tendo um gamepad.

Requisitos do driver do teclado

1. Os drivers de teclado só devem registrar códigos de tecla para as teclas que oferecem suporte. O registro de códigos de tecla em excesso pode confundir o algoritmo de classificação do dispositivo ou fazer com que o sistema detecte incorretamente os recursos de teclado compatíveis do dispositivo.

2. Os drivers de teclado precisam usar EV_KEY para informar pressionamentos de tecla, usando um valor 0 para indicar que uma tecla foi liberada, um valor 1 para indicar que uma tecla foi pressionada e um valor maior ou igual a 2 para indicar que a tecla está sendo repetida automaticamente.

3. O Android executa a repetição do teclado. A funcionalidade de repetição automática precisa ser desativada no driver.

4. Os drivers de teclado podem indicar opcionalmente o uso do HID ou o código de verificação de nível baixo enviando EV_MSC com MSC_SCANCODE e um valor indicando o uso ou o código de verificação quando a tecla é pressionada. No momento, essas informações não são usadas pelo Android.

5. Os drivers de teclado precisam oferecer suporte à configuração de estados de LED quando EV_LED for gravado no dispositivo. O driver hid-input faz isso automaticamente. No momento em que este artigo foi escrito, o Android usava LED_CAPSLOCK, LED_SCROLLLOCK e LED_NUMLOCK. Esses LEDs só precisam de suporte quando o teclado tem as luzes indicadoras associadas.

6. Os drivers de teclado para teclados integrados (por exemplo, usando uma matriz GPIO) precisam enviar eventos EV_KEY com um valor de 0 para todas as teclas que ainda estiverem pressionadas quando o dispositivo for para o modo de suspensão. Caso contrário, as teclas podem ficar presas e repetir automaticamente para sempre.

Operação do teclado

Confira a seguir um breve resumo da operação do teclado no Android.

1. O EventHub lê eventos brutos do driver evdev e mapeia códigos de tecla do Linux (às vezes chamados de códigos de verificação) para códigos de tecla do Android usando o mapa de layout de teclas do teclado.

2. O InputReader consome os eventos brutos e atualiza o estado da metachave. Por exemplo, se a tecla de deslocamento para a esquerda for pressionada ou solta, o leitor vai definir ou redefinir os bits META_SHIFT_LEFT_ON e META_SHIFT_ON de acordo.

3. O InputReader notifica o InputDispatcher sobre o evento principal.

4. O InputDispatcher pergunta ao WindowManagerPolicy o que fazer com o evento principal chamando WindowManagerPolicy.interceptKeyBeforeQueueing. Esse método faz parte de um caminho crítico responsável por ativar o dispositivo quando determinadas teclas são pressionadas. O EventHub mantém uma trava de ativação ao longo desse caminho crítico para garantir que ele seja concluído.

5. Se uma InputFilter estiver em uso, o InputDispatcher vai dar a ela a chance de consumir ou transformar a chave. O InputFilter pode ser usado para implementar políticas de acessibilidade de baixo nível em todo o sistema.

6. O InputDispatcher enfileira a chave para processamento na linha de execução.

7. Quando o InputDispatcher retira a chave da fila, ele dá ao WindowManagerPolicy uma segunda chance de interceptar o evento de tecla chamando WindowManagerPolicy.interceptKeyBeforeDispatching. Esse método processa atalhos do sistema e outras funções.

8. O InputDispatcher identifica o alvo do evento principal (a janela em foco) e aguarda até que ele esteja pronto. Em seguida, o InputDispatcher envia o evento principal para o aplicativo.

9. No aplicativo, o evento de tecla se propaga pela hierarquia de visualização até a visualização em foco para o envio de teclas pré-IME.

10. Se o evento de tecla não for processado no envio antes do IME e um IME estiver em uso, o evento de tecla será enviado ao IME.

11. Se o evento de tecla não for consumido pelo IME, ele será propagado pela hierarquia de visualização até a visualização em foco para o envio de tecla padrão.

12. O aplicativo informa ao InputDispatcher se o evento chave foi consumido. Se o evento não for consumido, o InputDispatcher vai chamar WindowManagerPolicy.dispatchUnhandledKey para aplicar o comportamento "padrão". Dependendo da ação de fallback, o ciclo de envio de eventos principais pode ser reiniciado usando um código de chave diferente. Por exemplo, se um aplicativo não processar KEYCODE_ESCAPE, o sistema poderá reenviar o evento principal como KEYCODE_BACK.

Configuração do teclado

O comportamento do teclado é determinado pelo layout das teclas, pelo mapa de caracteres e pela configuração do dispositivo de entrada.

Consulte as seções a seguir para mais detalhes sobre os arquivos que participam da configuração do teclado:

• Arquivos de layout de chave
• Arquivos de mapa de caracteres-chave
• Arquivos de configuração de dispositivos de entrada

Propriedades

As propriedades de configuração do dispositivo de entrada a seguir são usadas para teclados.

keyboard.layout

Definição:keyboard.layout = <name>

Especifica o nome do arquivo de layout de chave associado ao dispositivo de entrada, excluindo a extensão .kl. Se esse arquivo não for encontrado, o sistema de entrada usará o layout de teclas padrão.

Os espaços no nome são convertidos em sublinhados durante a pesquisa.

Consulte a documentação do arquivo de layout de chave para mais detalhes.

keyboard.characterMap

Definição:keyboard.characterMap = <name>

Especifica o nome do arquivo de mapa de caracteres de chave associado ao dispositivo de entrada, excluindo a extensão .kcm. Se esse arquivo não for encontrado, o sistema de entrada usará o mapa de caracteres de chave padrão.

Os espaços no nome são convertidos em sublinhados durante a pesquisa.

Consulte a documentação do arquivo de mapa de caracteres de chave para mais detalhes.

keyboard.orientationAware

Definição:keyboard.orientationAware = 0 | 1

Especifica se o teclado precisa reagir às mudanças de orientação da tela.

• Se o valor for 1, as teclas do teclado direcional serão giradas quando a orientação da tela associada mudar.

• Se o valor for 0, o teclado não será afetado por mudanças na orientação da tela.

O valor padrão é 0.

A detecção de orientação é usada para oferecer suporte à rotação das teclas do teclado direcional, como no Motorola Droid. Por exemplo, quando o dispositivo é girado no sentido horário em 90 graus a partir da orientação natural, KEYCODE_DPAD_UP é remapeado para produzir KEYCODE_DPAD_RIGHT, já que a tecla "para cima" aponta para "direita" quando o dispositivo é mantido nessa orientação.

keyboard.builtIn

Definição:keyboard.builtIn = 0 | 1

Especifica se o teclado é integrado (fisicamente conectado) ou não.

O valor padrão é 1 se o nome do dispositivo terminar com -keypad. Caso contrário, será 0.

O teclado integrado sempre recebe um ID de dispositivo de 0. Outros teclados que não são integrados recebem IDs de dispositivos exclusivos diferentes de zero.

O uso de um ID de 0 para o teclado integrado é importante para manter a compatibilidade com o campo KeyCharacterMap.BUILT_IN_KEYBOARD, que especifica o ID do teclado integrado e tem um valor de 0. Esse campo foi descontinuado na API, mas os aplicativos mais antigos ainda podem usá-lo.

Um teclado de função especial (cujo mapeamento de caracteres de tecla especifica um tipo de SPECIAL_FUNCTION) nunca será registrado como o teclado integrado, independentemente da configuração dessa propriedade. Isso ocorre porque um teclado de função especial não é destinado a ser usado para digitação geral.

Exemplos de configurações

# This is an example input device configuration file for a built-in
# keyboard that has a DPad.

# The keyboard is internal because it is part of the device.
device.internal = 1

# The keyboard is the default built-in keyboard so it should be assigned
# an id of 0.
keyboard.builtIn = 1

# The keyboard includes a DPad which is mounted on the device.  As the device
# is rotated the orientation of the DPad rotates along with it, so the DPad must
# be aware of the display orientation.  This ensures that pressing 'up' on the
# DPad always means 'up' from the perspective of the user, even when the entire
# device has been rotated.
keyboard.orientationAware = 1

Observações sobre compatibilidade

Antes do Honeycomb, o mapeador de entrada de teclado não usava propriedades de configuração. Todos os teclados foram considerados conectados fisicamente e com orientação. O layout padrão e o mapa de caracteres da chave foram nomeados como qwerty em vez de Generic. O formato do mapa de caracteres também era muito diferente, e o framework não oferecia suporte a teclados completos ou externos no estilo PC.

Ao fazer upgrade de dispositivos para o Honeycomb, crie ou atualize a configuração necessária e os arquivos de mapa de chaves.

Usos de HID, códigos de chave do Linux e códigos de chave do Android

O sistema se refere a chaves usando vários identificadores diferentes, dependendo da camada de abstração.

Para dispositivos HID, cada chave tem um uso HID associado. O driver hid-input do Linux e os drivers HID específicos do fornecedor e do dispositivo são responsáveis por analisar relatórios HID e mapear usos HID para códigos de chave do Linux.

À medida que o Android lê eventos EV_KEY do kernel do Linux, ele traduz cada código de chave do Linux no código de chave do Android correspondente, de acordo com o arquivo de layout de chave do dispositivo.

Quando o evento de tecla é enviado a um aplicativo, a instância android.view.KeyEvent informa o código de tecla do Linux como o valor de getScanCode() e o código de tecla do Android como o valor de getKeyCode(). Para os fins do framework, apenas o valor de getKeyCode() é importante.

As informações de uso do HID não são usadas pelo próprio Android nem transmitidas para os aplicativos.

Tabelas de código

As tabelas a seguir mostram como os usos de HID, os códigos de tecla do Linux e os códigos de tecla do Android estão relacionados.

A coluna LKC especifica o código de chave do Linux em hexadecimal.

A coluna AKC especifica o código de chave do Android em hexadecimal.

A coluna "Anotações" se refere às anotações postadas após a tabela.

A coluna "Versão" especifica a primeira versão da plataforma Android que incluiu essa chave no mapa de chaves padrão. Várias linhas são mostradas nos casos em que o mapa de teclas padrão mudou entre as versões. A versão mais antiga indicada é 1.6.

• No Gingerbread (2.3) e em versões anteriores, o mapa de teclas padrão era qwerty.kl. Esse mapa de teclas foi destinado apenas ao uso com o Android Emulator e não foi projetado para oferecer suporte a teclados externos arbitrários. No entanto, alguns OEMs adicionaram suporte a teclados Bluetooth à plataforma e usaram qwerty.kl para fornecer os mapeamentos de teclado necessários. Consequentemente, esses mapeamentos mais antigos podem ser interessantes para OEMs que estão criando periféricos para esses dispositivos específicos. Os mapeamentos são substancialmente diferentes dos atuais, principalmente no que diz respeito ao tratamento da chave HOME. É recomendável que todos os novos periféricos sejam desenvolvidos de acordo com o Honeycomb ou mapas de teclas mais recentes (ou seja, HID padrão).

• A partir do Honeycomb (3.0), o mapa de teclas padrão é Generic.kl. Esse mapa de teclas foi projetado para oferecer suporte a teclados completos de PC. A maioria das funcionalidades dos teclados HID padrão deve funcionar imediatamente.

O mapeamento do código da chave pode variar de acordo com as versões do kernel do Linux e do Android. Quando as mudanças são conhecidas nos mapas de teclas padrão do Android, elas são indicadas na coluna "Versão".

Os drivers HID específicos do dispositivo e os mapas de teclas podem aplicar mapeamentos diferentes do que os indicados aqui.

Página de teclado e teclado numérico HID (0x07)

Página de computador genérica HID (0x01)

Página de consumidor HID (0x0c)

Outros mapeamentos não HID

Esses mapeamentos descrevem funções que não aparecem no HID, mas para as quais os códigos de chave do Linux existem.

Chaves legadas sem suporte

Esses mapeamentos apareceram em versões anteriores do Android, mas eram inconsistentes com o HID ou usavam códigos de chave não padrão do Linux. Eles não são mais compatíveis.

Observações

1. O código de chave do Android associado a chaves alfanuméricas e simbólicas comuns pode variar de acordo com o layout e o idioma do teclado. Por motivos históricos, os códigos de verificação física e os usos de HID associados às teclas de um teclado geralmente são definidos de forma posicional, embora os rótulos impressos nessas teclas possam variar de um idioma para outro.

   Em um teclado em inglês dos EUA (QWERTY), a tecla alfabética no canto superior esquerdo é identificada como Q. Em um teclado francês (AZERTY), a tecla na mesma posição é identificada como A. Apesar do rótulo, em ambos os teclados, a chave alfabética no canto superior esquerdo é referenciada usando o uso HID 0x07 0x0014, que é mapeado para o código de chave KEY_Q do Linux.

   Quando o Android está configurado com um layout de teclado em inglês dos EUA, o código de tecla KEY_Q do Linux é mapeado para o código de tecla KEYCODE_Q do Android e produz os caracteres "Q" e "q". No entanto, quando o Android é configurado com um layout de teclado francês, o código de tecla KEY_Q do Linux é mapeado para o código de tecla KEYCODE_A do Android e produz os caracteres 'A' e 'a'.

   O código de chave do Android normalmente reflete a interpretação da chave específica da linguagem. Portanto, um código de chave do Android diferente pode ser usado para diferentes idiomas.

2. 0x0c 0x022f AC Zoom é definido no HID como um controle linear, mas o kernel o mapeia como uma chave, o que provavelmente está incorreto.

3. As teclas de função KEY_FN_* do Linux são mapeadas para códigos de tecla mais simples, mas são enviadas com o bit de metaestado META_FUNCTION definido como verdadeiro.

4. Antes do Android Ice Cream Sandwich 4.0, o layout de teclas padrão continha mapeamentos para alguns códigos de teclas extras que não eram definidos nos cabeçalhos do kernel do Linux. Esses mapeamentos foram removidos porque esses códigos de chaves indefinidos foram atribuídos a significados diferentes em versões mais recentes do kernel do Linux.

Fontes

1. Tabelas de uso de HID USB v1.12
2. Kernel do Linux 2.6.39: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java