spmenu.conf documentation15 Oct 2023 14:59
Home All
Basics
Hacker

spmenu.conf documentation

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

The spmenu.conf configuration file (usually located in ~/.config/spmenu/spmenu.conf and is XDG Base Directory compliant) can be used to configure all exposed spmenu options, including theming.

The config file is not created by default though, but a default config file can be found in /usr/share/spmenu/spmenu.conf and copied to said location. It will then be loaded on startup. This example config file contains all the default options. (file a bug report if it doesn't)

spmenu.conf is rarely specified by scripts, and shouldn't ideally not be used with scripts if possible. binds.conf and theme.conf exist for a reason. spmenu.conf should be dedicated to options that the user has full control over.

Config file loading

When spmenu is loaded, it loads these files in this order:

This means if spmenu.conf does not exist the default options will be used. If it does exist, it will be loaded. Then, if a binds.conf exists its binds will override the ones spmenu.conf provide. Then, if a theme exists it will override options provided by spmenu.conf or built in options. Finally, the xrdb will be loaded if X11 is used and any colors are specified.

Syntax

NOTE: libconfig is used for the configuration file.

Any valid spmenu.conf will start with spmenu = { (optionally after comments). If not, spmenu will not bother trying to load any options. The spmenu configuration files all resemble C mixed with JSON, and are quite simple.

spmenu config files contain a setting with the value being a group. In this case, it's named spmenu. It (like all settings) ends with a semicolon.

The shell of a spmenu configuration file would look something like this:

spmenu = {

};

The setting needs to be filled with something though, as in the above example it's completely empty. So the setting will usually contain another setting with the value this time being a list. The value of the list will usually be a group. This group often (but not always) contains settings that spmenu will load.

Below is a simple example changing the default protocol from Wayland to X11.

spmenu = {
    option = ( {
        option1 = 0;
        option2 = 1;
        option3 = "Hello world!";
    } );
};

As you can tell, everything is built around a setting. Note that indentation or spaces/tabs geneerally don't matter, and spmenu can usually load it anyway, even if it's unreadable to the user.

Just like C, comments can be in // form or /* */ form.

In practice, keybinds may be set like this:

spmenu = {
    keys = (
           {
               mode = <mode>;
               modifier = "<modifier>";
               key = "<key>";
               function = "<function>";
               argument = "<argument>";
           },
         ),
};

Or a mouse bind:

spmenu = {
    mouse = (
            {
                click = "<click>";
                button = "<button>";
                function = "<function>";
                argument = "<argument>";
            },
};

Supported strings

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

See also

spmenu wiki articles licensed under the CC-BY-SA 4.0 license. Powered by swiki.