fuzzel.ini(5)

# NAME
fuzzel.ini - configuration file for *fuzzel*(1)


# DESCRIPTION

*fuzzel* uses the standard _unix configuration format_, with section
based key/value pairs. The default section is usually unnamed,
i.e. not prefixed with a _[section]_. However it can also be
explicitly named _[main]_, say if it needs to be reopened after any of
the other sections.

fuzzel will search for a configuration file in the following locations,
in this order:

	- *XDG_CONFIG_HOME/fuzzel/fuzzel.ini* (defaulting to
	  *~/.config/fuzzel/fuzzel.ini* if unset)
	- *XDG_CONFIG_DIRS/fuzzel/fuzzel.ini* (defaulting to
	  */etc/xdg/fuzzel/fuzzel.ini* if unset)

An example configuration file containing all options with their default value
commented out will usually be installed to */etc/xdg/fuzzel/fuzzel.ini*.

# SECTION: main

*output*
	Output (monitor) to display on. You can list the available outputs
	with *wlr-randr* or with Sway using *swaymsg -t get_outputs*.

	Example: _DP-1_

	Default: Not set-- let the compositor choose output.

*font*
	Comma separated list of fonts to use, in fontconfig format. That
	is, a font name followed by a list of colon-separated
	options. Most noteworthy is *:size=n*, which is used to set the
	font size. Note that the font size is also affected by the
	*dpi-aware* option.
	
	Examples:
		- Dina:weight=bold:slant=italic
		- Courier New:size=12
		- Fantasque Sans Mono:fontfeatures=ss01
	
	Default: _monospace_.

*dpi-aware*
	*auto*, *yes*, or *no*.
	
	When set to *yes*, fonts are sized using the monitor's DPI, making
	a font of a given size have the same physical size, regardless of
	monitor.
	
	In this mode, the monitor's scaling factor is ignored; doubling
	the scaling factor will *not* double the font size.
	
	When set to *no*, the monitor's DPI is ignored. The font is
	instead sized using the monitor's scaling factor; doubling the
	scaling factor *does* double the font size.
	
	Finally, if set to *auto*, fonts will be sized using the monitor's
	DPI if _all_ monitors have a scaling factor of 1. If at least one
	monitor as a scaling factor larger than 1 (regardless of whether
	the fuzzel window is mapped on that monitor or not), fonts will be
	scaled using the scaling factor.
	
	Note that this option typically does not work with bitmap fonts,
	which only contains a pre-defined set of sizes, and cannot be
	dynamically scaled. Whichever size (of the available ones) that
	best matches the DPI or scaling factor, will be used.
	
	Also note that if the font size has been specified in pixels
	(*:pixelsize=*_N_, instead of *:size=*_N_), DPI scaling
	(*dpi-aware=yes*) will have no effect (the specified pixel size
	will be used as is). But, if the monitor's scaling factor is used
	to size the font (*dpi-aware=no*), the font's pixel size will be
	multiplied with the scaling factor.
	
	Default: _auto_.

*prompt*=
	String to use as input prompt. Note that trailing spaces are
	trimmed, unless the string is quoted. Default: _"> "_.

*icon-theme*
	Icon theme. Note that the name is case sensitive. Default:
	_hicolor_.

*icons-enabled*
	Boolean. When enabled, application icons (from the selected
	*icon-theme*) will be rendered. Default: _yes_.

*fields*
	Comma separated list of XDG Desktop entry fields to match
	against.
	
	Even though fuzzel only displays the application names,
	matching can (and by default is) be done against other fields as
	well. Supported fields are:
	
	- filename
	- name
	- generic
	- exec
	- categories
	- keywords
	- comment
	
	Default: _filename,name,generic_.

*password-character*
	Default character to use with the command line option
	*--password*. Note that this can be overridden on the command
	line, by explicitly specifying the character with
	*--password=X*. Default: _\*_.

*filter-desktop*
	Boolean. Filter desktop files based on the value of XDG_CURRENT_DESKTOP.

