Repository files navigation

Libinput-gestures is a utility which readslibinputgesturesfrom your touchpad and maps them to gestures you configure in aconfiguration file. Each gesture can be configured to activate a shellcommand which is typically anxdotool command to actiondesktop/window/application keyboard combinations and commands. See theexamples in the providedlibinput-gestures.conf file. My motivationfor creating this is to use triple swipe up/down to switch workspaces,and triple swipe right/left to go backwards/forwards in my browser, asper the default configuration.

Note thatlibinput does not interpret gestures fortouchscreensso this utility can only be used for a touchpad, not a touchscreen.

This small and simple utility is only intended to be used temporarilyuntil GNOME and other DE's action libinput gestures natively. It parsesthe output of thelibinput list-devices andlibinput debug-eventsutilities so is a little fragile to any version changes in their outputformat.

This utility is developed and tested on Arch linux using the GNOME 3 DEon Xorg and Wayland. It works somewhat incompletely on Wayland (viaXWayland). See the WAYLAND section below and the comments in the defaultlibinput-gestures.conf file. It has beenreported to work withKDE.I am not sure how well this will work on all Linux systems and DE's etc.

The latest version and documentation is available athttps://github.com/bulletmark/libinput-gestures.

You needpython 3.8 or later,python2 is not supported. You also needlibinput release 1.0 or later.

Youmust be a member of theinput group to have permissionto read the touchpad device:

sudo gpasswd -a $USER input

After executing the above command, reboot your system.

Note adding yourself to theinput group makes ALL/dev/inputdevices readable by your user account and some consider this a securityrisk. If you are concerned then consider adding a udev rule to apply adynamic user ACL asdescribedhere,rather than adding yourself to theinput group.

Most/many users will require to install the following although neither areactual dependencies because some custom configurations will not requirethem. If you are unsure initially, install both of them.

# E.g. On Arch:sudo pacman -S wmctrl xdotool# E.g. On Debian based systems, e.g. Ubuntu:sudo apt-get install wmctrl xdotool# E.g. On Fedora:sudo dnf install wmctrl xdotool

NOTE: Arch users can now just installlibinput-gestures from theAUR. Then skip to the next CONFIGURATION section.

Debian and Ubuntu users may also need to installlibinput-tools ifthat package exists in your release:

sudo apt-get install libinput-tools

Install this software:

git clone https://github.com/bulletmark/libinput-gestures.gitcd libinput-gesturessudo ./libinput-gestures-setup install

It is helpful to start by reading the documentation aboutwhat libinputcalls gestures.Many users will be happy with the default configuration in which caseyou can just type the following and you are ready to go:

libinput-gestures-setup autostart start

Otherwise, if you want to create your own custom gestures etc, keepreading ..

The default gestures are in/etc/libinput-gestures.conf. If you wantto create your own custom gestures then copy that file to~/.config/libinput-gestures.conf and edit it. There are many examplesand options described in that file. The available gestures are:

NOTE: If you don't use "natural" scrolling direction for your touchpadthen you may want to swap the default left/right and up/downconfigurations.

You can choose to specify a specific finger count, typically3 or morefingers for swipe,and2 or more for pinch.If a finger count is specified then the command is executed when exactly thatnumber of fingers is used in the gesture. If not specified then thecommand is executed when that gesture is invoked with any number offingers. Gestures specified with finger count have priority over thesame gesture specified without any finger count.

Of course, 2 finger swipes and taps are already interpreted by your DEand appsfor scrolling etc.

IMPORTANT: Test the program. Check for reported errors in your customgestures, missing packages, etc:

# Ensure the program is stoppedlibinput-gestures-setup stop# Test to print out commands that would be executed:libinput-gestures -d(<ctrl-c> to stop)

Confirm that the correct commands are reported for your 3 fingerswipe up/down/left/right gestures, and your 2 or 3 finger pinchin/out gestures. Some touchpads can also support 4 finger gestures.If you have problems then follow the TROUBLESHOOTING steps below.

Apart from simple environment variable and~ substitutions within theconfigured command name,libinput-gestures does not run the configuredcommand under a shell so shell argument substitutions and expansions etcwill not be parsed. This is for efficiency and because most don't needit. This also means yourPATH is not respected of course so you mustspecify the full path to any command. If you need something morecomplicated, you can add your commands in an executable personal script,e.g.~/bin/libinput-gestures.sh with a#!/bin/sh shebang. Optionallythat script can take arguments. Run that script by hand until you get itworking then configure the script path as your command in yourlibinput-gestures.conf.

In most cases,libinput-gestures automatically determines yourtouchpad device. However, you can specify it in your configuration fileif needed. If you have multiple touchpads you can also specifylibinput-gestures to use all devices. See the notes in the defaultlibinput-gestures.conf file about thedevice configuration command.

