Tệp bố cục phím

Tệp bố cục phím (tệp .kl) liên kết mã phím và mã trục của Linux với mã phím và mã trục của Android, đồng thời chỉ định cờ chính sách liên quan. Các tệp bố cục phím dành riêng cho thiết bị là:

• Bắt buộc đối với các thiết bị đầu vào nội bộ (tích hợp) có các phím, bao gồm cả các phím đặc biệt như âm lượng, nguồn và phím đa phương tiện của tai nghe.
• Không bắt buộc đối với các thiết bị đầu vào khác nhưng nên dùng đối với bàn phím và cần điều khiển dùng cho mục đích đặc biệt.

Nếu không có tệp bố cục phím dành riêng cho thiết bị, thì hệ thống sẽ chọn một bố cục mặc định.

Vị trí

Các tệp bố cục phím được tìm theo mã nhận dạng nhà cung cấp USB, sản phẩm (và phiên bản tuỳ chọn) hoặc theo tên thiết bị đầu vào. Các đường dẫn sau đây được tham khảo theo thứ tự:

• /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

Khi tạo đường dẫn tệp chứa tên thiết bị, tất cả ký tự trong tên thiết bị ngoại trừ "0"-"9", "a"-"z", "A"-"Z", "-" hoặc "_" sẽ được thay thế bằng "_".

Tệp bố cục phím chung

Hệ thống cung cấp một tệp bố cục phím chung tích hợp đặc biệt có tên là Generic.kl. Bố cục phím này nhằm hỗ trợ nhiều loại bàn phím và cần điều khiển tiêu chuẩn bên ngoài. Đừng sửa đổi bố cục khoá chung!

Cú pháp

Tệp bố cục khoá là tệp văn bản thuần tuý bao gồm các khai báo khoá hoặc trục và cờ.

Khai báo khoá

Nội dung khai báo khoá bao gồm từ khoá key, theo sau là số mã khoá Linux và tên mã khoá Android, hoặc cách sử dụng từ khoá, theo sau là cách sử dụng HID và tên mã khoá Android. Mức sử dụng HID được biểu thị dưới dạng số nguyên 32 bit, trong đó 16 bit cao đại diện cho trang sử dụng HID và 16 bit thấp đại diện cho mã nhận dạng mức sử dụng HID. Sau mỗi nội dung khai báo có thể là một nhóm cờ chính sách tuỳ chọn được phân tách bằng khoảng trắng.

key 1     ESCAPE
key 114   VOLUME_DOWN
key 16    Q                 VIRTUAL
key usage 0x0c006F          BRIGHTNESS_UP

Các cờ chính sách sau đây được nhận dạng:

• FUNCTION: Phím này phải được diễn giải như thể phím FUNCTION cũng được nhấn.
• GESTURE: Khoá do cử chỉ của người dùng tạo ra, chẳng hạn như vuốt màn hình cảm ứng bằng lòng bàn tay.
• VIRTUAL: Khoá là một phím mềm ảo (nút cảm ứng) nằm cạnh màn hình cảm ứng chính. Điều này sẽ kích hoạt logic chống hiện tượng nhấp nháy đặc biệt (xem bên dưới).

Khai báo trục

Mỗi phần khai báo trục bao gồm từ khoá axis, theo sau là số mã trục Linux và bộ hạn định kiểm soát hành vi của trục, bao gồm ít nhất một tên mã trục Android.

Trục cơ bản

Trục cơ bản chỉ ánh xạ mã trục Linux đến tên mã trục Android. Nội dung khai báo sau đây liên kết ABS_X (được biểu thị bằng 0x00) với AXIS_X (được biểu thị bằng X).

axis 0x00 X

Trong ví dụ trên, nếu giá trị của ABS_X là 5 thì AXIS_X được đặt thành 5.

Trục phân tách

