Schlüsselkartendateien

Tastenzuordnungsdateien ( .kcm -Dateien) sind für die Zuordnung von Kombinationen von Android-Tastencodes mit Modifikatoren zu Unicode-Zeichen verantwortlich.

Für alle internen (eingebauten) Eingabegeräte mit Tasten sind gerätespezifische Tastenlayoutdateien erforderlich , und sei es nur, um dem System mitzuteilen, dass es sich bei dem Gerät nur um ein Spezialgerät (keine vollständige Tastatur) handelt.

Gerätespezifische Tastenlayoutdateien sind für externe Tastaturen optional und werden oft überhaupt nicht benötigt. Das System bietet eine generische Tastenbelegung, die für viele externe Tastaturen geeignet ist.

Wenn keine gerätespezifische Tastenlayoutdatei verfügbar ist, wählt das System stattdessen einen Standard aus.

Standort

Schlüsselzeichentabellendateien werden nach USB-Hersteller, Produkt- (und optional Versions-)ID oder nach Eingabegerätenamen lokalisiert.

Die folgenden Pfade werden der Reihe nach konsultiert.

  • /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

Beim Erstellen eines Dateipfads, der den Gerätenamen enthält, werden alle Zeichen im Gerätenamen außer „0“ – „9“, „a“ – „z“, „A“ – „Z“, „-“ oder „_“ angezeigt. werden durch „_“ ersetzt.

Generische Schlüsselzeichentabellendatei

Das System stellt eine spezielle integrierte Schlüsselzeichentabellendatei mit dem Namen Generic.kcm bereit. Diese Tastenbelegung soll eine Vielzahl standardmäßiger externer Tastaturen unterstützen.

Ändern Sie nicht die generische Tastenzeichentabelle!

Virtuelle Tastenzeichentabellendatei

Das System stellt eine spezielle integrierte Tastenzeichentabellendatei namens Virtual.kcm bereit, die von den virtuellen Tastaturgeräten verwendet wird.

Das virtuelle Tastaturgerät ist ein synthetisches Eingabegerät mit der ID -1 (siehe KeyCharacterMap.VIRTUAL_KEYBOARD ). Es ist auf allen Android-Geräten ab Android Honeycomb 3.0 verfügbar. Der Zweck des virtuellen Tastaturgeräts besteht darin, ein bekanntes integriertes Eingabegerät bereitzustellen, das zum Einfügen von Tastenanschlägen in Anwendungen durch den IME oder durch Testinstrumente verwendet werden kann, selbst für Geräte, die keine integrierte Tastatur haben.

Es wird davon ausgegangen, dass die virtuelle Tastatur über ein vollständiges QWERTY-Layout verfügt, das auf allen Geräten gleich ist. Dies ermöglicht es Anwendungen, Tastenanschläge über das virtuelle Tastaturgerät einzugeben und immer die gleichen Ergebnisse zu erzielen.

Ändern Sie nicht die Zeichentabelle der virtuellen Tasten!

Syntax

Eine Tastenzuordnungsdatei ist eine reine Textdatei, die aus einer Tastaturtypdeklaration und einer Reihe von Tastendeklarationen besteht.

Deklaration des Tastaturtyps

Eine Tastaturtypdeklaration beschreibt das Gesamtverhalten der Tastatur. Eine Zeichentabellendatei muss eine Tastaturtypdeklaration enthalten. Aus Gründen der Übersichtlichkeit wird es häufig oben in der Datei platziert.

type FULL

