spmenu-wiki/binds.conf documentation.md

# binds.conf documentation

**NOTE: A list of modes, modifiers, keys, functions and what arguments
those functions expect can be found in [[Configurable keybinds]].**

The binds.conf allows key and mouse binds to be configurated outside of the
regular spmenu.conf config file.

This configuration file is primarily used by shell scripts that utilize
spmenu. This is because it allows scripts to override keybinds without
altering the user's existing configuration file or theming in any way.

The binds.conf configuration file is nearly identical to spmenu.conf
with key and mouse binds. Anything not related to input is not
recognized when using this file. Any valid binds.conf will start
with `binds = {` as opposed to `spmenu = {` or `theme = {`.

It should be noted that if the file is loaded, it will override
**all** existing binds from the user's regular configuration.

For example, if you want to have a binds.conf configuration
with the only bind being the quit bind, you could do something
like this:

```spmenu config
bind = {
    keys = ( {
            mode = -1;
            modifier = "None";
            key = "Esc";
            function = "quit";
            argument = "0";
        },
};
```

This is the exact same format keybinds in the regular config file use.
Same goes for mouse binds. This is an example allowing clicking on items
and outputting them:

```spmenu config
bind = {
    mouse = ( {
            click = "ClickItem";
            button = "Left Click";
            function = "selecthover";
            argument = "0";
        },
};
```

## Supported strings

Tip: Use `Ctrl+f` to search this list, because it is quite long.

- **bind.keys.modifier**
  - Description: Modifier that must be pressed for the function to be executed
  - Type: String
- **bind.keys.mode**
  - Description: Mode that must be in use for the function to be executed
  - Type: Integer
- **bind.keys.key**
  - Description: Key that must be pressed for the function to be executed
  - Type: String
- **bind.keys.function**
  - Description: Function to execute when the conditions are met
  - Type: String
- **bind.keys.argument**
  - Description: Argument passed to the function
  - Type: String
- **bind.keys.ignoreglobalkeys**
  - Description: Ignore hardcoded keybinds
  - Type: Integer
- **bind.keys.forceinsertmode**
  - Type: Integer
- **bind.mouse.click**
  - Description: Area where the click must have been for the function to be executed
  - Type: String
- **bind.mouse.button**
  - Description: Mouse button that must have been used to click for the
  function to be executed
  - Type: String
- **bind.mouse.function**
  - Description: Function to execute when all conditions are met
  - Type: string
- **bind.mouse.argument**
  - Description: Argument passed to the function
  - Type: String
- **bind.mouse.ignoreglobalmouse**
  - Description: Ignore hardcoded mouse binds
  - Type: Integer
- **bind.mouse.scrolldistance**
  - Description: Distance to scroll for a scroll action to count
  - Type: Integer
  - Note: Only applies for Wayland

## See also

- [[Configurable keybinds]]
- [[spmenu.conf documentation]]
- [[theme.conf documentation]]