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 chave específicos do dispositivo são:

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

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

Localização

Os arquivos de layout de chave 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érico

O sistema fornece um arquivo de layout de chave genérico embutido especial 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 de chave genérico!

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 de chave

As declarações de chave consistem na chave de palavra- key seguida por um número de código de chave do Linux e um nome de código de chave do Android, ou o uso de palavra-chave seguido por um uso de HID e um nome de código de chave do Android. O uso HID é representado como um inteiro de 32 bits, onde os 16 bits altos representam a página de uso HID e os 16 bits baixos representam o ID de uso 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 estivesse pressionada.
  • GESTURE : A chave gerada por um gesto do usuário, como palma da mão na tela sensível ao toque.
  • VIRTUAL : A tecla é uma tecla virtual virtual (botão capacitivo) adjacente à tela de toque principal. Isso faz com que a lógica de debounce especial seja habilitada (veja abaixo).

Declarações do 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 reportado pelo dispositivo codifica dois eixos lógicos diferentes mutuamente exclusivos.

A declaração a seguir mapeia os 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 igual ao valor de divisão de 0x7f , então AXIS_GAS e AXIS_BRAKE sã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 relatar eventos de entrada mesmo quando o joystick não está sendo usado, devido ao ruído. Esse ruído geralmente vem dos sticks 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 dispositivo de entrada especificarem o valor plano central dos eixos do joystick, mas nem todos os drivers o relatam 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 em torno da posição central do eixo que deve ser considerado como centralizado.

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 plano 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 não dimensionadas) é ruído e tratar esses valores provenientes do joystick como zero.

Observação : enquanto o arquivo de layout de chave especifica 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 do Android.

axis 0x03 Z flat 4096

No exemplo acima, o valor plano central é 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 virtuais virtuais

O sistema de entrada fornece recursos especiais para implementar 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 de IU do sistema. Como as teclas 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 de 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 teclas do Linux, em seguida, usa o arquivo de layout de chave para traduzir códigos de chave do Linux em códigos de chave do Android (para obter detalhes sobre arquivos de mapa de chave virtual, consulte Dispositivos de toque ). O arquivo de layout de teclas para o dispositivo de entrada da tela de 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 do kernel é responsável por traduzir os toques em códigos de chave do Linux que o sistema de entrada traduz em códigos de chave do Android usando o arquivo de layout de chave. O arquivo de layout de tecla para o dispositivo de entrada de botão capacitivo deve especificar o mapeamento de tecla apropriado e incluir o sinalizador VIRTUAL para cada tecla.

Quando as teclas virtuais virtuais estão localizadas dentro ou próximas fisicamente 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 superior na tela. Para evitar isso, o sistema de entrada aplica um pequeno debouncing de modo que os pressionamentos de tecla virtual virtual 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 habilitar o debounce de tecla virtual:

  1. Forneça um arquivo de layout de tecla para a tela de 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. Defina o valor do tempo de silêncio da chave virtual em uma sobreposição de recurso 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 chave usando a ferramenta Validate Keymaps .