Trục phân tách ánh xạ mã trục Linux đến hai tên mã trục Android, sao cho các giá trị nhỏ hơn hoặc lớn hơn ngưỡng được phân tách trên hai trục khác nhau khi được ánh xạ. Việc liên kết này hữu ích khi một trục vật lý duy nhất do thiết bị báo cáo mã hoá hai trục logic khác nhau loại trừ lẫn nhau.

Nội dung khai báo sau đây liên kết các giá trị của trục ABS_Y (được biểu thị bằng 0x01) với AXIS_GAS khi nhỏ hơn 0x7f hoặc với AXIS_BRAKE khi lớn hơn 0x7f.

axis 0x01 split 0x7f GAS BRAKE

Trong ví dụ trên, nếu giá trị của ABS_Y là 0x7d thì AXIS_GAS được đặt thành 2 (0x7f - 0x7d) và AXIS_BRAKE được đặt thành 0. Ngược lại, nếu giá trị của ABS_Y là 0x83, thì AXIS_GAS được đặt thành 0 và AXIS_BRAKE được đặt thành 4 (0x83 - 0x7f). Cuối cùng, nếu giá trị của ABS_Y bằng giá trị phân tách của 0x7f, thì cả AXIS_GAS và AXIS_BRAKE đều được đặt thành 0.

Trục đảo ngược

Trục đảo ngược sẽ đảo ngược dấu của giá trị trục. Nội dung khai báo sau đây ánh xạ ABS_RZ (được biểu thị bằng 0x05) đến AXIS_BRAKE (được biểu thị bằng BRAKE) và đảo ngược đầu ra bằng cách phủ định đầu ra đó.

axis 0x05 invert BRAKE

Trong ví dụ trên, nếu giá trị của ABS_RZ là 2 thì AXIS_BRAKE sẽ được đặt thành -2.

Tuỳ chọn căn giữa phẳng

Thiết bị cần điều khiển có thể báo cáo các sự kiện đầu vào ngay cả khi không sử dụng thiết bị cần điều khiển do nhiễu. Độ nhiễu này thường đến từ cần điều khiển bên trái và/hoặc bên phải, khiến trình điều khiển báo cáo giá trị vị trí gần 0. Giá trị "center flat" (phẳng ở giữa) chỉ định lượng nhiễu dự kiến từ bộ điều khiển ở trạng thái nghỉ.

Giao thức đầu vào Linux cung cấp một cách để trình điều khiển thiết bị đầu vào chỉ định giá trị phẳng ở giữa của trục cần điều khiển, nhưng không phải trình điều khiển nào cũng báo cáo giá trị này và một số trình điều khiển cung cấp giá trị không chính xác. Để giải quyết vấn đề này, bạn có thể thêm tuỳ chọn flat sau phần khai báo trục để chỉ định chiều rộng của vùng xung quanh vị trí trung tâm của trục cần được xem là ở giữa.

Ví dụ: nếu trình điều khiển thiết bị báo cáo các giá trị cho AXIS_X trong khoảng từ 0 đến 100, thì hệ thống đầu vào Android sẽ ánh xạ 0 thành -1 và 100 thành 1. Trung tâm của phạm vi sẽ là 50 trong toạ độ chưa điều chỉnh theo tỷ lệ và 0 trong toạ độ đã điều chỉnh theo tỷ lệ. Nếu giá trị phẳng bằng 10, thì nhà phát triển nên giả định rằng mọi giá trị AXIS_X được báo cáo trong khoảng từ -0,1 đến 0,1 (từ 40 đến 60 theo toạ độ chưa được điều chỉnh theo tỷ lệ) là nhiễu và coi các giá trị đó đến từ cần điều khiển là 0.

Lưu ý: Mặc dù tệp bố cục khoá chỉ định giá trị cho không gian toạ độ của trình điều khiển, nhưng giá trị do android.view.InputDevice.MotionRange#getFlat() báo cáo nằm trong không gian toạ độ Android.

axis 0x03 Z flat 4096

Trong ví dụ trên, giá trị phẳng ở giữa được đặt thành 4096.

