按鍵佈局文件

按鍵佈局檔案( .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指示)對應到AXIS_GAS (小於0x7f時)或對應到AXIS_BRAKE (當大於0x7f時)。

axis 0x01 split 0x7f GAS BRAKE

在上面的範例中,如果ABS_Y的值為0x7d ,則AXIS_GAS設定為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 上),則它們會由系統 UI 套件中的導覽列元件實作。由於圖形虛擬軟鍵是在系統的高層實現的,因此不涉及按鍵佈局文件,且以下資訊不適用。
  2. 如果虛擬軟鍵被實現為作為主觸控螢幕一部分的擴展可觸摸區域(例如在 Nexus One 上),則輸入系統使用虛擬鍵映射檔案將 X/Y 觸控座標轉換為 Linux 鍵代碼,然後使用按鍵佈局檔案將Linux按鍵代碼轉換為Android按鍵代碼(有關虛擬按鍵映射檔案的詳細信息,請參閱觸摸設備)。觸控螢幕輸入裝置的按鍵佈局檔案必須指定適當的按鍵對映並包含每個按鍵的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>
    

驗證

您應該使用驗證鍵盤映射工具驗證您的鍵盤佈局文件。