ervin/comfortable-swipe
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Rico Tiongson 2020-05-02 02:48:21 +08:00
parent cf96a92e09
commit 3cceef39a9
2 changed files with 175 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
README.md
View File

@ -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 1. **_Important_**: After inputing your `sudo` password, log out then log back in
## List of Commands ## List of Commands
1. Start the Program 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] comfortable-swipe autostart [on|off|toggle|status|path]
``` ```
1. Help / version
```
comfortable-swipe --help
comfortable-swipe --version
```
1. List configurations 1. List configurations
```bash ```bash
@ -93,6 +85,7 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures
``` ```
1. Get config (examples) 1. Get config (examples)
```bash ```bash
$ comfortable-swipe left3 $ comfortable-swipe left3
ctrl+alt+Right ctrl+alt+Right
@ -136,17 +129,17 @@ Comfortable, seamless, and fast 3-finger (and 4-finger) touchpad swipe gestures
``` ```
1. Delete config 1. Delete config
```bash ```bash
$ comfortable-swipe config delete mouse3 $ comfortable-swipe config delete mouse3
Deleted: Deleted:
left3 = ctrl+super+Right mouse3 = button1
``` ```
1. List all cofigurations 1. List all cofigurations
```bash ```bash
$ comfortable-swipe config list $ comfortable-swipe config list
threshold = 1.0 threshold = 1.0
left4 = ctrl+super+shift+Right left4 = ctrl+super+shift+Right
right3 = ctrl+super+Left 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: 1. Show path to config file:
```bash ```bash
$ comfortable-swipe config path $ comfortable-swipe config path
/home/hikari9/.config/comfortable-swipe.conf /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 ## Swipe Gesture Configurations
The default configuration file is located at `~/.config/comfortable-swipe.conf`. The default configuration file is located at `~/.config/comfortable-swipe.conf`.
Comfortable swipe makes use of **keyboard shortcuts** to perform swipes, through `xdotool`. Comfortable swipe makes use of **keyboard shortcuts** to perform swipes, through `xdotool`.
Edit the configuration file by running: Edit the configuration file by running:
``` ```
@ -191,19 +198,21 @@ comfortable-swipe start
## Configuration Reference ## Configuration Reference
| Key | Value | Defaults | | Key | Value | Defaults |
| --------- | :--------------------------------------------------------------------: | ------------------------------------------------------------ | | --------- | :--------------------------------------------------------------------: | ----------------------------------------------------------------- |
| left3 | 3-finger swipe left | ctrl+alt+Right | | left3 | 3-finger swipe left | ctrl+alt+Right |
| left4 | 4-finger swipe left | ctrl+alt+shift+Right | | left4 | 4-finger swipe left | ctrl+alt+shift+Right |
| right3 | 3-finger swipe right | ctrl+alt+Left | | right3 | 3-finger swipe right | ctrl+alt+Left |
| right4 | 4-finger swipe right | ctrl+alt+shift+Left | | right4 | 4-finger swipe right | ctrl+alt+shift+Left |
| up3 | 3-finger swipe up | ctrl+alt+Down | | up3 | 3-finger swipe up | ctrl+alt+Down |
| up4 | 4-finger swipe up | ctrl+alt+shift+Down | | up4 | 4-finger swipe up | ctrl+alt+shift+Down |
| down3 | 3-finger swipe down | ctrl+alt+Up | | down3 | 3-finger swipe down | ctrl+alt+Up |
| down4 | 4-finger swipe down | ctrl+alt+shift+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 | | 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)) | | | mouse3 | mouses a mouse button when 3 fingers are down | button1 <br> (see [Mouse Gestures](#mouse-gestures-experimental)) | |
| mouse4 | mouses a mouse button when 4 fingers are down | button1 (see [Mouse Gestures](#mouse-gestures-experimental) | | mouse4 | mouses a mouse button when 4 fingers are down | button1 <br> (see [Mouse Gestures](#mouse-gestures-experimental) |
### Keystrokes
Taken from `man xdotool`: 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. 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/) - [Unity Keyboard Shortcuts](https://cheatography.com/sapemeg/cheat-sheets/ubuntu-unity-16-04/)
- [GNOME Keyboard Shortcuts](https://wiki.gnome.org/Design/OS/KeyboardShortcuts) - [GNOME Keyboard Shortcuts](https://wiki.gnome.org/Design/OS/KeyboardShortcuts)
- [KDE Keyboard Shortcuts](https://community.linuxmint.com/tutorial/view/47) - [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 ## Example Configurations
This section includes some example configurations which you can use for your swipe experience. This section includes some example configurations which you can use for your swipe experience.
@ -381,6 +388,7 @@ Examples:
```bash ```bash
mouse3 = move mouse3 = move
``` ```
```bash ```bash
mouse4 = move 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 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_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 -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.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.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.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 -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.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.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.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.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.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_UPDATE +2.10s 3 -4.13/ 0.42 (-11.15/ 1.12 unaccelerated)
event9 GESTURE_SWIPE_END +2.11s 3 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. 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@ <COMMAND>) | \
tee >(grep "SWIPE left4" --line-buffered | xargs -I@ <COMMAND>) | \
tee >(grep "SWIPE right3" --line-buffered | xargs -I@ <COMMAND>) | \
tee >(grep "SWIPE right4" --line-buffered | xargs -I@ <COMMAND>) | \
tee >(grep "SWIPE up3" --line-buffered | xargs -I@ <COMMAND>) | \
tee >(grep "SWIPE up4" --line-buffered | xargs -I@ <COMMAND>) | \
tee >(grep "SWIPE down3" --line-buffered | xargs -I@ <COMMAND>) | \
tee >(grep "SWIPE down4" --line-buffered | xargs -I@ <COMMAND>)
```
Substitute `<COMMAND>` with the shell command of your choice.
## Uninstall ## Uninstall
Run the following script: Run the following script:

2
config/comfortable-swipe.desktop
View File

@ -1,8 +1,8 @@
[Desktop Entry] [Desktop Entry]
Type=Application Type=Application
Exec=comfortable-swipe start
Name=Comfortable Swipe Name=Comfortable Swipe
Comment=Comfortable 3/4-finger touchpad gestures Comment=Comfortable 3/4-finger touchpad gestures
Exec=comfortable-swipe start
Hidden=false Hidden=false
NoDisplay=false NoDisplay=false
X-GNOME-Autostart-enabled=true X-GNOME-Autostart-enabled=true