Folgende Tastaturtypen werden erkannt:

  • NUMERIC : Eine numerische Tastatur (12 Tasten).

    Eine numerische Tastatur unterstützt die Texteingabe mithilfe eines Multi-Tap-Ansatzes. Möglicherweise müssen Sie mehrmals auf eine Taste tippen, um den gewünschten Buchstaben oder das gewünschte Symbol zu generieren.

    Diese Art von Tastatur ist im Allgemeinen für die Daumeneingabe konzipiert.

    Entspricht KeyCharacterMap.NUMERIC .

  • PREDICTIVE : Eine Tastatur mit allen Buchstaben, aber mit mehr als einem Buchstaben pro Taste.

    Diese Art von Tastatur ist im Allgemeinen für die Daumeneingabe konzipiert.

    Entspricht KeyCharacterMap.PREDICTIVE .

  • ALPHA : Eine Tastatur mit allen Buchstaben und vielleicht ein paar Zahlen.

    Eine alphabetische Tastatur unterstützt die direkte Texteingabe, verfügt jedoch möglicherweise über ein komprimiertes Layout und einen kleinen Formfaktor. Im Gegensatz zu einer FULL Tastatur sind einige Symbole möglicherweise nur mit speziellen Zeichenwählern auf dem Bildschirm zugänglich. Um die Tippgeschwindigkeit und -genauigkeit zu verbessern, bietet das Framework außerdem spezielle Funktionen für alphabetische Tastaturen wie automatische Großschreibung und umschaltbare/gesperrte UMSCHALT- und ALT-Tasten.

    Diese Art von Tastatur ist im Allgemeinen für die Daumeneingabe konzipiert.

  • FULL : Eine vollwertige Tastatur im PC-Stil.

    Eine Volltastatur verhält sich wie eine PC-Tastatur. Der Zugriff auf alle Symbole erfolgt direkt durch Drücken von Tasten auf der Tastatur, ohne Bildschirmunterstützung oder Funktionen wie automatische Großschreibung.

    Diese Art von Tastatur ist im Allgemeinen für das vollständige Tippen mit zwei Händen ausgelegt.

  • SPECIAL_FUNCTION : Eine Tastatur, die nur zum Ausführen von Systemsteuerungsfunktionen und nicht zum Tippen verwendet wird.

    Eine Sonderfunktionstastatur besteht nur aus nicht druckbaren Tasten wie HOME und POWER, die eigentlich nicht zum Tippen verwendet werden.

Die Tastenzuordnungen Generic.kcm und Virtual.kcm sind beide FULL Tastaturen.

Schlüsselerklärungen

Schlüsseldeklarationen bestehen jeweils aus dem Schlüsselwort key , gefolgt von einem Android-Schlüsselcodenamen, einer offenen geschweiften Klammer, einer Reihe von Eigenschaften und Verhaltensweisen und einer schließenden geschweiften Klammer.

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

Eigenschaften

Jede Schlüsseleigenschaft stellt eine Zuordnung von einem Schlüssel zu einem Verhalten her. Um die Schlüsselzeichentabellendateien kompakter zu gestalten, können mehrere Eigenschaften demselben Verhalten zugeordnet werden, indem sie durch ein Komma getrennt werden.

Im obigen Beispiel wird der label Eigenschaft das Verhalten 'A' zugewiesen. Ebenso wird den Eigenschaften ctrl , alt und meta gleichzeitig das Verhalten none zugewiesen.

Folgende Eigenschaften werden erkannt:

  • label : Gibt die Beschriftung an, die physisch auf die Taste gedruckt wird, wenn sie aus einem einzelnen Zeichen besteht. Dies ist der Wert, der von der Methode KeyCharacterMap.getDisplayLabel zurückgegeben wird.

  • number : Gibt das Verhalten (Zeichen, das eingegeben werden soll) an, wenn eine numerische Textansicht den Fokus hat, beispielsweise wenn der Benutzer eine Telefonnummer eingibt.

    Kompakte Tastaturen kombinieren häufig mehrere Symbole in einer einzigen Taste, sodass dieselbe Taste möglicherweise zum Eingeben von '1' und 'a' oder '#' und 'q' verwendet werden kann. Für diese Tasten sollte die Eigenschaft number festgelegt werden, um anzugeben, welches Symbol gegebenenfalls in einem numerischen Kontext eingegeben werden soll.

    Einige typische „numerische“ Symbole sind die Ziffern '0' bis '9' , '#' , '+' , '(' , ')' , ',' und '.' .

  • base : Gibt das Verhalten (Zeichen, das eingegeben werden soll) an, wenn keine Modifikatoren gedrückt werden.

  • <Modifikator> oder <Modifikator1> + <Modifikator2> + ...: Gibt das Verhalten (Zeichen, das eingegeben werden soll) an, wenn die Taste gedrückt wird und alle angegebenen Modifikatoren aktiv sind.

    Beispielsweise gibt die Modifikatoreigenschaft shift ein Verhalten an, das angewendet wird, wenn entweder der Modifikator LINKE UMSCHALTTASTE oder RECHTE UMSCHALTTASTE gedrückt wird.

    In ähnlicher Weise gibt die Modifikatoreigenschaft rshift+ralt ein Verhalten an, das angewendet wird, wenn die beiden Modifikatoren RECHTE UMSCHALTTASTE und RECHTE ALT-TASTE gleichzeitig gedrückt werden.

