Re: [PATCH 2/4] Documentation: Add evdev type and code definitions

[Chase Douglas <chase.douglas@canonical.com>]

On 12/16/2010 09:56 AM, Chris Bagwell wrote:
> On Wed, Dec 15, 2010 at 5:59 PM, Peter Hutterer
> <peter.hutterer@who-t.net> wrote:
>> On Tue, Dec 14, 2010 at 01:21:10PM -0800, Chase Douglas wrote:
>>> +* BTN_TOOL_<name>, BTN_TOUCH:
>>> +  - These codes are used in conjunction with input trackpads, tablets, and
>>> +    touchscreens. These devices may be used with fingers, pens, or other tools.
>>> +    When an event occurs and a tool is used, the corresponding BTN_TOOL_<name>
>>> +    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. For non-tablet devices, the tool is usually
>>> +    BTN_TOUCH.
>>
>> BTN_TOUCH is used as proximity delimiter. e.g. wacom sends BTN_TOOL_PEN when
>> the pen comes into proximity and (in addition) BTN_TOUCH when the pen
>> actually touches the tablet. synaptics does the same IIRC except that it
>> doesn't support hovering, so BTN_TOOL_FINGER and BTN_TOUCH are always
>> set/unset in the same EV_SYN frame.
> 
> This area is where most special cases are so somehow I think it
> deserves extra attention.  Either in paragraphs or in sample events.
> 
> There is the special historical case of touchscreen were
> BTN_TOOL_FINGER is not sent; which mostly works because most
> touchscreens do not support proximity/hover concepts.  It can
> recommend not to use this approach and to use new ioctl() to convey
> touchscreen vs. touchpad information.
> 
> Just an FYI: Synaptics is only sending BTN_TOUCH when pressure is >30
> for what ever historical reason (and duplicating logic in
> xf86-input-synaptics) so it usually won't be in same sync window as
> BTN_TOOL_FINGER.  I think its only touchpad left doing this so I think
> we may want to recommend best practice is to have BTN_TOOL_FINGER/*TAP
> and BTN_TOUCH track each other when hover is not supported.

I have attempted to capture this in the document.

>>> +* BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP:
>>> +  - These codes denote one, two, three, and four finger interaction on a
>>> +    trackpad or touchscreen. For example, if the user uses two fingers and moves
>>> +    them on the touchpad in an effort to scroll content on screen,
>>> +    BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion.
>>> +    Note that these codes and the BTN_TOOL_<name> and BTN_TOUCH codes are
>>> +    orthogonal in purpose. A trackpad event generated by finger touches should
>>> +    generate events for one code from each group.
> 
> We should probably recommend a best practice here.  Almost all drivers
> today send only 1 of BTN_TOOL_FINGER/*TAP today.  For example, if 1
> touch then BTN_TOOL_FINGER=1 and BTN_TOOL_DOUBLETAP=0 and during 2
> touch then BTN_TOOL_FINGER=0 and BTN_TOOL_DOUBLETAP=1.
> 
> I think at least 1 driver sends them concurrently today and you must
> look for highest finger count tool.  I'm pretty sure historically a
> lot of the drivers sent them concurrently as well.

I tried to convey both points in the documentation for these codes, and
hopefully examples added to the document will help as well.

>>> +
>>> +EV_ABS:
>>> +----------
>>> +EV_ABS events describe absolute changes in a property. For example, a touchpad
>>> +may emit coordinates for a touch location.
>>> +
>>> +A few EV_ABS codes have special meanings:
>>> +
>>> +* ABS_PRESSURE:
>>> +  - Used to describe the pressure of a touch interaction on an input device.
>>
>> again, that's not really special IMO. it pretty much does what it says on
>> the box :)
> 
> :-)
> 
> It may be worth noting though that this is optional event.  When it
> doesn't exist then BTN_TOUCH indicates touch.  When it does exist then
> this is preferred indication of touch and should be used to debounced
> touches because of fact that majority of touchpad/touchscreen will
> start detecting contact while hovering.  But then that leads to
> optional ABS_DISTANCE...

All of the evdev codes are optional, unless stated somewhere in here
otherwise like BTN_TOUCH (in my next revision). I feel this falls into
how userspace should use the codes, not the definition of the codes.

Thanks!

-- Chase