Fichiers de carte de caractères clés

Les fichiers de mappage de caractères clés (fichiers .kcm ) sont responsables du mappage des combinaisons de codes de touches Android avec des modificateurs aux caractères Unicode.

Des fichiers de disposition de touches spécifiques au périphérique sont requis pour tous les périphériques d'entrée internes (intégrés) dotés de touches, ne serait-ce que pour indiquer au système que le périphérique est uniquement destiné à un usage spécial (pas un clavier complet).

Les fichiers de disposition des touches spécifiques à l'appareil sont facultatifs pour les claviers externes et ne sont souvent pas nécessaires du tout. Le système fournit une table de caractères générique adaptée à de nombreux claviers externes.

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

Emplacement

Les fichiers de mappage de caractères clés 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/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
• /odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
• /vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
• /system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
• /data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm
• /odm/usr/keychars/DEVICE_NAME.kcm
• /vendor/usr/keychars/DEVICE_NAME.kcm
• /system/usr/keychars/DEVICE_NAME.kcm
• /data/system/devices/keychars/DEVICE_NAME.kcm
• /odm/usr/keychars/Generic.kcm
• /vendor/usr/keychars/Generic.kcm
• /system/usr/keychars/Generic.kcm
• /data/system/devices/keychars/Generic.kcm
• /odm/usr/keychars/Virtual.kcm
• /vendor/usr/keychars/Virtual.kcm
• /system/usr/keychars/Virtual.kcm
• /data/system/devices/keychars/Virtual.kcm

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 mappage de caractères clés génériques

Le système fournit un fichier spécial de mappage de caractères clés intégré appelé Generic.kcm . Cette table de caractères clés est destinée à prendre en charge une variété de claviers externes standard.

Ne modifiez pas la carte des caractères clés génériques !

Fichier de mappage de caractères de clé virtuelle

Le système fournit un fichier spécial de mappage de caractères clés intégré appelé Virtual.kcm qui est utilisé par les périphériques de clavier virtuel.

Le périphérique clavier virtuel est un périphérique d'entrée synthétique dont l'identifiant est -1 (voir KeyCharacterMap.VIRTUAL_KEYBOARD ). Il est présent sur tous les appareils Android à partir d'Android Honeycomb 3.0. L'objectif du dispositif de clavier virtuel est de fournir un dispositif d'entrée intégré connu qui peut être utilisé pour injecter des frappes dans des applications par l'IME ou par une instrumentation de test, même pour des dispositifs qui ne disposent pas de claviers intégrés.

Le clavier virtuel est supposé avoir une disposition QWERTY complète qui est la même sur tous les appareils. Cela permet aux applications d'injecter des frappes à l'aide du clavier virtuel et d'obtenir toujours les mêmes résultats.

Ne modifiez pas la carte des caractères des touches virtuelles !

Syntaxe

Un fichier de mappage de caractères clés est un fichier texte brut composé d'une déclaration de type de clavier et d'un ensemble de déclarations de touches.

Déclaration du type de clavier

Une déclaration de type de clavier décrit le comportement global du clavier. Un fichier de mappage de caractères doit contenir une déclaration de type de clavier. Pour plus de clarté, il est souvent placé en haut du fichier.

type FULL

Les types de clavier suivants sont reconnus :

• NUMERIC : Un clavier numérique (12 touches).

  Un clavier numérique prend en charge la saisie de texte en utilisant une approche multi-tap. Il peut être nécessaire d'appuyer plusieurs fois sur une touche pour générer la lettre ou le symbole souhaité.

  Ce type de clavier est généralement conçu pour la saisie avec le pouce.

  Correspond à KeyCharacterMap.NUMERIC .

• PREDICTIVE : Un clavier avec toutes les lettres, mais avec plus d'une lettre par touche.

  Ce type de clavier est généralement conçu pour la saisie avec le pouce.

  Correspond à KeyCharacterMap.PREDICTIVE .

• ALPHA : Un clavier avec toutes les lettres, et peut-être quelques chiffres.

  Un clavier alphabétique prend directement en charge la saisie de texte, mais peut avoir une disposition condensée avec un petit facteur de forme. Contrairement à un clavier FULL , certains symboles ne peuvent être accessibles qu'à l'aide de sélecteurs de caractères spéciaux à l'écran. De plus, pour améliorer la vitesse et la précision de la frappe, le framework offre des fonctionnalités spéciales pour les claviers alphabétiques, telles que la capitalisation automatique et les touches SHIFT et ALT basculées/verrouillées.

  Ce type de clavier est généralement conçu pour la saisie avec le pouce.

• FULL : Un clavier complet de style PC.

  Un clavier complet se comporte comme un clavier de PC. Tous les symboles sont accessibles directement en appuyant sur les touches du clavier sans support à l'écran ni fonctionnalités telles que la majuscule automatique.

  Ce type de clavier est généralement conçu pour une saisie à deux mains.

