spmenu

1. What is spmenu?

spmenu is a program for X11 that reads standard input and allows the user to select items separated by a newline. It is a fork of suckless's dmenu which is a good more minimal alternative to spmenu.

Unlike dmenu and the many builds out there, spmenu has features like color support, Vim-like modes, image support, proper keybind configuration, and more.

2. Usage

On runtime, spmenu reads from standard input (stdin). spmenu items are separated by a newline (\n). When (by default) Enter is pressed, the selected item will be piped to stdout.

This allows things like printf "Apple\nOrange\nPear\n" | spmenu. This command will spawn an spmenu window with three items, 'Apple', 'Orange' and 'Pear'. This can be used in shell scripts to create interactive menus.

On top of this, you can specify arguments to change the behavior of spmenu. See a list below for a list.

3. Arguments

spmenu -l Set line count to stdin
spmenu -h Set spmenu line height to
spmenu -g Set the number of grids to
spmenu -gc Generate image cache
spmenu -rw Enable relative input width
spmenu -nrw Disable relative input width
spmenu -f Grabs keyboard before reading stdin
spmenu -F Enable fuzzy matching
spmenu -P Hide characters
spmenu -p Set spmenu prompt text to
spmenu -a Enable alpha
spmenu -na Disable alpha
spmenu -cp Color prompt
spmenu -ncp Don't color prompt
spmenu -tp Allow the user to type
spmenu -nt Don't allow typing, the user must select an option
spmenu -x Offset spmenu x position by
spmenu -y Offset spmenu y position by
spmenu -n Preselect in the list of items
spmenu -z Width of the spmenu window
spmenu -nmt Set normal mode text to
spmenu -imt Set insert mode text to
spmenu -bw Width of the border. 0 will disable the border
spmenu -s Use case-sensitive matching
spmenu -i Use case-insensitive matching
spmenu -nm Start spmenu in normal mode
spmenu -im Start spmenu in insert mode
spmenu -t Position spmenu at the top of the screen
spmenu -b Position spmenu at the bottom of the screen
spmenu -c Position spmenu at the center of the screen
spmenu -hm Hide mode indicator
spmenu -hmc Hide match count
spmenu -sm Show mode indicator
spmenu -smc Show match count
spmenu -xrdb Load .Xresources on runtime
spmenu -w Embed spmenu inside
spmenu -H Specify a path to save the history to
spmenu -ig Set image gaps to
spmenu -lp Set the vertical padding
spmenu -hp Set the horizontal padding
spmenu -la Set the left arrow to
spmenu -ra Set the right arrow to
spmenu -is Image size
spmenu -it Position the image at the top
spmenu -ib Position the image at the bottom
spmenu -ic Position the image in the center
spmenu -itc Position the image in the top center
spmenu -wm Spawn spmenu as a window manager controlled client/window. Useful for testing
spmenu -v Print spmenu version to stdout
spmenu -fn Set the spmenu font to
spmenu -nif Set the normal item foreground color
spmenu -nib Set the normal item background color
spmenu -sif Set the selected item foreground color
spmenu -sib Set the selected item background color
spmenu -pfg Set the prompt foreground color
spmenu -pbg Set the prompt background color
spmenu -ifg Set input foreground color
spmenu -ibg Set input background color
spmenu -mbg Set the menu background color
spmenu -nhf Set the normal highlight foreground color
spmenu -nhb Set the normal highlight background color
spmenu -shf Set the selected highlight foreground color
spmenu -shb Set the selected highlight background color
spmenu -shb Set the selected highlight background color
spmenu -nfg Set the foreground color for the match count
spmenu -nbg Set the background color for the match count
spmenu -mfg Set the foreground color for the mode indicator
spmenu -mbg Set the background color for the mode indicator
spmenu -laf Set the left arrow foreground color
spmenu -raf Set the right arrow foreground color
spmenu -lab Set the left arrow background color
spmenu -rab Set the right arrow background color
spmenu -cc Set the caret color
spmenu -bc Set the border color
spmenu -sgr0 Set the SGR 0 color
spmenu -sgr1 Set the SGR 1 color
spmenu -sgr2 Set the SGR 2 color
spmenu -sgr3 Set the SGR 3 color
spmenu -sgr4 Set the SGR 4 color
spmenu -sgr5 Set the SGR 5 color
spmenu -sgr6 Set the SGR 6 color
spmenu -sgr7 Set the SGR 7 color
spmenu -sgr8 Set the SGR 8 color
spmenu -sgr9 Set the SGR 9 color
spmenu -sgr10 Set the SGR 10 color
spmenu -sgr11 Set the SGR 11 color
spmenu -sgr12 Set the SGR 12 color
spmenu -sgr13 Set the SGR 13 color
spmenu -sgr14 Set the SGR 14 color
spmenu -sgr15 Set the SGR 15 color

There are also extra arguments recognized for dmenu compatibility. These are:

spmenu -nb Set the normal background color
spmenu -nf Set the normal foreground color
spmenu -sb Set the selected background color
spmenu -sf Set the selected foreground color

4. Keybinds

See keybinds.h for a list.

5. Modes

One of the features that separate spmenu from dmenu is spmenu's different modes. As of version 0.2, there are two modes. Normal mode and Insert mode. These modes are of course similar to Vim.

Normal mode is the mode spmenu starts in unless a mode argument is specified. In normal mode, all keys perform some action, but you cannot type any actual text to filter items. This mode is used for navigation, as well as quickly selecting an item.

Insert mode is entered through (by default) pressing i in normal mode. In this mode, most keybinds do nothing. When you are in insert mode, you filter items by typing text into the field. Once you're done with insert mode, you can press Escape to enter normal mode again.

6. -p option

spmenu has a -p option, which stands for prompt. It allows you to specify text to display next to the item list. It is displayed on the left side of the spmenu window. It should be noted that the prompt is purely visual though.

7. Images

spmenu supports drawing images. This image is placed on the left side of the menu window. To use an image, pipe IMG:/path/to/image to spmenu. If you want you can specify arguments like usual. Note that you should add a Tab (\t) character after the path to the image file. Otherwise the text after will be interpreted as part of the filename and the image will not be drawn.

Any text after the Tab character will be interpreted as a regular item. In practice, drawing an image might look like this:

printf "IMG:/path/to/image\tThis is text, look at that image, isn't it awesome?\n" | spmenu

There are also a few image related arguments, such as -is, -ig, -it, -ib, -ic, -itc and -gc. Be careful with the image size (-is) argument though.

8. Colored text

spmenu supports colored text through SGR sequences. This is the same colors that you might already be using in your shell scripts. This means you can pipe practically any colored shell script straight into spmenu, no need to filter the output or anything.

A list of SGR sequences will not be provided here, but spmenu supports most color sequences. There are also a few arguments, you can override SGR colors on-the-fly using the -sgr arguments.

8.2 KiB Raw Blame History