Configuration - bakkeby/dmenu GitHub Wiki

This section outlines the various configuration options in config.h, what they do and what to refer to.

The general principle here is that the configuration defines the default behaviour of dmenu while most features and functionality can be enabled (or disabled) using command line arguments.

/* -fn option overrides fonts[0]; default X11 font or font set */
static char *fonts[] =
{
	"monospace:size=10"
};

The fonts config is a list of font names that the dmenu will use for displaying text.

The first in the list will be the primary font while the rest will be fallback fonts that are used should the primary font does not have a specific glyph (character).

The font names can generally be found by using the fc-list command in a terminal.

Keep in mind that not all fonts are created equally. When combining different fonts they may have to be set to different sizes to appear roughly the same.

If text size is significantly different to the size of symbols then you can try setting pixelsize instead of size in the font string.

Refer to the ColorEmoji functionality if you plan to enable coloured emoji in the bar.

Refer to the fontconfig page for details when it comes to system configuration:

• https://freedesktop.org/software/fontconfig/fontconfig-user.html

static char *prompt = NULL; /* -p  option; prompt to the left of input field */

The prompt setting controls the default leading prompt indicating what kind of options dmenu is presenting. This is more commonly set via the -p (or -prompt) command line option.

Here is an example setting a prompt of "Files:" when running dmenu:

$ ls | dmenu -p "Files:"

Which shows up like:

static const char *dynamic = NULL; /* -dy option; dynamic command to run on input change */

The dynamic setting controls the default command that is executed on every input change to update the current options. This is more commonly set via the -dy command line option.

For more information refer to the Dynamic Options page.

static const char *lsymbol = "<"; // shown when there are more items on the left
static const char *rsymbol = ">"; // shown when there are more items on the right

The left and right symbols (lsymbol and rsymbol settings respectively) are shown when there are more items present in the given direction. These are configurable as per the symbols patch for dmenu.

/* Powerline options, one of:
 *    PwrlNone, PwrlRightArrow, PwrlLeftArrow, PwrlForwardSlash or PwrlBackslash */
static int powerline = PwrlNone;
/* By default the powerline separator will take up the full space between dmenu items.
 * This option allows for the size to be reduced by a number of pixels, e.g. a value of 3
 * will shave off three pixels on each side of the separator. This can be used to adjust
 * the angle of a powerline slash or arrow. */
static int powerline_size_reduction_pixels = 0;

This option allows for powerline separators to be drawn between dmenu items in the form of arrows or slashes.

The powerline_size_reduction_pixels setting allows for the width of the powerline separator to be reduced in order to adjust the angle of the slash or arrow.

/* Functionality that is enabled by default, see util.h for options */
static unsigned long functionality = 0
	|Alpha // enables transparency
	|CaseSensitive // makes dmenu case sensitive by default
//	|Centered // dmenu appears in the center of the screen
//	|ColorEmoji // enables color emoji support (removes Xft workaround)
//	|ContinuousOutput // makes dmenu print out selected items immediately rather than at the end
	|FuzzyMatch // allows fuzzy-matching of items in dmenu
//	|HighlightAdjacent // makes dmenu highlight items adjacent to the selected item
//	|Incremental // makes dmenu print out the current text each time a key is pressed
//	|InstantReturn // makes dmenu select an item immediately if there is only one matching option left
//	|Managed // allow dmenu to be managed by window managers (disables override_redirect)
//	|PasswordInput // indicates that the input is a password and should be masked
//	|PrintIndex // makes dmenu print out the 0-based index instead of the matched text itself
//	|PrintInputText // makes dmenu print the input text instead of the selected item
//	|PromptIndent // makes dmenu indent items at the same level as the prompt on multi-line views
//	|RejectNoMatch // makes dmenu reject input if it would result in no matching item
//	|RestrictReturn // disables Shift-Return and Ctrl-Return to restrict dmenu to only output one item
//	|ShowNumbers // makes dmenu display the number of matched and total items in the top right corner
	|Sort // allow dmenu to sort menu items after matching
	|TopBar // dmenu appears at the top of the screen
	|Xresources // makes dmenu read X resources at startup
;

The functionality setting controls whether specific features are enabled or disabled.

The user can control which features are enabled by uncommenting or commenting out listed options in this list.

Refer to the Functionality page for more details.

/* Alpha values. You only need to add colour schemes here if you want different levels of
 * transparency per scheme. The default values are defined in the alpha_default array in drw.c. */
static const unsigned int alphas[SchemeLast][2] = {
	/*               fg      bg   */
	[SchemeNorm] = { OPAQUE, 0xd0 },
};

The alpha configuration controls the transparency levels of colours used in the dmenu window and this is defined on a per colour scheme basis.

If a colour scheme is not explicitly listed in the alphas array above then they will default to having an opaque foreground and a background opacity of 0xd0.

In other words you do not need to add colour schemes here unless you want something that has more or less opacity than the defaults.

SchemeNorm is listed here primarily as an example for how to configure this, but also because many compilers do not like empty initialisers.

The foreground (fg) colour transparency is used for text and is by default opaque.

The background (bg) colour transparency is by default 0xd0 (about 82% opacity).

Should you, for whatever reason, want to change the default alpha values then refer to the following variable in drw.c:

static const unsigned int alpha_default[] = { 0xffU, 0xd0U };

