bemenu/man/bemenu.1.scd.in

bemenu(1)

# NAME

*bemenu* - dynamic menu inspired by *dmenu*(1)

# SYNOPSIS

*bemenu* [*-hCiKTvwx*] [*-I* <_index_>] [*-l* <_lines_>] [*-P* <_prefix_>]
	\[*-p* <_prompt_>] [*--ifne*] [*--scrollbar* _none_|_always_|_autohide_]
	\[*--binding* _vim_] [*--fork*] [_backend_options_]

*bemenu-run* [*-hCiKTvwx*] [*-I* <_index_>] [*-l* <_lines_>] [*-P* <_prefix_>]
	\[*-p* <_prompt_>] [*--ifne*] [*--scrollbar* _none_|_always_|_autohide_]
	\[*--binding* _vim_] [*--fork*] [*--no-exec*] [_backend-options_]

# DESCRIPTION

*bemenu* is a dynamic menu for *tty*(4) (using *ncurses*(3)), X11 and Wayland,
inspired by *dmenu*(1).

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
*<carriage-return>*, the selected items are printed to standard output (one per
line) and *bemenu* exits.

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.

*bemenu-run* is a special-case invocation of *bemenu*, where the input is the
list of executables under PATH and the selected items are executed.

# OPTIONS

*-h, --help*
	Print a help message to standard output and exit.

*-C, --no-cursor*
	Disable all cursor events.

*-I, --index* <_index_>
	Highlight the item at _index_ at the start. Indices start at 0. By
	default, the first item is highlighted.

*-i, --ignorecase*
	Filter items case-insensitively.

*-K, --no-keyboard*
	Disable all keyboard events.

*-l, --list* "<_number_> _down_|_up_"
	List items vertically _down_ or _up_ with the given _number_ of lines.

*-P, --prefix* <_prefix_>
	Display _prefix_ before the highlighted item in a vertical list.

*-p, --prompt* <_prompt_>
	Defines the _prompt_ text to be displayed to the left of the input
	field. Defaults to ‘bemenu’.

*-s, --no-spacing*
	Disable the title spacing on entries.

*-T, --no-touch*
	Disable all touch events.

*-v, --version*
	Print the *bemenu* version number to standard output and exit.

*-w, --wrap*
	Advancing past the end of the list returns you to the start.

*-x, --password* _none_|_hide_|_indicator_
	Specify how the filter text should be displayed:
