Les fichiers de mappage des caractères de touche (fichiers .kcm) sont chargés de mapper les combinaisons de codes de touche Android avec des modificateurs sur les caractères Unicode.
Les fichiers de disposition des touches spécifiques à l'appareil sont obligatoires 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 l'appareil est à usage spécial uniquement (et non 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 carte de caractères de touche générique adaptée à de nombreux claviers externes.
Si aucun fichier de disposition des touches spécifique à l'appareil n'est disponible, le système choisit une disposition par défaut.
Position
Les fichiers de mappage de caractères de clé sont situés par fournisseur USB, par ID de produit (et éventuellement de version) ou par nom du 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 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 ceux compris entre '0' et '9', entre 'a' et 'z', entre 'A' et 'Z', ou entre '-' et '_', sont remplacés par '_'.
Fichier de mappage des caractères de clé générique
Le système fournit un fichier de mappage de caractères de clé intégré spécial appelé Generic.kcm.
Cette carte de caractères de clavier est destinée à prendre en charge divers claviers externes standards.
Ne modifiez pas la table de correspondance des caractères de clé générique.
Fichier de mappage des caractères de la touche virtuelle
Le système fournit un fichier de mappage de caractères de clé intégré spécial appelé Virtual.kcm, qui est utilisé par les périphériques de clavier virtuel.
L'appareil de clavier virtuel est un appareil d'entrée synthétique dont l'ID est -1 (voir KeyCharacterMap.VIRTUAL_KEYBOARD). Il est présent sur tous les appareils Android à partir d'Android Honeycomb 3.0. L'objectif du clavier virtuel est de fournir un périphérique d'entrée intégré connu qui peut être utilisé pour injecter des frappes dans les applications par l'IME ou par l'instrumentation de test, même pour les appareils qui ne disposent pas de claviers intégrés.
On suppose que le clavier virtuel dispose d'une disposition QWERTY complète qui est identique sur tous les appareils. Cela permet aux applications d'injecter des frappes à l'aide de l'appareil de clavier virtuel et d'obtenir toujours les mêmes résultats.
Ne modifiez pas le mappage des caractères des touches virtuelles.
Syntaxe
Un fichier de mappage de caractères de clé est un fichier au format 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 claviers suivants sont reconnus:
-
NUMERIC: clavier numérique (12 touches).Un clavier numérique permet de saisir du texte à l'aide d'une approche multi-tapping. Vous devrez peut-être 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 au pouce.
Correspond à
KeyCharacterMap.NUMERIC. -
PREDICTIVE: clavier contenant toutes les lettres, mais avec plusieurs lettres par touche.Ce type de clavier est généralement conçu pour la saisie au pouce.
Correspond à
KeyCharacterMap.PREDICTIVE. -
ALPHA: clavier avec toutes les lettres et peut-être quelques chiffres.Un clavier alphabétique permet de saisir du texte directement, mais peut avoir une mise en page 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 saisie, le framework fournit des affordances spéciales pour les claviers alphabétiques, telles que la mise en majuscule automatique et les touches SHIFT et ALT activées / verrouillées.Ce type de clavier est généralement conçu pour la saisie au pouce.
-
FULL: clavier complet de type PC.Un clavier complet se comporte comme un clavier d'ordinateur. Tous les symboles sont accessibles directement en appuyant sur les touches du clavier, sans assistance à l'écran ni affordances telles que la mise en majuscule automatique.
Ce type de clavier est généralement conçu pour la saisie à deux mains.
-
SPECIAL_FUNCTION: clavier utilisé uniquement pour effectuer des fonctions de contrôle système plutôt que pour saisir du texte.Un clavier de fonction spécial ne se compose que de touches non imprimantes telles que HOME et POWER, qui ne sont pas réellement utilisées pour la saisie.
Les mappages de caractères des touches Generic.kcm et Virtual.kcm sont tous deux des claviers FULL.
Déclarations clés
Les déclarations de clés se composent chacune du mot clé key, suivi d'un nom de code de touche Android, d'une accolade ouvrante, d'un ensemble de propriétés et de comportements, puis 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 des caractères de clé plus compacts, plusieurs propriétés peuvent être mappées sur le même comportement en les séparant par une virgule.
Dans l'exemple ci-dessus, le comportement 'A' est attribué à la propriété label.
De même, le comportement none est attribué simultanément aux propriétés ctrl, alt et meta.
Les propriétés suivantes sont reconnues:
-
label: spécifie le libellé imprimé physiquement sur la touche, lorsqu'il ne comporte qu'un seul caractère. Il s'agit de la valeur renvoyée par la méthodeKeyCharacterMap.getDisplayLabel. -
number: spécifie le comportement (caractère à saisir) lorsqu'une vue de texte numérique est sélectionnée, par exemple lorsque l'utilisateur saisit un numéro de téléphone.Les claviers compacts combinent souvent plusieurs symboles sur une même touche, de sorte que la même touche puisse être utilisée pour saisir
'1'et'a', ou'#'et'q', par exemple. Pour ces touches, la propriéténumberdoit être définie pour indiquer le symbole à saisir dans un contexte numérique, le cas échéant.Les 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é de modificateur
shiftspécifie un comportement qui s'applique lorsque le modificateur SHIFT GAUCHE ou SHIFT DROIT est enfoncé.De même, la propriété de modificateur
rshift+raltspécifie un comportement qui s'applique lorsque les modificateurs MAJ DROITE et ALT DROITE sont enfoncés simultanément.
Les modificateurs suivants sont reconnus dans les propriétés de modificateur:
shift: s'applique lorsque le modificateur MAJ GAUCHE ou MAJ DROITE est enfoncé.lshift: s'applique lorsque le modificateur MAJ est enfoncé.rshift: s'applique lorsque le modificateur MAJ DROITE est enfoncé.alt: s'applique lorsque la touche de modification ALT GAUCHE ou ALT DROITE est enfoncée.lalt: s'applique lorsque le modificateur ALT GAUCHE est enfoncé.ralt: s'applique lorsque le modificateur ALT DROITE est enfoncé.ctrl: s'applique lorsque le modificateur CTRL GAUCHE ou CTRL DROIT est enfoncé.lctrl: s'applique lorsque le modificateur CONTROLE GAUCHE est enfoncé.rctrl: s'applique lorsque le modificateur CONTROLE DROIT est enfoncé.meta: s'applique lorsque le modificateur META GAUCHE ou META DROITE est enfoncé.lmeta: s'applique lorsque le modificateur META GAUCHE est enfoncé.rmeta: s'applique lorsque le modificateur META DROITE est enfoncé.sym: s'applique lorsque le modificateur SYMBOL est enfoncé.fn: s'applique lorsque le modificateur FUNCTION est enfoncé.capslock: s'applique lorsque le modificateur de verrouillage des majuscules est verrouillé.numlock: s'applique lorsque le modificateur Verr Num est verrouillé.scrolllock: s'applique lorsque le modificateur SCROLL LOCK est verrouillé.
L'ordre dans lequel les propriétés sont listées est important. Lorsque vous mappez 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 saisissez pas de caractère.Ce comportement est appliqué par défaut lorsqu'aucun caractère n'est spécifié. La spécification de
noneest facultative, mais elle améliore la clarté. -
'X': saisissez le littéral de caractère spécifié.Ce comportement permet de saisir le caractère spécifié dans la vue de texte sélectionnée. Le littéral de caractère peut être n'importe quel caractère ASCII ou l'une des séquences d'échappement suivantes:
'\\': saisissez un caractère barre oblique inversée.'\n': saisissez un caractère de nouvelle ligne (utilisez-le pour la touche ENTRÉE).'\t': saisissez un caractère TABULATION.'\'': saisissez un apostrophe.'\"': saisissez un guillemet.'\uXXXX': saisissez le caractère Unicode dont le point de code est donné en hexadécimal par XXXX.
-
fallback<Nom du code de touche Android>: effectue une action par défaut si la touche n'est pas gérée par l'application.Ce comportement entraîne la simulation d'une autre pression de touche par le système lorsqu'une application ne gère pas la touche spécifiée en mode natif. Il permet de prendre en charge le comportement par défaut des nouvelles touches que toutes les applications ne savent pas gérer, telles que la touche Échap ou les touches du clavier numérique (lorsque la touche NumLock n'est pas enfoncée).
Lorsqu'un comportement de remplacement est effectué, l'application reçoit deux pressions sur les touches : une pour la touche d'origine et une autre pour la touche de remplacement sélectionnée. Si l'application gère la clé d'origine lors de la mise en service, l'événement de clé de remplacement sera annulé (
KeyEvent.isCanceledrenverratrue).
Le système réserve deux caractères Unicode pour effectuer des fonctions spéciales:
-
'\uef00': lorsque ce comportement est effectué, la vue de 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 de 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 caractères de combinaison de caractères de touche morte diacritique:
'\u0300': accent grave.'\u0301': accent aigu.'\u0302': accent circonflexe.'\u0303': accent aigu.'\u0308': accent umlaut.
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 saisit une touche morte avec accent grave suivie de la lettre "a", le résultat est "à".
Pour en savoir plus sur la gestion des touches mortes, consultez KeyCharacterMap.getDeadChar.
Commentaires
Les lignes de commentaire commencent par "#" et se poursuivent jusqu'à la fin de la ligne. Comme ceci :
# 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 pression de touche et des modificateurs actuellement enfoncés.
MAJ+A
Supposons que l'utilisateur ait appuyé simultanément sur A et Maj. 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 de la première à la dernière 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. Elle spécifie essentiellement le comportement par défaut de la clé, sauf si elle est remplacée par les propriétés suivantes.
Étant donné que la propriété base s'applique à cette pression de touche, le système note 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'elles serait plus spécifique que base et la remplacerait. Il rencontre shift, qui s'applique également à la pression sur la touche MAJ + A. Le système décide donc d'ignorer le comportement de la propriété base et choisit le comportement associé à la propriété shift, qui est 'A' (saisissez le caractère A).
Il continue ensuite à analyser la table, mais aucune autre propriété ne s'applique à cette pression de touche (le verrouillage des majuscules n'est pas activé, aucune touche Ctrl, Alt ou Meta n'est enfoncée).
Le comportement résultant de la combinaison de touches MAJ + A est donc 'A'.
CONTRÔLE + A
Voyons maintenant ce qui se passe si l'utilisateur appuie simultanément sur A et CONTROL.
Comme précédemment, le système analyse la table des propriétés. Il remarquerait que la propriété base s'applique, mais continuerait également l'analyse jusqu'à atteindre la propriété control. Comme il se trouve que la propriété control apparaît après base, son comportement remplace celui de base.
Le comportement résultant de la combinaison de touches CTRL+A est donc none.
ÉCHAP
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 remplacement.
Comme aucun caractère littéral ne s'affiche, aucun caractère ne sera saisi.
Lors du traitement de la clé, le système envoie d'abord KEYCODE_ESCAPE à l'application. Si l'application ne le gère pas, le système réessayera, mais cette fois, il enverra KEYCODE_BACK à l'application comme demandé par le comportement de remplacement.
Ainsi, les applications qui reconnaissent et acceptent KEYCODE_ESCAPE ont la possibilité de le gérer tel quel, mais les autres applications qui ne le font pas peuvent effectuer l'action de remplacement consistant à traiter la clé comme si elle était KEYCODE_BACK.
NUMPAD_0 avec ou sans verrouillage numérique
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 saisit 0 lorsque la touche Verr Num est enfoncée. Lorsque la touche Num Lock n'est pas enfoncée, la touche est transmise à l'application comme d'habitude. Si elle n'est pas gérée, la touche de remplacement KEYCODE_INSERT est transmise à 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 remplacement améliorent considérablement la compatibilité avec les anciennes applications qui ne reconnaissent pas ou ne prennent pas en charge directement toutes les touches présentes sur un clavier de 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 de caractères de clé 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 compilation.
Bien que le nouveau format utilise la même extension .kcm, la syntaxe est très différente (et beaucoup plus puissante).
À partir d'Android Honeycomb 3.0, tous les fichiers de mappage de caractères de clé Android doivent utiliser la nouvelle syntaxe et le nouveau format de fichier de texte brut décrits 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 sur la langue
Android n'est actuellement pas compatible avec les claviers multilingues. De plus, la carte de caractères de touche générique intégrée suppose une disposition de clavier en anglais américain.
Les OEM sont encouragés à fournir des cartes de caractères de touches personnalisées pour leurs claviers s'ils sont conçus pour d'autres langues.
Les futures versions d'Android pourraient mieux prendre en charge les claviers multilingues ou les dispositions de clavier sélectionnables par l'utilisateur.
Validation
Veillez à valider vos fichiers de mappage de touches à l'aide de l'outil Valider les claviers.