Dispositivos de teclado

O Android oferece suporte a uma variedade de dispositivos de teclado, incluindo teclados de funções especiais (controles de volume e energia), teclados QWERTY integrados compactos e teclados externos estilo PC com todos os recursos.

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

Classificação do teclado

Um dispositivo de entrada é classificado como teclado se uma das seguintes condições for válida:

• O dispositivo de entrada relata a presença de quaisquer códigos de teclas do Linux usados ​​em teclados, incluindo 0 a 0xff ou KEY_OK a KEY_MAX .

• O dispositivo de entrada relata a presença de quaisquer códigos de chave do Linux usados ​​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 do joystick e do gamepad são relatados por eventos EV_KEY da mesma forma que as teclas do teclado são relatadas. Assim, joysticks e gamepads também utilizam arquivos de mapas principais para configuração.

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

O sistema então tenta determinar características adicionais do dispositivo.

• Se o dispositivo de entrada tiver teclas mapeadas para KEYCODE_Q , então o dispositivo será considerado como tendo um teclado alfabético (em oposição ao numérico). A capacidade do teclado alfabético é relatada no objeto Configuration do recurso como KEYBOARD_QWERTY .

• Se o dispositivo de entrada tiver chaves mapeadas para KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT , KEYCODE_DPAD_RIGHT e KEYCODE_DPAD_CENTER (todas devem estar presentes), então o dispositivo será considerado como tendo um teclado direcional. A capacidade do teclado direcional é relatada 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, então o dispositivo será considerado como tendo um gamepad.

Requisitos de driver de teclado

1. Os drivers de teclado só devem registrar códigos de teclas para as teclas que realmente suportam. O registro de códigos de teclas em excesso pode confundir o algoritmo de classificação do dispositivo ou fazer com que o sistema detecte incorretamente os recursos de teclado suportados pelo dispositivo.

2. Os drivers de teclado devem usar EV_KEY para relatar pressionamentos de teclas, 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 foi pressionada. sendo repetido automaticamente.

3. O Android executa sua própria repetição de teclado. A funcionalidade de repetição automática deve estar desabilitada no driver.

4. Os drivers de teclado podem indicar opcionalmente o uso de HID ou código de varredura de baixo nível enviando EV_MSC com MSC_SCANCODE e um valor indicando o uso ou código de varredura quando a tecla é pressionada. Esta informação não é usada atualmente pelo Android.

5. Os drivers de teclado devem dar suporte à configuração de estados de LED quando EV_LED é gravado no dispositivo. O driver hid-input lida com isso automaticamente. No momento em que este livro foi escrito, o Android usava LED_CAPSLOCK , LED_SCROLLLOCK e LED_NUMLOCK . Esses LEDs só precisam ser suportados quando o teclado realmente possui as luzes indicadoras associadas.

6. Drivers de teclado para teclados incorporados (por exemplo, usando uma matriz GPIO) devem enviar eventos EV_KEY com valor 0 para quaisquer teclas que ainda estejam pressionadas quando o dispositivo estiver no modo de suspensão. Caso contrário, as teclas poderão ficar presas e serão repetidas automaticamente para sempre.

Operação do teclado

A seguir está um breve resumo da operação do teclado no Android.

1. O EventHub lê eventos brutos do driver evdev e mapeia códigos-chave do Linux (às vezes chamados de códigos de varredura) em códigos-chave do Android usando o mapa de layout de teclas do teclado.

2. O InputReader consome os eventos brutos e atualiza o estado da meta-chave. Por exemplo, se a tecla shift esquerda for pressionada ou liberada, o leitor irá definir ou redefinir os bits META_SHIFT_LEFT_ON e META_SHIFT_ON de acordo.

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

4. O InputDispatcher pergunta ao WindowManagerPolicy o que fazer com o evento chave chamando WindowManagerPolicy.interceptKeyBeforeQueueing . Este método faz parte de um caminho crítico responsável por despertar o dispositivo quando determinadas teclas são pressionadas. O EventHub mantém efetivamente um wake lock ao longo desse caminho crítico para garantir que ele será executado até a conclusão.

