[PATCH libinput] Initial move of some wiki contents into main documentation.
Peter Hutterer
peter.hutterer at who-t.net
Wed Dec 17 14:10:45 PST 2014
On Tue, Dec 16, 2014 at 07:59:55PM -0800, Jon A. Cruz wrote:
> 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.
I fully agree, having this here is a lot better than on the wiki. means we
can be a lot more specific to the implementation bits and all the @page bits
are directly linkable from the wiki. Just two minor nitpicks below,
otherwise I'm happy with this (the content needs rewording, but I'm happy to
do that once we merge this).
>
> Signed-off-by: Jon A. Cruz <jonc at osg.samsung.com>
> ---
> configure.ac | 9 ++++++++
> doc/Makefile.am | 18 ++++++++++++----
> doc/absolute-axes.dox | 37 ++++++++++++++++++++++++++++++++
> doc/clickpad-softbuttons.dox | 45 +++++++++++++++++++++++++++++++++++++++
> doc/dot/seats-sketch.gv | 41 ++++++++++++++++++++++++++++++++++++
> doc/seats.dox | 10 +++++++++
> doc/t440-support.dox | 50 ++++++++++++++++++++++++++++++++++++++++++++
> 7 files changed, 206 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"])
> +
you don't seem to be using HAVE_DOT anywhere. I think we should just
group doxygen and dot together into a --enable-documentation=auto switch
with the usual behaviour: default is autodetect, yes requires the packages,
no ignores it.
> 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..e8ffa1a
> --- /dev/null
> +++ b/doc/absolute-axes.dox
> @@ -0,0 +1,37 @@
> +/**
> + 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.
applies for all: please wrap this to 78 chars
Cheers,
Peter
> +
> +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..e74ee84
> --- /dev/null
> +++ b/doc/clickpad-softbuttons.dox
> @@ -0,0 +1,45 @@
> +/**
> + 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..7d4f959
> --- /dev/null
> +++ b/doc/t440-support.dox
> @@ -0,0 +1,50 @@
> +/**
> + 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 @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