forked from speedie/spmenu
302 lines
8.6 KiB
Groff
302 lines
8.6 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" "dynamic menu"
|
||
|
.hy
|
||
|
.SH spmenu
|
||
|
.SS 1. 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.
|
||
|
.SS 2. 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 3. Arguments
|
||
|
.IP \[bu] 2
|
||
|
spmenu -l Set line count to stdin
|
||
|
.IP \[bu] 2
|
||
|
spmenu -h Set spmenu line height to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -g Set the number of grids to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -gc 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 -p Set spmenu prompt text to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -a Enable alpha
|
||
|
.IP \[bu] 2
|
||
|
spmenu -na Disable alpha
|
||
|
.IP \[bu] 2
|
||
|
spmenu -cp Color prompt
|
||
|
.IP \[bu] 2
|
||
|
spmenu -ncp Don\[cq]t color prompt
|
||
|
.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 Offset spmenu x position by
|
||
|
.IP \[bu] 2
|
||
|
spmenu -y Offset spmenu y position by
|
||
|
.IP \[bu] 2
|
||
|
spmenu -n Preselect in the list of items
|
||
|
.IP \[bu] 2
|
||
|
spmenu -z Width of the spmenu window
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nmt Set normal mode text to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -imt Set insert mode text to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -bw Width of the border.
|
||
|
0 will disable the border
|
||
|
.IP \[bu] 2
|
||
|
spmenu -s Use case-sensitive matching
|
||
|
.IP \[bu] 2
|
||
|
spmenu -i 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 -sm Show mode indicator
|
||
|
.IP \[bu] 2
|
||
|
spmenu -smc Show match count
|
||
|
.IP \[bu] 2
|
||
|
spmenu -xrdb Load .Xresources on runtime
|
||
|
.IP \[bu] 2
|
||
|
spmenu -w Embed spmenu inside
|
||
|
.IP \[bu] 2
|
||
|
spmenu -H Specify a path to save the history to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -ig Set image gaps to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -lp Set the vertical padding
|
||
|
.IP \[bu] 2
|
||
|
spmenu -hp Set the horizontal padding
|
||
|
.IP \[bu] 2
|
||
|
spmenu -la Set the left arrow to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -ra Set the right arrow to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -is 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/window.
|
||
|
Useful for testing
|
||
|
.IP \[bu] 2
|
||
|
spmenu -v Print spmenu version to stdout
|
||
|
.IP \[bu] 2
|
||
|
spmenu -fn Set the spmenu font to
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nif Set the normal item foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nib Set the normal item background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -sif Set the selected item foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -sib Set the selected item background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -pfg Set the prompt foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -pbg Set the prompt background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -ifg Set input foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -ibg Set input background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -mbg Set the menu background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nhf Set the normal highlight foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nhb Set the normal highlight background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -shf Set the selected highlight foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -shb Set the selected highlight background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -shb Set the selected highlight background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nfg Set the foreground color for the match count
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nbg Set the background color for the match count
|
||
|
.IP \[bu] 2
|
||
|
spmenu -mfg Set the foreground color for the mode indicator
|
||
|
.IP \[bu] 2
|
||
|
spmenu -mbg Set the background color for the mode indicator
|
||
|
.IP \[bu] 2
|
||
|
spmenu -laf Set the left arrow foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -raf Set the right arrow foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -lab Set the left arrow background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -rab Set the right arrow background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -cc Set the caret color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -bc 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 -nb Set the normal background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -nf Set the normal foreground color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -sb Set the selected background color
|
||
|
.IP \[bu] 2
|
||
|
spmenu -sf Set the selected foreground color
|
||
|
.SS 4. Keybinds
|
||
|
.PP
|
||
|
See \f[V]keybinds.h\f[R] for a list.
|
||
|
.SS 5. 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 6. -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 7. 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]tThis is text, look 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 \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].
|
||
|
Be careful with the image size (-is) argument though.
|
||
|
.SS 8. 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
|
||
|
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 \f[V]-sgr\f[R] arguments.
|