Update README

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:
 
 ```
@@ -192,7 +199,7 @@ 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                                                     |
@@ -202,8 +209,10 @@ comfortable-swipe start
 | 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)) |  |
+| 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`:
 
@@ -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 -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.
 
+## 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
 
 Run the following script:

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