.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "bemenu" "1" "2024-03-09"
.PP
.SH NAME
.PP
\fBbemenu\fR - dynamic menu inspired by \fBdmenu\fR(1)
.PP
.SH SYNOPSIS
.PP
\fBbemenu\fR [\fB-hCiKTvwx\fR] [\fB-I\fR <\fIindex\fR>] [\fB-l\fR <\fIlines\fR>] [\fB-P\fR <\fIprefix\fR>]
.RS 4
[\fB-p\fR <\fIprompt\fR>] [\fB--ifne\fR] [\fB--scrollbar\fR \fInone\fR|\fIalways\fR|\fIautohide\fR]
[\fB--binding\fR \fIvim\fR] [\fB--fork\fR] [\fIbackend_options\fR]
.PP
.RE
\fBbemenu-run\fR [\fB-hCiKTvwx\fR] [\fB-I\fR <\fIindex\fR>] [\fB-l\fR <\fIlines\fR>] [\fB-P\fR <\fIprefix\fR>]
.RS 4
[\fB-p\fR <\fIprompt\fR>] [\fB--ifne\fR] [\fB--scrollbar\fR \fInone\fR|\fIalways\fR|\fIautohide\fR]
[\fB--binding\fR \fIvim\fR] [\fB--fork\fR] [\fB--no-exec\fR] [\fIbackend-options\fR]
.PP
.RE
.SH DESCRIPTION
.PP
\fBbemenu\fR is a dynamic menu for \fBtty\fR(4) (using \fBncurses\fR(3)), X11 and Wayland,
inspired by \fBdmenu\fR(1).\&
.PP
It reads a list of newline-separated items from standard input and then presents
them as a list, where the user can select one or more of them.\& When pressing
\fB<carriage-return>\fR, the selected items are printed to standard output (one per
line) and \fBbemenu\fR exits.\&
.PP
Entering text will filter the items to those that match the input.\& If the number
of items exceeds the size of the list, the items will be paginated.\&
.PP
\fBbemenu-run\fR is a special-case invocation of \fBbemenu\fR, where the input is the
list of executables under PATH and the selected items are executed.\&
.PP
.SH OPTIONS
.PP
\fB-h, --help\fR
.RS 4
Print a help message to standard output and exit.\&
.PP
.RE
\fB-C, --no-cursor\fR
.RS 4
Disable all cursor events.\&
.PP
.RE
\fB-I, --index\fR <\fIindex\fR>
.RS 4
Highlight the item at \fIindex\fR at the start.\& Indices start at 0.\& By
default, the first item is highlighted.\&
.PP
.RE
\fB-i, --ignorecase\fR
.RS 4
Filter items case-insensitively.\&
.PP
.RE
\fB-K, --no-keyboard\fR
.RS 4
Disable all keyboard events.\&
.PP
.RE
\fB-l, --list\fR "<\fInumber\fR> \fIdown\fR|\fIup\fR"
.RS 4
List items vertically \fIdown\fR or \fIup\fR with the given \fInumber\fR of lines.\&
.PP
.RE
\fB-P, --prefix\fR <\fIprefix\fR>
.RS 4
Display \fIprefix\fR before the highlighted item in a vertical list.\&
.PP
.RE
\fB-p, --prompt\fR <\fIprompt\fR>
.RS 4
Defines the \fIprompt\fR text to be displayed to the left of the input
field.\& Defaults to ‘bemenu’.\&
.PP
.RE
\fB-s, --no-spacing\fR
.RS 4
Disable the title spacing on entries.\&
.PP
.RE
\fB-T, --no-touch\fR
.RS 4
Disable all touch events.\&
.PP
.RE
\fB-v, --version\fR
.RS 4
Print the \fBbemenu\fR version number to standard output and exit.\&
.PP
.RE
\fB-w, --wrap\fR
.RS 4
Advancing past the end of the list returns you to the start.\&
.PP
.RE
\fB-x, --password\fR \fInone\fR|\fIhide\fR|\fIindicator\fR
.RS 4
Specify how the filter text should be displayed:
.RE
.TS
allbox;l lx
l lx
l lx.
T{
\fBnone\fR
T}	T{
Display the input (the default).\&
T}
T{
\fBhide\fR
T}	T{
Do not display any input.\&
T}
T{
\fBindicator\fR
T}	T{
Replace input with asterisks.\&
T}
.TE
.sp 1
\fB--fixed-height\fR
.RS 4
Prevent the display from changing height on filter.\&
.PP
.RE
\fB--accept-single\fR
.RS 4
Immediately return if there is only one item.\&
.PP
.RE
\fB--auto-select\fR
.RS 4
When one entry is left, automatically select it.\&
.PP
.RE
\fB--binding\fR
.RS 4
Use alternative key bindings.\& Available options: vim
.PP
.RE
\fB--fork\fR
.RS 4
Always \fBfork\fR(2) before executing the selections.\& Disabled by default
when using the terminal backend.\&
.PP
.RE
\fB--ifne\fR
.RS 4
Only display menu if there are items.\&
.PP
.RE
\fB--single-instance\fR
.RS 4
Force a single menu instance.\&
.PP
.RE
\fB--no-exec\fR
.RS 4
Print the selected items to standard output instead of executing them.\&
.PP
.RE
\fB--scrollbar\fR \fInone\fR|\fIalways\fR|\fIautohide\fR
.RS 4
Specify when to show a scrollbar for vertical lists:
.RE
.TS
allbox;l lx
l lx
l lx.
T{
\fBnone\fR
T}	T{
Never display a scrollbar (the default).\&
T}
T{
\fBalways\fR
T}	T{
Always display a scrollbar.\&
T}
T{
\fBautohide\fR
T}	T{
Only display a scrollbar when the number of items exceeds the number of lines.\&
T}
.TE
.sp 1
\fB-e, --vim-esc-exits\fR
.RS 4
Exit bemenu when pressing escape in normal mode for vim bindings.\&
.PP
.RE
\fB-N, --vim-normal-mode\fR
.RS 4
Start in normal mode for vim bindings.\&
.PP
.RE
\fB-F, --filter\fR
.RS 4
Filter items for a given string before showing the menu.\&
Affects \fB--ifne\fR and \fB--accept-single\fR
.PP
.RE
.SS Backend options
.PP
These options are only available on backends specified in the parentheses:
.PP
\fB-b, --bottom\fR (Wayland, X11)
.RS 4
The list will appear at the bottom of the screen.\&
.PP
.RE
\fB-c, --center\fR (Wayland, X11)
.RS 4
The list will appear at the center of the screen.\& (wx)
.PP
.RE
\fB-f, --grab\fR (Wayland, X11)
.RS 4
Show the \fBbemenu\fR window whilst reading the items.\&
.PP
.RE
\fB-B, --border\fR (Wayland, X11)
.RS 4
Specify the width of the border in pixels around the menu.\&
.PP
.RE
\fB--bdr\fR (Wayland, X11)
.RS 4
Specify the border color.\&
.PP
.RE
\fB-R, --border-radius\fR (Wayland, X11)
.RS 4
Specify the radius of the border around the menu (0 = no curved borders).\&
.PP
.RE
\fB-H, --line-height\fR <\fIheight\fR> (Wayland, X11)
.RS 4
Specify the \fIheight\fR in point size to make each entry.\&
.PP
.RE
\fB--ch\fR (Wayland, X11)
.RS 4
Specify the height of the cursor (0 = scales with line height).\&
.PP
.RE
\fB--cw\fR (Wayland, X11)
.RS 4
Specify the width of the cursor.\&
.PP
.RE
\fB-m, --monitor\fR <\fIindex\fR> (Wayland, X11)
.RS 4
Specify the monitor \fIindex\fR where the list should appear.\& Monitor
indices start at zero.\& The interpretation of the given argument depends
on the utilized backend.\& With X11 and Wayland, a value of ‘-1’ or
\fBfocused\fR indicates that the current monitor should be used (the
default).\& With Wayland, the \fIindex\fR should be a string specifying a
specific monitor name.\& The value ‘-2’ or \fBall\fR indicates that the list
should appear on all monitors.\&
.PP
.RE
\fB-n, --no-overlap\fR (Wayland)
.RS 4
Set the \fBbemenu\fR window to be on top of any other panels.\&
.PP
.RE
\fB-M, --margin\fR <\fImargin\fR> (Wayland, X11)
.RS 4
Specify the \fImargin\fR (empty space) in pixels to leave between menu and
vertical view borders.\& \fBbemenu\fR will reduce it'\&s size to fit in space
between gaps.\&
.PP
.RE
\fB--hp\fR (Wayland, X11)
.RS 4
Specify the horizontal padding for the entries in single line mode.\&
.PP
.RE
\fB-W, --width-factor\fR <\fIfactor\fR> (Wayland, X11)
.RS 4
Specify the relative width factor as a floating point number.\& It makes
sense to set it between 0 and 1 to define how much of the screen width
\fBbemenu\fR will use.\& However, \fBbemenu\fR will still respect \fImargin\fR, so if
resulting size is greater than space between gaps, \fBbemenu\fR will ignore
\fIfactor\fR and use available space instead.\&
.PP
.RE
\fB--fn\fR <\fIname\fR [\fIsize\fR]> (Wayland, X11)
.RS 4
Specify the font family \fIname\fR and \fIsize\fR to be used.\& For more options,
consult the \fIPango Reference Manual\fR for
\fBpango_font_description_from_string\fR().\&
.PP
.RE
The following options control the colours for various parts of the list
for the Wayland and X11 backends.\& Each takes an argument in the form of:
.PP
.RS 4
\fB#\fR\fIRGB\fR[\fIA\fR]
.PP
.RE
where \fIR\fR, \fIG\fR, \fIB\fR and \fIA\fR are hexadecimal integers from 00–FF that
control the red, green, blue and alpha-transparency channels.\&
.PP
\fB--tb\fR <\fIcolor\fR>	Title background.\&
.PP
\fB--tf\fR <\fIcolor\fR>	Title foreground.\&
.PP
\fB--fb\fR <\fIcolor\fR>	Filter background.\&
.PP
\fB--ff\fR <\fIcolor\fR>	Filter foreground
.PP
\fB--cb\fR <\fIcolor\fR>	Cursor background.\&
.PP
\fB--cf\fR <\fIcolor\fR>	Cursor foreground
.PP
\fB--nb\fR <\fIcolor\fR>	Normal background.\&
.PP
\fB--nf\fR <\fIcolor\fR>	Normal foreground.\&
.PP
\fB--hb\fR <\fIcolor\fR>	Highlighted background.\&
.PP
\fB--hf\fR <\fIcolor\fR>	Highlighted foreground.\&
.PP
\fB--fbb\fR <\fIcolor\fR>	Feedback background.\&
.PP
\fB--fbf\fR <\fIcolor\fR>	Feedback foreground.\&
.PP
\fB--sb\fR <\fIcolor\fR>	Selected background.\&
.PP
\fB--sf\fR <\fIcolor\fR>	Selected foreground.\&
.PP
\fB--ab\fR <\fIcolor\fR>	Alternating background color.\&
.PP
\fB--af\fR <\fIcolor\fR>	Alternating foreground color.\&
.PP
\fB--scb\fR <\fIcolor\fR>	Scrollbar background.\&
.PP
\fB--scf\fR <\fIcolor\fR>	Scrollbar foreground.\&
.PP
.SH KEYBOARD COMMANDS
.PP
\fBbemenu\fR supports keyboard commands to move around the list and edit the filter.\&
In the following examples, \fBC-x\fR means \fB<control-x>\fR, \fBM-x\fR means \fB<alt-x>\fR and
\fBS-x\fR means \fB<shift-x>\fR:
.PP
\fB<cursor-up>, S-<cursor-left>, C-p, M-j, M-l\fR
.RS 4
Highlight the previous item.\&
.PP
.RE
\fB<cursor-down>, <tab>, C-n, M-h, M-k\fR
.RS 4
Highlight the next item.\&
.PP
.RE
\fBPageUp, M-v, M-u\fR
.RS 4
Show the previous page of items, preserving the offset of the currently
highlighted item, if possible.\&
.PP
.RE
\fBPageDown, C-v, M-d\fR
.RS 4
Show the next page of items, preserving the offset of the currently
highlighted item, if possible.\&
.PP
.RE
\fBS-M-<, S-PageUp\fR
.RS 4
Highlight the first item in the list.\&
.PP
.RE
\fBS-M->, S-PageDown\fR
.RS 4
Highlight the last item in the list.\&
.PP
.RE
\fBS-<tab>\fR
.RS 4
Copy the highlighted item to the filter.\&
.PP
.RE
\fB<escape>, C-g\fR
.RS 4
Terminate \fBbemenu\fR without printing items.\&
.PP
.RE
\fBC-<carriage-return>, C-m\fR
.RS 4
Print selected items and the currently highlighted one, and exit.\& Items
are printed in the order they were selected, with the currently
highlighted item printed last.\&
.PP
.RE
\fBS-<carriage-return>, Insert\fR
.RS 4
Print the filter text to standard output and exit.\&
.PP
.RE
\fBC-b, C-l, <cursor-left>\fR
.RS 4
Move cursor left.\&
.PP
.RE
\fBC-f, <cursor-right>\fR
.RS 4
Move cursor right.\&
.PP
.RE
\fBC-a, Home\fR
.RS 4
Move cursor to the start.\&
.PP
.RE
\fBC-e, End\fR
.RS 4
Move cursor to the end.\&
.PP
.RE
\fB<backspace> C-h\fR
.RS 4
Remove character before the cursor.\&
.PP
.RE
\fB<delete>\fR
.RS 4
Remove character at the cursor.\&
.PP
.RE
\fBC-u, S-<delete>\fR
.RS 4
Remove all characters before the cursor.\&
.PP
.RE
\fBC-k\fR
.RS 4
Remove all characters after the cursor.\&
.PP
.RE
\fBC-w\fR
.RS 4
Clear the filter.\&
.PP
.RE
\fBC-y\fR
.RS 4
Paste the clipboard.\&
.PP
.RE
\fBM-[1-9]\fR
.RS 4
Print selected items and exit with a custom error code 10 (\fBM-1\fR)
through 18 (\fBM-9\fR), see \fIEXIT STATUS\fR.\&
.PP
.RE
\fBM-0\fR
.RS 4
Print selected items and exit with the custom error code 19, see \fIEXIT
STATUS\fR.\&
.PP
.RE
.SS Vim bindings
.PP
\fBbemenu\fR uses vim-like modal entry if invoked with \fB--binding vim\fR.\&
These bindings roughly emulate insert and normal vim modes.\&
The initial mode is insert mode, unless \fB--vim-normal-mode\fR is specified.\&
.PP
In insert mode, all keys function as described above except for the following:
.PP
\fB<escape>\fR
.RS 4
Switch to normal mode.\&
.PP
.RE
In normal mode, only the following keys have meaning:
.PP
\fBq\fR
.RS 4
Terminate \fBbemenu\fR without printing items.\&
.PP
.RE
\fBi\fR
.RS 4
Enter insert mode.\&
.PP
.RE
\fBI\fR
.RS 4
Enter insert mode after moving the cursor to the start.\&
.PP
.RE
\fBa\fR
.RS 4
Enter insert mode after moving the cursor right.\&
.PP
.RE
\fBA\fR
.RS 4
Enter insert mode after moving the cursor to the end.\&
.PP
.RE
\fBcc\fR
.RS 4
Enter insert mode after clearing the filter.\&
.PP
.RE
\fBcw\fR
.RS 4
Enter insert mode after removing all characters between the cursor and
the start of the next word.\&
.PP
.RE
\fBcb\fR
.RS 4
Enter insert mode after removing all characters between the start of
the word and the cursor.\&
.PP
.RE
\fBc$\fR
.RS 4
Enter insert mode after removing all characters after the cursor.\&
.PP
.RE
\fBc0\fR
.RS 4
Enter insert mode after removing all characters before the cursor.\&
.PP
.RE
\fBn\fR, \fBj\fR
.RS 4
Highlight the next item.\&
.PP
.RE
\fBp\fR, \fBk\fR
.RS 4
Highlight the previous item.\&
.PP
.RE
\fBgg\fR
.RS 4
Highlight the first item in the list.\&
.PP
.RE
\fBG\fR
.RS 4
Highlight the last item in the list.\&
.PP
.RE
\fBH\fR
.RS 4
Highlight the first visible item.\&
.PP
.RE
\fBM\fR
.RS 4
Highlight the middle-most visible item.\&
.PP
.RE
\fBL\fR
.RS 4
Highlight the last visible item.\&
.PP
.RE
\fBv\fR
.RS 4
Select or deselect the higlighted item.\&
.PP
.RE
\fBF\fR
.RS 4
Show the next page of items.\&
.PP
.RE
\fBB\fR
.RS 4
Show the previous page of items.\&
.PP
.RE
\fBh\fR
.RS 4
Move cursor left.\&
.PP
.RE
\fBl\fR
.RS 4
Move cursor right.\&
.PP
.RE
\fB0\fR
.RS 4
Move cursor to the start.\&
.PP
.RE
\fB$\fR
.RS 4
Move cursor to the end.\&
.PP
.RE
\fBw\fR
.RS 4
Move cursor forward to the start of a word.\&
.PP
.RE
\fBb\fR
.RS 4
Move cursor backward to the start of a word.\&
.PP
.RE
\fBe\fR
.RS 4
Move cursor forward to the end of a word.\&
.PP
.RE
\fBx\fR
.RS 4
Remove character at the cursor.\&
.PP
.RE
\fBX\fR
.RS 4
Remove character before the cursor.\&
.PP
.RE
\fBdw\fR
.RS 4
Remove all characters between the cursor and start of the next word.\&
.PP
.RE
\fBdb\fR
.RS 4
Remove all characters between the start of the word and the cursor.\&
.PP
.RE
\fBd$\fR
.RS 4
Remove all characters after the cursor.\&
.PP
.RE
\fBd0\fR
.RS 4
Remove all characters before the cursor.\&
.PP
.RE
\fBdd\fR
.RS 4
Clear the filter.\&
.PP
.RE
.SH ENVIRONMENT
.PP
.TS
allbox;l lx
l lx
l lx
l lx
l lx.
T{
\fBBEMENU_OPTS\fR
T}	T{
An alternative way to pass command line arguments to \fBbemenu\fR.\&
T}
T{
\fBBEMENU_BACKEND\fR
T}	T{
Force a backend to be used.\& If empty, one of the GUI backends (Wayland, X11) will be selected automatically.\& The accepted values are \fBcurses\fR, \fBwayland\fR and \fBx11\fR.\&
T}
T{
\fBBEMENU_RENDERER\fR
T}	T{
Force a backend by loading its shared object from the set value.\&
T}
T{
\fBBEMENU_RENDERERS\fR
T}	T{
Override the backend search path to the set value.\& Defaults to \fI/usr/lib/bemenu\fR.\&
T}
T{
\fBBEMENU_SCALE\fR
T}	T{
Override the rendering scale factor for the GUI backends.\&
T}
.TE
.sp 1
.SH EXIT STATUS
.PP
\fB0\fR
.RS 4
bemenu ran successfully.\&
.PP
.RE
\fB1\fR
.RS 4
The user exited without selecting, or bemenu encountered an error.\&
.PP
.RE
\fB10-19\fR
.RS 4
The user specified a custom exit code with \fBM-[0-9]\fR, see \fIKEYBOARD
COMMANDS\fR.\&
.PP
.RE
.SH SEE ALSO
.PP
\fBdmenu\fR(1), \fBfork\fR(2), \fBncurses\fR(3), \fBtty\fR(4)
.PP
\fIPango Reference Manual\fR, https://developer.\&gnome.\&org/pango/1.\&46/, August 20,
2020, Fonts — pango_font_description_from_string().\&
.PP
.SH AUTHORS
.PP
\fBbemenu\fR is written and maintained by Jari Vetoniemi <\fImailroxas@gmail.\&com\fR>
with the help of various contributors.\&