To [re-]start the app immediately and also to enable it to startautomatically at login, just type the following:

libinput-gestures-setup stop desktop autostart start

The following commands are available:

Enable the app to start automatically in the background when youlog in with:

libinput-gestures-setup autostart

Disable the app from starting automatically with:

libinput-gestures-setup autostop

Start the app immediately in the background:

libinput-gestures-setup start

Stop the background app immediately with:

libinput-gestures-setup stop

Restart the app, e.g. to reload the configuration file, with:

libinput-gestures-setup restart

Check the status of the app with:

libinput-gestures-setup status

You can specify multiple user commands tolibinput-gestures-setup toaction in sequence.

Note that on some uncommon systems thenlibinput-gestures-setup startmay fail to start the application returning you a messageDon't knowhow to invoke libinput-gestures.desktop. If you get this error message,install the dex package, preferably from your system packagesrepository, and try again.

By default,libinput-gestures is started with your DE as a desktopapplication. There is also an option to start as asystemd userservice. However, onsome systems this can be unreliable (on system restart, the applicationwill get started but occasionally will be unable to receive commands).If you want to try it, type:

libinput-gestures-setup stop service autostart start

You can switch back to the desktop option with the command:

libinput-gestures-setup stop desktop autostart start

# cd to source dir, as abovegit pullsudo ./libinput-gestures-setup installlibinput-gestures-setup restart

libinput-gestures-setup stop autostopsudo libinput-gestures-setup uninstall

This utility exploitsxdotool for many use cases which unfortunatelyonly works with X11/Xorg based applications. Soxdotool shortcuts forthe desktop do not work under GNOME on Wayland which is the defaultsince GNOME 3.22. However, it is found thatwmctrl desktop selectioncommands do work under GNOME on Wayland (via XWayland) so this utilityadds a built-in_internal command which can be used to switchworkspaces using the swipe commands. The_internalws_up andws_down commands usewmctrl to work out the current workspace andselect the next one. Since this works on both Wayland and Xorg, and withGNOME, KDE, and other EWMH compliant desktops, it is the defaultconfiguration command for swipe up and down commands inlibinput-gestures.conf. See the comments in that file about otheroptions you can do with the_internal command. Unfortunately_internal does not work with Compiz for Ubuntu Unity desktop so alsosee the explicit example there for Unity.

Of course,xdotool commands do work via XWayland for Xorg based appsso, for example, page forward/back swipe gestures do work for Firefoxand Chrome browsers when running on Wayland as per the defaultconfiguration.

Note if you runlibinput-gestures on GNOME with Wayland, be sure tochange or disable the yourlibinput-gestures.conf configured gesturesto not clash with the native gestures.

GNOME 3.38 and earlier on Wayland natively implements the followinggestures:

• 3 finger pinch opens/close the GNOME overview.
• 4 finger swipe up/down changes workspaces

GNOME 40->46 on Wayland natively implements the followinggestures:

• 3 finger swipe up/down opens the GNOME overview.
• 3 finger swipe left/right changes workspaces

Note that GNOME 40->46 does not use 4 finger gestures so you can freelyassign them usinglibinput-gestures.

GNOME 47 and above implements the same gestures as GNOME 40->46 but alsoduplicates those gestures to 4 finger gestures so you can't use them forlibinput-gestures unless you do one of the following to disable 3 fingergestures in GNOME.

1. Install theDisable 3 FingerGesturesGNOME shell extension (recommended).

2. Patchgnome-shell to stop it using 3 finger gestures using thispatch script.

GNOME on Xorg does not natively implement any gestures.

They are not enabled in the defaultlibinput-gestures.confconfiguration file but you can enable extended gestures which augmentthe gestures listed above in CONFIGURATION. See the commented outexamples inlibinput-gestures.conf.

• swipe right_up (e.g. jump to next open browser tab)
• swipe left_up (e.g. jump to previous open browser tab)
• swipe left_down (e.g. close current browser tab)
• swipe right_down (e.g. reopen and jump to last closed browser tab)
• pinch clockwise
• pinch anticlockwise

So instead of just configuring the usual swipe up/down and left/righteach at 90 degrees separation, you can add the above extra 4 swipes togive a total of 8 swipe gestures each at 45 degrees separation. It worksbetter than you may expect, at least after some practice. It means youcan completely manage browser tabs from your touchpad.

Libinput version 1.19.0 addedHOLDgesturesto augment the standard SWIPE and PINCH gestures. They are actioned with1 or more fingers after holding them for a small time period and aresimply set ON as a trigger.libinput-gestures interprets them to commands you canconfigure in yourlibinput-gestures.conf, e.g:

gesture hold on 4 xdotool key control+t

