按鍵佈局文件

按鍵佈局文件( .kl文件)將 Linux 按鍵代碼和軸代碼映射到 Android 按鍵代碼和軸代碼,並指定相關的策略標誌。特定於設備的鍵佈局文件是:

  • 帶有按鍵的內部(內置)輸入設備需要,包括音量、電源和耳機媒體鍵等特殊按鍵。
  • 對於其他輸入設備是可選的,但推薦用於專用鍵盤和操縱桿。

如果沒有設備特定的按鍵佈局文件可用,系統將選擇默認值。

地點

按鍵佈局文件按 USB 供應商、產品(和可選的版本)ID 或輸入設備名稱定位。依次查詢以下路徑:

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

構造包含設備名稱的文件路徑時,設備名稱中除 '0'-'9'、'a'-'z'、'A'-'Z'、'-' 或 '_' 之外的所有字符替換為“_”。

通用鍵佈局文件

系統提供了一個特殊的內置通用鍵佈局文件,稱為Generic.kl 。此按鍵佈局旨在支持各種標準外接鍵盤和操縱桿。不要修改通用鍵佈局!

句法

鍵佈局文件是由鍵或軸聲明和標誌組成的純文本文件。

關鍵聲明

密鑰聲明由關鍵字key後跟 Linux 密鑰代碼號和 Android 密鑰代碼名稱組成,或者由關鍵字用法後跟 HID 用法和 Android 密鑰代碼名稱組成。 HID 使用情況表示為一個 32 位整數,其中高 16 位表示 HID 使用頁面,低 16 位表示 HID 使用 ID。任何一個聲明都可以後跟一組可選的以空格分隔的策略標誌。

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

識別以下策略標誌:

  • FUNCTION :該鍵應被解釋為好像也按下了 FUNCTION 鍵。
  • GESTURE :由用戶手勢生成的鍵,例如手掌觸摸屏。
  • VIRTUAL :該鍵是與主觸摸屏相鄰的虛擬軟鍵(電容式按鈕)。這會導致啟用特殊的去抖動邏輯(見下文)。

軸聲明

每個軸聲明都包含關鍵字axis ,後跟一個 Linux 軸代碼編號和控制軸行為的限定符,包括至少一個 Android 軸代碼名稱。

基本軸

基本軸只是將 Linux 軸代碼映射到 Android 軸代碼名稱。以下聲明將ABS_X (由0x00表示)映射到AXIS_X (由X表示)。

axis 0x00 X

在上面的示例中,如果ABS_X的值為5 ,則AXIS_X設置為5

拆分軸

拆分軸將 Linux 軸代碼映射到兩個 Android 軸代碼名稱,以便在映射時將小於或大於閾值的值拆分到兩個不同的軸上。當設備報告的單個物理軸對兩個不同的互斥邏輯軸進行編碼時,此映射很有用。

以下聲明將ABS_Y軸的值(由0x01表示)映射到小於0x7f時的AXIS_GAS或大於0x7f時的AXIS_BRAKE

axis 0x01 split 0x7f GAS BRAKE

在上面的示例中,如果AXIS_GAS ABS_Y 0x7d 2 ( 0x7f - 0x7d ) 並且AXIS_BRAKE設置為0 。相反,如果ABS_Y的值為0x83 ,則AXIS_GAS設置為0AXIS_BRAKE設置為4 ( 0x83 - 0x7f )。最後,如果ABS_Y的值等於0x7f的拆分值,則AXIS_GASAXIS_BRAKE都設置為0

倒軸

反轉軸反轉軸值的符號。以下聲明將ABS_RZ (由0x05表示)映射到AXIS_BRAKE (由BRAKE表示),並通過取反來反轉輸出。

axis 0x05 invert BRAKE

在上面的示例中,如果ABS_RZ的值為2 ,則AXIS_BRAKE設置為-2

中心平面選項