• SPECIAL_FUNCTION : Un clavier qui est uniquement utilisé pour exécuter des fonctions de contrôle du système plutôt que pour taper.

  Un clavier à fonctions spéciales se compose uniquement de touches non imprimables telles que HOME et POWER qui ne sont pas réellement utilisées pour la saisie.

Les cartes de caractères clés Generic.kcm et Virtual.kcm sont toutes deux des claviers FULL .

Déclarations clés

Les déclarations de clé se composent chacune du mot-clé key suivi d'un nom de code de clé Android, d'une accolade ouverte, d'un ensemble de propriétés et de comportements et d'une accolade fermante.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Propriétés

Chaque propriété de clé établit un mappage d'une clé à un comportement. Pour rendre les fichiers de mappage de caractères clés plus compacts, plusieurs propriétés peuvent être mappées au même comportement en les séparant par une virgule.

Dans l'exemple ci-dessus, la propriété label se voit attribuer le comportement 'A' . De même, les propriétés ctrl , alt et meta se voient toutes simultanément attribuer le comportement none .

Les propriétés suivantes sont reconnues :

• label : Spécifie l’étiquette qui est physiquement imprimée sur la clé, lorsqu’elle est constituée d’un seul caractère. Il s'agit de la valeur renvoyée par la méthode KeyCharacterMap.getDisplayLabel .

• number : Spécifie le comportement (caractère à saisir) lorsqu'une vue de texte numérique a le focus, par exemple lorsque l'utilisateur tape un numéro de téléphone.

  Les claviers compacts combinent souvent plusieurs symboles en une seule touche, de sorte que la même touche peut être utilisée pour taper '1' et 'a' ou '#' et 'q' , par exemple. Pour ces clés, la propriété number doit être définie pour indiquer quel symbole doit être saisi dans un contexte numérique, le cas échéant.

  Certains symboles "numériques" typiques sont les chiffres '0' à '9' , '#' , '+' , '(' , ')' , ',' et '.' .

• base : Spécifie le comportement (caractère à saisir) lorsqu'aucun modificateur n'est enfoncé.

• <modifier> ou <modifier1> + <modifier2> + ... : Spécifie le comportement (caractère à saisir) lorsque la touche est enfoncée et que tous les modificateurs spécifiés sont actifs.

  Par exemple, la propriété du modificateur shift spécifie un comportement qui s'applique lorsque le modificateur MAJ GAUCHE ou MAJ DROITE est enfoncé.

  De même, la propriété du modificateur rshift+ralt spécifie un comportement qui s'applique lorsque les modificateurs RIGHT SHIFT et RIGHT ALT sont enfoncés simultanément.

Les modificateurs suivants sont reconnus dans les propriétés du modificateur :

• shift : S'applique lorsque le modificateur LEFT SHIFT ou RIGHT SHIFT est enfoncé.
• lshift : S'applique lorsque le modificateur LEFT SHIFT est enfoncé.
• rshift : S'applique lorsque le modificateur RIGHT SHIFT est enfoncé.
• alt : S'applique lorsque le modificateur LEFT ALT ou RIGHT ALT est enfoncé.
• lalt : S'applique lorsque le modificateur LEFT ALT est enfoncé.
• ralt : S'applique lorsque le modificateur RIGHT ALT est enfoncé.
• ctrl : s'applique lorsque le modificateur CONTROLE GAUCHE ou CONTROLE DROITE est enfoncé.
• lctrl : S'applique lorsque le modificateur CONTROLE GAUCHE est enfoncé.
• rctrl : S'applique lorsque le modificateur RIGHT CONTROL est enfoncé.
• meta : s'applique lorsque le modificateur LEFT META ou RIGHT META est enfoncé.
• lmeta : S'applique lorsque le modificateur LEFT META est enfoncé.
• rmeta : S'applique lorsque le modificateur RIGHT META est enfoncé.
• sym : S'applique lorsque le modificateur SYMBOLE est enfoncé.
• fn : S'applique lorsque le modificateur FUNCTION est enfoncé.
• capslock : S'applique lorsque le modificateur CAPS LOCK est verrouillé.
• numlock : S'applique lorsque le modificateur NUM LOCK est verrouillé.
• scrolllock : S'applique lorsque le modificateur SCROLL LOCK est verrouillé.

L'ordre dans lequel les propriétés sont répertoriées est important. Lors du mappage d'une clé à un comportement, le système analyse toutes les propriétés pertinentes dans l'ordre et renvoie le dernier comportement applicable qu'il a trouvé.

Par conséquent, les propriétés spécifiées ultérieurement remplacent les propriétés spécifiées précédemment pour une clé donnée.

Comportements

