Fichiers de disposition des touches

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

• Obligatoire pour les périphériques d'entrée internes (intégrés) avec des touches, y compris les touches spéciales telles que les touches de volume, de mise sous tension et les touches multimédias du casque.
• Facultatif pour les autres périphériques d'entrée, mais recommandé pour les claviers et joysticks à usage spécial.

Si aucun fichier de mise en page des touches spécifique à l'appareil n'est disponible, le système choisit une mise en page par défaut.

Position

Les fichiers de mise en page des touches sont situés par fournisseur USB, par ID de produit (et éventuellement de version) ou par nom de l'appareil 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 création d'un chemin d'accès au fichier contenant le nom de l'appareil, tous les caractères du nom de l'appareil, à l'exception de '0' à '9', 'a' à 'z', 'A' à 'Z', '-' ou '_', sont remplacés par '_'.

Fichier de disposition des 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 de touches est conçue pour être compatible avec divers claviers et joysticks externes standards. Ne modifiez pas la mise en page des clés génériques.

Syntaxe

Un fichier de mise en page de clé est un fichier au format texte brut composé de déclarations et d'indicateurs de clé ou d'axe.

Déclarations clés

Les déclarations de clés se composent du mot clé key, suivi d'un numéro de code de touche Linux et d'un nom de code de touche Android, ou de l'utilisation du mot clé, suivie d'une utilisation HID et d'un nom de code de touche Android. L'utilisation HID est représentée sous la forme d'un entier 32 bits, où les 16 bits supérieurs représentent la page d'utilisation HID et les 16 bits inférieurs représentent l'ID d'utilisation HID. Chacune de ces déclarations peut être suivie d'un ensemble facultatif d'indicateurs de stratégie délimités par des espaces blancs.

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 FUNCTION était également enfoncée.
• GESTURE: clé générée par un geste utilisateur, tel que la paume de la main sur l'écran tactile.
• VIRTUAL: la touche est une touche virtuelle (bouton capacitif) adjacente à l'écran tactile principal. Une logique de débouncing spéciale est alors activée (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 modificateurs qui contrôlent le comportement de l'axe, y compris au moins un nom de code d'axe Android.

Axes de base

Une 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, AXIS_X est définie sur 5.

Axes fractionnés

Une axe fractionné mappe un code d'axe Linux à 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 de la mise en correspondance. Ce mappage est utile lorsqu'une seule axe physique signalée par l'appareil encode deux axes logiques différents et exclusifs.

La déclaration suivante mappe les valeurs de l'axe ABS_Y (indiquées par 0x01) sur AXIS_GAS lorsqu'elles sont inférieures à 0x7f ou sur 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, AXIS_GAS est définie sur 2 (0x7f - 0x7d) et AXIS_BRAKE sur 0. À l'inverse, si la valeur de ABS_Y est 0x83, AXIS_GAS est définie sur 0 et AXIS_BRAKE sur 4 (0x83 - 0x7f). Enfin, si la valeur de ABS_Y est égale à la valeur de fractionnement de 0x7f, AXIS_GAS et AXIS_BRAKE sont définis sur 0.

Axes inversés

Une échelle inversée inverse le signe de la valeur de l'échelle. La déclaration suivante mappe ABS_RZ (indiqué par 0x05) sur AXIS_BRAKE (indiqué par BRAKE) et inverse la sortie en la niant.

axis 0x05 invert BRAKE

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

Option de plan plat au centre

En raison du bruit, un joystick peut signaler des événements d'entrée même lorsqu'il n'est pas utilisé. Ce bruit provient généralement des manettes de gauche et/ou de droite, et entraîne la transmission d'une valeur de position proche de 0 par le pilote. La valeur "center flat" spécifie le niveau de bruit à attendre du contrôleur au repos.

Le protocole d'entrée Linux permet aux pilotes d'appareils d'entrée de spécifier la valeur plate du centre des axes du joystick, mais tous les pilotes ne le signalent pas et certains 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 à considérer comme centrée.

Par exemple, si un pilote d'appareil indique des valeurs pour AXIS_X comprises entre 0 et 100, 0 sera mappé sur -1 et 100 sur 1 par le système d'entrée Android. Le centre de la plage sera de 50 dans les coordonnées non mises à l'échelle et de 0 dans les coordonnées mises à l'échelle. Si une valeur plate est égale à 10, 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 étalées) est du bruit et traiter ces valeurs provenant du joystick comme nulles.

Remarque: Bien que le fichier de mise en page des touches spécifie la valeur pour l'espace de coordonnées du pilote, la valeur indiqué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 de la position centrale est définie sur 4096.

Commentaires

Les lignes de commentaire commencent par # et se poursuivent 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...

Commandes 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édias du connecteur 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

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

Touches virtuelles

Le système de saisie fournit des fonctionnalités spéciales pour implémenter des touches virtuelles dans les cas d'utilisation suivants:

1. Si les touches virtuelles sont affichées graphiquement à l'écran (comme sur le Galaxy Nexus), elles sont implémentées par le composant de la barre de navigation dans le package d'UI système. Étant donné que les touches virtuelles graphiques sont implémentées à un niveau élevé du système, les fichiers de mise en page des touches ne sont pas concernés et les informations suivantes ne s'appliquent pas.
2. Si les touches 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 de saisie utilise un fichier de mappage de touches virtuel pour traduire les coordonnées tactiles X/Y en codes de touche Linux, puis le fichier de mise en page des touches pour traduire les codes de touche Linux en codes de touche Android (pour en savoir plus sur les fichiers de mappage de touches virtuels, consultez la section Appareils tactiles). Le fichier de mise en page 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 virtuelles sont implémentées en tant que boutons capacitifs distincts de l'écran tactile principal (comme sur le Nexus S), le pilote de périphérique du noyau ou le micrologiciel est chargé de traduire les pressions en codes de touche Linux, que le système de saisie traduit ensuite en codes de touche Android à l'aide du fichier de mise en page des touches. Le fichier de mise en page des touches du périphérique d'entrée à boutons capacitifs doit spécifier le mappage de touches approprié et inclure l'indicateur VIRTUAL pour chaque touche.

Lorsque les touches virtuelles se trouvent à l'intérieur ou à proximité de l'écran tactile, les utilisateurs peuvent facilement appuyer accidentellement sur un bouton lorsqu'ils touchent l'écran en bas ou lorsqu'ils glissent leur doigt de haut en bas ou de bas en haut. Pour éviter cela, le système d'entrée applique un petit débouncing afin que les pressions sur les touches virtuelles soient ignorées pendant une courte période après le dernier appui sur l'écran tactile (ce délai est appelé temps de pause des touches virtuelles).

Pour activer le débogage des touches virtuelles:

1. Fournissez un fichier de mise en page de 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 pause de la touche virtuelle dans une superposition de ressources pour la ressource config.xml du 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>
   

Validation

Vous devez valider vos fichiers de disposition des touches à l'aide de l'outil Valider les claviers.