Appareils avec clavier

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Android est compatible avec divers claviers, y compris des claviers de fonction spéciaux (boutons de contrôle du volume et de l'alimentation), des claviers Qwerty intégrés compacts et des claviers externes de type PC entièrement fonctionnels.

Ce document ne concerne que les claviers physiques. Pour en savoir plus sur les claviers virtuels (éditeurs de méthode d'entrée), consultez le SDK Android.

Classification des claviers

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 touche Linux utilisés sur les claviers, y compris 0 à 0xff ou KEY_OK à KEY_MAX.

• L'appareil d'entrée signale la présence de codes de touche Linux utilisés sur les joysticks et les manettes de jeu, y compris BTN_0 à BTN_9, BTN_TRIGGER à BTN_DEAD ou BTN_A à BTN_THUMBR.

Les joysticks sont actuellement classés comme claviers, car les boutons de joystick et de manette de jeu sont signalés par des événements EV_KEY de la même manière que les touches de clavier. Par conséquent, les manettes et les manettes de jeu utilisent également des fichiers de mappage de touches 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 mise en page du clavier.

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

• Si l'appareil d'entrée comporte des touches mappées sur KEYCODE_Q, il est considéré comme disposant d'un clavier alphabétique (par opposition à un clavier numérique). La fonctionnalité de clavier alphabétique est signalée dans l'objet de ressource Configuration sous la forme KEYBOARD_QWERTY.

• Si l'appareil d'entrée comporte 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), l'appareil est considéré comme disposant d'un clavier directionnel. La fonctionnalité de clavier directionnel est signalée dans l'objet de ressource Configuration sous la forme NAVIGATION_DPAD.

• Si l'appareil d'entrée comporte des touches mappées sur KEYCODE_BUTTON_A ou d'autres touches associées à une manette de jeu, l'appareil est considéré comme doté d'une manette de jeu.

Exigences concernant le pilote de clavier

1. Les pilotes de clavier ne doivent enregistrer que les codes de touche pour les touches qu'ils prennent réellement en charge. L'enregistrement de codes de touche en trop peut prêter à confusion pour l'algorithme de classification de l'appareil ou entraîner une détection incorrecte des fonctionnalités de clavier compatibles de l'appareil par le système.

2. Les pilotes de clavier doivent utiliser EV_KEY pour signaler les pressions sur les touches, 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 répétée 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 HID ou le code de balayage de bas niveau en envoyant EV_MSC avec MSC_SCANCODE et une valeur indiquant l'utilisation ou le code de balayage lorsque la touche est enfoncée. Ces informations ne sont pas utilisées par Android pour le moment.

5. Les pilotes de clavier doivent prendre en charge le paramétrage des états des LED lorsque EV_LED est écrit sur l'appareil. Le pilote hid-input gère cela automatiquement. Au moment de la rédaction de cet article, Android utilise LED_CAPSLOCK, LED_SCROLLLOCK et LED_NUMLOCK. Ces LED ne doivent être compatibles que lorsque le clavier dispose réellement des voyants associés.

6. Les pilotes de clavier pour les claviers intégrés (par exemple, à l'aide d'une matrice GPIO) doivent s'assurer d'envoyer des événements EV_KEY avec une valeur de 0 pour toutes les touches qui sont toujours enfoncées lorsque l'appareil passe en veille. Sinon, les touches risquent de rester enfoncées et de se répéter automatiquement indéfiniment.

Fonctionnement du clavier

Vous trouverez ci-dessous un bref résumé du fonctionnement du clavier sur Android.

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

2. InputReader consomme les événements bruts et met à jour l'état de la touche 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. InputReader informe InputDispatcher de l'événement clé.

4. InputDispatcher demande à WindowManagerPolicy ce qu'il doit faire de l'événement de touche 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. EventHub maintient efficacement un verrouillage de réveil tout au long de ce chemin critique pour s'assurer qu'il s'exécute jusqu'à son achèvement.

5. Si un InputFilter est actuellement utilisé, le InputDispatcher lui donne la possibilité de consommer ou de transformer la clé. InputFilter peut être utilisé pour implémenter des règles d'accessibilité de bas niveau pour l'ensemble du système.

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

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

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

9. Dans l'application, l'événement de touche se propage dans la hiérarchie des vues jusqu'à la vue active pour la distribution des touches avant l'IME.

10. Si l'événement de touche n'est pas géré dans la distribution pré-IME et qu'un IME est utilisé, l'événement de touche est envoyé à l'IME.

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

12. L'application indique à InputDispatcher si l'événement de touche a été consommé. Si l'événement n'a pas été consommé, InputDispatcher appelle WindowManagerPolicy.dispatchUnhandledKey pour appliquer le comportement de "recours". En fonction de l'action de remplacement, le cycle de distribution des événements de touche peut être redémarré à l'aide d'un autre code de touche. Par exemple, si une application ne gère pas KEYCODE_ESCAPE, le système peut rediriger l'événement de touche en tant que KEYCODE_BACK.

Configuration du clavier

Le comportement du clavier est déterminé par la mise en page des touches, le mappage des caractères de touche et la configuration du périphérique d'entrée.

Pour en savoir plus sur les fichiers qui participent à la configuration du clavier, consultez les sections suivantes:

• Fichiers de mise en page des touches
• Fichiers de carte de personnages clés
• Fichiers de configuration des périphériques d'entrée

Propriétés

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

keyboard.layout

Définition:keyboard.layout = <nom>

Indique le nom du fichier de mise en page des touches associé au périphérique d'entrée, sans l'extension .kl. Si ce fichier n'est pas trouvé, le système de saisie utilise la disposition des touches par défaut.

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

Pour en savoir plus, consultez la documentation du fichier de mise en page des clés.

keyboard.characterMap

Définition:keyboard.characterMap = <nom>

Indique le nom du fichier de mappage des caractères de touche associé au périphérique d'entrée, sans l'extension .kcm. Si ce fichier n'est pas trouvé, le système d'entrée utilisera plutôt la carte de caractères de touche par défaut.

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

Pour en savoir plus, consultez la documentation sur le fichier de mappage des caractères clés.

keyboard.orientationAware

Définition:keyboard.orientationAware = 0 | 1

Indique si le clavier doit réagir aux changements d'orientation de l'écran.

• Si la valeur est 1, les touches du clavier directionnel sont pivotées lorsque l'orientation de l'écran associé change.

• Si la valeur est 0, le clavier est insensible aux changements d'orientation de l'écran.

La valeur par défaut est 0.

La prise en compte de l'orientation permet de gérer la rotation des touches du clavier directionnel, comme sur le Motorola Droid. Par exemple, lorsque l'appareil est pivoté 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, car la touche "Haut" finit par pointer vers la "droite" lorsque l'appareil est tenu dans cette orientation.

keyboard.builtIn

Définition:keyboard.builtIn = 0 | 1

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

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

L'ID de l'appareil du clavier intégré est toujours 0. Les autres claviers non intégrés sont associés à des ID d'appareil uniques non nuls.

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

Un clavier à fonction spéciale (dont le mappage de caractères de clé 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 à touches spéciales n'est pas conçu pour la saisie générale.

Exemples de configurations

# 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 connectés et tenir compte de l'orientation. La disposition des touches et la carte des caractères de touche par défaut étaient nommées qwerty au lieu de Generic. Le format de la carte des caractères de touche était également très différent, et le framework n'était pas compatible avec les claviers complets de type PC ni les claviers externes.

Lorsque vous mettez à niveau des appareils vers Honeycomb, veillez à créer ou à mettre à jour les fichiers de configuration et de mappage des touches nécessaires.

Utilisations HID, codes de touche Linux et codes de touche Android

Le système fait référence aux clés à l'aide de plusieurs identifiants différents, en fonction de la couche d'abstraction.

Pour les appareils HID, chaque touche est associée à une utilisation HID. Le pilote hid-input Linux et les pilotes HID spécifiques au fournisseur et à l'appareil sont chargés d'analyser les rapports HID et de mapper les utilisations HID sur les codes de touche Linux.

Lorsque Android lit les événements EV_KEY à partir du noyau Linux, il traduit chaque code de touche Linux en son code de touche Android correspondant, conformément au fichier de mise en page des touches de l'appareil.

Lorsque l'événement de touche est distribué à une application, l'instance android.view.KeyEvent indique le code de touche Linux comme valeur de getScanCode() et le code de touche 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.

Tables de code

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

La colonne "LKC" spécifie le code de touche Linux au format hexadécimal.

La colonne "AKC" spécifie le code de touche Android en hexadécimal.

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

La colonne "Version" spécifie la première version de la plate-forme Android ayant inclus cette touche dans sa table de correspondance des touches par défaut. Plusieurs lignes s'affichent lorsque le mappage de touches par défaut a changé entre les versions. La version la plus ancienne indiquée est 1.6.

• Dans Gingerbread (2.3) et les versions antérieures, la disposition des touches par défaut était qwerty.kl. Cette carte de touches n'était destinée qu'à être utilisée avec Android Emulator et n'était pas destinée à prendre en charge des claviers externes arbitraires. Néanmoins, quelques OEM ont ajouté la prise en charge des claviers 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 fabriquent des périphériques pour ces appareils spécifiques. Notez que les mappages sont sensiblement différents des mappages actuels, en particulier en ce qui concerne le traitement de la clé HOME. Nous vous recommandons de développer tous les nouveaux périphériques selon la disposition Honeycomb ou des dispositions de clavier plus récentes (par exemple, HID standard).

• Depuis Honeycomb (3.0), la disposition des touches par défaut est Generic.kl. Ce mappage de touches a été conçu pour prendre en charge les claviers de type PC complets. La plupart des fonctionnalités des claviers HID standards devraient fonctionner immédiatement.

La mise en correspondance des codes de touche 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 à l'appareil peuvent appliquer des mappages différents de ceux indiqués ici.

Page du clavier et du clavier HID (0x07)

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

Page du consommateur HID (0x0c)

Mises en correspondance non HID supplémentaires

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

Clés anciennes non compatibles

Ces mappages apparaissaient dans les versions précédentes d'Android, mais ils n'étaient pas cohérents avec HID ou utilisaient des codes de touche Linux non standards. Elles ne sont plus compatibles.

Notes

1. Le code de touche 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 physiques et les utilisations HID associés aux touches d'un clavier sont souvent définis en fonction de la position, même si les libellés imprimés sur ces touches peuvent varier d'une langue à l'autre.

   Sur un clavier en anglais américain (QWERTY), la touche alphabétique en haut à gauche est la touche Q. Sur un clavier français (AZERTY), la touche à la même position est marquée A. Malgré l'étiquette, sur les deux claviers, la touche alphabétique en haut à gauche est référencée à l'aide de l'utilisation HID 0x07 0x0014, qui est mappée sur le code de touche Linux KEY_Q.

   Lorsque Android est configuré avec une disposition de clavier en anglais américain, le code de touche Linux KEY_Q est mappé sur le code de touche Android KEYCODE_Q et produit les caractères "Q" et "q". Toutefois, lorsque Android est configuré avec une disposition de clavier français, le code de touche Linux KEY_Q est mappé sur le code de touche Android KEYCODE_A et produit les caractères "A" et "a".

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

2. 0x0c 0x022f AC Zoom est défini dans le HID comme une commande linéaire, mais le noyau le mappe en tant que touche, ce qui est probablement incorrect.

3. Les touches de fonction Linux KEY_FN_* sont mappées sur des codes de touche plus simples, mais elles sont distribuées avec le bit d'état méta 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 touche supplémentaires qui n'étaient pas définis dans les en-têtes du noyau Linux principal. Ces mappages ont depuis été supprimés, car ces codes de touche non définis ont depuis été attribués à des significations différentes dans les versions plus récentes du noyau Linux.

Sources

1. Tables d'utilisation des périphériques HID USB v1.12
2. Kernel Linux 2.6.39: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java