Chaque propriété correspond à un comportement. Le comportement le plus courant consiste à saisir un caractère, mais il en existe d'autres.

Les comportements suivants sont reconnus :

• none : Ne tapez pas de caractère.

  Ce comportement est le comportement par défaut lorsqu'aucun caractère n'est spécifié. Spécifier none facultatif mais cela améliore la clarté.

• 'X' : Tapez le caractère littéral spécifié.

  Ce comportement entraîne la saisie du caractère spécifié dans la vue texte ciblée. Le caractère littéral peut être n'importe quel caractère ASCII ou l'une des séquences d'échappement suivantes :

  • '\\' : saisissez un caractère barre oblique inverse.
  • '\n' : Tapez un caractère de nouvelle ligne (utilisez-le pour ENTER / RETURN).
  • '\t' : Tapez un caractère TAB.
  • '\'' : Tapez un caractère apostrophe.
  • '\"' : saisissez un guillemet.
  • '\uXXXX' : Tapez le caractère Unicode dont le point de code est donné en hexadécimal par XXXX.

• fallback <Nom du code de la clé Android> : effectuez une action par défaut si la clé n'est pas gérée par l'application.

  Ce comportement amène le système à simuler une pression de touche différente lorsqu'une application ne gère pas nativement la touche spécifiée. Il est utilisé pour prendre en charge le comportement par défaut des nouvelles touches que toutes les applications ne savent pas gérer, telles que ESCAPE ou les touches du pavé numérique (lorsque le verrouillage numérique n'est pas enfoncé).

  Lorsqu'un comportement de secours est effectué, l'application reçoit deux pressions sur une touche : une pour la touche d'origine et une autre pour la touche de secours sélectionnée. Si l'application gère la clé d'origine lors de l'activation de la clé, l'événement de clé de secours sera annulé ( KeyEvent.isCanceled renverra true ).

Le système réserve deux caractères Unicode pour exécuter des fonctions spéciales :

• '\uef00' : lorsque ce comportement est effectué, la vue texte consomme et supprime les quatre caractères précédant le curseur, les interprète comme des chiffres hexadécimaux et insère le point de code Unicode correspondant.

• '\uef01' : lorsque ce comportement est effectué, la vue texte affiche une boîte de dialogue de sélection de caractères contenant divers symboles.

Le système reconnaît les caractères Unicode suivants comme combinant des caractères diacritiques de clé morte :

• '\u0300' : Accent grave.
• '\u0301' : Accent aigu.
• '\u0302' : Accent circonflexe.
• '\u0303' : Accent tilde.
• '\u0308' : Accent tréma.

Lorsqu'une touche morte est saisie suivie d'un autre caractère, la touche morte et les caractères suivants sont composés. Par exemple, lorsque l'utilisateur tape une touche morte avec accent grave suivi de la lettre « a », le résultat est « à ».

Reportez-vous à KeyCharacterMap.getDeadChar pour plus d’informations sur la gestion des clés mortes.

commentaires

Les lignes de commentaires commencent par « # » et se poursuivent jusqu'à la fin de la ligne. Comme ça:

# A comment!

Les lignes vides sont ignorées.

Comment les combinaisons de touches sont mappées aux comportements

Lorsque l'utilisateur appuie sur une touche, le système recherche le comportement associé à la combinaison de cette touche enfoncée et des modificateurs actuellement enfoncés.

MAJ + A

Supposons que l'utilisateur appuie simultanément sur A et SHIFT. Le système localise d'abord l'ensemble des propriétés et des comportements associés à KEYCODE_A .

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Le système analyse les propriétés du premier au dernier et de gauche à droite, en ignorant les propriétés label et number , qui sont spéciales.

La première propriété rencontrée est base . La propriété base s'applique toujours à une touche, quels que soient les modificateurs enfoncés. Il spécifie essentiellement le comportement par défaut de la clé à moins qu'il ne soit remplacé par les propriétés suivantes. Puisque la propriété base s'applique à cette pression sur une touche, le système prend note du fait que son comportement est 'a' (tapez le caractère a ).

Le système continue ensuite d'analyser les propriétés suivantes au cas où l'une d'entre elles serait plus spécifique que base et la remplacerait. Il rencontre shift qui s'applique également à l'appui sur la touche SHIFT + A. Le système décide donc d'ignorer le comportement de la propriété de base et choisit le comportement associé à la propriété shift , qui est 'A' (tapez le caractère A ).

Il continue ensuite à parcourir la table, mais aucune autre propriété ne s'applique à cette pression de touche (CAPS LOCK n'est pas verrouillé, aucune touche CONTROL n'est enfoncée, aucune touche ALT n'est enfoncée et aucune touche META n'est enfoncée).

Ainsi, le comportement résultant pour la combinaison de touches SHIFT + A est 'A' .

