Fichiers de mappage 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 touche Android avec des modificateurs en caractères Unicode.

Les fichiers de disposition des touches spécifiques à l'appareil sont obligatoires pour toutes les applications internes (intégrées). des périphériques d'entrée dotés de clés, ne serait-ce que pour indiquer au système que le périphérique est à usage spécial uniquement (pas un clavier complet).

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

Si aucun fichier de disposition de clé spécifique à l'appareil n'est disponible, le système choisissez une valeur par défaut à la place.

Position

Les fichiers de mappage des caractères clés sont localisés en fonction du fournisseur de la clé USB, du produit (et éventuellement de la version). ou par nom de périphérique d'entrée.

Les chemins d'accès 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

Lorsque vous créez un chemin d'accès contenant le nom de l'appareil, tous les caractères dans le nom de l'appareil autre que "0" - "9", "a - z", "A - Z" ou "-" ; 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 de clé intégré appelé Generic.kcm. Ce mappage de caractères clés est destiné à prendre en charge divers types claviers.

Ne modifiez pas le mappage de caractères clés génériques.

Fichier de mappage de caractères clés virtuels

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

Le clavier virtuel est un périphérique 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 de l'appareil à clavier virtuel est de fournir un périphérique d'entrée intégré connu qui peut être utilisé pour injecter les frappes dans les applications par l'IME ou une instrumentation de test, pour les appareils qui ne disposent pas de claviers intégrés.

Le clavier virtuel est censé avoir une disposition QWERTY complète qui correspond même sur tous les appareils. Cela permet aux applications d'injecter frappes à l'aide du périphérique à clavier virtuel et obtiennent toujours les mêmes résultats.

Ne modifiez pas le mappage de caractères clés virtuels.

Syntaxe

Un fichier de mappage de caractères de touche est un fichier en texte brut composé d'un type de clavier et un ensemble de déclarations de clé.

Déclaration du type de clavier

Une déclaration de type de clavier décrit le comportement général 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 reconnus sont les suivants:

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

    Un clavier numérique permet de saisir du texte en appuyant plusieurs fois. 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 avec le 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 avec le pouce.

    Correspond à KeyCharacterMap.PREDICTIVE.

  • ALPHA: un clavier contenant toutes les lettres, et éventuellement quelques chiffres

    Un clavier alphabétique permet de saisir directement du texte, mais il peut avoir un condensé mise en page avec un petit facteur de forme. Contrairement à un clavier FULL, Les 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 affordances spéciales pour les claviers alphabétiques, comme les majuscules automatiques ; et les touches MAJ et ALT activées / verrouillées.

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

  • FULL: clavier complet de type PC.

    Un clavier complet se comporte comme un clavier de PC. Accès direct à tous les symboles en appuyant sur les touches du clavier sans affichage à l'écran ni affordance, de majuscules automatiques.

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

  • SPECIAL_FUNCTION: clavier qui sert uniquement à exécuter des fonctions de commande du système plutôt que pour la saisie.

    Un clavier à fonction spéciale ne contient que des touches non imprimables telles que HOME et POWER qui ne sont pas réellement utilisés pour la saisie.

Les mappages de caractères Generic.kcm et Virtual.kcm sont tous deux des claviers FULL.

Déclarations de clé

Les déclarations de clé sont chacune composées du mot clé key suivi d'un code de clé Android. une accolade ouvrante, un ensemble de propriétés et de comportements, et une accolade fermée.

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

Propriétés

Chaque propriété de clé établit un mappage entre une clé et un comportement. Pour que le fichiers de mappage des caractères clés plus compacts, plusieurs propriétés peuvent être mappées au 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, les propriétés ctrl, alt et meta sont toutes attribuées simultanément le comportement none.

Les propriétés suivantes sont reconnues:

  • label: spécifie l'étiquette physiquement imprimée sur la clé, lorsqu'elle se compose d'un seul caractère. C'est la valeur renvoyée par la méthode KeyCharacterMap.getDisplayLabel.

  • number: spécifie le comportement (caractère à saisir) lorsqu'une valeur numérique l'affichage de texte est sélectionné, par exemple lorsque l'utilisateur saisit un numéro de téléphone.

    Les claviers compacts combinent souvent plusieurs symboles en une seule touche, de sorte que la même clé peut être utilisée pour saisir '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.

    Les valeurs "numériques" les symboles sont des chiffres '0' à '9', '#', '+', '(', ')', ',' et '.'.

  • base: spécifie le comportement (caractère à saisir) en l'absence de modificateurs. doivent appuyer.

  • <modificateur> ou <modifier1>+<modifier2>+...: spécifie les paramètres (caractère à saisir) lorsque l'utilisateur appuie sur la touche et que toutes les que les modificateurs spécifiés sont actifs.

    Par exemple, la propriété de modificateur shift spécifie un comportement qui s'applique lorsque vous appuyez sur la touche de modification LEFT SHIFT ou RIGHT SHIFT.

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

