[PATCH libinput] Initial move of some wiki contents into main documentation.

Jon A. Cruz jonc at osg.samsung.com
Wed Dec 17 19:30:30 PST 2014

This moves some information from the wiki into the main generated doxygen
documenation. It is fairly rought but includes examples for inline and
stand-alone diagrams, linking to external HTML pages, etc.

Among other things, it allows for better cross-referencing into the
main doxygen contents and thus for overall shorter documentation.

Signed-off-by: Jon A. Cruz <jonc at osg.samsung.com>
 configure.ac                 |  9 ++++++
 doc/Makefile.am              | 18 +++++++++---
 doc/absolute-axes.dox        | 64 ++++++++++++++++++++++++++++++++++++++++++
 doc/clickpad-softbuttons.dox | 67 ++++++++++++++++++++++++++++++++++++++++++++
 doc/dot/seats-sketch.gv      | 41 +++++++++++++++++++++++++++
 doc/seats.dox                | 10 +++++++
 doc/t440-support.dox         | 66 +++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 271 insertions(+), 4 deletions(-)
 create mode 100644 doc/absolute-axes.dox
 create mode 100644 doc/clickpad-softbuttons.dox
 create mode 100644 doc/dot/seats-sketch.gv
 create mode 100644 doc/seats.dox
 create mode 100644 doc/t440-support.dox

diff --git a/configure.ac b/configure.ac
index 33e380c..329f224 100644
--- a/configure.ac
+++ b/configure.ac
@@ -76,6 +76,15 @@ else
 AM_CONDITIONAL([HAVE_DOXYGEN], [test "x$have_doxygen" = "xyes"])
