bemenu/README.md

bemenu

Dynamic menu library and client program inspired by dmenu

Releases

Releases are signed with 29317348D687B86B and published on GitHub.

Building

# Build everything
make

# To build only certain features, pass the targets which you are interested into
#
# You can also use the following meta-targets for common features:
# - clients (bemenu, bemenu-run)
# - x11
# - wayland
# - curses
#
# For example this would build the bemenu and bemenu-run binaries and the x11 backend:
make clients x11

# To install the built features, simply run:
make install

# NOTE: You may get errors during install when not building all the features.
#       These errors are free to ignore if `Install OK!` is printed.

# By default that will install to /usr/local, but you can change this with PREFIX
make install PREFIX=/usr

# Other usual variables are available for modifying such as DESTDIR, bindir, libdir and mandir
# Note that if you want a custom PREFIX or libdir, you should pass those during build as well,
# since they will be used compile-time to figure out where to load backends from!

# HTML API documentation (requires doxygen installed):
make doxygen

# To test from source, you have to point the LD_LIBRARY_PATH and BEMENU_RENDERERS variables:
LD_LIBRARY_PATH=. BEMENU_RENDERERS=. ./bemenu-run

OSX

Homebrew

# Make sure you have GNU Make and pkg-config installed
brew install make pkg-config

# You may need to setup your pkg-config to point to the brew version of the libraries
# For example to build curses backend, you'd do:
PKG_CONFIG_PATH="/usr/local/opt/ncurses/lib/pkgconfig" sh build-osx.sh curses

# Other than that, follow the normal build steps, but use `build-osx.sh` instead of make

Nix

There is default.nix provided in this repo, you can install bemenu with it by running

nix-env -i -f default.nix

This installs only the curses backend.

Dependencies

• C compiler
• scdoc to generate manpage

Backend-specific

All dependencies below are searched with pkg-config

Backend	Dependencies
curses	ncursesw
x11	x11, xinerama, cairo, pango, pangocairo
Wayland	wayland-client, wayland-protocols, cairo, pango, pangocairo, xkbcommon

Currently, pasting from clipboard is done at runtime with wl-paste -t text/plain and xclip -t text/plain -out, attempted in that order.

Installing the dependencies

Ubuntu 20.04

sudo apt install scdoc wayland-protocols libcairo-dev libpango1.0-dev libxkbcommon-dev libwayland-dev

Environment variables

Variable	Description	Value
BEMENU_OPTS	Options for bemenu, bemenu-run from env	Any cli argument
BEMENU_BACKEND	Force backend by name	x11, wayland, curses
BEMENU_RENDERER	Force backend by loading a .so file	Path to the .so file
BEMENU_RENDERERS	Override the backend search path	Path to a directory
BEMENU_SCALE	Override the rendering scale factor	Float value

About Wayland support

Wayland is only supported by compositors that implement the wlr-layer-shell protocol. Typically wlroots-based compositors.

Keybindings

Default Bindings

Key	Binding
Left Arrow	Move cursor left
Right Arrow	Move cursor right
Up Arrow	Move to previous item
Down Arrow	Move to next item
Shift + Left Arrow	Select previous item
Shift + Right Arrow	Select next item
Shift + Alt + <	Select first item in actual list
Shift + Alt + >	Select last item in actual list
Shift + Page Up	Select first item in actual list
Shift + Page Down	Select last item in actual list
Page Up	Select first item in displayed list
Page Down	Select last item in displayed list
Tab	Move to next item
Shift + Tab	Select item and place it in filter
Esc	Exit bemenu
Insert	Return filter text or selected items if multi selection
Shift + Return	Return filter text or selected items if multi selection
Return	Execute selected item
Home	Curses cursor set to 0
End	Cursor set to end of filter text
Backspace	Delete character at cursor
Delete	Delete character at cursor
Delete Left	Delete text before cursor
Delete Right	Delete text after cursor
Word Delete	Delete all text in filter
Alt + v	Select last item in displayed list
Alt + j	Select next item
Alt + d	Select last item in display list
Alt + l	Select previous item
Alt + f	Select next item
Alt + 0-9	Execute selected item with custom exit code
Ctrl + Return	Select item but don't quit to select multiple items
Ctrl + g	Exit bemenu
Ctrl + n	Select next item
Ctrl + p	Select previous item
Ctrl + a	Move cursor to beginning of text in filter
Ctrl + e	Move cursor to end of text in filter
Ctrl + h	Delete character at cursor
Ctrl + u	Kill text behind cursor
Ctrl + k	Kill text after cursor
Ctrl + w	Kill all text in filter
Ctrl + m	Execute selected item
Ctrl + y	Paste clipboard

Vim Bindings

Vim bindings can be activated via the --binding vim option. All bindings are in vim normal mode. When bemenu is started with vim bindings it will be in insert mode. By pressing escape, normal mode can be activated.

Note: The default bindings can still be used for actions that do not have a separate vim binding such as launching a program or pasting.

Key	Binding
j/n	Goto next item
k/p	Goto previous item
h	Move cursor left
l	Move cursor right
q	Quit bemenu
v	Toggle item selection
i	Enter insert mode
I	Move to line start and enter insert mode
a	Move to the right and enter insert mode
A	Move to line end and enter insert mode
w	Move a word
b	Move a word backwards
e	Move to end of word
x	Delete a character
X	Delete a character before the cursor
0	Move to line start
$	Move to line end
gg	Goto first item
G	Goto last item
H	Goto first item in view
M	Goto middle item in view
L	Goto last item in view
F	Scroll one page of items down
B	Scroll one page of items up
dd	Delete the whole line
dw	Delete a word
db	Delete a word backwards
d0	Delete to start of line
d$	Delete to end of line
cc	Change the whole line
cw	Change a word
cb	Change a word backwards
c0	Change to start of line
c$	Change to end of line

Projects using bemenu

• pinentry-bemenu

License

• GNU GPLv3 (or any later version) for client program[s] and other sources except library and bindings
• GNU LGPLv3 (or any later version) for library and bindings