Bình luận

Dòng nhận xét bắt đầu bằng # và tiếp tục đến cuối dòng:

# A comment!

Các dòng trống sẽ bị bỏ qua.

Ví dụ

Bàn phím

# 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...

Điều khiển hệ thống

# 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

Nút cảm ứng

# 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

Điều khiển nội dung nghe nhìn trên giắc cắm tai nghe

# 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

Joystick

# 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

Phím mềm ảo

Hệ thống nhập cung cấp các tính năng đặc biệt để triển khai các phím mềm ảo trong các trường hợp sử dụng sau:

1. Nếu các phím mềm ảo hiển thị dưới dạng đồ hoạ trên màn hình (chẳng hạn như trên Galaxy Nexus), thì các phím này sẽ được triển khai bằng thành phần Thanh điều hướng trong gói Giao diện người dùng hệ thống. Vì các phím mềm ảo đồ hoạ được triển khai ở một lớp cao trong hệ thống, nên các tệp bố cục phím không liên quan và thông tin sau đây không áp dụng.
2. Nếu các phím mềm ảo được triển khai dưới dạng một vùng có thể chạm mở rộng là một phần của màn hình cảm ứng chính (chẳng hạn như trên Nexus One), thì hệ thống đầu vào sẽ sử dụng tệp bản đồ phím ảo để dịch toạ độ chạm X/Y thành mã phím Linux, sau đó sử dụng tệp bố cục phím để dịch mã phím Linux thành mã phím Android (để biết thông tin chi tiết về tệp bản đồ phím ảo, hãy xem phần Thiết bị cảm ứng). Tệp bố cục phím cho thiết bị đầu vào màn hình cảm ứng phải chỉ định mối liên kết phím thích hợp và bao gồm cờ VIRTUAL cho mỗi phím.
3. Nếu các phím mềm ảo được triển khai dưới dạng các nút cảm ứng tách biệt với màn hình cảm ứng chính (chẳng hạn như trên Nexus S), thì trình điều khiển thiết bị hạt nhân hoặc phần mềm sẽ chịu trách nhiệm chuyển đổi các thao tác chạm thành mã phím Linux. Sau đó, hệ thống đầu vào sẽ chuyển đổi các mã phím đó thành mã phím Android bằng cách sử dụng tệp bố cục phím. Tệp bố cục phím cho thiết bị đầu vào nút cảm ứng phải chỉ định liên kết phím thích hợp và bao gồm cờ VIRTUAL cho mỗi phím.

Khi các phím mềm ảo nằm trong hoặc ở gần màn hình cảm ứng, người dùng dễ dàng vô tình nhấn nút khi chạm vào gần cuối màn hình hoặc khi vuốt ngón tay từ trên xuống hoặc từ dưới lên trên màn hình. Để ngăn chặn điều này, hệ thống đầu vào sẽ áp dụng một chút độ trễ để các thao tác nhấn phím mềm ảo bị bỏ qua trong một khoảng thời gian ngắn sau lần chạm gần đây nhất trên màn hình cảm ứng (độ trễ này được gọi là thời gian yên tĩnh của phím ảo).

Cách bật tính năng loại bỏ xung đột nhấn phím mềm ảo:

1. Cung cấp tệp bố cục phím cho màn hình cảm ứng hoặc thiết bị đầu vào nút cảm ứng điện dung với cờ VIRTUAL được đặt cho mỗi phím.

   key 139    MENU           VIRTUAL
   key 172    HOME           VIRTUAL
   key 158    BACK           VIRTUAL
   key 217    SEARCH         VIRTUAL
   

2. Đặt giá trị của thời gian yên tĩnh của phím ảo trong lớp phủ tài nguyên cho tài nguyên config.xml của khung.

   <!-- 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>
   

Xác nhận kết quả

Bạn nên xác thực các tệp bố cục phím bằng công cụ Xác thực sơ đồ bàn phím.