Arquivos de layout de chave

Arquivos de layout de chave (arquivos .kl ) mapeiam códigos de chave e códigos de eixo do Linux para códigos de chave e códigos de eixo do Android e especificam sinalizadores de política associados. Os arquivos de layout de teclas específicos do dispositivo são:

  • Necessário para dispositivos de entrada internos (integrados) com teclas, incluindo teclas especiais, como volume, energia e teclas de mídia do fone de ouvido.
  • Opcional para outros dispositivos de entrada, mas recomendado para teclados e joysticks para fins especiais.

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

Localização

Os principais arquivos de layout 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/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 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 layout de chave genérica

O sistema fornece um arquivo especial de layout de chave genérico integrado chamado Generic.kl . Este layout de teclas destina-se a suportar uma variedade de teclados e joysticks externos padrão. Não modifique o layout genérico das teclas!

Sintaxe

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

Declarações principais

As declarações de chave consistem na palavra-chave key seguida por um número de código-chave do Linux e um nome de código-chave do Android, ou o uso da palavra-chave seguido por um uso de HID e um nome de código-chave do Android. O uso do HID é representado como um número inteiro de 32 bits, onde 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. Qualquer declaração pode ser seguida por um conjunto opcional de sinalizadores de política delimitados por espaços em branco.

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

Os seguintes sinalizadores de política são reconhecidos:

  • FUNCTION : A tecla deve ser interpretada como se a tecla FUNCTION também tivesse sido pressionada.
  • GESTURE : A tecla gerada por um gesto do usuário, como palmar a tela sensível ao toque.
  • VIRTUAL : A tecla é uma tecla virtual (botão capacitivo) adjacente à tela de toque principal. Isso faz com que a lógica especial de depuração seja habilitada (veja 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 Linux e qualificadores que controlam o comportamento do eixo, incluindo pelo menos um nome de código de eixo Android.

Eixos básicos

Um eixo básico simplesmente mapeia um código de eixo Linux para um nome de código de eixo 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 então AXIS_X será definido como 5 .

Eixos divididos

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

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

axis 0x01 split 0x7f GAS BRAKE

No exemplo acima, se o valor de ABS_Y for 0x7d então 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 então AXIS_GAS será definido como 0 e AXIS_BRAKE será definido como 4 ( 0x83 - 0x7f ). Finalmente, se o valor de ABS_Y for igual ao valor de divisão de 0x7f , então 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 negando-a.

axis 0x05 invert BRAKE

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

Opção plana central

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

O protocolo de entrada do Linux fornece uma maneira para os drivers de dispositivos de entrada especificarem o valor central plano dos eixos do joystick, mas nem todos os drivers relatam isso e alguns deles fornecem valores incorretos. Para resolver este problema, uma declaração de eixo pode ser seguida por uma opção flat que especifica a largura da região em torno da posição central do eixo que deve ser considerada centralizada.

Por exemplo, se um driver de dispositivo relatar valores para AXIS_X entre 0 e 100, 0 será mapeado para -1 e 100 será mapeado para 1 pelo sistema de entrada do Android. O centro do intervalo será 50 nas coordenadas sem escala e 0 nas coordenadas com escala. Se um valor fixo for igual a 10, os desenvolvedores devem assumir que qualquer valor AXIS_X relatado entre -0,1 e 0,1 (entre 40 e 60 em coordenadas sem escala) é ruído e tratar esses valores provenientes do joystick como zero.

Nota : Embora o arquivo de layout de chave especifique o valor para o espaço de coordenadas do driver, o valor relatado por android.view.InputDevice.MotionRange#getFlat() está no espaço de coordenadas Android.

axis 0x03 Z flat 4096

No exemplo acima, o valor central fixo é definido como 4096 .

Comentários

As linhas de comentários 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 do conector de 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

Controle de video game

# 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 programáveis ​​virtuais

O sistema de entrada fornece recursos especiais para implementação de teclas virtuais nos seguintes casos de uso:

  1. Se as teclas virtuais forem exibidas graficamente na tela (como no Galaxy Nexus), elas serão implementadas pelo componente Barra de Navegação no pacote System UI. Como as teclas programáveis ​​virtuais gráficas são implementadas em uma camada superior do sistema, os arquivos de layout de teclas não estão envolvidos e as informações a seguir não se aplicam.
  2. Se as teclas virtuais forem implementadas como uma região tocável 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 teclas do Linux, em seguida, usa o arquivo de layout de teclas para traduzir códigos de teclas do Linux em códigos de teclas do Android (para obter detalhes sobre arquivos de mapas de teclas virtuais, consulte Dispositivos Touch ). O arquivo de layout de teclas para o dispositivo de entrada da tela sensível ao toque deve especificar o mapeamento de teclas apropriado e incluir o sinalizador VIRTUAL para cada tecla.
  3. Se as teclas virtuais forem implementadas como botões capacitivos separados da tela de toque principal (como no Nexus S), o driver ou firmware do dispositivo kernel é responsável por traduzir os toques em códigos de chave do Linux que o sistema de entrada então traduz em códigos de chave do Android usando o arquivo de layout de chave. O arquivo de layout de teclas para o dispositivo de entrada de botão capacitivo deve especificar o mapeamento de teclas apropriado e incluir o sinalizador VIRTUAL para cada tecla.

Quando as teclas virtuais estão localizadas dentro ou nas proximidades físicas da tela sensível ao toque, é fácil para os usuários pressionarem acidentalmente um botão ao tocar próximo à parte inferior da tela ou ao deslizar um dedo de cima para baixo ou de baixo para baixo. superior na tela. Para evitar isso, o sistema de entrada aplica um pequeno debounce de modo que os pressionamentos de teclas virtuais sejam ignorados por um breve período de tempo após o toque mais recente na tela de toque (esse atraso é chamado de tempo de silêncio da tecla virtual ).

Para ativar a eliminação de teclas virtuais:

  1. Forneça um arquivo de layout de teclas para a tela sensível ao toque ou dispositivo de entrada de botão capacitivo com o sinalizador VIRTUAL definido para cada tecla.
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. Configure o valor do tempo de silêncio da chave virtual em uma sobreposição de recursos para o recurso config.xml da estrutura.
    <!-- 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

Você deve validar seus arquivos de layout de teclas usando a ferramenta Validar mapas de teclas .