[[ *none*
:< Display the input (the default).
|  *hide*
:  Do not display any input.
|  *indicator*
:  Replace input with asterisks.

*--fixed-height*
	Prevent the display from changing height on filter.

*--accept-single*
	Immediately return if there is only one item.

*--auto-select*
	When one entry is left, automatically select it.

*--binding*
	Use alternative key bindings. Available options: vim

*--fork*
	Always *fork*(2) before executing the selections. Disabled by default
	when using the terminal backend.

*--ifne*
	Only display menu if there are items.

*--single-instance*
	Force a single menu instance.

*--no-exec*
	Print the selected items to standard output instead of executing them.

*--scrollbar* _none_|_always_|_autohide_
	Specify when to show a scrollbar for vertical lists:
[[ *none*
:< Never display a scrollbar (the default).
|  *always*
:  Always display a scrollbar.
|  *autohide*
:  Only display a scrollbar when the number of items exceeds the number
   of lines.

*-e, --vim-esc-exits*
	Exit bemenu when pressing escape in normal mode for vim bindings.

*-N, --vim-normal-mode*
	Start in normal mode for vim bindings.

*-F, --filter*
	Filter items for a given string before showing the menu.
	Affects *--ifne* and *--accept-single*

## Backend options

These options are only available on backends specified in the parentheses:

*-b, --bottom* (Wayland, X11)
	The list will appear at the bottom of the screen.

*-c, --center* (Wayland, X11)
	The list will appear at the center of the screen. (wx)

*-f, --grab* (Wayland, X11)
	Show the *bemenu* window whilst reading the items.

*-B, --border* (Wayland, X11)
	Specify the width of the border in pixels around the menu.

*--bdr* (Wayland, X11)
	Specify the border color.

*-R, --border-radius* (Wayland, X11)
	Specify the radius of the border around the menu (0 = no curved borders).

*-H, --line-height* <_height_> (Wayland, X11)
	Specify the _height_ in point size to make each entry.

*--ch* (Wayland, X11)
	Specify the height of the cursor (0 = scales with line height).

*--cw* (Wayland, X11)
	Specify the width of the cursor.

*-m, --monitor* <_index_> (Wayland, X11)
	Specify the monitor _index_ 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
	*focused* indicates that the current monitor should be used (the
	default). With Wayland, the _index_ should be a string specifying a
	specific monitor name. The value ‘-2’ or *all* indicates that the list
	should appear on all monitors.

*-n, --no-overlap* (Wayland)
	Set the *bemenu* window to be on top of any other panels.

*-M, --margin* <_margin_> (Wayland, X11)
	Specify the _margin_ (empty space) in pixels to leave between menu and
	vertical view borders. *bemenu* will reduce it's size to fit in space
	between gaps.

*--hp* (Wayland, X11)
	Specify the horizontal padding for the entries in single line mode.

*-W, --width-factor* <_factor_> (Wayland, X11)
	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
	*bemenu* will use. However, *bemenu* will still respect _margin_, so if
	resulting size is greater than space between gaps, *bemenu* will ignore
	_factor_ and use available space instead.

*--fn* <_name_ [_size_]> (Wayland, X11)
	Specify the font family _name_ and _size_ to be used. For more options,
	consult the _Pango Reference Manual_ for
	*pango_font_description_from_string*().

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:

	*#*_RGB_[_A_]

where _R_, _G_, _B_ and _A_ are hexadecimal integers from 00–FF that
control the red, green, blue and alpha-transparency channels.

*--tb* <_color_>	Title background.

*--tf* <_color_>	Title foreground.

*--fb* <_color_>	Filter background.

*--ff* <_color_>	Filter foreground

*--cb* <_color_>	Cursor background.

*--cf* <_color_>	Cursor foreground

*--nb* <_color_>	Normal background.

*--nf* <_color_>	Normal foreground.

*--hb* <_color_>	Highlighted background.

*--hf* <_color_>	Highlighted foreground.

*--fbb* <_color_>	Feedback background.

*--fbf* <_color_>	Feedback foreground.

*--sb* <_color_>	Selected background.

*--sf* <_color_>	Selected foreground.

*--ab* <_color_>	Alternating background color.

*--af* <_color_>	Alternating foreground color.

*--scb* <_color_>	Scrollbar background.

*--scf* <_color_>	Scrollbar foreground.

# KEYBOARD COMMANDS

*bemenu* supports keyboard commands to move around the list and edit the filter.
In the following examples, *C-x* means *<control-x>*, *M-x* means *<alt-x>* and
*S-x* means *<shift-x>*:

*<cursor-up>, S-<cursor-left>, C-p, M-j, M-l*
	Highlight the previous item.

*<cursor-down>, <tab>, C-n, M-h, M-k*
	Highlight the next item.

*PageUp, M-v, M-u*
	Show the previous page of items, preserving the offset of the currently
	highlighted item, if possible.

*PageDown, C-v, M-d*
	Show the next page of items, preserving the offset of the currently
	highlighted item, if possible.

*S-M-<, S-PageUp*
	Highlight the first item in the list.

*S-M->, S-PageDown*
	Highlight the last item in the list.

*S-<tab>*
	Copy the highlighted item to the filter.

*<escape>, C-g*
	Terminate *bemenu* without printing items.

*C-<carriage-return>, C-m*
	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.

*S-<carriage-return>, Insert*
	Print the filter text to standard output and exit.

*C-b, C-l, <cursor-left>*
	Move cursor left.

*C-f, <cursor-right>*
	Move cursor right.

*C-a, Home*
	Move cursor to the start.

*C-e, End*
	Move cursor to the end.

*<backspace> C-h*
	Remove character before the cursor.

*<delete>*
	Remove character at the cursor.

*C-u, S-<delete>*
	Remove all characters before the cursor.

*C-k*
	Remove all characters after the cursor.

*C-w*
	Clear the filter.

*C-y*
	Paste the clipboard.

*M-[1-9]*
	Print selected items and exit with a custom error code 10 (*M-1*)
	through 18 (*M-9*), see _EXIT STATUS_.

*M-0*
	Print selected items and exit with the custom error code 19, see _EXIT
	STATUS_.

## Vim bindings

*bemenu* uses vim-like modal entry if invoked with *--binding vim*.
These bindings roughly emulate insert and normal vim modes.
The initial mode is insert mode, unless *--vim-normal-mode* is specified.

In insert mode, all keys function as described above except for the following:

*<escape>*
	Switch to normal mode.

In normal mode, only the following keys have meaning:

*q*
	Terminate *bemenu* without printing items.

*i*
	Enter insert mode.

*I*
	Enter insert mode after moving the cursor to the start.

*a*
	Enter insert mode after moving the cursor right.

*A*
	Enter insert mode after moving the cursor to the end.

*cc*
	Enter insert mode after clearing the filter.

*cw*
	Enter insert mode after removing all characters between the cursor and
	the start of the next word.

*cb*
	Enter insert mode after removing all characters between the start of
	the word and the cursor.

*c$*
	Enter insert mode after removing all characters after the cursor.

*c0*
	Enter insert mode after removing all characters before the cursor.

*n*, *j*
	Highlight the next item.

*p*, *k*
	Highlight the previous item.

*gg*
	Highlight the first item in the list.

*G*
	Highlight the last item in the list.

*H*
	Highlight the first visible item.

*M*
	Highlight the middle-most visible item.

*L*
	Highlight the last visible item.

*v*
	Select or deselect the higlighted item.

*F*
	Show the next page of items.

*B*
	Show the previous page of items.

*h*
	Move cursor left.

*l*
	Move cursor right.

*0*
	Move cursor to the start.

*$*
	Move cursor to the end.

*w*
	Move cursor forward to the start of a word.

*b*
	Move cursor backward to the start of a word.

*e*
	Move cursor forward to the end of a word.

*x*
	Remove character at the cursor.

*X*
	Remove character before the cursor.

*dw*
	Remove all characters between the cursor and start of the next word.

*db*
	Remove all characters between the start of the word and the cursor.

*d$*
	Remove all characters after the cursor.

*d0*
	Remove all characters before the cursor.

*dd*
	Clear the filter.

# ENVIRONMENT

[[ *BEMENU_OPTS*
:< An alternative way to pass command line arguments to *bemenu*.
|  *BEMENU_BACKEND*
:  Force a backend to be used. If empty, one of the GUI backends (Wayland, X11)
   will be selected automatically. The accepted values are *curses*, *wayland*
   and *x11*.
|  *BEMENU_RENDERER*
:  Force a backend by loading its shared object from the set value.
|  *BEMENU_RENDERERS*
:  Override the backend search path to the set value. Defaults to
   _@LIBDIR@/bemenu_.
|  *BEMENU_SCALE*
:  Override the rendering scale factor for the GUI backends.

# EXIT STATUS

*0*
	bemenu ran successfully.

*1*
	The user exited without selecting, or bemenu encountered an error.

*10-19*
	The user specified a custom exit code with *M-[0-9]*, see _KEYBOARD
	COMMANDS_.

# SEE ALSO

*dmenu*(1), *fork*(2), *ncurses*(3), *tty*(4)

_Pango Reference Manual_, https://developer.gnome.org/pango/1.46/, August 20,
2020, Fonts — pango_font_description_from_string().

# AUTHORS

*bemenu* is written and maintained by Jari Vetoniemi <_mailroxas@gmail.com_>
with the help of various contributors.