Tastenlayoutdateien

In Schlüssellayoutdateien (.kl-Dateien) werden Linux-Tasten- und -Achsencodes in Android-Tasten- und -Achsencodes umgewandelt und zugehörige Richtlinien-Flags angegeben. Gerätespezifische Dateien für das Tastenlayout:

  • Erforderlich für interne (eingebaute) Eingabegeräte mit Tasten, einschließlich spezieller Tasten wie Lautstärke, Ein/Aus und Medientasten für Headsets.
  • Optional für andere Eingabegeräte, aber empfohlen für Tastaturen und Joysticks mit spezieller Verwendung.

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

Standort

Dateien mit Tastaturlayouts werden anhand der ID des USB-Herstellers, des Produkts (und optional der Version) oder des Namens des Eingabegeräts gefunden. Die folgenden Pfade werden in der Reihenfolge abgefragt:

  • /odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /odm/usr/keylayout/DEVICE_NAME.kl
  • /vendor/usr/keylayout/DEVICE_NAME.kl
  • /system/usr/keylayout/DEVICE_NAME.kl
  • /data/system/devices/keylayout/DEVICE_NAME.kl
  • /odm/usr/keylayout/Generic.kl
  • /vendor/usr/keylayout/Generic.kl
  • /system/usr/keylayout/Generic.kl
  • /data/system/devices/keylayout/Generic.kl

Beim Erstellen eines Dateipfads, der den Gerätenamen enthält, werden alle Zeichen im Gerätenamen mit Ausnahme von „0“ bis „9“, „a“ bis „z“, „A“ bis „Z“, „-“ oder „_“ durch „_“ ersetzt.

Datei mit generischen Tastenlayouts

Das System bietet eine spezielle integrierte Datei mit einem generischen Tastenlayout namens Generic.kl. Dieses Tastenlayout ist für eine Vielzahl von standardmäßigen externen Tastaturen und Joysticks vorgesehen. Ändern Sie das Layout des generischen Schlüssels nicht.

Syntax

Eine Schlüssellayoutdatei ist eine Nur-Textdatei mit Schlüssel- oder Achsendeklarationen und Flags.

Wichtige Erklärungen

Schlüsseldeklarationen bestehen aus dem Keyword key, gefolgt von einer Linux-Schlüsselcodenummer und dem Namen des Android-Schlüsselcodes oder dem Keyword „Nutzung“, gefolgt von einer HID-Nutzung und dem Namen des Android-Schlüsselcodes. Die HID-Nutzung wird als 32-Bit-Ganzzahl dargestellt, wobei die oberen 16 Bit die HID-Nutzungsseite und die unteren 16 Bit die HID-Nutzungs-ID repräsentieren. Auf jede Erklärung kann optional eine Reihe von durch Leerzeichen getrennten Richtlinien-Flags folgen.

key 1     ESCAPE
key 114   VOLUME_DOWN
key 16    Q                 VIRTUAL
key usage 0x0c006F          BRIGHTNESS_UP

Die folgenden Richtlinien-Flags werden erkannt:

  • FUNCTION: Der Schlüssel sollte so interpretiert werden, als wäre auch die FUNCTION-Taste gedrückt.
  • GESTURE: Der Schlüssel, der durch eine Nutzergeste generiert wird, z. B. durch Berühren des Touchscreens mit der Handfläche.
  • VIRTUAL: Der Schlüssel ist eine virtuelle Softkey-Schaltfläche (kapazitive Schaltfläche) neben dem Haupt-Touchscreen. Dadurch wird eine spezielle Entprelllogik aktiviert (siehe unten).

Achsendeklarationen

Achsendeklarationen bestehen aus dem Schlüsselwort axis gefolgt von einer Linux-Achsencodenummer und Qualifiern, die das Verhalten der Achse steuern, einschließlich mindestens eines Android-Achsencodenamens.

Grundlegende Achsen

Bei einer einfachen Achse wird einfach ein Linux-Achsencode einem Android-Achsencode zugeordnet. In der folgenden Deklaration wird ABS_X (0x00) zu AXIS_X (X) zugeordnet.

axis 0x00 X

Wenn der Wert von ABS_X im obigen Beispiel 5 ist, wird AXIS_X auf 5 gesetzt.

Achsen teilen

Bei einer geteilten Achse wird ein Linux-Achsencode zwei Android-Achsencodenamen zugeordnet, sodass Werte, die unter oder über einem Grenzwert liegen, bei der Zuordnung auf zwei verschiedene Achsen aufgeteilt werden. Diese Zuordnung ist nützlich, wenn eine einzelne vom Gerät gemeldete physische Achse zwei verschiedene sich gegenseitig ausschließende logische Achsen codiert.

