spmenu/spmenu.1

.\" Automatically generated by Pandoc 3.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "spmenu" "1" "" "0.3.1" "dynamic menu"
.hy
.SH spmenu
.SS What is spmenu?
.PP
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\[cq]s dmenu which is a good more minimal
alternative to spmenu.
.PP
Unlike dmenu and the many builds out there, spmenu has features like
color support, Vim-like modes, image support, proper keybind
configuration, and more.
.PP
Most of these features can be disabled during compile time by editing
\f[V]toggle.mk\f[R].
.SS Usage
.PP
On runtime, spmenu reads from standard input (stdin).
spmenu items are separated by a newline (\f[V]\[rs]n\f[R]).
When (by default) Enter is pressed, the selected item will be piped to
stdout.
.PP
This allows things like
\f[V]printf \[dq]Apple\[rs]nOrange\[rs]nPear\[rs]n\[dq] | spmenu\f[R].
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.
.PP
On top of this, you can specify arguments to change the behavior of
spmenu.
See a list below for a list.
.SS Arguments
.PP
Miscellanious:
.IP \[bu] 2
spmenu -l, \[en]lines line - Set line count to stdin
.IP \[bu] 2
spmenu -mh, \[en]lineheight height - Set spmenu line height to height
.IP \[bu] 2
spmenu -g, \[en]columns grid - Set the number of grids to grid
.IP \[bu] 2
spmenu -gc, \[en]generate-cache - Generate image cache
.IP \[bu] 2
spmenu -ngc, \[en]no-generate-cache - Don\[cq]t generate image cache
.IP \[bu] 2
spmenu -rw, \[en]relative-width - Enable relative input width
.IP \[bu] 2
spmenu -nrw, \[en]no-relative-width - Disable relative input width
.IP \[bu] 2
spmenu -f, \[en]fast - Grabs keyboard before reading stdin
.IP \[bu] 2
spmenu -F, \[en]fuzzy - Enable fuzzy matching
.IP \[bu] 2
spmenu -NF, \[en]no-fuzzy - Disable fuzzy matching
.IP \[bu] 2
spmenu -P, \[en]password - Hide characters
.IP \[bu] 2
spmenu -Ps, \[en]password-symbol symbol - Set the password symbol to
symbol
.IP \[bu] 2
spmenu -p, \[en]prompt text - Set spmenu prompt text to text
.IP \[bu] 2
spmenu -ip, \[en]indent - Indent items to prompt width
.IP \[bu] 2
spmenu -nip, \[en]no-indent - Don\[cq]t indent items to prompt width
.IP \[bu] 2
spmenu -a, \[en]alpha - Enable alpha
.IP \[bu] 2
spmenu -na, \[en]no-alpha - Disable alpha
.IP \[bu] 2
spmenu -tp, \[en]allow-typing - Allow the user to type
.IP \[bu] 2
spmenu -nt, \[en]no-allow-typing - Don\[cq]t allow typing, the user must
select an option
.IP \[bu] 2
spmenu -x, \[en]x-position x offset - Offset spmenu x position by x
offset
.IP \[bu] 2
spmenu -y, \[en]y-position y offset - Offset spmenu y position by y
offset
.IP \[bu] 2
spmenu -n, \[en]preselect line - Preselect line in the list of items
.IP \[bu] 2
spmenu -z, \[en]width width - Width of the spmenu window
.IP \[bu] 2
spmenu -nmt, \[en]normal-mode-text text - Set normal mode text to text
.IP \[bu] 2
spmenu -imt, \[en]insert-mode-text text - Set insert mode text to text
.IP \[bu] 2
spmenu -bw, \[en]border-width width - Set width of the border to width .
0 will disable the border
.IP \[bu] 2
spmenu -so, \[en]sort - Sort matches
.IP \[bu] 2
spmenu -nso, \[en]no-sort - Don\[cq]t sort matches
.IP \[bu] 2
spmenu -pri, \[en]priority pri1,pri2,pri3 - Specify a list of items that
take priority
.IP \[bu] 2
spmenu -s, \[en]case-sensitive - Use case-sensitive matching
.IP \[bu] 2
spmenu -ns, \[en]case-insensitive - Use case-insensitive matching
.IP \[bu] 2
spmenu -nm, \[en]normal - Start spmenu in normal mode
.IP \[bu] 2
spmenu -im, \[en]insert - Start spmenu in insert mode
.IP \[bu] 2
spmenu -t, \[en]top - Position spmenu at the top of the screen
.IP \[bu] 2
spmenu -b, \[en]bottom - Position spmenu at the bottom of the screen
.IP \[bu] 2
spmenu -c, \[en]center - Position spmenu at the center of the screen
.IP \[bu] 2
spmenu -hm, \[en]hide-mode - Hide mode indicator
.IP \[bu] 2
spmenu -hmc, \[en]hide-match-count - Hide match count
.IP \[bu] 2
spmenu -hla, \[en]hide-left-arrow - Hide left arrow
.IP \[bu] 2
spmenu -hra, \[en]hide-right-arrow - Hide right arrow
.IP \[bu] 2
spmenu -hpr, \[en]hide-prompt - Hide prompt
.IP \[bu] 2
spmenu -hc, \[en]hide-cursor - Hide cursor
.IP \[bu] 2
spmenu -hhl, \[en]hide-highlighting - Hide highlight
.IP \[bu] 2
spmenu -hi, \[en]hide-image - Hide image
.IP \[bu] 2
spmenu -sm, \[en]show-mode - Show mode indicator
.IP \[bu] 2
spmenu -smc, \[en]show-match-count - Show match count
.IP \[bu] 2
spmenu -sla, \[en]show-left-arrow - Show left arrow
.IP \[bu] 2
spmenu -sra, \[en]show-right-arrow - Show right arrow
.IP \[bu] 2
spmenu -spr, \[en]show-prompt - Show prompt
.IP \[bu] 2
spmenu -sc, \[en]show-cursor - Show cursor
.IP \[bu] 2
spmenu -shl, \[en]show-highlighting - Show highlight
.IP \[bu] 2
spmenu -si, \[en]show-image - Show image
.IP \[bu] 2
spmenu -xrdb, \[en]xrdb - Load .Xresources on runtime
.IP \[bu] 2
spmenu -nxrdb, \[en]no-xrdb - Don\[cq]t load .Xresources on runtime
.IP \[bu] 2
spmenu -m, \[en]monitor monitor - Specify a monitor to run spmenu on
.IP \[bu] 2
spmenu -w, \[en]embed window id - Embed spmenu inside window id
.IP \[bu] 2
spmenu -H, \[en]hist-file hist file - Specify a path to save the history
to
.IP \[bu] 2
spmenu -ig, \[en]image-gaps gaps - Set image gaps to gaps
.IP \[bu] 2
spmenu -lp, \[en]vertical-padding padding - Set the vertical padding
.IP \[bu] 2
spmenu -hp, \[en]horizontal-padding padding - Set the horizontal padding
.IP \[bu] 2
spmenu -la, \[en]left-arrow-symbol symbol - Set the left arrow to symbol
.IP \[bu] 2
spmenu -ra, \[en]right-arrow-symbol symbol - Set the right arrow to
symbol
.IP \[bu] 2
spmenu -is, \[en]image-size size - Image size
.IP \[bu] 2
spmenu -it, \[en]image-top - Position the image at the top
.IP \[bu] 2
spmenu -ib, \[en]image-bottom - Position the image at the bottom
.IP \[bu] 2
spmenu -ic, \[en]image-center - Position the image in the center
.IP \[bu] 2
spmenu -itc, \[en]image-topcenter - Position the image in the top center
.IP \[bu] 2
spmenu -wm, \[en]managed, \[en]x11-client - Spawn spmenu as a window
manager controlled client/window.
Useful for testing
.IP \[bu] 2
spmenu -nwm, \[en]unmanaged - Don\[cq]t spawn spmenu as a window manager
controlled client/window.
Useful for testing
.IP \[bu] 2
spmenu -lcfg, \[en]load-config - Load spmenu configuration
(\[ti]/.spmenu or \[ti]/.config/spmenu/spmenurc)
.IP \[bu] 2
spmenu -ncfg, \[en]no-load-config - Don\[cq]t load spmenu configuration
(\[ti]/.spmenu or \[ti]/.config/spmenu/spmenurc)
.IP \[bu] 2
spmenu -v, \[en]version - Print spmenu version to stdout
.PP
Appearance:
.IP \[bu] 2
spmenu -fn, \[en]font font - Set the spmenu font to font
.IP \[bu] 2
spmenu -nif, \[en]normal-item-foreground color - Set the normal item
foreground color
.IP \[bu] 2
spmenu -nib, \[en]normal-item-background color - Set the normal item
background color
.IP \[bu] 2
spmenu -sif, \[en]selected-item-foreground color - Set the selected item
foreground color
.IP \[bu] 2
spmenu -sib, \[en]selected-item-background color - Set the selected item
background color
.IP \[bu] 2
spmenu -npf, \[en]normal-item-priority-foreground color - Set the normal
item (high priority) foreground color
.IP \[bu] 2
spmenu -npb, \[en]normal-item-priority-background color - Set the normal
item (high priority) background color
.IP \[bu] 2
spmenu -spf, \[en]selected-item-priority-foreground color - Set the
selected item (high priority) foreground color
.IP \[bu] 2
spmenu -spb, \[en]selected-item-priority-background color - Set the
selected item (high priority) background color
.IP \[bu] 2
spmenu -pfg, \[en]prompt-foreground color - Set the prompt foreground
color
.IP \[bu] 2
spmenu -pbg, \[en]prompt-background color - Set the prompt background
color
.IP \[bu] 2
spmenu -ifg, \[en]input-foreground color - Set input foreground color
.IP \[bu] 2
spmenu -ibg, \[en]input-background color - Set input background color
.IP \[bu] 2
spmenu -mnbg, \[en]menu-background color - Set the menu background color
.IP \[bu] 2
spmenu -nhf, \[en]normal-highlight-foreground color - Set the normal
highlight foreground color
.IP \[bu] 2
spmenu -nhb, \[en]normal-highlight-background color - Set the normal
highlight background color
.IP \[bu] 2
spmenu -shf, \[en]selected-highlight-foreground color - Set the selected
highlight foreground color
.IP \[bu] 2
spmenu -shb, \[en]selected-highlight-background color - Set the selected
highlight background color
.IP \[bu] 2
spmenu -nfg, \[en]number-foreground color - Set the foreground color for
the match count
.IP \[bu] 2
spmenu -nbg, \[en]number-background color - Set the background color for
the match count
.IP \[bu] 2
spmenu -mfg, \[en]mode-foreground color - Set the foreground color for
the mode indicator
.IP \[bu] 2
spmenu -mbg, \[en]mode-background color - Set the background color for
the mode indicator
.IP \[bu] 2
spmenu -laf, \[en]left-arrow-foreground color - Set the left arrow
foreground color
.IP \[bu] 2
spmenu -raf, \[en]right-arrow-foreground color - Set the right arrow
foreground color
.IP \[bu] 2
spmenu -lab, \[en]left-arrow-background color - Set the left arrow
background color
.IP \[bu] 2
spmenu -rab, \[en]right-arrow-background color - Set the right arrow
background color
.IP \[bu] 2
spmenu -cc, \[en]caret-foreground color - Set the caret color
.IP \[bu] 2
spmenu -bc, \[en]border-background color - Set the border color
.IP \[bu] 2
spmenu -sgr0, \[en]sgr0 color - Set the SGR 0 color
.IP \[bu] 2
spmenu -sgr1, \[en]sgr1 color - Set the SGR 1 color
.IP \[bu] 2
spmenu -sgr2, \[en]sgr2 color - Set the SGR 2 color
.IP \[bu] 2
spmenu -sgr3, \[en]sgr3 color - Set the SGR 3 color
.IP \[bu] 2
spmenu -sgr4, \[en]sgr4 color - Set the SGR 4 color
.IP \[bu] 2
spmenu -sgr5, \[en]sgr5 color - Set the SGR 5 color
.IP \[bu] 2
spmenu -sgr6, \[en]sgr6 color - Set the SGR 6 color
.IP \[bu] 2
spmenu -sgr7, \[en]sgr7 color - Set the SGR 7 color
.IP \[bu] 2
spmenu -sgr8, \[en]sgr8 color - Set the SGR 8 color
.IP \[bu] 2
spmenu -sgr9, \[en]sgr9 color - Set the SGR 9 color
.IP \[bu] 2
spmenu -sgr10, \[en]sgr10 color - Set the SGR 10 color
.IP \[bu] 2
spmenu -sgr11, \[en]sgr11 color - Set the SGR 11 color
.IP \[bu] 2
spmenu -sgr12, \[en]sgr12 color - Set the SGR 12 color
.IP \[bu] 2
spmenu -sgr13, \[en]sgr13 color - Set the SGR 13 color
.IP \[bu] 2
spmenu -sgr14, \[en]sgr14 color - Set the SGR 14 color
.IP \[bu] 2
spmenu -sgr15, \[en]sgr15 color - Set the SGR 15 color
.PP
There are also extra arguments recognized for dmenu compatibility.
These are:
.IP \[bu] 2
spmenu -S - Don\[cq]t sort matches
.IP \[bu] 2
spmenu -i - Use case-insensitive matching
.IP \[bu] 2
spmenu -nb color - Set the normal background color
.IP \[bu] 2
spmenu -nf color - Set the normal foreground color
.IP \[bu] 2
spmenu -sb color - Set the selected background color
.IP \[bu] 2
spmenu -sf color - Set the selected foreground color
.SS Keybinds
.PP
See \f[V]keybinds.h\f[R] for a list.
.SS Modes
.PP
One of the features that separate spmenu from dmenu is spmenu\[cq]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.
.PP
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.
.PP
Insert mode is entered through (by default) pressing \f[V]i\f[R] 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\[cq]re done with insert mode, you can press Escape to enter
normal mode again.
.SS -p option
.PP
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.
.SS Images
.PP
spmenu supports drawing images.
This image is placed on the left side of the menu window.
To use an image, pipe \f[V]IMG:/path/to/image\f[R] to spmenu.
If you want you can specify arguments like usual.
Note that you should add a Tab (\f[V]\[rs]t\f[R]) 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.
.PP
Any text after the Tab character will be interpreted as a regular item.
In practice, drawing an image might look like this:
.PP
\f[V]printf \[dq]IMG:/path/to/image\[rs]tLook at that image, isn\[aq]t it awesome?\[rs]n\[dq] | spmenu\f[R]
.PP
There are also a few image related arguments, such as:
.PP
\f[V]-is\f[R], \f[V]-ig\f[R], \f[V]-it\f[R], \f[V]-ib\f[R],
\f[V]-ic\f[R], \f[V]-itc\f[R] and \f[V]-gc\f[R].
.SS Colored text
.PP
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.
.PP
For 256 color support to work, you must add to the array.
See \f[V]libs/color.h\f[R] if you want this.
.PP
See `SGR sequences' for more information.
.SS SGR sequences
.PP
A basic supported SGR sequence looks like this: \f[V]\[rs]033[X;YZm\f[R]
.PP
Here, X specifies if you want normal or bright colors.
Y specifies if you want background or foreground.
Z specifies the color number.
.PP
Foreground colors: \f[V]30\f[R] through \f[V]37\f[R] Background colors:
\f[V]40\f[R] through \f[V]47\f[R] Reset: \f[V]0\f[R]
.PP
NOTE: \f[V];\f[R] is a separator, and in this example it separates the
color number and normal/bright.
\[rs]033 may also be written as \f[V]\[ha]]\f[R] or simply
\f[V]ESC\f[R].
.PP
spmenu supports most color sequences, although not true color by default
(unless -sgr arguments are used).
.PP
There are a few arguments, you can override SGR colors on-the-fly using
the \f[V]-sgrX\f[R] arguments.
See `Arguments' for more information.
.SS Configuration
.PP
spmenu has .Xresources (xrdb) support built in.
It reads the xrdb (.Xresources database) on runtime.
You may disable it by passing -nxrdb, or enable it by padding -xrdb.
.PP
spmenu loads \f[V]\[ti]/.config/spmenu/spmenurc\f[R] or alternatively if
you\[cq]re old fashioned, \f[V]\[ti]/.spmenurc\f[R].
This requires that \f[V]xrdb\f[R] is available on your operating system.
.PP
You can also use wildcards (such as \f[V]*\f[R]) to achieve a global
colorscheme.
Programs like \f[V]pywal\f[R] do this.