Fichiers de mise en page des clés

Les fichiers de disposition des touches (fichiers .kl ) mappent les codes de clé et les codes d'axe Linux aux codes de clé et aux codes d'axe Android et spécifient les indicateurs de stratégie associés. Les fichiers de disposition des touches spécifiques à l'appareil sont :

  • Requis pour les périphériques d'entrée internes (intégrés) dotés de touches, y compris les touches spéciales telles que les touches de volume, d'alimentation et multimédia du casque.
  • Facultatif pour d’autres périphériques d’entrée mais recommandé pour les claviers et joysticks à usage spécial.

Si aucun fichier de disposition de touches spécifique au périphérique n'est disponible, le système choisit une configuration par défaut à la place.

Emplacement

Les fichiers de disposition des touches sont localisés par fournisseur USB, identifiant de produit (et éventuellement de version) ou par nom de périphérique d'entrée. Les chemins suivants sont consultés dans l'ordre :

  • /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

Lors de la construction d'un chemin de fichier contenant le nom du périphérique, tous les caractères du nom du périphérique autres que « 0 » - « 9 », « a » - « z », « A » - « Z », « - » ou « _ » sont remplacés par '_'.

Fichier de disposition de touches générique

Le système fournit un fichier de disposition de touches générique intégré spécial appelé Generic.kl . Cette disposition des touches est destinée à prendre en charge une variété de claviers et de joysticks externes standard. Ne modifiez pas la disposition des touches génériques !

Syntaxe

Un fichier de disposition de touches est un fichier texte brut composé de déclarations et d'indicateurs de touches ou d'axes.

Déclarations clés

Les déclarations de clé se composent du mot-clé key suivi d'un numéro de code de clé Linux et d'un nom de code de clé Android, ou de l'utilisation du mot-clé suivi d'une utilisation HID et d'un nom de code de clé Android. L'utilisation du HID est représentée par un entier de 32 bits, où les 16 bits de poids fort représentent la page d'utilisation du HID et les 16 bits de poids faible représentent l'ID d'utilisation du HID. L'une ou l'autre déclaration peut être suivie d'un ensemble facultatif d'indicateurs de politique délimités par des espaces.

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

Les indicateurs de stratégie suivants sont reconnus :

  • FUNCTION : La touche doit être interprétée comme si la touche FONCTION était également enfoncée.
  • GESTURE : la clé générée par un geste de l'utilisateur, tel que toucher l'écran tactile.
  • VIRTUAL : La touche est une touche programmable virtuelle (bouton capacitif) adjacente à l'écran tactile principal. Cela entraîne l'activation d'une logique anti-rebond spéciale (voir ci-dessous).

Déclarations d'axe

Les déclarations d'axe se composent chacune du mot-clé axis suivi d'un numéro de code d'axe Linux et de qualificatifs qui contrôlent le comportement de l'axe, y compris au moins un nom de code d'axe Android.

Axes de base

Un axe de base mappe simplement un code d'axe Linux à un nom de code d'axe Android. La déclaration suivante mappe ABS_X (indiqué par 0x00 ) à AXIS_X (indiqué par X ).

axis 0x00 X

Dans l'exemple ci-dessus, si la valeur de ABS_X est 5 alors AXIS_X est défini sur 5 .

Diviser les axes

Un axe divisé mappe un code d'axe Linux sur deux noms de code d'axe Android, de sorte que les valeurs inférieures ou supérieures à un seuil soient réparties sur deux axes différents lors du mappage. Ce mappage est utile lorsqu'un seul axe physique signalé par l'appareil code deux axes logiques différents et mutuellement exclusifs.

La déclaration suivante mappe les valeurs de l'axe ABS_Y (indiquées par 0x01 ) à AXIS_GAS lorsqu'elles sont inférieures à 0x7f ou à AXIS_BRAKE lorsqu'elles sont supérieures à 0x7f .

axis 0x01 split 0x7f GAS BRAKE

Dans l'exemple ci-dessus, si la valeur de ABS_Y est 0x7d alors AXIS_GAS est défini sur 2 ( 0x7f - 0x7d ) et AXIS_BRAKE est défini sur 0 . Inversement, si la valeur de ABS_Y est 0x83 alors AXIS_GAS est défini sur 0 et AXIS_BRAKE est défini sur 4 ( 0x83 - 0x7f ). Enfin, si la valeur de ABS_Y est égale à la valeur de division de 0x7f alors AXIS_GAS et AXIS_BRAKE sont définis sur 0 .

Axes inversés

Un axe inversé inverse le signe de la valeur de l'axe. La déclaration suivante mappe ABS_RZ (indiqué par 0x05 ) à AXIS_BRAKE (indiqué par BRAKE ) et inverse la sortie en l'annulant.

axis 0x05 invert BRAKE

Dans l'exemple ci-dessus, si la valeur de ABS_RZ est 2 alors AXIS_BRAKE est défini sur -2 .