In der folgenden Deklaration werden Werte der ABS_Y-Achse (0x01) AXIS_GAS zugeordnet, wenn sie kleiner als 0x7f sind, und AXIS_BRAKE, wenn sie größer als 0x7f sind.

axis 0x01 split 0x7f GAS BRAKE

Wenn der Wert von ABS_Y im obigen Beispiel 0x7d ist, wird AXIS_GAS auf 2 (0x7f - 0x7d) und AXIS_BRAKE auf 0 gesetzt. Wenn der Wert von ABS_Y dagegen 0x83 ist, wird AXIS_GAS auf 0 und AXIS_BRAKE auf 4 (0x83 - 0x7f) gesetzt. Wenn der Wert von ABS_Y dem Split-Wert von 0x7f entspricht, werden sowohl AXIS_GAS als auch AXIS_BRAKE auf 0 gesetzt.

Umgekehrte Achsen

Bei einer umgekehrten Achse wird das Vorzeichen des Achsenwerts umgekehrt. In der folgenden Deklaration wird ABS_RZ (0x05) zu AXIS_BRAKE (BRAKE) zugeordnet und die Ausgabe durch Negieren umgekehrt.

axis 0x05 invert BRAKE

Wenn der Wert von ABS_RZ im obigen Beispiel 2 ist, wird AXIS_BRAKE auf -2 gesetzt.

Option „Zentrieren“

Ein Joystick kann aufgrund von Störungen Eingabeereignisse melden, auch wenn er nicht verwendet wird. Dieser Fehler stammt in der Regel vom linken und/oder rechten Stick und führt dazu, dass der Treiber einen Positionswert nahe 0 meldet. Der Wert „center flat“ gibt die Geräuschentwicklung des Controllers im Ruhezustand an.

Das Linux-Eingabeprotokoll bietet eine Möglichkeit für Eingabegerätetreiber, den Mittelwert der Joystickachsen anzugeben. Allerdings geben nicht alle Treiber diesen Wert an und einige liefern falsche Werte. Um dieses Problem zu beheben, kann einer Achsendeklaration eine flat-Option folgen, mit der die Breite des Bereichs um die Mittelposition der Achse angegeben wird, der als zentriert betrachtet werden soll.

Wenn ein Gerätetreiber beispielsweise Werte für AXIS_X zwischen 0 und 100 meldet, wird 0 vom Android-Eingabesystem auf -1 und 100 auf 1 zugeordnet. Der Mittelpunkt des Bereichs ist in den nicht skalierten Koordinaten 50 und in den skalierten Koordinaten 0. Wenn ein Wert für „flat“ gleich 10 ist, sollten die Entwickler davon ausgehen, dass alle AXIS_X-Werte zwischen -0,1 und 0,1 (zwischen 40 und 60 in nicht skalierten Koordinaten) als Rauschen zu betrachten sind und diese Werte vom Joystick als Null behandelt werden.

Hinweis: In der Schlüssellayoutdatei wird der Wert für den Fahrerkoordinatenraum angegeben. Der von android.view.InputDevice.MotionRange#getFlat() gemeldete Wert ist jedoch im Android-Koordinatenraum.

axis 0x03 Z flat 4096

Im obigen Beispiel ist der Wert für die Mitte flach auf 4096 festgelegt.

Kommentare

Kommentarzeilen beginnen mit # und gehen bis zum Ende der Zeile:

# A comment!

Leere Zeilen werden ignoriert.

Beispiele

Tastatur

# This is an example of a key layout file for a keyboard.

key 1     ESCAPE
key 2     1
key 3     2
key 4     3
key 5     4
key 6     5
key 7     6
key 8     7
key 9     8
key 10    9
key 11    0
key 12    MINUS
key 13    EQUALS
key 14    DEL

# etc...

System­steuerelemente

# This is an example of a key layout file for basic system controls,
# such as volume and power keys which are typically implemented as GPIO pins
# the device decodes into key presses.

key 114   VOLUME_DOWN
key 115   VOLUME_UP
key 116   POWER

Kapazitive Tasten

# This is an example of a key layout file for a touch device with capacitive buttons.

key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL

Mediensteuerung über den Headsetanschluss

# This is an example of a key layout file for headset mounted media controls.
# A typical headset jack interface might have special control wires or detect known
# resistive loads as corresponding to media functions or volume controls.
# This file assumes that the driver decodes these signals and reports media
# controls as key presses.

key 163   MEDIA_NEXT
key 165   MEDIA_PREVIOUS
key 226   HEADSETHOOK

