From f82aa16624998855dbfe96c6641906d67e47e352 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 22 Dec 2014 10:04:58 +1000 Subject: [PATCH] Improve the documentation Signed-off-by: Peter Hutterer --- doc/absolute-axes.dox | 42 +++++++++--------- doc/clickpad-softbuttons.dox | 101 ++++++++++++++++++++++++------------------- doc/seats.dox | 2 + doc/t440-support.dox | 58 ++++++++++++++----------- 4 files changed, 112 insertions(+), 91 deletions(-) diff --git a/doc/absolute-axes.dox b/doc/absolute-axes.dox index ee04113..f1ff973 100644 --- a/doc/absolute-axes.dox +++ b/doc/absolute-axes.dox @@ -1,5 +1,5 @@ /** -@page absolute_axes Absolute Axes in libinput +@page absolute_axes Absolute axes Devices with absolute axes are those that send positioning data for an axis in a device-specific coordinate range, defined by a minimum and a maximum value. @@ -12,28 +12,13 @@ libinput supports three types of devices with absolute axes: - single-touch screens - graphics tablets (currently WIP) -Touchpads are technically absolute devices, but the axis values are converted -to directional motion and posted as relative events. Touchpads do not count +Touchpads are technically absolute devices but libinput converts the axis values +to directional motion and posts events as relative events. Touchpads do not count as absolute devices in libinput. For all absolute devices in libinput, the default unit for x/y coordinates is in mm off the top left corner on the device, or more specifically off the -device's sensor, see @ref index "the API doc" - -@section absolute_axes_nonorm Why x/y coordinates are not normalized - -x/y are not given in @ref motion_normalization "normalized coordinates" -([0..1]) for one simple reason: the aspect ratio of virtually all current -devices is something other than 1:1. A normalized axes thus is only useful to -determine that the stylus is e.g. at 78% from the left, 34% from the top of -the device. Without knowing the per-axis resolution, these numbers are -meaningless. Worse, calculation based on previous coordinates is simply wrong: -a movement from 0/0 to 50%/50% is not a 45% degree line. - -This could be alleviated by providing resolution and information about the -aspect ratio to the caller. Which shifts processing and likely errors into the -caller for little benefit. Providing the x/y axes in mm from the outset -removes these errors. +device's sensor. @section absolute_axes_handling Handling of absolute coordinates @@ -46,8 +31,6 @@ this with - libinput_event_pointer_get_absolute_x_transformed() for pointer events - libinput_event_touch_get_x_transformed() for touch events -See @ref index "the API doc" for more details. - libinput's API only provides the call to map into a single coordinate range. If the coordinate range has an offset, the compositor is responsible for applying that offset after the mapping. For example, if the device is mapped @@ -61,4 +44,19 @@ buggy and must be fixed in the kernel. Some touchpad devices that do not provide resolution, those devices are correctly handled within libinput (touchpads are not absolute devices, as mentioned above). -*/ \ No newline at end of file +@section absolute_axes_nonorm Why x/y coordinates are not normalized + +x/y are not given in @ref motion_normalization "normalized coordinates" +([0..1]) for one simple reason: the aspect ratio of virtually all current +devices is something other than 1:1. A normalized axes thus is only useful to +determine that the stylus is e.g. at 78% from the left, 34% from the top of +the device. Without knowing the per-axis resolution, these numbers are +meaningless. Worse, calculation based on previous coordinates is simply wrong: +a movement from 0/0 to 50%/50% is not a 45% degree line. + +This could be alleviated by providing resolution and information about the +aspect ratio to the caller. Which shifts processing and likely errors into the +caller for little benefit. Providing the x/y axes in mm from the outset +removes these errors. + +*/ diff --git a/doc/clickpad-softbuttons.dox b/doc/clickpad-softbuttons.dox index 3ac0323..2653c3b 100644 --- a/doc/clickpad-softbuttons.dox +++ b/doc/clickpad-softbuttons.dox @@ -1,41 +1,28 @@ /** -@page clickpad_softbuttons Clickpad Software Button behavior +@page clickpad_softbuttons Clickpad software button behavior Clickpad is the name given to touchpads without physical buttons below the touchpad. Instead, the whole touchpad acts as a button and left or right button clicks are distinguished by the location and/or number of fingers on the touchpad. "ClickPad" is -a term coined by Synaptics Inc. but for simplicity we refer to any +a trademark by Synaptics Inc. but for simplicity we refer to any touchpad with the above feature as Clickpad, regardless of the manufacturer. -A clickpad is always marked with the INPUT_PROP_BUTTONPAD property. Note that -there is a type of clickpads that have the top section marked as software -buttons as well. See @ref t440_support "Lenovo *40 series touchpad support" -for details on the top software button. - -To perform a right-click on a Clickpad, two methods are available in libinput: - -- on Apple touchpads, a right click is performed by two fingers on the - touchpad while clicking, a behavior termed "clickfinger" -- on non-Apple touchpads, a right click is performed by a finger in a - software-defined right button area - -The button behavior depends on the hardware. Some Clickpads, notably some -Cypress ones, perform right button detection in firmware and appear to -userspace as if the touchpad had physical buttons. While physically clickpads, -these are not handled by the software and treated like traditional touchpads. +A clickpad is always marked with the INPUT_PROP_BUTTONPAD property. +To perform a right-click on a Clickpad, libinput provides @ref +software_buttons and @ref clickfinger. -The clickfinger behavior is subject to some restrictions: +In the page below, the term "click" shall refer to a physical button press +and/or release of the touchpad, the term "button event" refers to the events +generated by libinput and passed to the caller in response to a click. -- two fingers execute a right click, three fingers a middle click -- The Xorg synaptics driver uses 30% of the touchpad dimensions as threshold, - libinput does not have this restrictions. If two fingers are on the pad - while clicking, that is a two-finger click. -- clickfinger behavior is only enabled on Apple touchpads +@section software_buttons Software button areas -The button behavior is subject to some restrictions: - -The button area is usually defined like this: +On most clickpads, this is the default behavior. The bottom of the touchpad +is split in the middle to generate left or right button events on click. The +height of the button area depends on the hardware but is usually around +10mm. @dot digraph G { @@ -46,22 +33,48 @@ digraph G { } @enddot -The size of the buttons is hardware dependent. - -- if fingers are only down in the main area, a left click is generated -- if a finger is in the right area when the physical click happens, a right - click is generated -- if fingers are in both the left and right area, a middle click is generated -- fingers in the main area are not considered for right or middle click - generation -- if a finger starts in the main area, the software buttons do not apply to - that finger -- a finger in the software button area does not move the pointer, but once it - moves out of the button area it will control the pointer (if it's the first - finger to do so) +Left, right and middle button events can be triggered as follows: +- if a finger is in the main area or the left button area, a click generates + left button events. +- if a finger is in the right area, a click generates right button events. +- if there is a finger in both the left and right button area, a click + generates middle button events. + +If fingers are down in the main area in addition to fingers in the +left or right button area, those fingers are are ignored. +A release event always releases the buttons logically down, regardless of +the current finger position + +The movement of a finger can alter the button area behavior: +- if a finger starts in the main area and moves into the software button + area, the software buttons do not apply to that finger +- a finger in the software button area does not move the pointer +- if a finger moves out out of the button area it will control the pointer + if it's the first finger in the main area - once a finger has moved out of the button area, it cannot move back in and - trigger a right/middle button click -- a release event releases the buttons logically down, regardless of the - current finger position + trigger a right or middle button event + +@section clickfinger Clickfinger behavior + +This is the default behavior on Apple touchpads. +Here, a left, right, middle button event is generated when one, two, or +three fingers are held down on the touchpad when a physical click is +generated. The location of the fingers does not matter and there are no +software-defined button areas. + +The Xorg synaptics driver uses 30% of the touchpad dimensions as threshold, +libinput does not have this restriction. If two fingers are on the pad +while clicking, that is a two-finger click. + +@section special_clickpads Special Clickpads + +The Lenovo *40 series laptops have a clickpad that provides two software button sections, one at +the top and one at the bottom. See @ref t440_support "Lenovo *40 series touchpad support" +for details on the top software button. + +Some Clickpads, notably some Cypress ones, perform right button detection in +firmware and appear to userspace as if the touchpad had physical buttons. +While physically clickpads, these are not handled by the software and +treated like traditional touchpads. -*/ \ No newline at end of file +*/ diff --git a/doc/seats.dox b/doc/seats.dox index fe77760..0909450 100644 --- a/doc/seats.dox +++ b/doc/seats.dox @@ -1,6 +1,8 @@ /** @page seats Seats +Each device in libinput is associated with one physical seat and one logical seat. + @section seats_overview Overview @dotfile seats-sketch.gv diff --git a/doc/t440-support.dox b/doc/t440-support.dox index 6261ce0..277dbe8 100644 --- a/doc/t440-support.dox +++ b/doc/t440-support.dox @@ -1,6 +1,9 @@ /** @page t440_support Lenovo *40 series touchpad support +The Lenovo *40 series emulates trackstick buttons on the top part of the +touchpads. + @section t440_support_overview Overview The Lenovo *40 series introduced a new type of touchpad. Previously, all @@ -24,43 +27,48 @@ digraph G { } @enddot -The below is a list of what is needed for support of these devices. This page -only covers the top software buttons, the bottom button behavior is covered in -@ref clickpad_softbuttons "Clickpad software buttons". +This page only covers the top software buttons, the bottom button behavior +is covered in @ref clickpad_softbuttons "Clickpad software buttons". + +Clickpads with a top button area are marked with the INPUT_PROP_TOPBUTTONPAD +property. @section t440_support_btn_size Size of the buttons -The approximate size of the top software buttons is 8% of the touchpad's -announced range, starting from the top. Note that a -kernel patch is required to -get the right ranges. +The line of the buttons is 5mm from the top edge of the touchpad, +measurements of button presses showed that the size of the buttons needs to +be approximately 10mm high to work reliable (especially when using the +thumb to press the button). -The size of the left and right buttons is approximately 42%, the middle button -is centered and should be assigned approximately 16% of the touchpad width. +The width of the left and right buttons is approximately 42% of the +touchpad's width, the middle button is centered and should be assigned +approximately 16% of the touchpad width. @section t440_support_btn_behavior Button behavior -Movement in the top button area must not generate pointer movement, these -buttons are not replacement buttons for the bottom area but have their own -behaviour. They do not work for click-and-drag. +Movement in the top button area does not generate pointer movement. These +buttons are not replacement buttons for the bottom button area but have +their own behavior. +Semantically attached to the trackstick device, libinput re-routes events +from these buttons to appear through the trackstick device. The top button +areas work even if the touchpad is disabled but will be disabled when the +trackstick device is disabled. If the finger starts inside the top area and moves outside the button area -without the physical button being down, movement may start. - -Movement into the top button area should not trigger button events, a click +the finger is treated as dead and must be lifted to generate future buttons. +Likewise, movement into the top button area does not trigger button events, a click has to start inside this area to take effect. -The top button areas must work, even if the touchpad is otherwise disabled -(e.g. by a disable-while-typing feature). - -@section t440_support_identification Identification +@section t440_support_identification Kernel support -The touchpads can be identified by the PNPID, or by a DMI match +The firmware on touchpads providing top software buttons is buggy and +announces wrong ranges. Kernel +patches are required; these fixes are available in kernels +3.14.1, 3.15 and later but each touchpad needs a separate fix. -- Helix: PnPID: LEN0033, DMI substring match "Helix" -- T540: PnPID: LEN0034, DMI substring match "T540?" -- x240: PnPID: LEN0035, DMI substring match "X240" -- T440: PnPID: LEN0036, DMI substring match "T440?" -- Yoga: PnPID: LEN0042, DMI subString match "S1Yoga" +For a complete list of supported touchpads check the +kernel source (search for "topbuttonpad_pnp_ids"). */ -- 2.7.4