Dispositivos de teclado

O Android suporta uma variedade de dispositivos de teclado, incluindo teclados de função especial (controles de volume e energia), teclados QWERTY incorporados compactos e teclados externos estilo PC com todos os recursos.

Este documento descreve apenas teclados físicos. Consulte o Android SDK para obter informações sobre teclados virtuais (Input Method Editors).

Classificação do teclado

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

• O dispositivo de entrada relata 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 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 fazem uso de arquivos de mapa de teclas para configuração.

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

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

• Se o dispositivo de entrada tiver alguma tecla mapeada para KEYCODE_Q , 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 teclas mapeadas para KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT , KEYCODE_DPAD_RIGHT e KEYCODE_DPAD_CENTER (todos devem estar presentes), 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, o dispositivo será considerado como tendo um gamepad.

Requisitos do driver do teclado

1. Drivers de teclado só devem registrar códigos de teclas para as teclas que eles 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 do dispositivo.

2. Drivers de teclado devem usar EV_KEY para relatar pressionamentos de tecla, usando um valor de 0 para indicar que uma tecla foi liberada, um valor de 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 ser desabilitada no driver.

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

5. Drivers de teclado devem suportar a configuração de estados de LED quando EV_LED é gravado no dispositivo. O driver hid-input trata disso automaticamente. No momento da redação deste artigo, o Android usa LED_CAPSLOCK , LED_SCROLLLOCK e LED_NUMLOCK . Esses LEDs só precisam ser suportados quando o teclado realmente tiver as luzes indicadoras associadas.

6. Drivers de teclado para teclados integrados (por exemplo, usando uma matriz GPIO) devem certificar-se de enviar eventos EV_KEY com um valor de 0 para quaisquer teclas que ainda estejam pressionadas quando o dispositivo estiver em modo de suspensão. Caso contrário, as teclas podem ficar presas e se repetirão automaticamente para sempre.

Operação do teclado

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

1. O EventHub lê eventos brutos do driver evdev e mapeia os códigos de teclas do Linux (às vezes chamados de códigos de varredura) em códigos de teclas 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 acordo.

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

4. O InputDispatcher pergunta ao WindowManagerPolicy o que fazer com o evento de chave chamando WindowManagerPolicy.interceptKeyBeforeQueueing . Este método faz parte de um caminho crítico que é 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 seja 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 em todo o sistema de baixo nível.

6. O InputDispatcher enfileira a chave para processamento no encadeamento de expedição.

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

8. O InputDispatcher então identifica o destino do evento chave (a janela focada) e espera que eles fiquem prontos. Em seguida, o InputDispatcher entrega o evento de chave ao aplicativo.

9. Dentro do aplicativo, o evento de chave se propaga pela hierarquia de exibição para a exibição focada para o envio de chave pré-IME.

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

11. Se o evento de chave não foi consumido pelo IME, o evento de chave se propaga na hierarquia de exibição para a exibição focada para o envio de chave padrão.

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

Configuração do teclado

O comportamento do teclado é determinado pelo layout das teclas do teclado, mapa de caracteres das teclas e 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 de chave
• Arquivos de mapa de caracteres-chave
• Arquivos de configuração do dispositivo de entrada

Propriedades

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

keyboard.layout

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

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 chave 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 obter mais detalhes.

keyboard.characterMap

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

Especifica o nome do arquivo de mapa de caracteres 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-chave para obter mais detalhes.

keyboard.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 direcionais do teclado serão giradas quando a orientação de exibição associada for alterada.

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

O valor padrão é 0 .

O reconhecimento de orientação é usado para dar suporte à rotação das teclas direcionais do teclado, como no Motorola Droid. Por exemplo, quando o dispositivo é girado no sentido horário 90 graus 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.

keyboard.builtIn

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

Especifica se o teclado é 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 de 0 . Outros teclados que não são integrados são atribuídos a IDs de dispositivo diferentes de zero.

Usar um id de 0 para o teclado interno é importante para manter a compatibilidade com o campo KeyCharacterMap.BUILT_IN_KEYBOARD , que especifica o id do teclado interno e tem um valor de 0 . Este campo foi preterido na API, mas aplicativos mais antigos ainda podem usá-lo.

Um teclado de função especial (aquele cujo mapa de caracteres de teclas especifica um tipo de SPECIAL_FUNCTION ) nunca será registrado como o teclado interno, independentemente da configuração dessa 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 cientes da orientação. O layout de chave padrão e o mapa de caracteres de chave foram denominados qwerty em vez de Generic . O formato do mapa de caracteres-chave também era muito diferente e a estrutura não suportava teclados completos no estilo PC ou teclados externos.

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

Usos HID, códigos-chave do Linux e códigos-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 Linux e os drivers HID específicos do fornecedor e do dispositivo relacionados são responsáveis ​​por analisar os relatórios HID e mapear os usos HID para os códigos-chave do Linux.

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

Quando o evento de chave é despachado para um aplicativo, a instância android.view.KeyEvent relata o código de chave do Linux como o valor de getScanCode() e o código de chave do Android como o valor de getKeyCode() . Para os propósitos 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 os aplicativos.

Tabelas de códigos

As tabelas a seguir mostram como os usos do 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 de chave do Linux em hexadecimal.

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

A coluna Notas refere-se às notas postadas 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 foi alterado entre as versões. A versão mais antiga indicada é 1.6.

• No Gingerbread (2.3) e versões anteriores, o mapa de teclas padrão era qwerty.kl . Este mapa de teclas destina-se apenas ao uso com o Android Emulator e não deve ser usado para oferecer 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. Consequentemente, 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 tecla 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 estilo PC completos. A maioria das funcionalidades dos teclados HID padrão deve funcionar imediatamente.

O mapeamento de código de chave pode variar entre as versões do kernel Linux e do 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 teclas podem aplicar mapeamentos diferentes dos indicados aqui.

Teclado HID e Página de Teclado (0x07)

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

Página do consumidor HID (0x0c)

Additional non-HID Mappings

These mappings describe functions that do not appear in HID but for which Linux key codes exist.

Legacy Unsupported Keys

These mappings appeared in previous versions of Android but were inconsistent with HID or used non-standard Linux key codes. They are no longer supported.

Notas

1. The Android key code associated with common alphanumeric and symbolic keys may vary based on the keyboard layout and language. For historical reasons, the physical scan codes and HID usages associated with keys on a keyboard are often defined positionally even though the labels printed on those keys may vary from one language to another.

   On a US English (QWERTY) keyboard, the top-left alphabetic key is labeled Q. On a French (AZERTY) keyboard, the key in the same position is labeled A. Despite the label, on both keyboards the top-left alphabetic key is referred to using the HID usage 0x07 0x0014 which is mapped to the Linux key code KEY_Q.

   When Android is configured with a US English keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_Q and will produce the characters 'Q' and 'q'. However, when Android is configured with a French keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_A and will produce the characters 'A' and 'a'.

   The Android key code typically reflects the language-specific interpretation of the key, so a different Android key code may be used for different languages.

2. 0x0c 0x022f AC Zoom is defined in the HID as a linear control but the kernel maps it as a key, which is probably incorrect.

3. The Linux function keys KEY_FN_* are mapped to simpler key codes but are dispatched with the META_FUNCTION meta state bit set to true.

4. Prior to Android Ice Cream Sandwich 4.0, the default key layout contained mappings for some extra key codes that were not defined in the mainline Linux kernel headers. These mappings have since been removed because these previously undefined key codes have since been assigned different meanings in more recent versions of the Linux kernel.

Sources

1. USB HID Usage Tables v1.12
2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java