Joystick

# This is an example of a key layout file for a joystick.

# These are the buttons that the joystick supports, represented as keys.
key 304   BUTTON_A
key 305   BUTTON_B
key 307   BUTTON_X
key 308   BUTTON_Y
key 310   BUTTON_L1
key 311   BUTTON_R1
key 314   BUTTON_SELECT
key 315   BUTTON_START
key 316   BUTTON_MODE
key 317   BUTTON_THUMBL
key 318   BUTTON_THUMBR

# Left and right stick.
# The reported value for flat is 128 in a range of -32767 to 32768, which is absurd.
# This confuses applications that rely on the flat value because the joystick
# actually settles in a flat range of +/- 4096 or so. We override it here.
axis 0x00 X flat 4096
axis 0x01 Y flat 4096
axis 0x03 Z flat 4096
axis 0x04 RZ flat 4096

# Triggers.
axis 0x02 LTRIGGER
axis 0x05 RTRIGGER

# Hat.
axis 0x10 HAT_X
axis 0x11 HAT_Y

Virtuelle Softkeys

Das Eingabesystem bietet spezielle Funktionen für die Implementierung virtueller Softkeys in den folgenden Anwendungsfällen:

  1. Wenn die virtuellen Softkeys grafisch auf dem Display angezeigt werden (z. B. auf dem Galaxy Nexus), werden sie über die Navigationsleiste im System-UI-Paket implementiert. Da virtuelle Touchbedienungen auf einer hohen Schicht im System implementiert sind, kommen keine Tastenlayoutdateien zum Einsatz und die folgenden Informationen gelten nicht.
  2. Wenn die virtuellen Softkeys als erweiterte berührbare Region implementiert sind, die Teil des Haupt-Touchscreens ist (z. B. auf dem Nexus One), verwendet das Eingabesystem eine Datei mit einer virtuellen Tastenbelegung, um X/Y-Touch-Koordinaten in Linux-Tastencodes umzuwandeln, und dann die Datei mit dem Tastenlayout, um Linux-Tastencodes in Android-Tastencodes umzuwandeln. Weitere Informationen zu Dateien mit einer virtuellen Tastenbelegung finden Sie unter Touchbedienung. Die Datei mit dem Tastenlayout für das Eingabegerät mit Touchscreen muss die entsprechende Tastenzuordnung angeben und das Flag VIRTUAL für jede Taste enthalten.
  3. Wenn die virtuellen Softkeys als kapazitive Tasten implementiert sind, die vom Haupt-Touchscreen getrennt sind (z. B. auf dem Nexus S), ist der Kernel-Gerätetreiber oder die Firmware für die Umwandlung von Berührungen in Linux-Tastencodes verantwortlich, die dann vom Eingabesystem mithilfe der Tastenlayoutdatei in Android-Tastencodes umgewandelt werden. Die Tastenlayoutdatei für das Eingabegerät mit kapazitiven Tasten muss die entsprechende Tastenzuordnung angeben und das Flag VIRTUAL für jede Taste enthalten.

Wenn sich virtuelle Softkeys auf dem Touchscreen oder in unmittelbarer Nähe befinden, können Nutzer leicht versehentlich eine Taste drücken, wenn sie den Touchscreen unten berühren oder den Finger von oben nach unten oder von unten nach oben darüber bewegen. Um dies zu verhindern, wendet das Eingabesystem eine kleine Entprellung an, sodass Tastendrücke auf virtuelle Softkeys nach der letzten Berührung des Touchscreens für einen kurzen Zeitraum ignoriert werden. Diese Verzögerung wird als Ruhezeit der virtuellen Taste bezeichnet.

So aktivieren Sie die Debounce-Funktion für virtuelle Softkeys:

  1. Geben Sie eine Tastenlayoutdatei für das Touchscreen- oder kapazitive Eingabegerät an, wobei für jede Taste das Flag VIRTUAL festgelegt ist. 
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. Legen Sie den Wert der Ruhezeit des virtuellen Schlüssels in einem Ressourcen-Overlay für die Framework-Ressource config.xml fest. 
    <!-- Specifies the amount of time to disable virtual keys after the screen
is touched to filter out accidental virtual key presses due to swiping gestures
or taps near the edge of the display. May be 0 to disable the feature.
It is recommended that this value be no more than 250 ms.
This feature should be disabled for most devices. -->

<integer name="config_virtualKeyQuietTimeMillis">250</integer>

Zertifizierungsstufe

Sie sollten Ihre Tastenlayoutdateien mit dem Tool Validate Keymaps validieren.