按鍵佈局文件( .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
設置為0
, AXIS_BRAKE
設置為4
( 0x83 - 0x7f
)。最後,如果ABS_Y
的值等於0x7f
的拆分值,則AXIS_GAS
和AXIS_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
虛擬軟鍵
輸入系統提供了在以下用例中實現虛擬軟鍵的特殊功能:
- 如果虛擬軟鍵以圖形方式顯示在屏幕上(例如在 Galaxy Nexus 上),則它們由 System UI 包中的 Navigation Bar 組件實現。由於圖形虛擬軟鍵在系統的高層實現,因此不涉及按鍵佈局文件,以下信息不適用。
- 如果虛擬軟鍵被實現為作為主觸摸屏一部分的擴展可觸摸區域(例如在 Nexus One 上),則輸入系統使用虛擬鍵映射文件將 X/Y 觸摸坐標轉換為 Linux 鍵代碼,然後使用按鍵佈局文件將 Linux 按鍵代碼轉換為 Android 按鍵代碼(有關虛擬按鍵映射文件的詳細信息,請參閱Touch Devices )。觸摸屏輸入設備的按鍵佈局文件必須指定適當的按鍵映射並包含每個按鍵的
VIRTUAL
標誌。 - 如果虛擬軟鍵被實現為與主觸摸屏分離的電容式按鈕(例如在 Nexus S 上),內核設備驅動程序或固件負責將觸摸轉換為 Linux 鍵代碼,然後輸入系統將其轉換為 Android 鍵代碼使用密鑰佈局文件。電容式按鈕輸入設備的按鍵佈局文件必須指定適當的按鍵映射並包含每個按鍵的
VIRTUAL
標誌。
當虛擬軟鍵位於觸摸屏內或物理上靠近觸摸屏時,用戶很容易在觸摸屏幕底部附近或從上到下或從下到上滑動手指時意外按下按鈕屏幕頂部。為了防止這種情況,輸入系統應用了一些去抖動功能,以便在最近一次觸摸觸摸屏後的一小段時間內忽略虛擬軟鍵按下(這種延遲稱為虛擬鍵靜默時間)。
要啟用虛擬軟鍵去抖動:
- 為觸摸屏或電容式按鈕輸入設備提供按鍵佈局文件,並為每個按鍵設置
VIRTUAL
標誌。key 139 MENU VIRTUAL key 172 HOME VIRTUAL key 158 BACK VIRTUAL key 217 SEARCH VIRTUAL
- 在框架
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工具來驗證您的按鍵佈局文件。