5. Se um InputFilter estiver em uso, o InputDispatcher lhe dará 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 no thread de despacho.

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

8. O InputDispatcher então identifica o alvo do evento principal (a janela em foco) e espera que eles fiquem prontos. Em seguida, o InputDispatcher entrega o evento chave ao aplicativo.

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

10. Se o evento principal não for tratado no despacho pré-IME e um IME estiver em uso, o evento principal será entregue ao IME.

11. Se o evento-chave não tiver sido consumido pelo IME, o evento-chave se propagará para baixo na hierarquia de visualização até a visualização em foco para envio de chave padrão.

12. O aplicativo reporta ao InputDispatcher se o evento principal foi consumido. Se o evento não foi consumido, o InputDispatcher chama WindowManagerPolicy.dispatchUnhandledKey para aplicar o comportamento de "substituição". Dependendo da ação de fallback, o ciclo de despacho de evento chave pode ser reiniciado usando um código chave diferente. Por exemplo, se um aplicativo não manipular KEYCODE_ESCAPE , o sistema poderá reenviar o evento chave como KEYCODE_BACK .

Configuração do teclado

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

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

• Arquivos de layout principais
• Arquivos de mapa de caracteres principais
• Arquivos de configuração do dispositivo de entrada

Propriedades

As seguintes propriedades de configuração de dispositivo de entrada são usadas para teclados.

teclado.layout

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

Especifica o nome do arquivo de layout de teclas associado ao dispositivo de entrada, excluindo a extensão .kl . Se este 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 principal para obter mais detalhes.

teclado.characterMap

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

Especifica o nome do arquivo de mapa de caracteres principais associado ao dispositivo de entrada, excluindo a extensão .kcm . Se este arquivo não for encontrado, o sistema de entrada usará o mapa de caracteres-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 principais para obter mais detalhes.

teclado.orientationAware

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

Especifica se o teclado deve reagir às alterações de orientação de exibição.

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

• Se o valor for 0 , o teclado estará imune a alterações de orientação de exibição.

O valor padrão é 0 .

O reconhecimento de orientação é usado para suportar a rotação das teclas direcionais do teclado, como no Motorola Droid. Por exemplo, quando o dispositivo é girado 90 graus no sentido horário a partir de sua orientação natural, KEYCODE_DPAD_UP é remapeado para produzir KEYCODE_DPAD_RIGHT , pois a tecla 'para cima' acaba apontando para 'direita' quando o dispositivo é mantido nessa orientação.

teclado.builtIn

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

Especifica se o teclado é integrado (conectado fisicamente).

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

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

Usar um id 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 0 . Este campo foi descontinuado na API, mas aplicativos mais antigos ainda podem utilizá-lo.

Um teclado de função especial (aquele cujo mapa de caracteres de teclas especifica um tipo de SPECIAL_FUNCTION ) nunca será registrado como teclado integrado, independentemente da configuração desta propriedade. Isso ocorre porque um teclado de função especial, por definição, não se destina a ser usado para digitação de uso geral.

Configurações de exemplo

# 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

Notas de compatibilidade

Antes do Honeycomb, o mapeador de entrada do teclado não usava nenhuma propriedade de configuração. Todos os teclados foram considerados fisicamente conectados e com reconhecimento de orientação. O layout de teclas padrão e o mapa de caracteres principais foram nomeados qwerty em vez de Generic . O formato do mapa de caracteres principais também era muito diferente e a estrutura não suportava teclados completos no estilo PC ou teclados externos.

Ao atualizar dispositivos para Honeycomb, certifique-se de criar ou atualizar a configuração necessária e os principais arquivos de mapa.

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

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

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

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