Les modificateurs suivants sont reconnus dans leurs propriétés:

  • shift: s'applique lorsque l'utilisateur appuie sur la touche de modification LEFT SHIFT ou RIGHT SHIFT.
  • lshift: s'applique lorsque l'utilisateur appuie sur la touche de modification LEFT SHIFT.
  • rshift: s'applique lorsque l'utilisateur appuie sur la touche de modification DROITE.
  • alt: s'applique lorsque l'utilisateur appuie sur la touche de modification ALT GAUCHE ou DROITE.
  • lalt: s'applique lorsque l'utilisateur appuie sur la touche de modification ALT GAUCHE.
  • ralt: s'applique lorsque l'utilisateur appuie sur la touche de modification ALT DROITE.
  • ctrl: s'applique lorsque l'utilisateur appuie sur la touche de modification GAUCHE ou DROITE.
  • lctrl: s'applique lorsque l'utilisateur appuie sur la touche de modification GAUCHE.
  • rctrl: s'applique lorsque l'utilisateur appuie sur la touche de modification DROITE.
  • meta: s'applique lorsque l'utilisateur appuie sur le modificateur MÉTA GAUCHE ou MÉTA DROIT.
  • lmeta: s'applique lorsque l'utilisateur appuie sur la touche de modification Méta GAUCHE.
  • rmeta: s'applique lorsque l'utilisateur appuie sur le modificateur Méta DROITE.
  • sym: s'applique lorsque l'utilisateur appuie sur le modificateur SYMBOL.
  • fn: s'applique lorsque l'utilisateur appuie sur le modificateur FUNCTION.
  • capslock: s'applique lorsque le modificateur VERR MAJ est verrouillé.
  • numlock: s'applique lorsque le modificateur NUM LOCK est verrouillé.
  • scrolllock: s'applique lorsque le modificateur VERROUILLAGE DES DÉTECTEURS est verrouillé.

L'ordre dans lequel les établissements sont listés est important. Lorsque vous mappez une clé le système analyse toutes les propriétés pertinentes dans l'ordre et renvoie la dernière tout comportement applicable détecté.

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

Comportements

Chaque propriété correspond à un comportement. Le comportement le plus courant consiste à taper un caractère mais il y en a d'autres.

Les comportements reconnus sont les suivants:

  • none: ne saisissez pas de caractère.

    Il s'agit du comportement par défaut lorsqu'aucun caractère n'est spécifié. Spécifier none est facultative, mais elle améliore la clarté.

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

    Ce comportement entraîne la saisie du caractère spécifié dans la affichage du texte. Le littéral de caractère peut être n'importe quel caractère ASCII ou l'une des suivantes:

    • '\\': saisissez une barre oblique inverse.
    • '\n': saisissez un nouveau caractère de ligne (à utiliser pour ENTRÉE / RENVOYÉ).
    • '\t': saisissez un caractère TAB.
    • '\'': saisissez un caractère d'apostrophe.
    • '\"': saisissez un guillemet.
    • '\uXXXX': saisissez le caractère Unicode dont le point de code est indiqué en hexadécimal par XXXX.

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

    Ce comportement oblige le système à simuler une pression de touche différente lorsqu'une application ne gère pas la clé spécifiée de manière native. Il est utilisé pour prendre en charge le comportement par défaut pour les nouvelles clés que toutes les applications ne savent pas gérer, comme ESCAPE ou touches du clavier numérique (lorsque vous n'appuyez pas sur le verrouillage numérique).

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

Le système réserve deux caractères Unicode pour l'exécution de fonctions spéciales:

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

  • '\uef01': lorsque ce comportement est appliqué, l'affichage de texte affiche une Boîte de dialogue de l'outil de sélection de caractères contenant divers symboles.

Le système reconnaît les caractères Unicode suivants comme combinant des morts diacritiques Caractères clés:

  • '\u0300': accent grave.
  • '\u0301': accent aigu.
  • '\u0302': accent circonflexe
  • '\u0303': accent tilde.
  • '\u0308': accent mlaut.

