From: Peter Hutterer Date: Sun, 3 Jun 2018 23:20:15 +0000 (+1000) Subject: doc: improve the 'tools' page X-Git-Tag: 1.11.0~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f82e77830fd73140fd70d6b5e1767a8a7443762d;p=platform%2Fupstream%2Flibinput.git doc: improve the 'tools' page Signed-off-by: Peter Hutterer --- diff --git a/doc/tools.dox b/doc/tools.dox index b6cbdc58..c38c2fc7 100644 --- a/doc/tools.dox +++ b/doc/tools.dox @@ -1,16 +1,25 @@ /** @page tools Helper tools -libinput provides a `libinput` tool to query state and events. -The two most common invocations are -@ref libinput-list-devices and @ref libinput-debug-events. The @ref -libinput-record tools are used to analyze and reproduce events sequences on -developer machines, particularly useful when a user experiences a bug. - -A full explanation of the various commands available in the libinput tool is -available in the libinput(1) man page. Generally, the tool must be run as -root to have access to the kernel's @c /dev/input/event* -device files. +libinput provides a `libinput` tool to query state and events. This tool +takes a subcommand as argument, similar to the **git** command. A full +explanation of the various commands available in the libinput tool is +available in the **libinput(1)** man page. + +The most common tools used are: +- `libinput list-devices`: to list locally available devices, see @ref + libinput-list-devices "here" +- `libinput debug-events`: to monitor and debug events, see @ref + libinput-debug-events "here" +- `libinput debug-gui`: to visualize events, see @ref libinput-debug-gui + "here" +- `libinput record`: to record an event sequence for replaying, see @ref + libinput-record "here" +- `libinput measure`: measure properties on a kernel device, see @ref + libinput-measure "here" + +Most the tools must be run as root to have access to the kernel's @c +/dev/input/event* device files. @section libinput-list-devices libinput list-devices @@ -19,6 +28,9 @@ recognized by libinput and can help identifying why a device behaves different than expected. For example, if a device does not show up in the output, it is not a supported input device. +@note This tool does **not** show your desktop's configuration, just the +libinput built-in defaults. + @verbatim $ sudo libinput list-devices [...] @@ -48,9 +60,6 @@ binary state all available options are listed, with the default one prefixed with an asterisk (*). In the example above, the default click method is button-areas but clickinger is available. -Note that the default configuration may differ from the configuration -applied by the desktop environment. - @note This tool is intended to be human-readable and may change its output at any time. @@ -62,8 +71,46 @@ to identify why a device behaves different than expected. $ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger @endverbatim -See the libinput(1) man page or the @c --help output for information about -the available options. +All configuration options (enable/disable tapping, +etc.) are available as commandline arguments. To reproduce the event +sequence as your desktop session sees it, ensure that all options are turned +on or off as required. See the **libinput-debug-events(1)** man page or the +`--help` output for information about the available options. + +@note When submitting a bug report, always use the `--verbose` flag to get +additional information: `libinput debug-events --verbose ` + +An example output from this tool may look like the snippet below. + +@verbatim +$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger +-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k +-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k +-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S +-event1 DEVICE_ADDED Sleep Button seat0 default group4 cap:k +-event4 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=3 seat0 default group5 cap: +-event11 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=7 seat0 default group6 cap: +-event12 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=8 seat0 default group7 cap: +-event13 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=9 seat0 default group8 cap: +-event14 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=10 seat0 default group9 cap: +-event19 DEVICE_ADDED Integrated Camera: Integrated C seat0 default group10 cap:k +-event15 DEVICE_ADDED HDA Intel PCH Dock Mic seat0 default group11 cap: +-event16 DEVICE_ADDED HDA Intel PCH Mic seat0 default group12 cap: +-event17 DEVICE_ADDED HDA Intel PCH Dock Headphone seat0 default group13 cap: +-event18 DEVICE_ADDED HDA Intel PCH Headphone seat0 default group14 cap: +-event6 DEVICE_ADDED ELAN Touchscreen seat0 default group15 cap:t size 305x172mm ntouches 10 calib +-event3 DEVICE_ADDED AT Translated Set 2 keyboard seat0 default group16 cap:k +-event20 DEVICE_ADDED SynPS/2 Synaptics TouchPad seat0 default group17 cap:pg size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on +-event21 DEVICE_ADDED TPPS/2 IBM TrackPoint seat0 default group18 cap:p left scroll-nat scroll-button +-event7 DEVICE_ADDED ThinkPad Extra Buttons seat0 default group19 cap:k +-event20 POINTER_MOTION +3.62s 2.72/ -0.93 + event20 POINTER_MOTION +3.63s 1.80/ -1.42 + event20 POINTER_MOTION +3.65s 6.16/ -2.28 + event20 POINTER_MOTION +3.66s 6.42/ -1.99 + event20 POINTER_MOTION +3.67s 8.99/ -1.42 + event20 POINTER_MOTION +3.68s 11.30/ 0.00 + event20 POINTER_MOTION +3.69s 21.32/ 1.42 +@endverbatim @section libinput-debug-gui libinput debug-gui @@ -72,11 +119,16 @@ touch events, pointer motion, scroll axes and gestures. Since this tool gathers data directly from libinput, it is thus suitable for pointer-acceleration testing. +@note This tool does **not** use your desktop's configuration, just the +libinput built-in defaults. + @verbatim -$ sudo libinput debug-gui +$ sudo libinput debug-gui --enable-tapping @endverbatim -See the libinput(1) man page or the @c --help output for information about +As with @ref libinput-debug-events, all options must be specified on the +commandline to emulate the correct behavior. +See the **libinput-debug-gui(1)** man page or the `--help` output for information about the available options. @section libinput-record libinput record and libinput replay @@ -123,7 +175,7 @@ Without arguments, `libinput record` displays the available devices and lets the user select one. Supply the number (17 in this case for `/dev/input/event17`) and the tool will print the device information and events to the file it is redirected to. More arguments are available, see -the `libinput-record` man page. +the **libinput-record(1)** man page. Reproduce the bug, ctrl+c and attach the output file to a bug report. For data protection, `libinput record` obscures key codes by default, any @@ -147,8 +199,8 @@ sequence again, Ctrl+C stops it and removes the virtual device. Users are advised to always replay a recorded event sequence to ensure they have captured the bug. -More arguments are available, see the `libinput-record` and -`libinput-replay` man pages. +More arguments are available, see the **libinput-record(1)** and +**libinput-replay(1)** man pages. @subsection libinput-record-multiple Recording multiple devices at once @@ -174,4 +226,12 @@ Replaying events is the same as for a single recording: $ sudo libinput replay touchpad-bug.log @endverbatim +@subsection libinput-measure Measuring device properties with libinput measure + +The `libinput measure` tool is a multiplexer for various sub-tools that can +measure specific properties on the device. These tools generally measure one +thing and one thing only and their usage is highly specific to the tool. +Please see the **libinput-measure(1)** man page for information about what +tools are available and the man page for each respective tool. + */