Die folgenden Modifikatoren werden in den Modifikatoreigenschaften erkannt:

  • shift : Wird angewendet, wenn entweder der Modifikator LINKE UMSCHALTTASTE oder RECHTE UMSCHALTTASTE gedrückt wird.
  • lshift : Wird angewendet, wenn der Modifikator LEFT SHIFT gedrückt wird.
  • rshift : Wird angewendet, wenn der RIGHT SHIFT-Modifikator gedrückt wird.
  • alt : Gilt, wenn entweder der Modifikator LINKE ALT- oder RECHTE ALT-Taste gedrückt wird.
  • lalt : Wird angewendet, wenn der Modifikator LINKS ALT gedrückt wird.
  • ralt : Wird angewendet, wenn der Modifikator RECHTE ALT gedrückt wird.
  • ctrl : Wird angewendet, wenn entweder der Modifikator LINKE STEUERUNG oder RECHTE STEUERUNG gedrückt wird.
  • lctrl : Wird angewendet, wenn der Modifikator LEFT CONTROL gedrückt wird.
  • rctrl : Wird angewendet, wenn der Modifikator RECHTE STEUERUNG gedrückt wird.
  • meta : Wird angewendet, wenn entweder der Modifikator LEFT META oder RIGHT META gedrückt wird.
  • lmeta : Wird angewendet, wenn der Modifikator LEFT META gedrückt wird.
  • rmeta : Wird angewendet, wenn der Modifikator RIGHT META gedrückt wird.
  • sym : Wird angewendet, wenn der SYMBOL-Modifikator gedrückt wird.
  • fn : Gilt, wenn der FUNCTION-Modifikator gedrückt wird.
  • capslock : Gilt, wenn der CAPS LOCK-Modifikator gesperrt ist.
  • numlock : Gilt, wenn der Modifikator NUM LOCK gesperrt ist.
  • scrolllock : Gilt, wenn der SCROLL LOCK-Modifikator gesperrt ist.

Die Reihenfolge, in der die Eigenschaften aufgelistet sind, ist von Bedeutung. Beim Zuordnen eines Schlüssels zu einem Verhalten durchsucht das System alle relevanten Eigenschaften der Reihe nach und gibt das zuletzt gefundene anwendbare Verhalten zurück.

Folglich haben Eigenschaften, die später angegeben werden, Vorrang vor Eigenschaften, die zuvor für einen bestimmten Schlüssel angegeben wurden.

Verhaltensweisen

Jede Eigenschaft ist einem Verhalten zugeordnet. Das häufigste Verhalten ist das Eintippen eines Zeichens, aber es gibt noch andere.

Folgende Verhaltensweisen werden erkannt:

  • none : Geben Sie kein Zeichen ein.

    Dieses Verhalten ist die Standardeinstellung, wenn kein Zeichen angegeben wird. Die Angabe von none ist optional, verbessert aber die Übersichtlichkeit.

  • 'X' : Geben Sie das angegebene Zeichenliteral ein.

    Dieses Verhalten führt dazu, dass das angegebene Zeichen in die fokussierte Textansicht eingegeben wird. Das Zeichenliteral kann ein beliebiges ASCII-Zeichen oder eine der folgenden Escape-Sequenzen sein:

    • '\\' : Geben Sie einen Backslash ein.
    • '\n' : Geben Sie ein neues Zeilenzeichen ein (verwenden Sie dieses für ENTER/RETURN).
    • '\t' : Geben Sie ein TAB-Zeichen ein.
    • '\'' : Geben Sie ein Apostrophzeichen ein.
    • '\"' : Geben Sie ein Anführungszeichen ein.
    • '\uXXXX' : Geben Sie das Unicode-Zeichen ein, dessen Codepunkt im Hexadezimalformat durch XXXX angegeben wird.

  • fallback <Name des Android-Schlüsselcodes>: Führen Sie eine Standardaktion aus, wenn der Schlüssel nicht von der Anwendung verarbeitet wird.

    Dieses Verhalten führt dazu, dass das System einen anderen Tastendruck simuliert, wenn eine Anwendung die angegebene Taste nicht nativ verarbeitet. Es wird verwendet, um das Standardverhalten für neue Tasten zu unterstützen, mit denen nicht alle Anwendungen umgehen können, z. B. ESCAPE oder Ziffernblocktasten (wenn die Num-Taste nicht gedrückt ist).

    Wenn ein Fallback-Verhalten ausgeführt wird, empfängt die Anwendung zwei Tastendrücke: einen für die ursprüngliche Taste und einen weiteren für die ausgewählte Fallback-Taste. Wenn die Anwendung während des Schlüsselvorgangs den ursprünglichen Schlüssel verarbeitet, wird das Fallback-Schlüsselereignis abgebrochen ( KeyEvent.isCanceled gibt true zurück).

