Pliki układu kluczy

Pliki układu klawiszy (pliki .kl) mapują kody klawiszy i osi Linuxa na kody klawiszy i osi Androida oraz określają powiązane flagi zasad. Pliki układu klawiszy związane z poszczególnymi urządzeniami to:

• Wymagany w przypadku wewnętrznych (wbudowanych) urządzeń wejściowych z klawiszami, w tym klawiszy specjalnych, takich jak klawisze głośności, zasilania i sterowania multimediami w słuchawkach.
• Opcjonalny w przypadku innych urządzeń wejściowych, ale zalecany w przypadku klawiatur i joysticków do specjalnych zastosowań.

Jeśli nie ma pliku z układem klawiszy dla danego urządzenia, system wybierze domyślny.

Lokalizacja

Pliki układu klawiszy są zlokalizowane według identyfikatora dostawcy USB, identyfikatora produktu (i opcjonalnie wersji) lub nazwy urządzenia wejściowego. W kolejności sprawdzane są te ścieżki:

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

Podczas tworzenia ścieżki pliku zawierającej nazwę urządzenia wszystkie znaki w nazwie urządzenia inne niż „0–9”, „a–z”, „A–Z”, „–” lub „_” są zastępowane przez „_”.

Plik z ogólnym układem klawiszy

System udostępnia specjalny wbudowany plik z generycznym układem klucza o nazwie Generic.kl. Ten układ klawiszy jest przeznaczony do obsługi różnych standardowych klawiatur zewnętrznych i joysticków. Nie modyfikuj ogólnego układu klucza!

Składnia

Plik układu klucza to zwykły plik tekstowy zawierający deklaracje kluczy lub osi oraz flagi.

Deklaracje kluczy

Deklaracje kluczy składają się ze słowa kluczowego key, a następnie numeru kodu klucza Linuxa i nazwy kodu klucza Androida lub użycia słowa kluczowego, a następnie użycia HID i nazwy kodu klucza Androida. Użycie HID jest reprezentowane jako 32-bitowa liczba całkowita, w której 16 bitów o większych wartościach reprezentuje stronę użycia HID, a 16 bitów o mniejszych wartościach reprezentuje identyfikator użycia HID. Po każdej deklaracji może następować opcjonalny zestaw flag zasad oddzielonych spacjami.

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

Rozpoznawane są te flagi zasad:

• FUNCTION: klawisz powinien być interpretowany tak, jak gdyby był też naciśnięty klawisz FUNKCJA.
• GESTURE: klucz wygenerowany przez gest użytkownika, taki jak dotknięcie ekranu dotykowego dłonią.
• VIRTUAL: przycisk jest wirtualnym przyciskiem dotykowym (przycisk pojemnościowy) obok głównego ekranu dotykowego. W efekcie włączona jest specjalna logika debouncingu (patrz poniżej).

Deklaracje osi

Deklaracje osi składają się ze słowa kluczowego axis, a następnie numeru kodu osi Linuxa i kwalifikatorów, które kontrolują zachowanie osi, w tym co najmniej 1 nazwę kodu osi Androida.

Osie podstawowe

Podstawowa oś po prostu mapuje kod osi Linuxa na nazwę kodu osi Androida. Poniższa deklaracja mapuje ABS_X (wskazany przez 0x00) na AXIS_X (wskazany przez X).

axis 0x00 X

W powyższym przykładzie, jeśli wartość ABS_X to 5, to AXIS_X ma wartość 5.

Dzielenie osi

Osie podzielone mapują kod osi Linuxa na 2 nazwy kodu osi Androida, tak aby wartości poniżej lub powyżej progu były mapowane na 2 różne osie. Takie mapowanie jest przydatne, gdy pojedyncza fizyczna oś raportowana przez urządzenie koduje 2 różne, wzajemnie wykluczające się osie logiczne.

W deklaracji poniżej wartości osi ABS_Y (oznaczone przez 0x01) są mapowane na AXIS_GAS, gdy są mniejsze niż 0x7f, lub na AXIS_BRAKE, gdy są większe niż 0x7f.

axis 0x01 split 0x7f GAS BRAKE

W powyższym przykładzie, jeśli wartość ABS_Y to 0x7d, to AXIS_GAS ma wartość 2 (0x7f - 0x7d), a AXIS_BRAKE ma wartość 0. Jeśli natomiast wartość ABS_Y to 0x83, to AXIS_GAS ma wartość 0, a AXIS_BRAKE – wartość 4(0x83 - 0x7f). Jeśli natomiast wartość ABS_Y jest równa wartości podziału 0x7f, to zarówno AXIS_GAS, jak i AXIS_BRAKE mają wartość 0.

odwrócone osie,

Odwrócona oś odwraca znak wartości osi. Poniższa deklaracja mapuje wartość ABS_RZ (oznaczoną jako 0x05) na wartość AXIS_BRAKE (oznaczoną jako BRAKE), a następnie odwraca wynik, negując go.

axis 0x05 invert BRAKE

W powyższym przykładzie, jeśli wartość ABS_RZ to 2, to AXIS_BRAKE ma wartość -2.

Opcja wyśrodkowania

