diff --git a/doc/absolute-axes.dox b/doc/absolute-axes.dox index ee041130..f1ff973b 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,13 +12,37 @@ 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" +device's sensor. + +@section absolute_axes_handling Handling of absolute coordinates + +In most use-cases, absolute input devices are mapped to a single screen. For +direct input devices such as touchscreens the aspect ratio of the screen and +the device match. Mapping the input device position to the output position is +thus a simple mapping between two coordinates. libinput provides the API for +this with + +- libinput_event_pointer_get_absolute_x_transformed() for pointer events +- libinput_event_touch_get_x_transformed() for touch events + +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 +to the right of two outputs, add the output offset to the transformed +coordinate. + +@section absolute_axes_nores Devices without x/y resolution + +An absolute device that does not provide a valid resolution is considered +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). @section absolute_axes_nonorm Why x/y coordinates are not normalized @@ -35,30 +59,4 @@ 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. -@section absolute_axes_handling Handling of absolute coordinates - -In most use-cases, absolute input devices are mapped to a single screen. For -direct input devices such as touchscreens the aspect ratio of the screen and -the device match. Mapping the input device position to the output position is -thus a simple mapping between two coordinates. libinput provides the API for -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 -to the right of two outputs, add the output offset to the transformed -coordinate. - -@section absolute_axes_nores Devices without x/y resolution - -An absolute device that does not provide a valid resolution is considered -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 +*/ diff --git a/doc/clickpad-softbuttons.dox b/doc/clickpad-softbuttons.dox index 3ac0323f..2653c3b7 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. +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. -To perform a right-click on a Clickpad, two methods are available in libinput: +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. -- 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 +@section software_buttons Software button areas -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. - -The clickfinger behavior is subject to some restrictions: - -- 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 - -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. +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 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) +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 -*/ \ No newline at end of file +@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. + +*/ diff --git a/doc/seats.dox b/doc/seats.dox index fe777606..09094508 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 6261ce02..277dbe8e 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 Kernel support -@section t440_support_identification Identification +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. -The touchpads can be identified by the PNPID, or by a DMI match - -- 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"). */