forked from speedie/spmenu
400 lines
12 KiB
Groff
400 lines
12 KiB
Groff
.\" Automatically generated by Pandoc 3.0.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.2.2" "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
|
|
.IP \[bu] 2
|
|
spmenu -l line - Set line count to stdin
|
|
.IP \[bu] 2
|
|
spmenu -mh height - Set spmenu line height to height
|
|
.IP \[bu] 2
|
|
spmenu -g grid - Set the number of grids to grid
|
|
.IP \[bu] 2
|
|
spmenu -gc - Generate image cache
|
|
.IP \[bu] 2
|
|
spmenu -ngc - Don\[cq]t generate image cache
|
|
.IP \[bu] 2
|
|
spmenu -rw - Enable relative input width
|
|
.IP \[bu] 2
|
|
spmenu -nrw - Disable relative input width
|
|
.IP \[bu] 2
|
|
spmenu -f - Grabs keyboard before reading stdin
|
|
.IP \[bu] 2
|
|
spmenu -F - Enable fuzzy matching
|
|
.IP \[bu] 2
|
|
spmenu -P - Hide characters
|
|
.IP \[bu] 2
|
|
spmenu -Ps symbol - Set the password symbol to symbol
|
|
.IP \[bu] 2
|
|
spmenu -p text - Set spmenu prompt text to text
|
|
.IP \[bu] 2
|
|
spmenu -ip - Indent items to prompt width
|
|
.IP \[bu] 2
|
|
spmenu -nip - Don\[cq]t indent items to prompt width
|
|
.IP \[bu] 2
|
|
spmenu -a - Enable alpha
|
|
.IP \[bu] 2
|
|
spmenu -na - Disable alpha
|
|
.IP \[bu] 2
|
|
spmenu -tp - Allow the user to type
|
|
.IP \[bu] 2
|
|
spmenu -nt - Don\[cq]t allow typing, the user must select an option
|
|
.IP \[bu] 2
|
|
spmenu -x x offset - Offset spmenu x position by x offset
|
|
.IP \[bu] 2
|
|
spmenu -y y offset - Offset spmenu y position by y offset
|
|
.IP \[bu] 2
|
|
spmenu -n line - Preselect line in the list of items
|
|
.IP \[bu] 2
|
|
spmenu -z width - Width of the spmenu window
|
|
.IP \[bu] 2
|
|
spmenu -nmt text - Set normal mode text to text
|
|
.IP \[bu] 2
|
|
spmenu -imt text - Set insert mode text to text
|
|
.IP \[bu] 2
|
|
spmenu -bw - Width of the border.
|
|
0 will disable the border
|
|
.IP \[bu] 2
|
|
spmenu -so - Sort matches
|
|
.IP \[bu] 2
|
|
spmenu -nso - Don\[cq]t sort matches
|
|
.IP \[bu] 2
|
|
spmenu -pri priority - Specify a list of items that take priority
|
|
.IP \[bu] 2
|
|
spmenu -s - Use case-sensitive matching
|
|
.IP \[bu] 2
|
|
spmenu -ns - Use case-insensitive matching
|
|
.IP \[bu] 2
|
|
spmenu -nm - Start spmenu in normal mode
|
|
.IP \[bu] 2
|
|
spmenu -im - Start spmenu in insert mode
|
|
.IP \[bu] 2
|
|
spmenu -t - Position spmenu at the top of the screen
|
|
.IP \[bu] 2
|
|
spmenu -b - Position spmenu at the bottom of the screen
|
|
.IP \[bu] 2
|
|
spmenu -c - Position spmenu at the center of the screen
|
|
.IP \[bu] 2
|
|
spmenu -hm - Hide mode indicator
|
|
.IP \[bu] 2
|
|
spmenu -hmc - Hide match count
|
|
.IP \[bu] 2
|
|
spmenu -hla - Hide left arrow
|
|
.IP \[bu] 2
|
|
spmenu -hra - Hide right arrow
|
|
.IP \[bu] 2
|
|
spmenu -hpr - Hide prompt
|
|
.IP \[bu] 2
|
|
spmenu -hc - Hide cursor
|
|
.IP \[bu] 2
|
|
spmenu -hhl - Hide highlight
|
|
.IP \[bu] 2
|
|
spmenu -hi - Hide image
|
|
.IP \[bu] 2
|
|
spmenu -sm - Show mode indicator
|
|
.IP \[bu] 2
|
|
spmenu -smc - Show match count
|
|
.IP \[bu] 2
|
|
spmenu -sla - Show left arrow
|
|
.IP \[bu] 2
|
|
spmenu -sra - Show right arrow
|
|
.IP \[bu] 2
|
|
spmenu -spr - Show prompt
|
|
.IP \[bu] 2
|
|
spmenu -sc - Show cursor
|
|
.IP \[bu] 2
|
|
spmenu -shl - Show highlight
|
|
.IP \[bu] 2
|
|
spmenu -si - Show image
|
|
.IP \[bu] 2
|
|
spmenu -xrdb - Load .Xresources on runtime
|
|
.IP \[bu] 2
|
|
spmenu -nxrdb - Don\[cq]t load .Xresources on runtime
|
|
.IP \[bu] 2
|
|
spmenu -m monitor - Specify a monitor to run spmenu on
|
|
.IP \[bu] 2
|
|
spmenu -w window id - Embed spmenu inside window id
|
|
.IP \[bu] 2
|
|
spmenu -H hist file - Specify a path to save the history to
|
|
.IP \[bu] 2
|
|
spmenu -ig gaps - Set image gaps to gaps
|
|
.IP \[bu] 2
|
|
spmenu -lp padding - Set the vertical padding
|
|
.IP \[bu] 2
|
|
spmenu -hp padding - Set the horizontal padding
|
|
.IP \[bu] 2
|
|
spmenu -la symbol - Set the left arrow to symbol
|
|
.IP \[bu] 2
|
|
spmenu -ra symbol - Set the right arrow to symbol
|
|
.IP \[bu] 2
|
|
spmenu -is size - Image size
|
|
.IP \[bu] 2
|
|
spmenu -it - Position the image at the top
|
|
.IP \[bu] 2
|
|
spmenu -ib - Position the image at the bottom
|
|
.IP \[bu] 2
|
|
spmenu -ic - Position the image in the center
|
|
.IP \[bu] 2
|
|
spmenu -itc - Position the image in the top center
|
|
.IP \[bu] 2
|
|
spmenu -wm - Spawn spmenu as a window manager controlled client
|
|
.IP \[bu] 2
|
|
spmenu -nwm - Don\[cq]t spawn spmenu as a window manager controlled
|
|
client
|
|
.IP \[bu] 2
|
|
spmenu -lcfg - Load spmenu configuration (\[ti]/.spmenu or
|
|
\[ti]/.config/spmenu/spmenurc)
|
|
.IP \[bu] 2
|
|
spmenu -ncfg - Don\[cq]t load spmenu configuration (\[ti]/.spmenu or
|
|
\[ti]/.config/spmenu/spmenurc)
|
|
.IP \[bu] 2
|
|
spmenu -v - Print spmenu version to stdout
|
|
.IP \[bu] 2
|
|
spmenu -fn font - Set the spmenu font to font
|
|
.IP \[bu] 2
|
|
spmenu -nif color - Set the normal item foreground color
|
|
.IP \[bu] 2
|
|
spmenu -nib color - Set the normal item background color
|
|
.IP \[bu] 2
|
|
spmenu -sif color - Set the selected item foreground color
|
|
.IP \[bu] 2
|
|
spmenu -sib color - Set the selected item background color
|
|
.IP \[bu] 2
|
|
spmenu -npf color - Set the normal item (high priority) foreground color
|
|
.IP \[bu] 2
|
|
spmenu -npb color - Set the normal item (high priority) background color
|
|
.IP \[bu] 2
|
|
spmenu -spf color - Set the selected item (high priority) foreground
|
|
color
|
|
.IP \[bu] 2
|
|
spmenu -spb color - Set the selected item (high priority) background
|
|
color
|
|
.IP \[bu] 2
|
|
spmenu -pfg color - Set the prompt foreground color
|
|
.IP \[bu] 2
|
|
spmenu -pbg color - Set the prompt background color
|
|
.IP \[bu] 2
|
|
spmenu -ifg color - Set input foreground color
|
|
.IP \[bu] 2
|
|
spmenu -ibg color - Set input background color
|
|
.IP \[bu] 2
|
|
spmenu -mbg color - Set the menu background color
|
|
.IP \[bu] 2
|
|
spmenu -nhf color - Set the normal highlight foreground color
|
|
.IP \[bu] 2
|
|
spmenu -nhb color - Set the normal highlight background color
|
|
.IP \[bu] 2
|
|
spmenu -shf color - Set the selected highlight foreground color
|
|
.IP \[bu] 2
|
|
spmenu -shb color - Set the selected highlight background color
|
|
.IP \[bu] 2
|
|
spmenu -shb color - Set the selected highlight background color
|
|
.IP \[bu] 2
|
|
spmenu -nfg color - Set the foreground color for the match count
|
|
.IP \[bu] 2
|
|
spmenu -nbg color - Set the background color for the match count
|
|
.IP \[bu] 2
|
|
spmenu -mfg color - Set the foreground color for the mode indicator
|
|
.IP \[bu] 2
|
|
spmenu -mbg color - Set the background color for the mode indicator
|
|
.IP \[bu] 2
|
|
spmenu -laf color - Set the left arrow foreground color
|
|
.IP \[bu] 2
|
|
spmenu -raf color - Set the right arrow foreground color
|
|
.IP \[bu] 2
|
|
spmenu -lab color - Set the left arrow background color
|
|
.IP \[bu] 2
|
|
spmenu -rab color - Set the right arrow background color
|
|
.IP \[bu] 2
|
|
spmenu -cc color - Set the caret color
|
|
.IP \[bu] 2
|
|
spmenu -bc color - Set the border color
|
|
.IP \[bu] 2
|
|
spmenu -sgr0 - Set the SGR 0 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr1 - Set the SGR 1 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr2 - Set the SGR 2 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr3 - Set the SGR 3 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr4 - Set the SGR 4 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr5 - Set the SGR 5 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr6 - Set the SGR 6 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr7 - Set the SGR 7 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr8 - Set the SGR 8 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr9 - Set the SGR 9 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr10 - Set the SGR 10 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr11 - Set the SGR 11 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr12 - Set the SGR 12 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr13 - Set the SGR 13 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr14 - Set the SGR 14 color
|
|
.IP \[bu] 2
|
|
spmenu -sgr15 - Set the SGR 15 color
|
|
.PP
|
|
There are also extra arguments recognized for dmenu compatibility.
|
|
These are:
|
|
.IP \[bu] 2
|
|
spmenu -i - Use case-insensitive matching
|
|
.IP \[bu] 2
|
|
spmenu -S - Don\[cq]t sort matches
|
|
.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.
|