diff options
Diffstat (limited to 'Documentation/input/event-codes.rst')
| -rw-r--r-- | Documentation/input/event-codes.rst | 79 |
1 files changed, 74 insertions, 5 deletions
diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index a8c0873beb95..4424cbff251f 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -137,7 +137,11 @@ A few EV_KEY codes have special meanings: code should be set to a value of 1. When the tool is no longer interacting with the input device, the BTN_TOOL_<name> code should be reset to 0. All trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name> - code when events are generated. + code when events are generated. Likewise all trackpads, tablets, and + touchscreens should export only one BTN_TOOL_<name> at a time. To not break + existing userspace, it is recommended to not switch tool in one EV_SYN frame + but first emitting the old BTN_TOOL_<name> at 0, then emit one SYN_REPORT + and then set the new BTN_TOOL_<name> at 1. * BTN_TOUCH: @@ -190,7 +194,26 @@ A few EV_REL codes have special meanings: * REL_WHEEL, REL_HWHEEL: - These codes are used for vertical and horizontal scroll wheels, - respectively. + respectively. The value is the number of detents moved on the wheel, the + physical size of which varies by device. For high-resolution wheels + this may be an approximation based on the high-resolution scroll events, + see REL_WHEEL_HI_RES. These event codes are legacy codes and + REL_WHEEL_HI_RES and REL_HWHEEL_HI_RES should be preferred where + available. + +* REL_WHEEL_HI_RES, REL_HWHEEL_HI_RES: + + - High-resolution scroll wheel data. The accumulated value 120 represents + movement by one detent. For devices that do not provide high-resolution + scrolling, the value is always a multiple of 120. For devices with + high-resolution scrolling, the value may be a fraction of 120. + + If a vertical scroll wheel supports high-resolution scrolling, this code + will be emitted in addition to REL_WHEEL or REL_HWHEEL. The REL_WHEEL + and REL_HWHEEL may be an approximation based on the high-resolution + scroll events. There is no guarantee that the high-resolution data + is a multiple of 120 at the time of an emulated REL_WHEEL or REL_HWHEEL + event. EV_ABS ------ @@ -212,11 +235,32 @@ A few EV_ABS codes have special meanings: BTN_TOOL_<name> signals the type of tool that is currently detected by the hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH. +* ABS_PROFILE: + + - Used to describe the state of a multi-value profile switch. An event is + emitted only when the selected profile changes, indicating the newly + selected profile value. + * ABS_MT_<name>: - Used to describe multitouch input events. Please see multi-touch-protocol.txt for details. +* ABS_PRESSURE/ABS_MT_PRESSURE: + + - For touch devices, many devices converted contact size into pressure. + A finger flattens with pressure, causing a larger contact area and thus + pressure and contact size are directly related. This is not the case + for other devices, for example digitizers and touchpads with a true + pressure sensor ("pressure pads"). + + A device should set the resolution of the axis to indicate whether the + pressure is in measurable units. If the resolution is zero, the + pressure data is in arbitrary units. If the resolution is non-zero, the + pressure data is in units/gram. For example, a value of 10 with a + resolution of 1 represents 10 gram, a value of 10 with a resolution of + 1000 represents 10 microgram. + EV_SW ----- @@ -310,7 +354,7 @@ INPUT_PROP_BUTTONPAD For touchpads where the button is placed beneath the surface, such that pressing down on the pad causes a button click, this property should be -set. Common in clickpad notebooks and macbooks from 2009 and onwards. +set. Common in Clickpad notebooks and Macbooks from 2009 and onwards. Originally, the buttonpad property was coded into the bcm5974 driver version field under the name integrated button. For backwards @@ -322,7 +366,7 @@ INPUT_PROP_SEMI_MT Some touchpads, most common between 2008 and 2011, can detect the presence of multiple contacts without resolving the individual positions; only the number of contacts and a rectangular shape is known. For such -touchpads, the semi-mt property should be set. +touchpads, the SEMI_MT property should be set. Depending on the device, the rectangle may enclose all touches, like a bounding box, or just some of them, for instance the two most recent @@ -356,11 +400,36 @@ can report through the rotational axes (absolute and/or relative rx, ry, rz). All other axes retain their meaning. A device must not mix regular directional axes and accelerometer axes on the same event node. +INPUT_PROP_PRESSUREPAD +---------------------- + +The INPUT_PROP_PRESSUREPAD property indicates that the device provides +simulated haptic feedback (e.g. a vibrator motor situated below the surface) +instead of physical haptic feedback (e.g. a hinge). This property is only set +if the device: + +- can differentiate between at least 5 fingers +- uses correct resolution for the X/Y (units and value) +- follows the MT protocol type B + +If the simulated haptic feedback is controllable by userspace the device must: + +- support simple haptic auto and manual triggering, and +- report correct force per touch, and correct units for them (newtons or grams), and +- provide the EV_FF FF_HAPTIC force feedback effect. + +Summing up, such devices follow the MS spec for input devices in +Win8 and Win8.1, and in addition may support the Simple haptic controller HID +table, and report correct units for the pressure. + +Where applicable, this property is set in addition to INPUT_PROP_BUTTONPAD, it +does not replace that property. + Guidelines ========== The guidelines below ensure proper single-touch and multi-finger functionality. -For multi-touch functionality, see the multi-touch-protocol.txt document for +For multi-touch functionality, see the multi-touch-protocol.rst document for more information. Mice |