由於噪聲,即使在不使用操縱桿時,操縱桿設備也可能報告輸入事件。這種噪音通常來自左搖桿和/或右搖桿,並導致駕駛員報告接近 0 的位置值。“中心平坦”值指定了控制器靜止時預期的噪音量。

Linux 輸入協議為輸入設備驅動程序提供了一種方法來指定操縱桿軸的中心平面值,但並非所有驅動程序都報告它並且其中一些提供了不正確的值。要解決此問題,軸聲明後可能會跟隨一個flat選項,該選項指定應視為居中的軸中心位置周圍區域的寬度。

例如,如果設備驅動程序報告AXIS_X的值介於 0 和 100 之間,那麼 Android 輸入系統會將 0 映射到 -1,而 100 將映射到 1。範圍的中心在未縮放坐標中為 50,在縮放坐標中為 0。如果平坦值等於 10,則開發人員應假定報告的任何介於 -0.1 和 0.1 之間(在未縮放坐標中介於 40 和 60 之間)的任何AXIS_X值都是噪聲,並將來自操縱桿的這些值視為零。

注意:雖然鍵佈局文件指定了驅動程序坐標空間的值,但 android.view.InputDevice.MotionRange#getFlat() 報告的值在 Android 坐標空間中。

axis 0x03 Z flat 4096

在上面的示例中,中心平面值設置為4096

註釋

註釋行以 # 開頭並一直到行尾:

# A comment!

空白行被忽略。

例子

鍵盤

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

系統控制

# 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

電容式按鈕

# 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

耳機插孔媒體控件

# 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

操縱桿

# 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

虛擬軟鍵

輸入系統提供了在以下用例中實現虛擬軟鍵的特殊功能:

  1. 如果虛擬軟鍵以圖形方式顯示在屏幕上(例如在 Galaxy Nexus 上),則它們由 System UI 包中的 Navigation Bar 組件實現。由於圖形虛擬軟鍵在系統的高層實現,因此不涉及按鍵佈局文件,以下信息不適用。
  2. 如果虛擬軟鍵被實現為作為主觸摸屏一部分的擴展可觸摸區域(例如在 Nexus One 上),則輸入系統使用虛擬鍵映射文件將 X/Y 觸摸坐標轉換為 Linux 鍵代碼,然後使用按鍵佈局文件將 Linux 按鍵代碼轉換為 Android 按鍵代碼(有關虛擬按鍵映射文件的詳細信息,請參閱Touch Devices )。觸摸屏輸入設備的按鍵佈局文件必須指定適當的按鍵映射並包含每個按鍵的VIRTUAL標誌。
  3. 如果虛擬軟鍵被實現為與主觸摸屏分離的電容式按鈕(例如在 Nexus S 上),內核設備驅動程序或固件負責將觸摸轉換為 Linux 鍵代碼,然後輸入系統將其轉換為 Android 鍵代碼使用密鑰佈局文件。電容式按鈕輸入設備的按鍵佈局文件必須指定適當的按鍵映射並包含每個按鍵的VIRTUAL標誌。

當虛擬軟鍵位於觸摸屏內或物理上靠近觸摸屏時,用戶很容易在觸摸屏幕底部附近或從上到下或從下到上滑動手指時意外按下按鈕屏幕頂部。為了防止這種情況,輸入系統應用了一些去抖動功能,以便在最近一次觸摸觸摸屏後的一小段時間內忽略虛擬軟鍵按下(這種延遲稱為虛擬鍵靜默時間)。

要啟用虛擬軟鍵去抖動:

  1. 為觸摸屏或電容式按鈕輸入設備提供按鍵佈局文件,並為每個按鍵設置VIRTUAL標誌。
    key 139    MENU           VIRTUAL
    key 172    HOME           VIRTUAL
    key 158    BACK           VIRTUAL
    key 217    SEARCH         VIRTUAL
    
  2. 在框架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>
    

驗證

您應該使用Validate Keymaps工具來驗證您的按鍵佈局文件。