diff --git a/README.md b/README.md index 2e7d4bd..3038380 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,6 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures 1. **_Important_**: After inputing your `sudo` password, log out then log back in - ## List of Commands 1. Start the Program @@ -70,13 +69,6 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures comfortable-swipe autostart [on|off|toggle|status|path] ``` -1. Help / version - - ``` - comfortable-swipe --help - comfortable-swipe --version - ``` - 1. List configurations ```bash @@ -93,6 +85,7 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures ``` 1. Get config (examples) + ```bash $ comfortable-swipe left3 ctrl+alt+Right @@ -136,17 +129,17 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures ``` 1. Delete config + ```bash $ comfortable-swipe config delete mouse3 - Deleted: - left3 = ctrl+super+Right + mouse3 = button1 ``` 1. List all cofigurations + ```bash $ comfortable-swipe config list - threshold = 1.0 left4 = ctrl+super+shift+Right right3 = ctrl+super+Left @@ -160,18 +153,32 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures ``` 1. Show path to config file: + ```bash $ comfortable-swipe config path - /home/hikari9/.config/comfortable-swipe.conf ``` +1. (Advanced) Show output with `--attach` + + Example output of 3-finger left, 4-finger left, 3-finger right, 3-finger up: + + ```bash + $ comfortable-swipe start --attach + SWIPE left3 + SWIPE left4 + SWIPE right3 + SWIPE up3 + ... + ``` + + You can also pass `--bare` to attach without actually swiping. + ## Swipe Gesture Configurations The default configuration file is located at `~/.config/comfortable-swipe.conf`. Comfortable swipe makes use of **keyboard shortcuts** to perform swipes, through `xdotool`. - Edit the configuration file by running: ``` @@ -191,19 +198,21 @@ comfortable-swipe start ## Configuration Reference -| Key | Value | Defaults | -| --------- | :--------------------------------------------------------------------: | ------------------------------------------------------------ | -| left3 | 3-finger swipe left | ctrl+alt+Right | -| left4 | 4-finger swipe left | ctrl+alt+shift+Right | -| right3 | 3-finger swipe right | ctrl+alt+Left | -| right4 | 4-finger swipe right | ctrl+alt+shift+Left | -| up3 | 3-finger swipe up | ctrl+alt+Down | -| up4 | 4-finger swipe up | ctrl+alt+shift+Down | -| down3 | 3-finger swipe down | ctrl+alt+Up | -| down4 | 4-finger swipe down | ctrl+alt+shift+Up | -| threshold | mouse movement pixels that trigger a swipe (can be as large as 1000.0) | 0.0, 240.0, 1000.0 | -| mouse3 | mouses a mouse button when 3 fingers are down | button1 (see [Mouse Gestures](#mouse-gestures-experimental)) | | -| mouse4 | mouses a mouse button when 4 fingers are down | button1 (see [Mouse Gestures](#mouse-gestures-experimental) | +| Key | Value | Defaults | +| --------- | :--------------------------------------------------------------------: | ----------------------------------------------------------------- | +| left3 | 3-finger swipe left | ctrl+alt+Right | +| left4 | 4-finger swipe left | ctrl+alt+shift+Right | +| right3 | 3-finger swipe right | ctrl+alt+Left | +| right4 | 4-finger swipe right | ctrl+alt+shift+Left | +| up3 | 3-finger swipe up | ctrl+alt+Down | +| up4 | 4-finger swipe up | ctrl+alt+shift+Down | +| down3 | 3-finger swipe down | ctrl+alt+Up | +| down4 | 4-finger swipe down | ctrl+alt+shift+Up | +| threshold | mouse movement pixels that trigger a swipe (can be as large as 1000.0) | 0.0, 240.0, 1000.0 | +| mouse3 | mouses a mouse button when 3 fingers are down | button1
(see [Mouse Gestures](#mouse-gestures-experimental)) | | +| mouse4 | mouses a mouse button when 4 fingers are down | button1
(see [Mouse Gestures](#mouse-gestures-experimental) | + +### Keystrokes Taken from `man xdotool`: @@ -221,14 +230,12 @@ Taken from `man xdotool`: Refer to https://www.linux.org/threads/xdotool-keyboard.10528/ for a complete list of keycodes you can use. -## Keyboard shortcuts +Keyboard shortcuts: - [Unity Keyboard Shortcuts](https://cheatography.com/sapemeg/cheat-sheets/ubuntu-unity-16-04/) - [GNOME Keyboard Shortcuts](https://wiki.gnome.org/Design/OS/KeyboardShortcuts) - [KDE Keyboard Shortcuts](https://community.linuxmint.com/tutorial/view/47) -> **Note**: You can check which desktop you are using with `echo $DESKTOP_SESSION`. - ## Example Configurations This section includes some example configurations which you can use for your swipe experience. @@ -381,6 +388,7 @@ Examples: ```bash mouse3 = move ``` + ```bash mouse4 = move ``` @@ -405,23 +413,147 @@ $ comfortable-swipe debug -event9 DEVICE_ADDED TouchPad seat0 default group7 cap:pg size 70x50mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on ... event9 GESTURE_SWIPE_BEGIN +2.03s 3 - event9 GESTURE_SWIPE_UPDATE +2.03s 3 -9.95/ 2.64 (-26.90/ 7.12 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.03s 3 -10.44/ 3.19 (-28.22/ 8.62 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.04s 3 -9.71/ 2.64 (-26.25/ 7.12 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.05s 3 -8.98/ 2.64 (-24.28/ 7.12 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.06s 3 -7.40/ 2.36 (-20.01/ 6.37 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.06s 3 -6.31/ 2.50 (-17.06/ 6.75 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.07s 3 -5.34/ 1.80 (-14.44/ 4.87 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.08s 3 -4.61/ 2.08 (-12.47/ 5.62 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.09s 3 -4.49/ 1.53 (-12.14/ 4.12 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.09s 3 -4.01/ 1.25 (-10.83/ 3.37 unaccelerated) - event9 GESTURE_SWIPE_UPDATE +2.10s 3 -4.13/ 0.42 (-11.15/ 1.12 unaccelerated) - event9 GESTURE_SWIPE_END +2.11s 3 - ... +event9 GESTURE_SWIPE_UPDATE +2.03s 3 -9.95/ 2.64 (-26.90/ 7.12 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.03s 3 -10.44/ 3.19 (-28.22/ 8.62 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.04s 3 -9.71/ 2.64 (-26.25/ 7.12 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.05s 3 -8.98/ 2.64 (-24.28/ 7.12 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.06s 3 -7.40/ 2.36 (-20.01/ 6.37 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.06s 3 -6.31/ 2.50 (-17.06/ 6.75 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.07s 3 -5.34/ 1.80 (-14.44/ 4.87 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.08s 3 -4.61/ 2.08 (-12.47/ 5.62 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.09s 3 -4.49/ 1.53 (-12.14/ 4.12 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.09s 3 -4.01/ 1.25 (-10.83/ 3.37 unaccelerated) +event9 GESTURE_SWIPE_UPDATE +2.10s 3 -4.13/ 0.42 (-11.15/ 1.12 unaccelerated) +event9 GESTURE_SWIPE_END +2.11s 3 +... ``` If you can see `GESTURE_SWIPE_XXX` in your output, that means your touchpad supports multi-touch swipe gestures. +## FAQ: Can I run a _shell command_ instead of a keystroke? + +**Answer 1**: _Unfortunately **NO**..._ + +For the following reasons: + +1. We want prioritize "comfort" over functionality, which we deliver through performance in our near-zero-overhead implementation (that's why C++) +2. Running a new shell command with unpredictable process time will break our unthreaded optimizations (unlike native keystrokes) +3. There are other gesture libraries that already do this properly (eg. [libinput gestures](https://github.com/bulletmark/libinput-gestures), [Fusuma](https://github.com/iberianpig/fusuma)), we don't want to be a clone of them + +That's why it's not possible... + +**Answer 2**: _... but actually **YES**!_ + +Although we don't provide this out of the box in our config, this can definitely be +done with the default bash tools. + +## Hack: Shell command on swipe + +Running shell commands our **NOT** part of the core features of comfortable-swipe, +but through the default bash tools you can _mimic_ this functionality via our program output. + +**Use Case**: _"I want to run `gnome-terminal` if I swipe up with 3 fingers."_ + +1. Attach the program to the shell: + + ```bash + comfortable-swipe start --attach + ``` + + Verify it outputs when you swipe left, left, up, right, up with 3 fingers: + + ```bash + $ comfortable-swipe start --attach + SWIPE left3 + SWIPE left3 + SWIPE up3 + SWIPE right3 + SWIPE up3 + ... + ``` + +1. Filter out the wanted gesture with `grep`. + + In our case, we want 3-finger swipe up which is "SWIPE up3": + + ```bash + $ comfortable-swipe start --attach | grep --line-buffered "SWIPE up3" + SWIPE up3 + SWIPE up3 + ... + ``` + + > **Note**: The flag `--line-buffered` ensures the output prints line-by-line. + +1. Now we can execute our shell command with `xargs`. + + So if we want "SWIPE up3" to open the terminal, + + ```bash + comfortable-swipe start --attach | grep "SWIPE up3" --line-buffered | xargs -I@ gnome-terminal + ``` + + > **Note**: The flag `-I@` in xargs substitutes the line "SWIPE xxx" to the charatcter "@", which you can use for your program. + +1. _Bonus_: Add to autostart + + Open our autostart file: + + ```bash + gedit "$(comfortable-swipe autostart path)" + ``` + + Tweak the `Exec` section: + + ```ini + [Desktop Entry] + Type=Application + Exec=comfortable-swipe start + Name=Comfortable Swipe + Comment=Comfortable 3/4-finger touchpad gestures + Hidden=false + NoDisplay=false + X-GNOME-Autostart-enabled=true + ``` + + To: + + ```ini + [Desktop Entry] + Type=Application + Exec=comfortable-swipe start --attach | grep "SWIPE up3" --line-buffered | xargs -I@ gnome-terminal + Name=Comfortable Swipe + Comment=Comfortable 3/4-finger touchpad gestures + Hidden=false + NoDisplay=false + X-GNOME-Autostart-enabled=true + ``` + +1. Log out and log back in. + You should now be able to run your custom shell commands on startup. + +1. _Bonus_: Use `--bare` instead of `--attach` to NOT run keystrokes while swiping + + ```bash + comfortable-swipe start --bare | grep "SWIPE up3" --line-buffered | xargs -I@ gnome-terminal + ``` + +1. _Bonus_: You can pipe multiple gestures with `tee`: + + ```bash + comfortable-swipe start --attach | \ + tee >(grep "SWIPE left3" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE left4" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE right3" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE right4" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE up3" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE up4" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE down3" --line-buffered | xargs -I@ ) | \ + tee >(grep "SWIPE down4" --line-buffered | xargs -I@ ) + ``` + + Substitute `` with the shell command of your choice. + ## Uninstall Run the following script: diff --git a/config/comfortable-swipe.desktop b/config/comfortable-swipe.desktop index 3b1da8f..c680906 100644 --- a/config/comfortable-swipe.desktop +++ b/config/comfortable-swipe.desktop @@ -1,8 +1,8 @@ [Desktop Entry] Type=Application +Exec=comfortable-swipe start Name=Comfortable Swipe Comment=Comfortable 3/4-finger touchpad gestures -Exec=comfortable-swipe start Hidden=false NoDisplay=false X-GNOME-Autostart-enabled=true