Urządzenie sterujące może zgłaszać zdarzenia wejścia nawet wtedy, gdy nie jest używane, z powodu hałasu. Ten szum pochodzi zwykle z lewego lub prawego drążka i powoduje, że sterownik raportuje wartość pozycji zbliżoną do 0. Wartość „center flat” określa poziom szumu, jaki można się spodziewać w przypadku spoczynku kontrolera.

Protokół wejściowy Linuxa umożliwia sterownikom urządzeń wejściowych określenie wartości środkowej osi drążka, ale nie wszystkie sterowniki to robią, a niektóre z nich podają nieprawidłowe wartości. Aby rozwiązać ten problem, po deklaracji osi może wystąpić opcja flat, która określa szerokość regionu wokół środkowej pozycji osi, która powinna być traktowana jako wyśrodkowana.

Jeśli na przykład sterownik urządzenia podaje wartości AXIS_X w zakresie od 0 do 100, system wejściowy Androida mapuje 0 na -1, a 100 na 1. Środek zakresu będzie wynosił 50 w nieskalowanych współrzędnych i 0 w skalowanych współrzędnych. Jeśli wartość płaska jest równa 10, deweloperzy powinni założyć, że każda wartość AXIS_X mieści się w zakresie od -0,1 do 0,1 (od 40 do 60 w nieprzeskalowanych współrzędnych) jest szumem, i traktować te wartości pochodzące z joysticka jako zero.

Uwaga: plik układu klawiszy określa wartość dla przestrzeni współrzędnych sterownika, ale wartość zwracana przez android.view.InputDevice.MotionRange#getFlat() jest w przestrzeni współrzędnych Androida.

axis 0x03 Z flat 4096

W powyższym przykładzie wartość środkowej płaszczyzny jest ustawiona na 4096.

Komentarze

Wiersze komentarzy zaczynają się od # i trwają do końca wiersza:

# A comment!

Puste wiersze są ignorowane.

Przykłady

Klawiatura

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

Systemowe elementy sterujące

# 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

Przyciski pojemnościowe

# 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

Sterowanie multimediami za pomocą gniazda słuchawek

# 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

Wirtualne klawisze

System wprowadzania danych udostępnia specjalne funkcje do implementowania wirtualnych przycisków w tych zastosowaniach:

1. Jeśli wirtualne przyciski ekranowe są wyświetlane graficznie na ekranie (np. w przypadku Galaxy Nexus), są one implementowane przez komponent paska nawigacyjnego w pakiecie interfejsu System UI. Ponieważ wirtualne klawisze graficzne są implementowane na wysokim poziomie w systemie, nie są one powiązane z plikami układu klawiszy, więc te informacje nie mają zastosowania.
2. Jeśli wirtualne przyciski są implementowane jako rozszerzony obszar dotykowy, który jest częścią głównego ekranu dotykowego (np. na Nexusie One), system wejściowy używa pliku mapy wirtualnych klawiszy do przekształcania współrzędnych X/Y w kody klawiszy Linuxa, a następnie używa pliku rozkładu klawiszy, aby przekształcać kody klawiszy Linuxa w kody klawiszy Androida (szczegółowe informacje o plikach mapy wirtualnych klawiszy znajdziesz w artykule Urządzenia dotykowe). Plik z rozkładem klawiszy dla urządzenia z ekranem dotykowym musi określać odpowiednie mapowanie klawiszy i zawierać flagę VIRTUAL dla każdego klawisza.
3. Jeśli wirtualne klawisze są implementowane jako przyciski pojemnościowe oddzielne od głównego ekranu dotykowego (jak w Nexusie S), sterownik urządzenia jądra lub oprogramowanie układowe odpowiada za przekształcanie dotyku w kody klawiszy Linuxa, które system wejściowy przekształca następnie w kody klawiszy Androida za pomocą pliku układu klawiszy. Plik układu klawiszy dla urządzenia z przyciskami pojemnościowymi musi określać odpowiednie mapowanie klawiszy i zawierać flagę VIRTUAL dla każdego klawisza.

Gdy wirtualne przyciski znajdują się na ekranie dotykowym lub w jego bezpośrednim sąsiedztwie, użytkownicy mogą przypadkowo nacisnąć przycisk, gdy dotkną ekranu w pobliżu dołu lub przesuną po nim palcem od góry do dołu bądź odwrotnie. Aby temu zapobiec, system wejściowy stosuje niewielkie odszumianie, dzięki któremu naciśnięcia wirtualnych przycisków są ignorowane przez krótki czas po ostatnim dotknięciu ekranu dotykowego (to opóźnienie nazywa się czasem bezczynności wirtualnego przycisku).

Aby włączyć debouncing wirtualnego przycisku:

1. Prześlij plik z rozkładem klawiszy dla ekranu dotykowego lub urządzenia wejściowego z przyciskami pojemnościowymi z flagą VIRTUAL ustawioną dla każdego klawisza.

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

2. Ustaw wartość klucza wirtualnego „quiet time” w nakładce zasobu dla zasobu framework config.xml.

   <!-- 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>
   

Weryfikacja

Plik układu klawiszy należy zweryfikować za pomocą narzędzia Sprawdzanie map klawiszy.