+if test "x$DOT" = "x"; then
+	AC_MSG_WARN([Graphviz's dot not found - required for documentation])
+	have_dot="no"
+	have_dot="yes"
+AM_CONDITIONAL([HAVE_DOT], [test "x$have_dot" = "xyes"])
 	      AS_HELP_STRING([--enable-event-gui], [Build the GUI event viewer (default=auto)]),
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8f05bd2..624326b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -6,10 +6,20 @@ noinst_DATA = html/index.html
 header_files = \
 	$(top_srcdir)/src/libinput.h \
-	$(top_srcdir)/README.txt
-html/index.html: libinput.doxygen $(header_files)
-	$(AM_V_GEN)$(DOXYGEN) $<
+	$(top_srcdir)/README.txt \
+	$(srcdir)/absolute-axes.dox \
+	$(srcdir)/clickpad-softbuttons.dox \
+	$(srcdir)/seats.dox \
+	$(srcdir)/t440-support.dox
+diagram_files = \
+	$(srcdir)/dot/seats-sketch.gv
+html/index.html: libinput.doxygen $(header_files) $(diagram_files)
+	$(AM_V_GEN)(cat $<; \
+          echo "INPUT = $(header_files)"; \
+          echo "DOTFILE_DIRS = $(srcdir)/dot"; \
+          ) | $(DOXYGEN) -
 	$(AM_V_at)rm -rf html
diff --git a/doc/absolute-axes.dox b/doc/absolute-axes.dox
new file mode 100644
index 0000000..ee04113
--- /dev/null
+++ b/doc/absolute-axes.dox
@@ -0,0 +1,64 @@
+ at page absolute_axes Absolute Axes in libinput
+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.
+Compare this to relative devices (e.g. a mouse) that can only detect
+directional data, not positional data.
+libinput supports three types of devices with absolute axes:
+ - multi-touch screens
+ - 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
+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"
+ at 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.
+ at 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
+ at 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
new file mode 100644
index 0000000..3ac0323
--- /dev/null
+++ b/doc/clickpad-softbuttons.dox
@@ -0,0 +1,67 @@
+ at 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. <a href="http://www.synaptics.com/en/clickpad.php">"ClickPad" is
+a term coined by Synaptics Inc.</a> 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.
+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:
+ at dot
+digraph G {
+  clickpad [
+      shape = "record";
+    label = "{\nMain\nArea\n\n|{LEFT|RIGHT}}";
+  ]
+ at 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)
+- 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
\ No newline at end of file
diff --git a/doc/dot/seats-sketch.gv b/doc/dot/seats-sketch.gv
new file mode 100644
index 0000000..f537df1
--- /dev/null
+++ b/doc/dot/seats-sketch.gv
@@ -0,0 +1,41 @@
+digraph seats
+  rankdir="BT";
+  node [
+    shape="box";
+  ]
+  kernel [label="Kernel"];
+  event0 [URL="\ref libinput_event"];
+  event1 [URL="\ref libinput_event"];
+  event2 [URL="\ref libinput_event"];
+  event3 [URL="\ref libinput_event"];
+  pseat0 [label="phys seat0"; URL="\ref libinput_seat_get_physical_name"];
+  pseat1 [label="phys seat1"; URL="\ref libinput_seat_get_physical_name"];
+  lseatA [label="log seat A"; URL="\ref libinput_seat_get_logical_name"];
+  lseatB [label="log seat B"; URL="\ref libinput_seat_get_logical_name"];
+  lseatC [label="log seat C"; URL="\ref libinput_seat_get_logical_name"];
+  ctx1 [label="libinput context 1"; URL="\ref libinput"];
+  ctx2 [label="libinput context 2"; URL="\ref libinput"];
+  kernel -> event0
+  kernel -> event1
+  kernel -> event2
+  kernel -> event3
+  event0 -> pseat0
+  event1 -> pseat0
+  event2 -> pseat0
+  event3 -> pseat1
+  pseat0 -> ctx1
+  pseat1 -> ctx2
+  ctx1 -> lseatA
+  ctx1 -> lseatB
+  ctx2 -> lseatC
\ No newline at end of file
diff --git a/doc/seats.dox b/doc/seats.dox
new file mode 100644
index 0000000..fe77760
--- /dev/null
+++ b/doc/seats.dox
@@ -0,0 +1,10 @@
+ at page seats Seats
+ at section seats_overview Overview
+ at dotfile seats-sketch.gv
+Details pending.
diff --git a/doc/t440-support.dox b/doc/t440-support.dox
new file mode 100644
index 0000000..6261ce0
--- /dev/null
+++ b/doc/t440-support.dox
@@ -0,0 +1,66 @@
+ at page t440_support Lenovo *40 series touchpad support
+ at section t440_support_overview Overview
+The Lenovo *40 series introduced a new type of touchpad. Previously, all
+laptops had a separate set of physical buttons for the
+<a href="http://en.wikipedia.org/wiki/Pointing_stick">trackstick</a>. This
+series removed these buttons, relying on a software emulation of the top
+section of the touchpad. This is visually marked on the trackpad itself,
+approximately like this:
+ at dot
+digraph G {
+  subgraph cluster_0 {
+    margin="0";
+    clickpad [
+      shape = "record";
+      color = "none";
+    label = "{{LLLLLLLLLL|MMMMM|RRRRRRRRR}|\n\n\n\n\n\n\n\n|{LLLLLLLL|          |RRRRRRRR}}";
+    ]
+  }
+ at 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
+ at ref clickpad_softbuttons "Clickpad software buttons".
+ at 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
+<a href="https://lkml.org/lkml/2014/3/7/722">kernel patch</a> is required to
+get the right ranges.
+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.
+ at 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.
+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
+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).
+ at section t440_support_identification Identification
+The touchpads can be identified by the PNPID, or by a DMI match
+- Helix: PnPID: <b>LEN0033</b>, DMI substring match <em>"Helix"</em>
+- T540: PnPID: <b>LEN0034</b>, DMI substring match <em>"T540?"</em>
+- x240: PnPID: <b>LEN0035</b>, DMI substring match <em>"X240"</em>
+- T440: PnPID: <b>LEN0036</b>, DMI substring match <em>"T440?"</em>
+- Yoga: PnPID: <b>LEN0042</b>, DMI subString match <em>"S1Yoga"</em>

More information about the wayland-devel mailing list