*fuzzy*
	Boolean. Enables or disables fuzzy matching. Default: _yes_.

*show-actions*
	Boolean. Some desktop files define "actions", in addition to the
	application itself. Examples are "new window", "preferences",
	etc. When this option is enabled, those actions will be listed by
	fuzzel. Default: _no_.

*terminal*
	terminal command to use when launching 'terminal' programs,
	e.g. \"xterm -e\". Default: _$TERMINAL -e_.

*launch-prefix*
	Prefix to add before argv of executed program.
	If set, fuzzel will pass the Desktop File ID of the chosen application
	(see the Desktop Entry specification) in the FUZZEL_DESKTOP_FILE_ID
	environment variables.
	Default: _not set_.

*lines*
	Number of matches to show. Default: _15_.

*width*
	Window width, in characters. Border and margins are not included
	in this. Default: _30_.

*tabs*
	Number of spaces a tab is expanded to. Default: _8_.

*horizontal-pad*
	Horizontal padding, in pixels, between border and
	content. Default: _40_.

*vertical-pad*
	Vertical padding, in pixels, between border and content. Default:
	_8_.

*inner-pad*
	Vertical padding between prompt and match list, in
	pixels. Default: _0_.

*image-size-ratio*
	The ratio of the large image displayed when there are only a "few"
	matches, compared to the full window size. Default: _0.5_.

*line-height*
	Override line height from font metrics. Default: use font metrics.

*letter-spacing*
	Additional letter spacing. Negative values are allowed. Default:
	_0_.

*layer*
	Which layer to render the fuzzel window on. Valid values are *top*
	and *overlay*.
	
	*top* renders above normal windows, but typically below fullscreen
	windows and lock screens.
	
	*overlay* renders on top of both normal windows and fullscreen
	windows. Note that the order is undefined if several windows use
	the same layer. Since e.g. lock screens typically use *overlay*,
	that means fuzzel may or may not appear on top of a lock screen.
	
	Default: _top_

*exit-on-keyboard-focus-loss*
	Boolean. If true, exit when the fuzzel window loses keyboard focus.
	
	Setting this to false can be useful on compositors where enabling
	"focus-follows-mouse" causes fuzzel to exit as soon as the mouse
	is moved over another window. Sway (<= 1.7) exhibits this
	behavior, for example.
	
	Default: _yes_

# SECTION: colors

All color values are in RGBA.

*background*
	Background color. Default: _fdf6e3dd_.

*text*
	Text (foreground) color of unselected entries. Default:
	_657b83ff_.

*match*
	Text (foreground) color of the matched substring. Default:
	_cb4b16ff_.

*selection*
	Background color of the selected entry. Default: _eee8d5dd_.

*selection-text*
	Text (foreground) color of the selected entry. Default:
	_657b83ff_.

*selection-match*
	Text (foreground) color of the matched substring of the
	selected entry. Default: _cb4b16ff_.

*border*
	Border color. Default: _002b36ff_.


# SECTION: border

*width*
	Width of the border, in pixels. Default: _1_.

*radius*
	Amount of corner "roundness". Default: _10_.

# SECTION: dmenu

*mode*
	One of *text* or *index*. Determines what fuzzel prints on stdout
	when an entry is selected: *text* prints the entry itself, *index*
	prints the index of the selected entry. Default: _text_.

*exit-immediately-if-empty*
	Boolean. If enabled, fuzzel will not run at all (i.e. it will not
	open a window, and will not print anything on stdout) if there's
	nothing on stdin. Default: _no_.


# SECTION: key-bindings

This section lets you override the default key bindings.

The general format is _action=combo1...comboN_. That is, each action
may have one or more key combinations, space separated. Each
combination is in the form _mod1+mod2+key_. The names of the modifiers
and the key *must* be valid XKB key names.

Note that if *Shift* is one of the modifiers, the _key_ *must not* be
in upper case. For example, *Control+Shift+V* will never trigger, but
*Control+Shift+v* will.