Das System reserviert zwei Unicode-Zeichen für die Ausführung spezieller Funktionen:

  • '\uef00' : Wenn dieses Verhalten ausgeführt wird, verbraucht und entfernt die Textansicht die vier Zeichen vor dem Cursor, interpretiert sie als Hexadezimalziffern und fügt den entsprechenden Unicode-Codepunkt ein.

  • '\uef01' : Wenn dieses Verhalten ausgeführt wird, zeigt die Textansicht ein Zeichenauswahldialogfeld an, das verschiedene Symbole enthält.

Das System erkennt die folgenden Unicode-Zeichen als Kombination diakritischer toter Schlüsselzeichen:

  • '\u0300' : Ernsthafter Akzent.
  • '\u0301' : Akuter Akzent.
  • '\u0302' : Zirkumflex-Akzent.
  • '\u0303' : Tilde-Akzent.
  • '\u0308' : Umlaut-Akzent.

Wenn eine tote Taste gefolgt von einem anderen Zeichen eingegeben wird, werden die tote Taste und die folgenden Zeichen zusammengesetzt. Wenn der Benutzer beispielsweise eine Tottaste mit Gravis-Akzent gefolgt vom Buchstaben „a“ eingibt, ist das Ergebnis „à“.

Weitere Informationen zur Handhabung toter Schlüssel finden Sie unter KeyCharacterMap.getDeadChar .

Kommentare

Kommentarzeilen beginnen mit „#“ und werden bis zum Ende der Zeile fortgesetzt. So was:

# A comment!

Leerzeilen werden ignoriert.

Wie Tastenkombinationen Verhaltensweisen zugeordnet werden

Wenn der Benutzer eine Taste drückt, sucht das System nach dem Verhalten, das mit der Kombination aus diesem Tastendruck und den aktuell gedrückten Modifikatoren verbunden ist.

UMSCHALT + A

Angenommen, der Benutzer hat gleichzeitig A und UMSCHALT gedrückt. Das System sucht zunächst nach den Eigenschaften und Verhaltensweisen, die mit KEYCODE_A verknüpft sind.

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

Das System durchsucht die Eigenschaften vom ersten bis zum letzten und von links nach rechts und ignoriert dabei die besonderen Eigenschaften label und number .

Die erste angetroffene Eigenschaft ist base . Die base gilt immer für eine Taste, unabhängig davon, welche Modifikatoren gedrückt werden. Es gibt im Wesentlichen das Standardverhalten für den Schlüssel an, sofern es nicht durch die folgenden Eigenschaften überschrieben wird. Da die base für diesen Tastendruck gilt, merkt sich das System die Tatsache, dass sein Verhalten 'a' ist (geben Sie das Zeichen a ein).

Das System scannt dann weiterhin nachfolgende Eigenschaften, falls diese spezifischer als base sind, und überschreibt diese. Es trifft auf shift , die auch für das Drücken der Tastenkombination UMSCHALT+A gilt. Das System beschließt daher, das Verhalten der base zu ignorieren und wählt das mit der shift verknüpfte Verhalten, nämlich 'A' (geben Sie das Zeichen A ein).

