A partir de 27 de março de 2025, recomendamos usar android-latest-release em vez de aosp-main para criar e contribuir com o AOSP. Para mais informações, consulte Mudanças no AOSP.

Esta página foi traduzida pela API Cloud Translation.

Arquivos de layout de chaves

Os arquivos de layout de teclas (arquivos .kl) mapeiam os códigos de teclas e de eixos do Linux para os códigos de teclas e de eixos do Android e especificam as flags de política associadas. Os arquivos de layout de teclas específicos do dispositivo são:

Obrigatório para dispositivos de entrada internos (integrados) com teclas, incluindo teclas especiais, como volume, energia e teclas de mídia de fones de ouvido.
Opcional para outros dispositivos de entrada, mas recomendado para teclas e joysticks de uso especial.

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

Local

Os arquivos de layout de teclas são localizados pelo fornecedor USB, pelo ID do produto (e, opcionalmente, da versão) ou pelo nome do dispositivo de entrada. Os seguintes caminhos são consultados em ordem:

/odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
/odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl
/odm/usr/keylayout/DEVICE_NAME.kl
/vendor/usr/keylayout/DEVICE_NAME.kl
/system/usr/keylayout/DEVICE_NAME.kl
/data/system/devices/keylayout/DEVICE_NAME.kl
/odm/usr/keylayout/Generic.kl
/vendor/usr/keylayout/Generic.kl
/system/usr/keylayout/Generic.kl
/data/system/devices/keylayout/Generic.kl

Ao criar um caminho de arquivo que contém o nome do dispositivo, todos os caracteres no nome do dispositivo, exceto "0"-"9", "a"-"z", "A"-"Z", "-" ou "_" são substituídos por "_".

Arquivo de layout de chave genérica

O sistema oferece um arquivo de layout de chave genérica integrado especial chamado Generic.kl. Esse layout de teclas tem como objetivo oferecer suporte a vários teclados externos e joysticks padrão. Não modifique o layout da chave genérica.

Sintaxe

Um arquivo de layout de chave é um arquivo de texto simples que consiste em declarações de chave ou eixo e flags.

Declarações de chaves

As declarações de chave consistem na palavra-chave key seguida de um número de código de chave Linux e nome de código de chave Android, ou o uso da palavra-chave seguido de um uso de HID e nome de código de chave Android. O uso do HID é representado como um número inteiro de 32 bits, em que os 16 bits mais altos representam a página de uso do HID e os 16 bits mais baixos representam o ID de uso do HID. Cada declaração pode ser seguida por um conjunto opcional de flags de política delimitadas por espaços em branco.

key 1     ESCAPE
key 114   VOLUME_DOWN
key 16    Q                 VIRTUAL
key usage 0x0c006F          BRIGHTNESS_UP

As seguintes flags de política são reconhecidas:

FUNCTION: a tecla precisa ser interpretada como se a tecla FUNCTION também estivesse sendo pressionada.
GESTURE: a chave gerada por um gesto do usuário, como tocar na tela touchscreen.
VIRTUAL: a chave é uma chave virtual (botão capacitivo) adjacente à tela touch principal. Isso faz com que a lógica de debouncing especial seja ativada (confira abaixo).

Declarações de eixo

Cada declaração de eixo consiste na palavra-chave axis seguida por um número de código de eixo do Linux e qualificadores que controlam o comportamento do eixo, incluindo pelo menos um nome de código de eixo do Android.

Eixos básicos

Um eixo básico simplesmente mapeia um código de eixo do Linux para um nome de código de eixo do Android. A declaração a seguir mapeia ABS_X (indicado por 0x00) para AXIS_X (indicado por X).

axis 0x00 X

No exemplo acima, se o valor de ABS_X for 5, AXIS_X será definido como 5.

Dividir eixos

Um eixo dividido mapeia um código de eixo do Linux para dois nomes de código de eixo do Android, de modo que valores menores ou maiores que um limite sejam divididos em dois eixos diferentes quando mapeados. Esse mapeamento é útil quando um único eixo físico informado pelo dispositivo codifica dois eixos lógicos diferentes e mutuamente exclusivos.

