[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
fi
AM_CONDITIONAL([HAVE_DOXYGEN], [test "x$have_doxygen" = "xyes"])
+AC_PATH_PROG(DOT, dot)
+if test "x$DOT" = "x"; then
+ AC_MSG_WARN([Graphviz's dot not found - required for documentation])
+ have_dot="no"
+else
+ have_dot="yes"
+fi
+AM_CONDITIONAL([HAVE_DOT], [test "x$have_dot" = "xyes"])
+
AC_ARG_ENABLE(event-gui,
AS_HELP_STRING([--enable-event-gui], [Build the GUI event viewer (default=auto)]),
[build_eventgui="$enableval"],
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) -
clean-local:
$(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
+coordinate.
+
+ 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>
+
+*/
--
1.9.1
More information about the wayland-devel
mailing list