CONTROLE + A

Considérons maintenant ce qui se passerait si l'utilisateur appuyait simultanément sur A et CONTROL.

Comme auparavant, le système analyserait le tableau des propriétés. Il remarquerait que la propriété base s'appliquait mais poursuivrait également l'analyse jusqu'à ce qu'elle atteigne finalement la propriété control . En l’occurrence, la propriété control apparaît après base , son comportement remplace donc celui de base .

Le comportement résultant de la combinaison de touches CONTROL + A est donc none .

S'ÉCHAPPER

Supposons maintenant que l'utilisateur ait appuyé sur ÉCHAP.

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

Cette fois le système obtient le comportement fallback BACK , un comportement de repli. Aucun caractère littéral n’apparaissant, aucun caractère ne sera saisi.

Lors du traitement de la clé, le système fournira d'abord KEYCODE_ESCAPE à l'application. Si l'application ne le gère pas, le système réessayera mais cette fois il fournira KEYCODE_BACK à l'application comme demandé par le comportement de secours.

Ainsi, les applications qui reconnaissent et prennent en charge KEYCODE_ESCAPE ont la possibilité de le gérer tel quel, mais d'autres applications qui ne le font pas peuvent à la place effectuer l'action de secours consistant à traiter la clé comme s'il s'agissait de KEYCODE_BACK .

NUMPAD_0 avec ou sans NUM LOCK

Les touches du pavé numérique ont des interprétations très différentes selon que la touche NUM LOCK est verrouillée ou non.

La déclaration de clé suivante garantit que KEYCODE_NUMPAD_0 tape 0 lorsque NUM LOCK est enfoncé. Lorsque NUM LOCK n'est pas enfoncé, la clé est délivrée à l'application comme d'habitude, et si elle n'est pas gérée, alors la clé de secours KEYCODE_INSERT est délivrée à la place.

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

Comme nous pouvons le constater, les déclarations de touches de secours améliorent considérablement la compatibilité avec les anciennes applications qui ne reconnaissent pas ou ne prennent pas directement en charge toutes les touches présentes sur un clavier de style PC complet.

Exemples

Clavier complet

# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.

type FULL

key C {
    label:                              'C'
    base:                               'c'
    shift, capslock:                    'C'
    alt:                                '\u00e7'
    shift+alt:                          '\u00c7'
    ctrl, meta:                         none
}

key SPACE {
    label:                              ' '
    base:                               ' '
    ctrl:                               none
    alt, meta:                          fallback SEARCH
}

key NUMPAD_9 {
    label, number:                      '9'
    base:                               fallback PAGE_UP
    numlock:                            '9'
    ctrl, alt, meta:                    none
}

Clavier alphanumérique

# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard.  Some keys are combined, such as `A` and `2`.  Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.

type ALPHA

key A {
    label:                              'A'
    number:                             '2'
    base:                               'a'
    shift, capslock:                    'A'
    alt:                                '#'
    shift+alt, capslock+alt:            none
}

key SPACE {
    label:                              ' '
    number:                             ' '
    base:                               ' '
    shift:                              ' '
    alt:                                '\uef01'
    shift+alt:                          '\uef01'
}

Manette de jeu

# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.

type SPECIAL_FUNCTION

key BUTTON_A {
    base:                               fallback BACK
}

key BUTTON_X {
    base:                               fallback DPAD_CENTER
}

key BUTTON_START {
    base:                               fallback HOME
}

key BUTTON_SELECT {
    base:                               fallback MENU
}

Remarque sur la compatibilité

Avant Android Honeycomb 3.0, la carte des caractères clés Android était spécifiée à l'aide d'une syntaxe très différente et était compilée dans un format de fichier binaire ( .kcm.bin ) au moment de la construction.

Bien que le nouveau format utilise la même extension .kcm , la syntaxe est assez différente (et bien plus puissante).

Depuis Android Honeycomb 3.0, tous les fichiers de mappage de caractères clés Android doivent utiliser la nouvelle syntaxe et le nouveau format de fichier de texte brut décrit dans ce document. L'ancienne syntaxe n'est pas prise en charge et les anciens fichiers .kcm.bin ne sont pas reconnus par le système.

Remarque linguistique

Android ne prend actuellement pas en charge les claviers multilingues. De plus, la carte des caractères génériques intégrée suppose une disposition de clavier en anglais américain.

Les constructeurs OEM sont encouragés à fournir des cartes de caractères personnalisées pour leurs claviers s'ils sont conçus pour d'autres langues.

Les futures versions d'Android pourraient offrir une meilleure prise en charge des claviers multilingues ou des dispositions de clavier sélectionnables par l'utilisateur.

Validation

Assurez-vous de valider vos fichiers de mappage de caractères clés à l'aide de l'outil Validate Keymaps .