Anschließend wird die Tabelle weiter durchsucht, es gelten jedoch keine weiteren Eigenschaften für diesen Tastendruck (FESTSTELLTASTE ist nicht gesperrt, keine STRG-Taste wird gedrückt, keine ALT-Taste wird gedrückt und keine META-Taste wird gedrückt).

Das resultierende Verhalten für die Tastenkombination SHIFT + A ist also 'A' .

STRG + A

Überlegen Sie nun, was passieren würde, wenn der Benutzer A und STRG gleichzeitig drücken würde.

Wie zuvor würde das System die Tabelle der Eigenschaften durchsuchen. Es würde zwar bemerken, dass die base angewendet wurde, würde aber auch mit dem Scannen fortfahren, bis es schließlich die control erreicht. Zufällig erscheint die control nach base , sodass ihr Verhalten das base überschreibt.

Das resultierende Verhalten für die Tastenkombination STRG + A ist also none .

FLUCHT

Angenommen, der Benutzer hat ESCAPE gedrückt.

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

Diesmal erhält das System das Verhalten fallback BACK , ein Fallback-Verhalten. Da kein Zeichenliteral erscheint, wird kein Zeichen eingegeben.

Bei der Verarbeitung des Schlüssels übermittelt das System zunächst KEYCODE_ESCAPE an die Anwendung. Wenn die Anwendung dies nicht verarbeiten kann, versucht das System es erneut, übermittelt dieses Mal jedoch KEYCODE_BACK an die Anwendung, wie vom Fallback-Verhalten gefordert.

Anwendungen, die KEYCODE_ESCAPE erkennen und unterstützen, haben also die Möglichkeit, damit umzugehen, wie sie sind, aber andere Anwendungen, die dies nicht tun, können stattdessen die Fallback-Aktion ausführen und den Schlüssel so behandeln, als wäre er KEYCODE_BACK .

NUMPAD_0 mit oder ohne NUM-Taste

Die Tasten des Ziffernblocks haben sehr unterschiedliche Bedeutungen, je nachdem, ob die NUM-Taste gesperrt ist.

Die folgende Schlüsseldeklaration stellt sicher, dass KEYCODE_NUMPAD_0 0 eingibt, wenn NUM LOCK gedrückt wird. Wenn die NUM-TASTE nicht gedrückt wird, wird die Taste wie gewohnt an die Anwendung übermittelt. Wenn sie nicht verarbeitet wird, wird stattdessen die Ersatztaste KEYCODE_INSERT übermittelt.

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

Wie wir sehen können, verbessern Ersatztastendeklarationen die Kompatibilität mit älteren Anwendungen erheblich, die nicht alle Tasten einer vollständigen PC-Tastatur erkennen oder direkt unterstützen.

Beispiele

Vollständige Tastatur

# 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
}

Alphanumerische Tastatur

# 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'
}

Gamepad

# 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
}

Kompatibilitätshinweis

Vor Android Honeycomb 3.0 wurde die Android-Tastenzeichentabelle mit einer ganz anderen Syntax spezifiziert und zum Zeitpunkt der Erstellung in ein Binärdateiformat ( .kcm.bin ) kompiliert.

Obwohl das neue Format dieselbe Erweiterung .kcm verwendet, ist die Syntax deutlich anders (und viel leistungsfähiger).

Ab Android Honeycomb 3.0 müssen alle Android-Schlüsselzeichentabellendateien die neue Syntax und das Nur-Text-Dateiformat verwenden, die in diesem Dokument beschrieben werden. Die alte Syntax wird nicht unterstützt und die alten .kcm.bin Dateien werden vom System nicht erkannt.

Sprachnotiz

Android unterstützt derzeit keine mehrsprachigen Tastaturen. Darüber hinaus geht die integrierte generische Tastenzeichentabelle von einem Tastaturlayout in US-Englisch aus.

OEMs werden aufgefordert, benutzerdefinierte Tastenbelegungen für ihre Tastaturen bereitzustellen, wenn diese für andere Sprachen konzipiert sind.

Zukünftige Versionen von Android bieten möglicherweise eine bessere Unterstützung für mehrsprachige Tastaturen oder vom Benutzer wählbare Tastaturlayouts.

Validierung

Stellen Sie sicher, dass Sie Ihre Tastenzuordnungsdateien mit dem Tool „Validate Keymaps“ validieren.