Hotkey Helper – Easily document, and discover sxhkd keybindings
https://ipfs.pics/ipfs/QmTdC3PnD1cEcqVo9cUjwY1PsYdVgRbwtypXTT5z8vC5cp
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).
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.
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.
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