A declaração a seguir mapeia os valores do eixo ABS_Y (indicados por 0x01) para AXIS_GAS quando for menor que 0x7f ou para AXIS_BRAKE quando for maior que 0x7f.

axis 0x01 split 0x7f GAS BRAKE

No exemplo acima, se o valor de ABS_Y for 0x7d, AXIS_GAS será definido como 2 (0x7f - 0x7d) e AXIS_BRAKE será definido como 0. Por outro lado, se o valor de ABS_Y for 0x83, AXIS_GAS será definido como 0 e AXIS_BRAKE será definido como 4 (0x83 - 0x7f). Por fim, se o valor de ABS_Y for igual ao valor de divisão de 0x7f, AXIS_GAS e AXIS_BRAKE serão definidos como 0.

Eixos invertidos

Um eixo invertido inverte o sinal do valor do eixo. A declaração a seguir mapeia ABS_RZ (indicado por 0x05) para AXIS_BRAKE (indicado por BRAKE) e inverte a saída, anulando-a.

axis 0x05 invert BRAKE

No exemplo acima, se o valor de ABS_RZ for 2, AXIS_BRAKE será definido como -2.

Opção de apartamento no centro

Um dispositivo joystick pode informar eventos de entrada mesmo quando não está sendo usado, devido ao ruído. Esse ruído normalmente vem dos sticks esquerdo e/ou direito e faz com que o driver informe um valor de posição próximo a 0. O valor "central plana" especifica a quantidade de ruído esperada do controlador em repouso.

O protocolo de entrada do Linux oferece uma maneira de os drivers de dispositivo de entrada especificarem o valor de plano central dos eixos do joystick, mas nem todos os drivers o informam e alguns deles fornecem valores incorretos. Para resolver esse problema, uma declaração de eixo pode ser seguida por uma opção flat que especifica a largura da região ao redor da posição central do eixo que deve ser considerada como centralizada.

Por exemplo, se um driver de dispositivo informar valores de AXIS_X entre 0 e 100, o sistema de entrada do Android vai mapear 0 para -1 e 100 para 1. O centro do intervalo será 50 nas coordenadas sem escalonamento e 0 nas coordenadas escalonadas. Se um valor plano for igual a 10, os desenvolvedores vão presumir que qualquer valor de AXIS_X informado entre -0,1 e 0,1 (entre 40 e 60 em coordenadas não dimensionadas) é ruído e tratar esses valores provenientes do joystick como zero.

Observação: embora o arquivo de layout de chaves especifique o valor para o espaço de coordenadas do driver, o valor informado por android.view.InputDevice.MotionRange#getFlat() está no espaço de coordenadas do Android.

axis 0x03 Z flat 4096

No exemplo acima, o valor da área central é definido como 4096.

Comentários

As linhas de comentário começam com # e continuam até o final da linha:

# A comment!

As linhas em branco são ignoradas.

Exemplos

Teclado

# This is an example of a key layout file for a keyboard.

key 1     ESCAPE
key 2     1
key 3     2
key 4     3
key 5     4
key 6     5
key 7     6
key 8     7
key 9     8
key 10    9
key 11    0
key 12    MINUS
key 13    EQUALS
key 14    DEL

# etc...

Controles do sistema

# This is an example of a key layout file for basic system controls,
# such as volume and power keys which are typically implemented as GPIO pins
# the device decodes into key presses.

key 114   VOLUME_DOWN
key 115   VOLUME_UP
key 116   POWER

Botões capacitivos

# This is an example of a key layout file for a touch device with capacitive buttons.

key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL

Controles de mídia da entrada para fone de ouvido

# This is an example of a key layout file for headset mounted media controls.
# A typical headset jack interface might have special control wires or detect known
# resistive loads as corresponding to media functions or volume controls.
# This file assumes that the driver decodes these signals and reports media
# controls as key presses.

key 163   MEDIA_NEXT
key 165   MEDIA_PREVIOUS
key 226   HEADSETHOOK

