# sxhkd

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Related articles

- Xbindkeys
- Xmodmap

sxhkd is a simple X hotkey daemon, by the developer of bspwm, that reacts to input events by executing commands.

## Installation

Install sxhkd or sxhkd-gitAUR.

## Configuration

### Configuration file

sxhkd defaults to `$XDG_CONFIG_HOME/sxhkd/sxhkdrc` for its configuration file. An alternate configuration file can be specified with the `-c` option.

Each line of the configuration file is interpreted as so:

- If it starts with `#`, it is ignored.
- If it starts with one or more white space commands, it is read as a command.
- Otherwise, it is parsed as a hotkey: each key name is separated by spaces and/or `+` characters.

General syntax:

    [MODIFIER + ]*[@|!]KEYSYM
        COMMAND

Where `MODIFIER` is one of the following names: `super`, `hyper`, `meta`, `alt`, `control`, `ctrl`, `shift`, `mode_switch`, `lock`, `mod1`, `mod2`, `mod3`, `mod4`, `mod5`. If `@` is added at the beginning of the keysym, the command will be run on key release events, otherwise on key press events. If `!` is added at the beginning of the keysym, the command will be run on motion notify events and must contain two integer conversion specifications which will be replaced by the x and y coordinates of the pointer relative to the root window referential (the only valid button keysyms for this type of hotkeys are: `button1`, ..., `button5`). The `KEYSYM` names are those your will get from `xev`.

Mouse hotkeys can be defined by using one of the following special keysym names: `button1`, `button2`, `button3`, ..., `button24`. The hotkey can contain a sequence of the form {`STRING_1`,…,`STRING_N`}, in which case, the command must also contain a sequence with N elements: the pairing of the two sequences generates N hotkeys. If the command includes curly braces (`{`, `}`) eg. `awk '{print $1}'`, escape them with backslash `\` eg. `awk '\{print $1\}'`. In addition, the sequences can contain ranges of the form `A-Z` where A and Z are alphanumeric characters.

What is actually executed is `SHELL -c COMMAND`, which means you can use environment variables in `COMMAND`. `SHELL` will be the content of the first defined environment variable in the following list: `SXHKD_SHELL`, `SHELL`. If sxhkd receives a `SIGUSR1` signal, it will reload its configuration file.

## Usage

After configuring it, you may wish to setup sxhkd to autostart. An example systemd service file is found here. This approach requires configuring Xorg as a systemd user service.

Alternatively, if your desktop environment supports the Desktop Application Autostart Specification you can also have it start sxhkd by creating an `sxhkd.desktop` file in the appropiate directory:

    ~/.config/autostart/sxhkd.desktop

    [Desktop Entry]
    Name=sxhkd
    Comment=Simple X hotkey daemon
    Exec=/usr/bin/sxhkd
    Terminal=false
    Type=Application

## Example

    $XDG_CONFIG_HOME/sxhkd/sxhkdrc

    # On mouse button 1 press Alt_R+F1
    button1
        xte "keydown Alt_R" "keydown F1" "keyup Alt_R" "keyup F1"

    # On mouse button 2 pause 3 seconds then press Alt_R+F2
    button2
        xte "sleep 3" "keydown Alt_R" "keydown F2" "keyup Alt_R" "keyup F2"

Reload user's sxhkd service

    $ systemctl --user restart sxhkd

## See also

- Official website - includes configuration options, example bindings, and source code.
- ArchLinux forum thread

Categories:

- Keyboard configuration
- X server