Note that *Alt* is usually called *Mod1*.

*xkbcli interactive-wayland* can be useful for finding keysym names.

A key combination can only be mapped to *one* action. Lets say you
want to bind *Control+k* to *next*. Since this is the default shortcut
for *delete-line*, you must unmap the default binding. This can be
done by setting _action=none_; e.g. *delete-line=none*.

*cancel*
	Quite fuzzel without executing anythingDefault: _Control+g
	Control+c Escape_.

*execute*
	Execute the currently selected entry. Or, in dmenu mode, print the
	selected entry on stdout. Default: _Return KP_Enter Control+y_.

*execute-or-next*
	If there is a single match, execute it. If there are more than one
	match, select the next entry. Wraps around when the last entry has
	been reached. Default: _Tab_.

*cursor-left*
	Moves the cursor one **character** to the left. Default: _Left
	Control+b_.

*cursor-left-word*
	Moves the cursor one **word** to the left. Default: _Control+Left
	Mod1+b_.

*cursor-right*
	Moves the cursor one **character** to the right. Default: _Right
	Control+f_.

*cursor-right-word*
	Moves the cursor one **word** to the right. Default:
	_Control+Right Mod1+f_.

*cursor-home*
	Moves the cursor to the beginning of the input. Default: _Home
	Control+a_.

*cursor-end*
	Moves the cursor to the end of the input. Default: _End
	Control+e_.

*delete-prev*
	Deletes the **character before** the cursor. Default: _BackSpace_.

*delete-prev-word*
	Deletes the **word before** the cursor. Default: _Mod1+BackSpace
	Control+BackSpace_.

*delete-next*
	Deletes the **character after** the cursor. Default: _Delete_.

*delete-next-word*
	Deletes the **word after** the cursor. Default: _Mod1+d
	Control+Delete_.

*delete-line*
	Deletes everything after the cursor. Default: _Control+k_.

*insert-selected*
	Copies the selected entry to the prompt, replacing the current
	prompt. In application mode, the *Exec* line is inserted, and in
	dmenu mode the entry itself is used. Default: _Control+Tab_.

*prev*
	Select the previous entry. Does *not* wrap around when the first
	entry has been reached. Default: _Up Control+p_.

*prev-with-wrap*
	Select the previous entry. Wraps around when the first entry has
	been reached. Default: _ISO_Left_Tab_.

*prev-page*
	Switch to the previous page. Default: _PageUp KP_PageUp_.

*next*
	Select the next entry. Does *not* wrap around when the last entry
	has been reached. Default: _Down Control+n_.

*next-with-wrap*
	Select the previous entry. Wraps around when the first entry has
	been reached. Default: _not bound_.

*next-page*
	Switch to the next page. Default: _Page_Down KP_Page_Down_.

*first*
	Select the first entry, on the first page. Default:
	_Control+Home_.

*last*
	Select the last entry, on the last page. Default: _Control+End_.

*custom-1*, *custom-2*, ..., *custom-19*
	Execute the currently selected entry, then exit with a non-zero
	exit code. *custom-1* exits with exit code 10, *custom-2* with 11,
	*custom-3* with 12, and so on.
	
	Default:
		- custom-1: _Mod1+1_
		- custom-2: _Mod1+2_
		- custom-3: _Mod1+3_
		- custom-4: _Mod1+4_
		- custom-5: _Mod1+5_
		- custom-6: _Mod1+6_
		- custom-7: _Mod1+7_
		- custom-8: _Mod1+8_
		- custom-9: _Mod1+9_
		- custom-10: _Mod1+10_
		- custom-11: _Mod1+11_
		- custom-12: _Mod1+12_
		- custom-13: _Mod1+13_
		- custom-14: _Mod1+14_
		- custom-15: _Mod1+15_
		- custom-16: _Mod1+16_
		- custom-17: _Mod1+17_
		- custom-18: _Mod1+18_
		- custom-19: _Mod1+19_

# SEE ALSO

*fuzzel*(1),
*https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html*