Lorsqu'une clé inactive est saisie suivie d'un autre caractère, la touche morte et les éléments suivants les caractères sont composés. Par exemple, lorsque l'utilisateur saisit l'accent grave mort suivie de la lettre "a", le résultat est "à".

Pour en savoir plus sur la gestion des clés mortes, consultez KeyCharacterMap.getDeadChar.

Commentaires

Les lignes de commentaire commencent par le signe "#" et continuer jusqu'à la fin de la ligne. Comme ceci :

# A comment!

Les lignes vides sont ignorées.

Comment les combinaisons de touches sont associées aux comportements

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

MAJ+A

Supposons que l’utilisateur appuie 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é détectée est base. La propriété base s'applique toujours d'une touche, peu importe la pression sur les modificateurs. Il spécifie essentiellement les paramètres 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 sur une touche, le système note son comportement est 'a' (saisissez le caractère a).

Le système continue ensuite à analyser les propriétés suivantes au cas où l'une d'entre elles serait sont plus spécifiques que base et les remplacent. Il rencontre shift, qui s'applique également lorsque l'utilisateur appuie sur MAJ+A. Le système décide donc d'ignorer le comportement de la propriété base et choisit celui associé à la propriété shift, à savoir 'A' (saisissez le caractère A) ;

Il continue ensuite à analyser la table, mais aucune autre propriété ne s'applique à cette appui sur une touche (la touche VERR MAJ n'est pas verrouillée, si vous appuyez sur la touche ALT ou sur la touche Méta).

Le comportement obtenu pour la combinaison de touches MAJ+A est donc 'A'.

CONTRÔLE+A

Voyons maintenant ce qui se passerait si l'utilisateur appuyait sur A et CONTROL en même temps.

Comme précédemment, le système analyse la table des établissements. Il remarquera que la propriété base a été appliquée, mais continuerait l'analyse jusqu'à elle a finalement atteint la propriété control. En l'occurrence, le control apparaît après base. Son comportement remplace donc celui de base.

Le comportement obtenu pour la combinaison de touches CONTROL + A est donc none.

ÉCHAP

Supposons maintenant que l'utilisateur appuie sur Échap (Échap).

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

Cette fois, le système obtient le comportement fallback BACK, qui est un comportement de remplacement. Comme aucun littéral de caractère n'apparaît, aucun caractère n'est saisi.

Lors du traitement de la clé, le système envoie d'abord KEYCODE_ESCAPE au application. Si ce n'est pas le cas, le système mais cette fois, KEYCODE_BACK est transmis à l'application demandée par le comportement de remplacement.

Ainsi, les applications qui reconnaissent et acceptent KEYCODE_ESCAPE ont le rôle la possibilité de les gérer telle quelle, mais d'autres applications qui ne peuvent pas effectuer l'action de remplacement consistant à traiter la clé comme si elle était KEYCODE_BACK.

NUMPAD_0 avec ou sans NUM LOCK

Les touches du clavier numérique ont une interprétation très différente selon que la touche VERR NUM est verrouillée.

La déclaration de clé suivante garantit que KEYCODE_NUMPAD_0 tape 0 lorsque l'utilisateur appuie sur la touche VERR NUM. Lorsque l'utilisateur n'appuie pas sur la touche VERR NUM, la touche est délivrée à l'application comme d'habitude. Si ce n'est pas le cas, le système la clé KEYCODE_INSERT est délivrée à la place.

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

Comme vous pouvez le voir, les déclarations de clé de remplacement améliorent considérablement la compatibilité avec des applications plus anciennes qui ne reconnaissent pas ou ne prennent pas directement en charge toutes les clés présentes sur un clavier de type 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, le mappage des caractères clés Android était spécifié utilisant une syntaxe très différente et a été compilé 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 assez différent (et beaucoup plus puissant).

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 texte brut décrits dans ce document. L'ancienne syntaxe n'est pas compatible et les anciens fichiers .kcm.bin ne sont pas reconnus par le système.

Remarque sur la langue

Pour le moment, Android n'est pas compatible avec les claviers multilingues. De plus, le la carte des caractères génériques intégrée suppose que la disposition du clavier est en anglais américain.

Les OEM sont encouragés à fournir des mappages de touches personnalisés pour leurs claviers. s'ils sont conçus pour d'autres langues.

Les futures versions d'Android offriront peut-être une meilleure compatibilité avec les claviers multilingues ou des dispositions de clavier sélectionnables par l'utilisateur.

Validation

Veillez à valider vos fichiers de mappage de caractères clés à l'aide du Outil Validate Keymaps (Valider les mappages de clavier)