Option appartement central

Un dispositif à joystick peut signaler des événements d'entrée même lorsque le joystick n'est pas utilisé, en raison du bruit. Ce bruit provient généralement des joysticks gauche et/ou droit et amène le conducteur à signaler une valeur de position proche de 0. La valeur « centre plat » spécifie la quantité de bruit à attendre du contrôleur au repos.

Le protocole d'entrée Linux permet aux pilotes de périphérique d'entrée de spécifier la valeur centrale plate des axes du joystick, mais tous les pilotes ne le signalent pas et certains d'entre eux fournissent des valeurs incorrectes. Pour résoudre ce problème, une déclaration d'axe peut être suivie d'une option flat qui spécifie la largeur de la région autour de la position centrale de l'axe qui doit être considérée comme centrée.

Par exemple, si un pilote de périphérique signale des valeurs pour AXIS_X comprises entre 0 et 100, alors 0 sera mappé à -1 et 100 sera mappé à 1 par le système de saisie Android. Le centre de la plage sera 50 dans les coordonnées non mises à l'échelle et 0 dans les coordonnées mises à l'échelle. Si une valeur plate est égale à 10, alors les développeurs doivent supposer que toute valeur AXIS_X signalée entre -0,1 et 0,1 (entre 40 et 60 en coordonnées non mises à l'échelle) est du bruit et traiter ces valeurs provenant du joystick comme nulles.

Remarque : alors que le fichier de disposition des touches spécifie la valeur de l'espace de coordonnées du pilote, la valeur rapportée par android.view.InputDevice.MotionRange#getFlat() se trouve dans l'espace de coordonnées Android.

axis 0x03 Z flat 4096

Dans l'exemple ci-dessus, la valeur centrale plate est définie sur 4096 .

commentaires

Les lignes de commentaires commencent par # et continuent jusqu'à la fin de la ligne :

# A comment!

Les lignes vides sont ignorées.

Exemples

Clavier

# 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...

Contrôles du système

# 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

Boutons capacitifs

# 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

Commandes multimédia de la prise casque

# 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

Manette

# 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

Touches programmables virtuelles

Le système de saisie offre des fonctionnalités spéciales pour la mise en œuvre de touches programmables virtuelles dans les cas d'utilisation suivants :

  1. Si les touches programmables virtuelles sont affichées graphiquement à l'écran (comme sur le Galaxy Nexus), elles sont implémentées par le composant Barre de navigation du package System UI. Étant donné que les touches programmables virtuelles graphiques sont implémentées à un niveau supérieur du système, les fichiers de disposition des touches ne sont pas impliqués et les informations suivantes ne s'appliquent pas.
  2. Si les touches programmables virtuelles sont implémentées en tant que région tactile étendue faisant partie de l'écran tactile principal (comme sur le Nexus One), le système d'entrée utilise un fichier de mappage de touches virtuelles pour traduire les coordonnées tactiles X/Y en codes de touches Linux. utilise ensuite le fichier de disposition des touches pour traduire les codes de touches Linux en codes de touches Android (pour plus de détails sur les fichiers de mappage de touches virtuelles, voir Appareils tactiles ). Le fichier de disposition des touches du périphérique d'entrée à écran tactile doit spécifier le mappage de touches approprié et inclure l'indicateur VIRTUAL pour chaque touche.
  3. Si les touches programmables virtuelles sont implémentées sous forme de boutons capacitifs distincts de l'écran tactile principal (comme sur le Nexus S), le pilote de périphérique ou le micrologiciel du noyau est responsable de la traduction des touches en codes de touches Linux que le système d'entrée traduit ensuite en codes de touches Android. en utilisant le fichier de disposition des touches. Le fichier de disposition des touches pour le périphérique d'entrée à bouton capacitif doit spécifier le mappage de touches approprié et inclure l'indicateur VIRTUAL pour chaque touche.

Lorsque les touches programmables virtuelles sont situées à l'intérieur ou à proximité physique de l'écran tactile, il est facile pour les utilisateurs d'appuyer accidentellement sur un bouton en touchant près du bas de l'écran ou en faisant glisser un doigt de haut en bas ou de bas en haut. en haut de l'écran. Pour éviter cela, le système de saisie applique un léger anti-rebond de sorte que les pressions sur les touches programmables virtuelles sont ignorées pendant une brève période après le contact le plus récent sur l'écran tactile (ce délai est appelé temps de silence des touches virtuelles ).

Pour activer l'anti-rebond des touches programmables virtuelles :

  1. Fournissez un fichier de disposition des touches pour l'écran tactile ou le périphérique d'entrée à bouton capacitif avec l'indicateur VIRTUAL défini pour chaque touche.
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. Définissez la valeur du temps de repos de la clé virtuelle dans une superposition de ressources pour la ressource framework config.xml .
    <!-- 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>

Validation

Vous devez valider vos fichiers de disposition de touches à l'aide de l'outil Validate Keymaps .