static char *colors[SchemeLast][ColCount] = {
	/*                        fg         bg         resource prefix */
	[SchemeNorm]          = { "#bbbbbb", "#222222", "norm" },
	[SchemeSel]           = { "#eeeeee", "#005577", "sel" },
	[SchemeOut]           = { "#000000", "#00ffff", "out" },
	[SchemeBorder]        = { "#000000", "#005577", "border" },
	[SchemePrompt]        = { "#eeeeee", "#005577", "prompt" },
	[SchemeAdjacent]      = { "#eeeeee", "#770000", "adjacent" },
	[SchemeSelHighlight]  = { "#ffc978", "#005577", "selhl" },
	[SchemeNormHighlight] = { "#ffc978", "#222222", "normhl" },
	[SchemeHp]            = { "#bbbbbb", "#333333", "hp" },
};

The colors array defines the colours used for the dmenu window including the border.

Each colour scheme consists of a foreground colour which is used for text and a background colour that is used for the background in the bar.

The resource prefix is used in relation to loading / overwriting the colour schemes via Xresources. Refer to the Xresources functionality for more information on that.

Should you need to add your own custom colour schemes then you can do so by expanding on the corresponding enum in dmenu.c. Start by searching for "SchemeNorm".

/* -l option; if nonzero, dmenu uses vertical list with given number of lines */
static unsigned int lines = 0;

The lines setting allows for dmenu to display options on separate lines rather than horizontally.

This is more commonly enabled using the -l command line option.

Example having dmenu present items over five lines:

$ ls | dmenu -c -l 5

Note that the left and right symbols do not show when presenting items across multiple lines.

/* -g option; if nonzero, dmenu uses a grid comprised of columns and lines */
static unsigned int columns = 0;

The columns setting allow for dmenu to display items in a grid. This is most commonly enabled using the -g command line option and this must be combined with lines (-l) to work.

The -g option is short for "grid" and this is used to be consistent with the original grid patch for dmenu and because other and perhaps more intuitive flags are reserved for different functionalities.

Example having dmenu present items over a 5x3 grid:

$ ls | dmenu -c -l 5 -g 3

static unsigned int lineheight = 0; /* -h option; minimum height of a menu line */

By default the minimum line height will be the size of the font height + 2 pixels (as in one additional pixel space above and below the text).

The lineheight setting controls the height of the dmenu bar, or the height of the dmenu lines when items are presented across multiple lines, provided that this is greater than the minimum.

If lineheight is 0 then the default line height is used.

If lineheight is -1 then the line height will be 2.5 times that of the font height:

The -h command line option can be used to specify the line height. This will have no effect if the provided value is less than the minimum (which depends on the font size).

Example having dmenu present items over a 5x3 grid with a line height of 60 pixels:

$ ls | dmenu -c -l 5 -g 3 -h 60

static unsigned int min_width = 500; /* minimum width when centered */

The min_width setting controls the default (minimum) width of dmenu when centered. In practice this controls the size of dmenu when centered. It is possible to override this size by using the -w command line option to set the width of dmenu.

Also refer to the Centered functionality.

static unsigned int maxhist = 15;
static int histnodup        = 1; /* if 0, record repeated histories */

These options originate from the navhistory patch for dmenu. The maxhist setting controls how many previous selections to remember while the histnodup controls whether to allow duplicate values in the history or not.

This is to be combined with the -H histfile command line option which specifies the history file to use.

Example using dmenu with a history file:

$ ls | dmenu -H histfile.dat

When using dmenu like this the selected item is stored in the given file histfile.dat.

$ cat histfile.dat
config.h
config.mk
arg.h

Exceptions to this:

• when selecting multiple items only the last selected item will be stored
• when selecting items using the mouse no item will be stored in the history

When using dmenu that has a history file like this then Alt+p and Alt+n keybindings can be used to navigate the history of previously chosen items.

/*
 * Characters not considered part of a word while deleting words
 * for example: " /?\"&[]"
 */
static const char worddelimiters[] = " ";

dmenu comes with a few built-in keybindings that work with words:

• Ctrl+w - delete the word on the left
• Alt+b (or Ctrl+Left) - move cursor to the start of the current word
• Alt+f (or Ctrl+Right) - move cursor to the end of the current word

The worddelimiters setting controls what characters are considered as word boundaries.

/* Default size of the window border */
static unsigned int border_width = 0;

The border_width setting controls the width of the border around dmenu. A border width of 0 means that dmenu is to be drawn with no border. This can also be set using the -bw command line option.

This feature originates from the border patch for dmenu.

Example having a border width of 0:

$ ls | dmenu -c -bw 5

Example having a border width of 5:

$ ls | dmenu -c -bw 0

/* Vertical and horizontal padding of dmenu in relation to monitor border */
static int vertpad = 0;
static int sidepad = 0;

The vertpad and sidepad options allows for dmenu to be placed with an offset to the monitor border. This is intended to allow for dmenu to be placed on top of the bar in dwm when the barpadding patch for dwm, which adds a gap between the bar and the edge of the monitor, has been applied.

This can also be controlled using the command line arguments of -xpad and -ypad if preferred.

If the position of dmenu is specified using the -x or -y command line arguments, or if dmenu is centered, then the vertical and horizontal padding will not be taken into account.