Quando o evento key é enviado para um aplicativo, a instância android.view.KeyEvent relata o código-chave do Linux como o valor de getScanCode() e o código-chave do Android como o valor de getKeyCode() . Para efeitos da estrutura, apenas o valor de getKeyCode() é importante.

Observe que as informações de uso do HID não são usadas pelo próprio Android nem passadas para aplicativos.

Tabelas de códigos

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

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

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

A coluna Notas refere-se às notas publicadas após a tabela.

A coluna Versão especifica a primeira versão da plataforma Android que incluiu essa chave em seu 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 é a 1.6.

• No Gingerbread (2.3) e versões anteriores, o mapa de teclas padrão era qwerty.kl . Este mapa de teclas foi projetado apenas para uso com o Android Emulator e não para suporte a teclados externos arbitrários. No entanto, alguns OEMs adicionaram suporte de teclado Bluetooth à plataforma e confiaram no qwerty.kl para fornecer os mapeamentos de teclado necessários. Conseqüentemente, esses mapeamentos mais antigos podem ser de interesse para OEMs que estão construindo periféricos para esses dispositivos específicos. Observe que os mapeamentos são substancialmente diferentes dos atuais, principalmente no que diz respeito ao tratamento da chave HOME . Recomenda-se 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 chaves padrão é Generic.kl . Este mapa de teclas foi projetado para suportar teclados completos no estilo PC. A maioria das funcionalidades dos teclados HID padrão deve funcionar imediatamente.

O mapeamento do código-chave pode variar entre as versões do kernel Linux e Android. Quando se sabe que ocorreram alterações nos mapas de teclas padrão do Android, elas são indicadas na coluna de versão.

Drivers HID específicos do dispositivo e mapas de chaves podem aplicar mapeamentos diferentes dos indicados aqui.

Teclado HID e página do teclado (0x07)

Página genérica do HID para desktop (0x01)

Página do consumidor HID (0x0c)

Mapeamentos adicionais não hid

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

Chaves legadas não suportadas

Esses mapeamentos apareceram nas versões anteriores do Android, mas eram inconsistentes com os códigos de chave Linux não padrão HID ou usados. Eles não são mais suportados.

Notas

1. O código -chave do Android associado a teclas alfanuméricas e simbólicas comuns pode variar com base no layout e no idioma do teclado. Por razões históricas, os códigos de varredura física e os usos ocultos associados às teclas em um teclado geralmente são definidos posicionalmente, mesmo que 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 superior esquerda é rotulada Q. Em um teclado francês (Azerty), a chave na mesma posição é rotulada A. Apesar da etiqueta, em ambos os teclados a tecla alfabética superior esquerda é referido usando o uso HID 0x07 0x0014, que é mapeado para o código -chave linux key_q.

   Quando o Android é configurado com um layout de teclado em inglês nos EUA, o Código do CECHO Linux Key_Q será mapeado para o código -chave do Android KeyCode_Q e produzirá os caracteres 'Q' e 'Q'. No entanto, quando o Android é configurado com um layout de teclado francês, o Código de Chave do Linux Key_Q será mapeado para o código -chave do Android KeyCode_A e produzirá os caracteres 'a' e 'a'.

   O código-chave do Android geralmente reflete a interpretação específica do idioma da chave; portanto, um código-chave 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 linux KEY_FN_* são mapeadas para os códigos de chave mais simples, mas são despachados com o bit meta de META_FUNCTION definido como true.

4. Antes do sanduíche de sorvete Android 4.0, o layout de chave padrão continha mapeamentos para alguns códigos -chave extras que não foram definidos nos cabeçalhos do kernel Linux da linha principal. Desde então, esses mapeamentos foram removidos porque esses códigos -chave anteriormente indefinidos foram atribuídos significados diferentes em versões mais recentes do kernel Linux.

Fontes

1. USB HID Usage Tables v1.12
2. Linux 2.6.39 kernel: incluir/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, genérico.kl, keyevent.java