The above gesture will open a new tab in your browser if you rest 4fingers statically on the touchpad. If you don't specify a finger countthen the command is executed when any number of fingers are used for thehold.

Optionally, you can configure a time delay on hold gestures to maplonger hold times to different commands. Any extra hold time can bespecified, as an integer or float value in decimal seconds. E.g.on+1is a hold + 1 extra second,on+3.5 is a hold + 3.5 extra seconds, etc.These can be configured in addition toon (which is effectively thesame ason+0), and also with different (or no specific) finger counts,e.g:

gesture hold on 4 xdotool key control+tgesture hold on+2.2 4 xdotool key control+w

The above will configure a second 4 finger hold gesture which, after 2.2extra seconds to a normal hold, will close the current tab in yourbrowser. You can configure as many hold gestures, with different timesand finger counts (or no specific finger count), as you like but it willquickly get unworkable if you add too many, or with close delays.

To get an idea of suitable hold times to configure, comment out all holdgestures in your configuration filelibinput-gestures.conf and runwith debug output. I.e. runlibinput-gestures -d in a terminal window(you may have to temporarily disablelibinput-gestures first byrunninglibinput-gestures-setup stop). Then experiment with differentholds which will print the times to the screen so you can choose what toconfigure for your hold gestures. Runlibinput-gestures-setup restartto restartlibinput-gestures after updating your configuration.

There are some situations where you may want to automatically stop,start, or restartlibinput-gestures. E.g. some touchpads have aproblem which causeslibinput-gestures (actually the underlyinglibinput debug-events) to hang after resuming from a system suspend sothose users want to stoplibinput-gestures when a system goes intosuspend and then start it again with resuming. You can use a companionprogramdbus-action todo this. See the example configuration forlibinput-gestures in thedefaultdbus-actionconfigurationfile.

Thedbus-action utility can also be used any similarsituation, e.g. when you remove/insert a detachable touchpad. It can beused to stop, start, or restartlibinput-gestures on any D-Bus event.

Please don't raise a github issue but provide little information aboutyour problem, and please don't raise an issue until you have consideredall the following steps.If you raise an issue ALWAYS include theoutput oflibinput-gestures -l to show the environment andconfiguration you are using, regardless of what the issue is about.

1. Ensure you are running the latest version from thelibinput-gestures github repository or from theArch AUR.

2. Ensure you have followed the installation instructions herecarefully. The most common mistake is that you have not added youruser to theinput group and rebooted your system as describedabove.

3. Perhaps temporarily remove your custom configuration to try with thedefault configuration.

4. Runlibinput-gestures-setup status and confirm it reports the setup that you expect.

5. Runlibinput-gestures on the command line in debug mode whileperforming some 3 and 4 finger left/right/up/down swipes, and somepinch in/outs. In debug mode, configured commands are not executed,they are merely output to the screen:

    libinput-gestures-setup stop libinput-gestures -d (<ctrl-c> to stop)

6. Runlibinput-gestures in raw mode by repeating the same commands asabove step but use the-r (--raw) switch instead of-d(--debug). Raw mode does nothing more than echo the raw gestureevents received fromlibinput debug-events. You should see thefollowing types of events when you move your fingers:

   • 1 and 2 finger movements should outputPOINTER_* type events
   • 3 (and above) finger movements should outputGESTURE_* type events.

   If you do not see anyGESTURE_* events then unfortunately yourtouchpad and/or libinput does not report multi-finger gestures solibinput-gestures can not work. The discrimination ofgestures is done completely within libinput, before they get passedtolibinput-gestures.

7. Search the web for Linux kernel and/or libinput issues relating toyour specific touchpad device and/or laptop/pc. Update your BIOS ifpossible.

8. Be sure that a configured external command works exactly how you wantwhen you run it directly on the command line,before you configureit forlibinput-gestures. E.g. runxdotool manually andexperiment with various arguments to work out exactly what argumentsit requires to do what you want, and only then add that command +arguments to your custom configuration in~/.config/libinput-gestures.conf. Clearly, if the your manualxdotool command does not work correctly then there is no pointraising anlibinput-gestures issue about it!

9. If you raise an issue, always include the output oflibinput-gestures -l to show the environment and configuration youare using. If appropriate, also paste the output from steps 4 and 5above. If your device is not being recognised bylibinput-gesturesat all, paste the complete output oflibinput list-devices(libinput-list-devices on libinput < v1.8).

Copyright (C) 2015 Mark Blakeney. This program is distributed under theterms of the GNU General Public License.This program is free software: you can redistribute it and/or modify itunder the terms of the GNU General Public License as published by theFree Software Foundation, either version 3 of the License, or any laterversion.This program is distributed in the hope that it will be useful, butWITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU GeneralPublic License athttps://en.wikipedia.org/wiki/GNU_General_Public_License for more details.