Périphériques clavier

Android prend en charge une variété de claviers, notamment des claviers à fonctions spéciales (commandes de volume et d'alimentation), des claviers QWERTY intégrés compacts et des claviers externes de style PC complets.

Ce document décrit uniquement les claviers physiques. Reportez-vous au SDK Android pour plus d'informations sur les claviers logiciels (éditeurs de méthodes de saisie).

Classement du clavier

Un périphérique d'entrée est classé comme clavier si l'une des conditions suivantes est remplie :

• Le périphérique d'entrée signale la présence de tous les codes de touches Linux utilisés sur les claviers, notamment 0 à 0xff ou KEY_OK à KEY_MAX .

• Le périphérique d'entrée signale la présence de tous les codes de clé Linux utilisés sur les joysticks et les manettes de jeu, notamment BTN_0 à BTN_9 , BTN_TRIGGER à BTN_DEAD ou BTN_A à BTN_THUMBR .

Les joysticks sont actuellement classés comme claviers car les boutons du joystick et de la manette de jeu sont signalés par les événements EV_KEY de la même manière que les touches du clavier. Ainsi, les joysticks et les manettes de jeu utilisent également des fichiers de cartes clés pour la configuration.

Une fois qu'un périphérique d'entrée a été classé comme clavier, le système charge le fichier de configuration du périphérique d'entrée et la disposition du clavier pour le clavier.

Le système tente ensuite de déterminer des caractéristiques supplémentaires de l'appareil.

• Si le périphérique d'entrée possède des touches mappées à KEYCODE_Q , alors le périphérique est considéré comme disposant d'un clavier alphabétique (par opposition à numérique). La fonctionnalité du clavier alphabétique est signalée dans l'objet Configuration de la ressource sous la forme KEYBOARD_QWERTY .

• Si le périphérique d'entrée possède des touches mappées sur KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT , KEYCODE_DPAD_RIGHT et KEYCODE_DPAD_CENTER (toutes doivent être présentes), alors le périphérique est considéré comme disposant d'un clavier directionnel. La capacité du clavier directionnel est signalée dans l'objet Configuration de la ressource sous la forme NAVIGATION_DPAD .

• Si le périphérique d'entrée possède des touches mappées à KEYCODE_BUTTON_A ou à d'autres touches liées à la manette de jeu, alors l'appareil est considéré comme disposant d'une manette de jeu.

Exigences du pilote de clavier

1. Les pilotes de clavier ne doivent enregistrer les codes de touches que pour les touches qu'ils prennent réellement en charge. L'enregistrement de codes de touches excédentaires peut perturber l'algorithme de classification de l'appareil ou amener le système à détecter de manière incorrecte les fonctionnalités de clavier prises en charge par l'appareil.

2. Les pilotes de clavier doivent utiliser EV_KEY pour signaler les pressions sur une touche, en utilisant une valeur de 0 pour indiquer qu'une touche est relâchée, une valeur de 1 pour indiquer qu'une touche est enfoncée et une valeur supérieure ou égale à 2 pour indiquer que la touche est enfoncée. se répétant automatiquement.

3. Android effectue sa propre répétition de clavier. La fonctionnalité de répétition automatique doit être désactivée dans le pilote.

4. Les pilotes de clavier peuvent éventuellement indiquer l'utilisation du HID ou le code d'analyse de bas niveau en envoyant EV_MSC avec MSC_SCANCODE et une valeur indiquant l'utilisation ou le code d'analyse lorsque la touche est enfoncée. Ces informations ne sont actuellement pas utilisées par Android.

5. Les pilotes de clavier doivent prendre en charge la définition des états des LED lorsque EV_LED est écrit sur le périphérique. Le pilote hid-input gère cela automatiquement. Au moment d'écrire ces lignes, Android utilise LED_CAPSLOCK , LED_SCROLLLOCK et LED_NUMLOCK . Ces LED ne doivent être prises en charge que lorsque le clavier dispose effectivement des voyants lumineux associés.

6. Les pilotes de clavier pour les claviers intégrés (par exemple, en utilisant une matrice GPIO) doivent veiller à envoyer des événements EV_KEY avec une valeur de 0 pour toutes les touches encore enfoncées lorsque l'appareil se met en veille. Sinon, les touches pourraient rester bloquées et se répéter automatiquement pour toujours.

Fonctionnement du clavier

Ce qui suit est un bref résumé du fonctionnement du clavier sur Android.

1. L' EventHub lit les événements bruts du pilote evdev et mappe les codes de touches Linux (parfois appelés codes de numérisation) en codes de touches Android à l'aide de la carte de disposition des touches du clavier.

2. Le InputReader consomme les événements bruts et met à jour l’état de la clé méta. Par exemple, si la touche Maj gauche est enfoncée ou relâchée, le lecteur définira ou réinitialisera les bits META_SHIFT_LEFT_ON et META_SHIFT_ON en conséquence.

3. Le InputReader informe le InputDispatcher de l’événement clé.

4. Le InputDispatcher demande à WindowManagerPolicy quoi faire avec l'événement clé en appelant WindowManagerPolicy.interceptKeyBeforeQueueing . Cette méthode fait partie d'un chemin critique chargé de réveiller l'appareil lorsque certaines touches sont enfoncées. L' EventHub maintient efficacement un wakelock le long de ce chemin critique pour garantir qu'il se déroulera jusqu'à son terme.

5. Si un InputFilter est actuellement utilisé, le InputDispatcher lui donne la possibilité de consommer ou de transformer la clé. Le InputFilter peut être utilisé pour mettre en œuvre des politiques d’accessibilité de bas niveau à l’échelle du système.

6. Le InputDispatcher met la clé en file d'attente pour le traitement sur le thread de répartition.

7. Lorsque InputDispatcher retire la clé de la file d'attente, il donne à WindowManagerPolicy une seconde chance d'intercepter l'événement de clé en appelant WindowManagerPolicy.interceptKeyBeforeDispatching . Cette méthode gère les raccourcis système et d’autres fonctions.

8. Le InputDispatcher identifie ensuite la cible de l'événement clé (la fenêtre ciblée) et attend qu'elle soit prête. Ensuite, InputDispatcher transmet l’événement clé à l’application.

9. Dans l'application, l'événement clé se propage dans la hiérarchie des vues jusqu'à la vue ciblée pour l'envoi de clés pré-IME.

10. Si l'événement clé n'est pas géré dans la répartition pré-IME et qu'un IME est utilisé, l'événement clé est transmis à l'IME.

11. Si l'événement clé n'a pas été consommé par l'IME, il se propage dans la hiérarchie des vues jusqu'à la vue ciblée pour la répartition des clés standard.

12. L'application indique à InputDispatcher si l'événement clé a été consommé. Si l’événement n’a pas été consommé, InputDispatcher appelle WindowManagerPolicy.dispatchUnhandledKey pour appliquer un comportement de « repli ». En fonction de l'action de secours, le cycle de répartition des événements clés peut être redémarré à l'aide d'un code clé différent. Par exemple, si une application ne gère pas KEYCODE_ESCAPE , le système peut rediffuser l'événement clé en tant que KEYCODE_BACK à la place.

Configuration du clavier

Le comportement du clavier est déterminé par la disposition des touches du clavier, la configuration des caractères des touches et la configuration du périphérique d'entrée.

Reportez-vous aux sections suivantes pour plus de détails sur les fichiers qui participent à la configuration du clavier :

• Fichiers de disposition des touches
• Fichiers de mappage de caractères clés
• Fichiers de configuration du périphérique d'entrée

Propriétés

Les propriétés de configuration du périphérique d'entrée suivantes sont utilisées pour les claviers.

clavier

Définition : keyboard.layout = <nom>

Spécifie le nom du fichier de disposition de touches associé au périphérique d'entrée, à l'exclusion de l'extension .kl . Si ce fichier n'est pas trouvé, le système de saisie utilisera à la place la disposition des touches par défaut.

Les espaces dans le nom sont convertis en traits de soulignement lors de la recherche.

Reportez-vous à la documentation du fichier de disposition des touches pour plus de détails.

clavier.characterMap

Définition : keyboard.characterMap = <nom>

Spécifie le nom du fichier de mappage de caractères clés associé au périphérique d'entrée, à l'exclusion de l'extension .kcm . Si ce fichier n'est pas trouvé, le système d'entrée utilisera à la place la carte de caractères clés par défaut.

Les espaces dans le nom sont convertis en traits de soulignement lors de la recherche.

Reportez-vous à la documentation du fichier de mappage de caractères clés pour plus de détails.

clavier.orientationAware

Définition : keyboard.orientationAware = 0 | 1

Spécifie si le clavier doit réagir aux changements d'orientation de l'affichage.

• Si la valeur est 1 , les touches du clavier directionnel pivotent lorsque l'orientation de l'affichage associée change.

• Si la valeur est 0 , le clavier est immunisé contre les changements d'orientation d'affichage.

La valeur par défaut est 0 .

La connaissance de l'orientation est utilisée pour prendre en charge la rotation des touches du clavier directionnel, comme sur le Motorola Droid. Par exemple, lorsque l'appareil pivote de 90 degrés dans le sens des aiguilles d'une montre par rapport à son orientation naturelle, KEYCODE_DPAD_UP est remappé pour produire KEYCODE_DPAD_RIGHT puisque la touche « haut » finit par pointer « vers la droite » lorsque l'appareil est maintenu dans cette orientation.

clavier.builtIn

Définition : keyboard.builtIn = 0 | 1

Spécifie si le clavier est le clavier intégré (connecté physiquement).

La valeur par défaut est 1 si le nom de l'appareil se termine par -keypad , 0 sinon.

Le clavier intégré se voit toujours attribuer un identifiant de périphérique de 0 . Les autres claviers non intégrés se voient attribuer des identifiants de périphérique uniques non nuls.

L'utilisation d'un identifiant de 0 pour le clavier intégré est importante pour maintenir la compatibilité avec le champ KeyCharacterMap.BUILT_IN_KEYBOARD , qui spécifie l'identifiant du clavier intégré et a une valeur de 0 . Ce champ est obsolète dans l'API, mais des applications plus anciennes peuvent encore l'utiliser.

Un clavier à fonction spéciale (celui dont la table de caractères spécifie un type de SPECIAL_FUNCTION ) ne sera jamais enregistré en tant que clavier intégré, quel que soit le paramètre de cette propriété. En effet, un clavier à fonctions spéciales n'est, par définition, pas destiné à être utilisé pour une saisie à des fins générales.

Exemples de configuration

# This is an example input device configuration file for a built-in
# keyboard that has a DPad.

# The keyboard is internal because it is part of the device.
device.internal = 1

# The keyboard is the default built-in keyboard so it should be assigned
# an id of 0.
keyboard.builtIn = 1

# The keyboard includes a DPad which is mounted on the device.  As the device
# is rotated the orientation of the DPad rotates along with it, so the DPad must
# be aware of the display orientation.  This ensures that pressing 'up' on the
# DPad always means 'up' from the perspective of the user, even when the entire
# device has been rotated.
keyboard.orientationAware = 1

Remarques sur la compatibilité

Avant Honeycomb, le mappeur de saisie au clavier n'utilisait aucune propriété de configuration. Tous les claviers étaient supposés être physiquement attachés et conscients de leur orientation. La disposition des touches par défaut et la carte des caractères clés ont été nommées qwerty au lieu de Generic . Le format de la carte des caractères clés était également très différent et le framework ne prenait pas en charge les claviers complets de style PC ni les claviers externes.

Lors de la mise à niveau des appareils vers Honeycomb, assurez-vous de créer ou de mettre à jour les fichiers de configuration et de mappage de touches nécessaires.

Utilisations HID, codes clés Linux et codes clés Android

Le système fait référence aux clés en utilisant plusieurs identifiants différents, selon la couche d'abstraction.

Pour les appareils HID, chaque clé est associée à une utilisation HID. Le pilote Linux hid-input et les pilotes HID associés au fournisseur et au périphérique sont responsables de l'analyse des rapports HID et du mappage des utilisations HID aux codes clés Linux.

Lorsqu'Android lit les événements EV_KEY du noyau Linux, il traduit chaque code de clé Linux en code de clé Android correspondant en fonction du fichier de disposition de clé de l'appareil.

Lorsque l'événement clé est distribué à une application, l'instance android.view.KeyEvent signale le code clé Linux comme valeur de getScanCode() et le code clé Android comme valeur de getKeyCode() . Pour les besoins du framework, seule la valeur de getKeyCode() est importante.

Notez que les informations d'utilisation HID ne sont pas utilisées par Android lui-même ni transmises aux applications.

Tableaux de codes

Les tableaux suivants montrent comment les utilisations HID, les codes clés Linux et les codes clés Android sont liés les uns aux autres.

La colonne LKC spécifie le code de la clé Linux en hexadécimal.

La colonne AKC spécifie le code de la clé Android en hexadécimal.

La colonne Notes fait référence aux notes publiées après le tableau.

La colonne Version précise la première version de la plateforme Android à avoir inclus cette clé dans son mappage de touches par défaut. Plusieurs lignes sont affichées dans les cas où la configuration des touches par défaut a changé entre les versions. La version la plus ancienne indiquée est la 1.6.

• Dans Gingerbread (2.3) et les versions antérieures, la configuration des touches par défaut était qwerty.kl . Cette carte de touches était uniquement destinée à être utilisée avec l'émulateur Android et n'était pas destinée à être utilisée pour prendre en charge des claviers externes arbitraires. Néanmoins, quelques constructeurs OEM ont ajouté la prise en charge du clavier Bluetooth à la plate-forme et se sont appuyés sur qwerty.kl pour fournir les mappages de clavier nécessaires. Par conséquent, ces mappages plus anciens peuvent intéresser les OEM qui construisent des périphériques pour ces appareils particuliers. A noter que les mappages sont sensiblement différents de ceux actuels, notamment en ce qui concerne le traitement de la touche HOME . Il est recommandé que tous les nouveaux périphériques soient développés selon le Honeycomb ou des cartes de touches plus récentes (c'est-à-dire HID standard).

• Depuis Honeycomb (3.0), la configuration des touches par défaut est Generic.kl . Cette carte de touches a été conçue pour prendre en charge les claviers complets de style PC. La plupart des fonctionnalités des claviers HID standard devraient fonctionner immédiatement.

Le mappage du code clé peut varier selon les versions du noyau Linux et d'Android. Lorsque des modifications sont connues dans les mappages de touches par défaut d'Android, elles sont indiquées dans la colonne version.

Les pilotes HID et les mappages de touches spécifiques au périphérique peuvent appliquer des mappages différents de ceux indiqués ici.

Clavier HID et page du clavier (0x07)

Page de bureau générique HID (0x01)

Page consommateur HID (0x0c)

Mappages supplémentaires non HID

Ces mappages décrivent des fonctions qui n'apparaissent pas dans HID mais pour lesquelles des codes clés Linux existent.

Clés héritées non prises en charge

Ces mappages apparaissaient dans les versions précédentes d'Android mais étaient incompatibles avec HID ou utilisaient des codes clés Linux non standard. Ils ne sont plus pris en charge.

Remarques

1. Le code de la clé Android associé aux touches alphanumériques et symboliques courantes peut varier en fonction de la disposition du clavier et de la langue. Pour des raisons historiques, les codes de numérisation physique et les utilisations HID associés aux touches d'un clavier sont souvent définis de manière positionnelle, même si les étiquettes imprimées sur ces touches peuvent varier d'une langue à l'autre.

   Sur un clavier anglais américain (QWERTY), la touche alphabétique supérieure gauche est étiquetée Q. Sur un clavier français (AZERTY), la touche dans la même position est étiquetée A. Malgré l'étiquette, sur les deux claviers, la touche alphabétique supérieure gauche est fait référence à l'utilisation de l'utilisation HID 0x07 0x0014 qui est mappée au code clé Linux KEY_Q.

   Lorsqu'Android est configuré avec une disposition de clavier en anglais américain, le code clé Linux KEY_Q sera mappé au code clé Android KEYCODE_Q et produira les caractères « Q » et « q ». Cependant, lorsque Android est configuré avec un clavier français, le code clé Linux KEY_Q sera mappé au code clé Android KEYCODE_A et produira les caractères « A » et « a ».

   Le code de la clé Android reflète généralement l'interprétation de la clé spécifique à la langue, de sorte qu'un code de clé Android différent peut être utilisé pour différentes langues.

2. 0x0c 0x022f AC Zoom est défini dans le HID comme un contrôle linéaire mais le noyau le mappe comme une clé, ce qui est probablement incorrect.

3. Les touches de fonction Linux KEY_FN_* sont mappées à des codes de touches plus simples mais sont distribuées avec le bit de méta-état META_FUNCTION défini sur true.

4. Avant Android Ice Cream Sandwich 4.0, la disposition des touches par défaut contenait des mappages pour certains codes de touches supplémentaires qui n'étaient pas définis dans les en-têtes principaux du noyau Linux. Ces mappages ont depuis été supprimés car ces codes clés auparavant non définis se sont vu attribuer des significations différentes dans les versions plus récentes du noyau Linux.

Sources

1. Tableaux d'utilisation USB HID v1.12
2. Noyau Linux 2.6.39 : include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS : qwerty.kl, Generic.kl, KeyEvent.java