키 레이아웃 파일

키 레이아웃 파일(.kl 파일)은 Linux 키 코드와 축 코드를 Android 키 코드 및 축 코드에 매핑하고 관련 정책 플래그를 지정합니다. 기기별 키 레이아웃 파일은 다음과 같습니다.

  • 음량, 전원 및 헤드셋 미디어 키와 같은 특수 키 등의 키를 포함하는 내부(내장형) 입력 장치의 경우 필수입니다.
  • 다른 입력 기기의 경우 선택사항이지만 특수 용도의 키보드 및 조이스틱의 경우 권장됩니다.

기기별 키 레이아웃 파일이 없으면 시스템에서 대신 기본값을 선택합니다.

위치

키 레이아웃 파일은 USB 공급업체, 제품 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이라 불리는 특수한 내장형 일반 키 레이아웃 파일을 제공합니다. 이 키 레이아웃은 다양한 표준 외부 키보드와 조이스틱을 지원하는 용도입니다. 일반 키 레이아웃은 수정하면 안 됩니다.

구문

키 레이아웃 파일은 키 또는 축 선언 및 플래그로 구성되는 일반 텍스트 파일입니다.

키 선언

키 선언은 Linux 키 코드 번호 및 Android 키 코드명 앞의 키워드 앞의 key 또는 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로 구성됩니다. 키워드에는 1개 이상의 Android 축 코드명을 포함하는 축의 동작을 제어하는 Linux 축 코드 번호와 한정자가 뒤따릅니다.

기본 축

기본 축은 단순히 Linux 축 코드를 Android 축 코드명에 매핑합니다. 다음 선언은 0x00으로 표시된 ABS_X를 X로 표시된 AXIS_X에 매핑합니다.

axis 0x00 X

위의 예에서는 ABS_X의 값이 5인 경우 AXIS_X가 5로 설정됩니다.

분할 축

분할 축은 Linux 축 코드를 Android 축 코드명에 매핑하며, 매핑 시 기준보다 작거나 큰 값이 두 개의 상이한 축에 걸쳐 분할됩니다. 이 매핑은 기기에서 보고된 단일 실제 축이 상호 배타적인 두 개의 상이한 논리 축을 인코딩하는 경우에 유용합니다.

다음 선언은 0x01로 표시된 ABS_Y 축의 값을 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으로 설정됩니다.

반전 축

반전 축은 축 값의 신호를 반전합니다. 다음 선언은 0x05로 표시된 ABS_RZ를 BRAKE로 표시된 AXIS_BRAKE로 매핑하고 이를 무효화하여 출력을 반전합니다.

axis 0x05 invert BRAKE

위의 예에서는 ABS_RZ의 값이 2인 경우 AXIS_BRAKE가 -2로 설정됩니다.

Center flat 옵션

조이스틱 기기는 조이스틱이 사용되지 않는 경우에도 노이즈로 인한 입력 이벤트를 보고할 수 있습니다. 이 노이즈는 보통 왼쪽 또는 오른쪽 스틱에서 발생하며, 드라이버가 0 근처의 위치 값을 보고하도록 만듭니다. 'center flat' 값은 유휴 상태의 컨트롤러에서 예상되는 노이즈의 양을 지정합니다.

Linux 입력 프로토콜은 입력 기기 드라이버가 조이스틱 축의 center flat 값을 지정할 수 있는 방법을 제공하지만 모든 드라이버에서 이를 보고하지는 않으며 일부 드라이버는 잘못된 값을 제공할 수 있습니다. 이 문제를 해결하기 위해 축 선언에는 중앙에 위치한 것으로 간주되어야 하는 축 중앙 위치 주변의 너비를 지정하는 flat 옵션이 뒤따를 수 있습니다.

예를 들어 기기 드라이버가 AXIS_X의 값으로 0~100을 보고하는 경우에는 Android 입력 시스템에 의해 0이 -1에 매핑되고 100이 1에 매핑됩니다. 범위의 중심은 확장되지 않은 좌표에서 50, 확장된 좌표에서는 0이 됩니다. flat 값이 10과 동일한 경우 개발자는 -0.1~0.1(확장되지 않은 좌표에서는 40~60)로 보고된 모든 AXIS_X 값을 노이즈로 가정해야 하며, 조이스틱에서 발생한 이러한 값을 0으로 취급해야 합니다.

참고: 키 레이아웃 파일은 드라이버 좌표 공간의 값을 지정하지만 android.view.InputDevice.MotionRange#getFlat()에 의해 보고된 값은 Android 좌표 공간에 위치합니다.

axis 0x03 Z flat 4096

위 예에서는 center flat 값이 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>

유효성 검사

키 맵 유효성 검사 도구를 사용하여 키 레이아웃 파일의 유효성을 검사해야 합니다.