Hotkey Helper

Hotkey Helper – Easily document, and discover sxhkd keybindings

https://ipfs.pics/ipfs/QmTdC3PnD1cEcqVo9cUjwY1PsYdVgRbwtypXTT5z8vC5cp

What is it

Hotkey Helper is a little scheme program that parses .sxhkdrc files, taking the hotkeys and some specially formatting comments to create a documented list associating keybindings with their actions. With the latest updates intelligent parsing is added, allowing hotkeys to be executed by string (this results in some neat applications, which you can see in the usage section).

Installation

This program requires chicken scheme, a couple of libraries, and ninja as the build system.

Installing chicken scheme should be relatively easily, and likely available in the repos of insert distribution here.

To install the required libraries, run the following in your shell

chicken-install -s shell fmt args comparse irregex list-of

After cloning this repo, run ninja in the top level directory, it should produce an executable named hotkeys. Simply move hotkeys to somewhere in PATH, and you are done.

.sxhkdrc Setup

In order to use the program’s functionality, you need to tweak your .sxhkdrc to include special comments designed as documentation for keybindings.

The special syntax for these documentation comments is any line beginning with “# ;; “. Set these comments up above every keybinding you wish to document.

# Example keybinding with documentation
# ;; Quit bspwm
super + alt + Escape
    bspc quit
# This would show up in the formatted output as:
# super alt Escape - Quit bspwm

Additionally, {} can be used to denote lists mapping multiple segments of documentation to multiple hotkey segments at once

# Example of segmented documentation
# ;; Move the current window {left,down,up,right}
super + {h,j,k,l}
  bspc node -s {west,south,north,east}
# This would expand in output as:
# super h                  - Move the current window left
# super j                  - Move the current window down
# super k                  - Move the current window up
# super l                  - Move the current window right

This allows for fast, compact documentation for keybindings of arbitrary complexity.

Usage

To use the program, run hotkeys.

hotkeys

This will print the usage for the program

Usage: hotkeys [options...]

 -e, --execute=HOTKEY     Execute command for HOTKEY
 -p, --print              Print hotkeys
 -f, --file=NAME          Parse file NAME
 -h, --help               Display this text

By default, hotkeys looks in the default sxhkd config folder (~/.config/sxhkd/sxhkdrc) for the sxhkdrc file. You can also pass a path argument, for the location of your .sxhkdrc file.

hotkeys -f /path/to/.sxhkdrc

However this will do nothing either, you need to pass an action argument to the program, currently -p or -e to tell hotkeys what to do with the file.

-p

Print a formatted list of hotkeys.

-e

Execute a hotkey string (e.g “super w”).

Upon running hotkeys -p, you should get a formatted list of hotkeys printed to the terminal, something like

[~/repos/scm/hotkey-helper] ->>  hotkeys -p
super question           - Show keybindings
super i                  - Capture notes using org-mode
super space              - Run a command
super Return             - Spawn terminal
XF86AudioStop            - Open ncmpcpp
XF86AudioPrev            - Previous song
XF86AudioNext            - Next song
XF86AudioPlay            - Play mpd
XF86AudioRaiseVolume     - Raise Volume
XF86AudioLowerVolume     - Lower Volume
super button1-3          - Focus window
button1                  - Focus window
super ctrl h             - Move window to the left monitor
super ctrl l             - Move window to the right monitor
super bracketleft        - Go backward a desktop
super bracketright       - Go forward a desktop
super shift bracketleft  - Move window back a desktop
super shift bracketright - Move window forward a desktop
super h                  - Move the current window left
super j                  - Move the current window down
super k                  - Move the current window up
super l                  - Move the current window right
super m                  - Make window biggest
super p                  - Open password manager
Print                    - Take a screenshot
super apostrophe         - Swap last two window
super grave              - Goto last window
super Tab                - Goto last desktop
super s                  - Make window float
super f                  - Make window fullscreen
super t                  - Make window tiled
super b                  - Balance windows
super w                  - Close window
super shift w            - Show window list
super Delete             - Suspend
super alt Escape         - Quit bspwm
super Escape             - Restart sxhkd

The output is tabulated (thanks to the fmt library), so all the descriptions are neatly aligned and easy on the eyes.

This output can be piped to the likes of dmenu, or rofi.

# An example from my own config.
hotkeys -p | rofi -i -p "Hotkeys: "

Doing this with a program like rofi allows for powerful searching of hotkeys on the system.

By running hotkeys -e, you can execute a command associated with a keybinding. For instance, from the above configuration super w is bound to closing a window. Thus calling:

hotkeys -e "super w"

Will close a window, as expected.

By combining the -p flag, and the -e flag, you can create a relatively powerful system for discovery and remembering your keybindings by having hotkeys -e run the output of the hotkeys searching script from earlier.

# Adapted from the last shell script.
hotkeys -e "$(hotkeys -p | rofi -p Hotkeys: -i -dmenu | awk -F- '{print $1}')"

The example gif shows how this script works