Joystick

# This is an example of a key layout file for a joystick.

# These are the buttons that the joystick supports, represented as keys.
key 304   BUTTON_A
key 305   BUTTON_B
key 307   BUTTON_X
key 308   BUTTON_Y
key 310   BUTTON_L1
key 311   BUTTON_R1
key 314   BUTTON_SELECT
key 315   BUTTON_START
key 316   BUTTON_MODE
key 317   BUTTON_THUMBL
key 318   BUTTON_THUMBR

# Left and right stick.
# The reported value for flat is 128 in a range of -32767 to 32768, which is absurd.
# This confuses applications that rely on the flat value because the joystick
# actually settles in a flat range of +/- 4096 or so. We override it here.
axis 0x00 X flat 4096
axis 0x01 Y flat 4096
axis 0x03 Z flat 4096
axis 0x04 RZ flat 4096

# Triggers.
axis 0x02 LTRIGGER
axis 0x05 RTRIGGER

# Hat.
axis 0x10 HAT_X
axis 0x11 HAT_Y

Teclas virtuais

O sistema de entrada oferece recursos especiais para implementar teclas virtuais nos seguintes casos de uso:

Se as teclas virtuais forem mostradas graficamente na tela (como no Galaxy Nexus), elas serão implementadas pelo componente da barra de navegação no pacote da interface do sistema. Como as teclas virtuais gráficas são implementadas em uma camada alta do sistema, os arquivos de layout de teclas não são envolvidos e as informações a seguir não se aplicam.
Se as teclas virtuais forem implementadas como uma região sensível ao toque estendida que faz parte da tela de toque principal (como no Nexus One), o sistema de entrada usa um arquivo de mapa de teclas virtuais para traduzir as coordenadas de toque X/Y em códigos de tecla do Linux e, em seguida, usa o arquivo de layout de teclas para traduzir os códigos de tecla do Linux em códigos de tecla do Android. Para saber mais sobre arquivos de mapa de teclas virtuais, consulte Dispositivos com tela touch. O arquivo de layout de teclas do dispositivo de entrada da tela touch precisa especificar o mapeamento de teclas apropriado e incluir a flag VIRTUAL para cada tecla.
Se as teclas virtuais flexíveis forem implementadas como botões capacitivos separados da tela touch principal (como no Nexus S), o driver de dispositivo do kernel ou o firmware será responsável por traduzir toques em códigos de teclas do Linux, que o sistema de entrada vai traduzir em códigos de teclas do Android usando o arquivo de layout de teclas. O arquivo de layout de teclas para o dispositivo de entrada de botão capacitivo precisa especificar o mapeamento de teclas apropriado e incluir a flag VIRTUAL para cada tecla.

Quando as teclas virtuais estão localizadas dentro ou em proximidade física da tela sensível ao toque, é fácil para os usuários pressionarem um botão acidentalmente ao tocar perto da parte de baixo da tela ou ao deslizar um dedo de cima para baixo ou de baixo para cima na tela. Para evitar isso, o sistema de entrada aplica uma pequena debounce, de modo que as pressões de teclas virtuais sejam ignoradas por um breve período após o toque mais recente na tela sensível ao toque. Esse atraso é chamado de tempo de silêncio da tecla virtual.

Para ativar o debouncing da tecla virtual:

Forneça um arquivo de layout de teclas para a tela touchscreen ou o dispositivo de entrada com a flag VIRTUAL definida para cada tecla.

key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL

Define o valor do tempo de silêncio da chave virtual em uma sobreposição de recursos para o recurso config.xml do framework.

<!-- Specifies the amount of time to disable virtual keys after the screen
is touched to filter out accidental virtual key presses due to swiping gestures
or taps near the edge of the display. May be 0 to disable the feature.
It is recommended that this value be no more than 250 ms.
This feature should be disabled for most devices. -->

<integer name="config_virtualKeyQuietTimeMillis">250</integer>

Validação

Valide seus arquivos de layout de teclas usando a ferramenta Validar mapeamentos de teclas.