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 (embutidos) 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 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 de USB, id de produto (e opcionalmente versão) ou por nome de 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 que não sejam '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 interno 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 palavra-chave key seguida por um número de código de chave Linux e um nome de código de chave Android, ou o uso de palavra-chave seguido por um uso HID e um nome de código de chave 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 FUNÇÃO também fosse pressionada. -
GESTURE: A tecla gerada por um gesto do usuário, como a palma da mão na tela sensível ao toque. -
VIRTUAL: A tecla é uma tecla programável virtual (botão capacitivo) adjacente à tela de toque principal. Isso faz com que a lógica de debouncing especial 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 seguinte declaração 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 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. Esse mapeamento é útil quando um único eixo físico relatado pelo dispositivo codifica dois eixos lógicos diferentes 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 é definido como 2 ( 0x7f - 0x7d ) e AXIS_BRAKE é 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 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 negando-a.
axis 0x05 invert BRAKE
No exemplo acima, se o valor de ABS_RZ for 2 , AXIS_BRAKE será definido como -2 .
Opção plana central
Um dispositivo de 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 manípulos esquerdo e/ou direito e faz com que o motorista relate um valor de posição próximo a 0. O valor "center flat" especifica a quantidade de ruído a ser 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 relatam isso 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 considerado centralizado.
Por exemplo, se um driver de dispositivo relatar valores para AXIS_X entre 0 e 100, então 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 sem escala) é ruído e tratar esses valores provenientes do joystick como zero.
Observação : 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 do Android.
axis 0x03 Z flat 4096
No exemplo acima, o valor central plano é 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 do 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 implementar teclas programáveis virtuais nos seguintes casos de uso:
- Se as teclas programáveis virtuais forem exibidas graficamente na tela (como no Galaxy Nexus), elas serão implementadas pelo componente Navigation Bar 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.
- Se as teclas programáveis 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 teclas do Linux, em seguida, usa o arquivo de layout de teclas para converter os códigos de teclas do Linux em códigos de teclas do Android (para obter detalhes sobre arquivos de mapa de teclas virtuais, consulte Dispositivos de toque ). O arquivo de layout de tecla para o dispositivo de entrada de tela sensível ao toque deve especificar o mapeamento de tecla apropriado e incluir o sinalizador
VIRTUALpara cada tecla. - Se as teclas programáveis virtuais forem implementadas como botões capacitivos separados da tela de toque principal (como no Nexus S), o driver do dispositivo do kernel ou o firmware será responsável por traduzir os toques em códigos-chave do Linux que o sistema de entrada traduz em códigos-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
VIRTUALpara cada tecla.
Quando as teclas programáveis virtuais estão localizadas dentro ou próximas fisicamente da tela sensível ao toque, é fácil para os usuários pressionar acidentalmente um botão ao tocar próximo à parte inferior da tela ou ao deslizar o dedo de cima para baixo ou de baixo para baixo. superior na tela. Para evitar isso, o sistema de entrada aplica um pouco de debounce, de modo que os pressionamentos de tecla programável virtual sejam ignorados por um breve período de tempo após o toque mais recente na tela sensível ao toque (esse atraso é chamado de tempo de inatividade da tecla virtual ).
Para habilitar o debouncing de tecla programável virtual:
- Forneça um arquivo de layout de tecla para a tela sensível ao toque ou dispositivo de entrada de botão capacitivo com o sinalizador
VIRTUALdefinido para cada tecla.key 139 MENU VIRTUAL key 172 HOME VIRTUAL key 158 BACK VIRTUAL key 217 SEARCH VIRTUAL
- Configure o valor do tempo de inatividade da chave virtual em uma sobreposição de recurso para o recurso
config.xmlda 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 .