主要版面配置檔案

按鍵版面配置檔案 (.kl 檔案) 會對應 Linux 按鍵碼和軸碼 ，並指定相關聯的政策標記。 裝置專屬的主要版面配置檔案如下：

  • 對於具有金鑰的內部 (內建) 輸入裝置，此為必填屬性，包括 音量、電源和耳機媒體鍵等特殊按鍵。
  • 對於其他輸入裝置，此為選填屬性，但建議用於其他輸入裝置 特殊功能鍵盤和搖桿

如果沒有裝置專屬的按鍵版面配置檔案，系統會選擇 。

位置

主要版面配置檔案位於 USB 供應商、產品 (以及選用版本) 中 或是輸入的裝置名稱我們會依序諮詢下列路徑：

  • /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 設為 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 之間， 那麼 0 會對應至 -1，而 100 會由 Android 輸入系統對應至 1。 範圍中心在未縮放座標的範圍內為 50，縮放座標則為 0。 如果固定值等於 10 那麼開發人員應假設AXIS_X -0.1 和 0.1 (未縮放座標介於 40 到 60 之間) 是雜訊，然後處理 將這個搖桿轉換成零

注意：雖然索引鍵版面配置檔案會指定這個值 驅動程式座標空間 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>

驗證

建議您使用 驗證按鍵對應配置工具。