キーレイアウト ファイル

キーレイアウト ファイル（.kl ファイル）では、Linux キーコードと軸コードを Android キーコードと軸コードにマッピングし、関連するポリシーフラグを指定します。デバイス固有のキーレイアウト ファイルは、対象により使い分けできます。

  • 必須: 音量、電源、ヘッドセットのメディアキーなど、特殊なキーを備えた内部（組み込み）入力デバイス。
  • 任意: その他の入力デバイス。ただし、特殊な用途のキーボードやジョイスティックの場合には、使用が推奨されます。

デバイス固有のキーレイアウト ファイルがない場合は、デフォルトの設定が選択されます。

場所

キーレイアウト ファイルは、USB ベンダー ID とプロダクト ID（オプションでバージョン 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: キーがファンクション キーも合わせて押されたものとして解釈されます。
  • GESTURE: タッチ スクリーンを手で操作するなど、ユーザーのジェスチャーによってキーが生成されます。
  • VIRTUAL: メインのタッチ スクリーンに隣接する仮想のソフトキー（静電容量方式のボタン）がキーになります。これにより、特殊なデバウンス ロジックが有効になります（以下を参照）。

軸の宣言

軸の宣言では、キーワード axis の後に Linux の軸コード番号と軸の動作を制御する修飾子（1 つ以上の Android 軸コード名を含む）を続けて指定します。

基本軸

基本軸では、Linux の軸コードを Android 軸コード名にマッピングします。次の宣言では、ABS_X（0x00 と表示される）を AXIS_X（X と表示される）にマッピングします。

axis 0x00 X

上記の例では、ABS_X の値が 5 である場合に、AXIS_X を 5 に設定します。

分割軸

分割軸では、Linux 軸コードを 2 つの Android 軸コード名にマッピングします。マッピングの際に、値がしきい値より小さい場合と大きい場合でそれぞれ別の軸に分割されます。このマッピングは、デバイスからレポートされる単一の物理軸に対して、相互に重複することのない 2 つの論理軸をエンコードする場合に有用です。

次の宣言では、ABS_Y 軸の値（0x01 と表示される）が 0x7f より小さい場合には AXIS_GAS にマッピングし、0x7f より大きい場合には AXIS_BRAKE にマッピングします。

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 の範囲にある場合、Android の入力システムによって 0 は -1 に、100 は 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>

検証

キーレイアウト ファイルはキーマップの検証ツールを使用して検証する必要があります。