Configuration - bakkeby/dusk GitHub Wiki

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

static const unsigned int borderpx = 5;  /* border pixel of windows */

The border pixel determines the size of the coloured border around client windows. This will also affect the size of the bar border if the functionality is enabled.

Also refer to the setborderpx function.

static const unsigned int snap = 32;  /* snap pixel */

The snap value determines how far (in pixels) the mouse cursor have to move when moving or resizing a tiled window before it snaps out of tiled and becomes floating.

The value is also used when moving a window using the mouse where if the window border is less than snap pixels away from the monitor window area, which is the screen real estate less the space used by the bars, then the window will snap to that edge.

Refer to the movemouse and resizemouse functions.

static const unsigned int gappih = 5;  /* horiz inner gap between windows */
static const unsigned int gappiv = 5;  /* vert inner gap between windows */
static const unsigned int gappoh = 5;  /* horiz outer gap between windows and screen edge */
static const unsigned int gappov = 5;  /* vert outer gap between windows and screen edge */

The gap values determine the default inner and outer horizontal and vertical gap sizes.

Refer to the Gaps topic.

static const unsigned int smartgaps_fact = 0;  /* smartgaps factor when there is only one client; 0 = no gaps, 3 = 3x outer gaps */

The smartgaps_fact value either removes or exaggerates gaps when there is only a single client visible on a workspace.

Refer to the SmartGaps functionality.

static unsigned int attachdefault = AttachAside;  /* AttachMaster, AttachAbove, AttachSide, AttachBelow, AttachBottom */

The attachdefault setting controls where in the client stack a new window will appear by default.

Refer to Attach and the setattachdefault function.

static const int initshowbar = 1;  /* 0 means no bar */

The initshowbar configuration item controls whether or not the bars are shown when the window manager first starts up.

Refer to the showbar and hidebar functions.

static const int bar_height = 0;  /* 0 means derive from font, >= 1 explicit height */

By default the height of the bar is derived based on the font size.

This can be overridden by explicitly setting the bar_height value.

Note that if the bars configuration specify an exact height for a bar then that will take precedence over the value set here.

static const int vertpad = 5;  /* vertical (outer) padding of bar */
static const int sidepad = 5;  /* horizontal (outer) padding of bar */

The vertpad and sidepad settings add vertical and horizontal padding between the bar and the edge of the monitor if the BarPadding functionality is enabled.

static const int iconsize    = 16;  /* icon size */
static const int iconspacing = 5;   /* space between icon and title */

These define the window title icon size and the distance between the icon and the window title text.

Not all applications provide an icon.

Refer to the flexwintitle page for more details.

static int floatposgrid_x = 5;  /* float grid columns */
static int floatposgrid_y = 5;  /* float grid rows */

The floatposgrid_x and floatposgrid_y controls the default grid size when using the floatpos grid placement feature.

static const int horizpadbar = 2;  /* horizontal (inner) padding for statusbar (increases lrpad) */
static const int vertpadbar  = 0;  /* vertical (inner) padding for statusbar (increases bh, overridden by bar_height) */

When text is drawn on the bar there is some blank space that is added on the left of the text and on the right of the text so that the text is not crammed to either side. This is referred to as the left/right padding (lrpad) and by default this is equal to the height of the font used.

This value represents the total amount of padding and it is divided equally between the left and right hand side of the text.

The horizpadbar setting can be used to adjust this value where a positive value will increase the padding and a negative value will reduce it.

The bar height (bh) is by default set to the height of the font used. The vertpadbar setting can be used to adjust the height of the bar where a positive value will increase the bar height and a negative value will reduce it.

If the bar_height variable is set, however, then that will override the bar height as well as this vertpadbar setting.

If the bars configuration specify an exact height for a bar then that will take precedence.

static const char slopspawnstyle[] = "-t 0 -c 0.92,0.85,0.69,0.3 -o"; /* do NOT define -f (format) here */

The slopspawnstyle option affects the appearance and behaviour of the select operation when using the riospawn function.

static const char slopresizestyle[] = "-t 0 -c 0.92,0.85,0.69,0.3"; /* do NOT define -f (format) here */

The slopresizestyle option affects the appearance and behaviour of the select operation when using the rioresize function.

static const unsigned int systrayspacing = 2;   /* systray spacing */

The systrayspacing setting controls the spacing between icons in the systray.

Refer to the Systray functionality.

static const char *toggle_float_pos = "50% 50% 80% 80%"; // default floating position when triggering togglefloating

The toggle_float_pos setting defines the size and position of a window when it is first changed from tiled to floating using the togglefloating function.

static const double defaultopacity = 0;   /* client default opacity, e.g. 0.75. 0 means don't apply opacity */

The defaultopacity config controls the default opacity for new windows by setting the _NET_WM_WINDOW_OPACITY property on the window.

This depends on that the compositor will take this property into account.

Refer to the changeopacity function.

static const double moveopacity = 0;   /* client opacity when being moved, 0 means don't apply opacity */

The moveopacity config can be used to change the transparency level of a window while it is being moved.

Refer to the movemouse function.

static const double resizeopacity = 0;   /* client opacity when being resized, 0 means don't apply opacity */

The resizeopacity config can be used to change the transparency level of a window while it is being resized.

Refer to the resizemouse function.

static const double placeopacity = 0;   /* client opacity when being placed, 0 means don't apply opacity */

The placeopacity config can be used to change the transparency level of a window while it is being placed.

Refer to the placemouse function.

/* Indicators: see lib/bar_indicators.h for options */
static int indicators[IndicatorLast] = {
	[IndicatorWsOcc] = INDICATOR_NONE,
	[IndicatorWsSel] = INDICATOR_NONE,
	[IndicatorWsVis] = INDICATOR_NONE,
	[IndicatorWsNorm] = INDICATOR_NONE,
	[IndicatorPinnedWs] = INDICATOR_NONE,
	[IndicatorFakeFullScreen] = INDICATOR_PLUS,
	[IndicatorFakeFullScreenActive] = INDICATOR_PLUS_AND_LARGER_SQUARE,
	[IndicatorFloatFakeFullScreen] = INDICATOR_PLUS,
	[IndicatorFloatFakeFullScreenActive] = INDICATOR_PLUS_AND_LARGER_SQUARE,
	[IndicatorTiled] = INDICATOR_NONE,
	[IndicatorFloating] = INDICATOR_TOP_LEFT_LARGER_SQUARE,
};

These define what kind of graphical indicators are used on the bar to:

• show what workspaces that have clients on them (IndicatorWsOcc)
• show which workspace is currently selected (IndicatorWsSel)
• show which workspace is visible, but not selected (IndicatorWsVis)
• show which workspace is not visible (IndicatorWsNorm)
• show which workspaces are pinned (IndicatorPinnedWs), refer to the togglepinnedws function
• highlight that a client window is available for fake fullscreen (IndicatorFakeFullScreen), refer to the FakeFullScreen flag
• highlight that a client window is floating (IndicatorFloating), refer to the Floating topic
• highlight that a client window is tiled (IndicatorTiled), refer to the Tiled topic

Refer to the Bar Indicators page.

/* Custom indicators using status2d markup, e.g. enabled via INDICATOR_CUSTOM_3 */
static char *custom_2d_indicator_1 = "^c#00A523^^r0,h,w,2^"; // green underline
static char *custom_2d_indicator_2 = "^c#55cdfc^^r3,3,4,4^^c#E72608^^r4,4,2,2^"; // blue rectangle
static char *custom_2d_indicator_3 = "^f-10^^c#E72608^𐄛"; // example using a character as an indicator
static char *custom_2d_indicator_4 = "^c#E26F0B^^r0,h,w,1^^r0,0,1,h^^r0,0,w,1^^rw,0,1,h^"; // orange box
static char *custom_2d_indicator_5 = "^c#CB9700^^r0,h,w,1^^r0,0,w,1^"; // top and bottom lines
static char *custom_2d_indicator_6 = "^c#F0A523^^r6,2,1,-4^^r-6,2,1,-4^"; // orange vertical bars

These are custom indicators that are using the status2d markup for special effects.

Refer to the Bar Indicators page.

/* The below are only used if the WorkspaceLabels functionality is enabled */
static char *occupied_workspace_label_format = "%s: %s";     /* format of a workspace label */
static char *vacant_workspace_label_format = "%s";           /* format of an empty / vacant workspace */
static int lowercase_workspace_labels = 1;                   /* whether to change workspace labels to lower case */
static int prefer_window_icons_over_workspace_labels = 0;    /* whether to use window icons instead of labels if present */
static int swap_occupied_workspace_label_format_strings = 0; /* 0 gives "icon: label", 1 gives "label: icon" */

These settings influence how workspace labels are presented.

Refer to the WorkspaceLabels functionality page for more details.

/* This determines what happens with pinned workspaces on a monitor when that monitor is removed.
 *   0 - the workspaces becomes unpinned and is moved to another monitor or
 *   1 - the workspace clients are moved to the selected workspace on the first monitor, but
 *       the workspace itself is hidden
 *
 * Non-pinned workspaces are always redistributed among the remaining monitors.
 */
static const int workspaces_per_mon = 0;

This configuration option controls how pinned workspaces are handled when the monitor they are on is removed.

The default behaviour is that the workspace becomes unpinned and is moved to another monitor.

If workspaces_per_mon is set to 1 then pinned workspaces will be hidden from view and any clients on these workspaces will be moved to the selected workspace on the first monitor.

In either case if the monitor comes back again then the workspaces will be moved back to that monitor provided that the workspace is pinned to the designated monitor in the workspace rules.

The workspaces_per_mon feature is specifically intended for the instructions in this guide.

static uint64_t functionality = 0
//	|AutoReduceNmaster // automatically reduce the number of master clients if one is closed
//	|SmartGaps // enables no or increased gaps if there is only one visible window
//	|SmartGapsMonocle // enforces no gaps in monocle layout
	|Systray // enables a systray in the bar
	|Swallow // allows X applications started from the command line to swallow the terminal
	...
;

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.

static int flexwintitle_masterweight     = 15; // master weight compared to hidden and floating window titles
static int flexwintitle_stackweight      = 4;  // stack weight compared to hidden and floating window titles
static int flexwintitle_hiddenweight     = 0;  // hidden window title weight
static int flexwintitle_floatweight      = 0;  // floating window title weight, set to 0 to not show floating windows
static int flexwintitle_separator        = borderpx; // width of client separator

The flexwintitle weights control the size of window titles in the bar. This allows for the window title of a master client to be bigger than that of stack clients as an example.

A weight of 0 means above means that hidden and floating windows will not be drawn alongside tiled master and stack window titles.

The flexwintitle_separator value controls the amount of space between window titles in the bar.

Refer to the flexwintitle page for more details.

static const char *fonts[]               = { "monospace:size=10" };
static       char dmenufont[60]          = "monospace:size=10";

The fonts config is a list of font names that the window manager will use for displaying text on the bar.

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

The dmenu colours define the colours used when opening dmenu from within the window manager.

static char dmenunormfgcolor[] = "#D9CFC5";
static char dmenunormbgcolor[] = "#492B2D";
static char dmenuselfgcolor[] = "#D9CFC5";
static char dmenuselbgcolor[] = "#82363A";
static char dmenubordercolor[] = "#492B2D";

These variables are used in the dmenucmd command and can be overwritten using Xresources.

/* Xresources preferences to load at startup. */
static const ResourcePref resources[] = {
	{ "dmenunormfgcolor", STRING, &dmenunormfgcolor },
	{ "dmenunormbgcolor", STRING, &dmenunormbgcolor },
	{ "dmenuselfgcolor", STRING, &dmenuselfgcolor },
	{ "dmenuselbgcolor", STRING, &dmenuselbgcolor },
	{ "dmenu.border.bg.color", STRING, &dmenubordercolor },
	{ "dmenufont", STRING, &dmenufont },
};

The Xresource preferences contain additional variables whose values can be overridden by data in Xresources.

/* Default opacity levels         fg      bg     border */
unsigned int default_alphas[] = { OPAQUE, 0xd0U, OPAQUE };

This configuration controls the opacity levels of colours used in the bar and the setting above defines the (default) opacity levels for all colour schemes.

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).

The client border colour transparency is by default opaque.

Should you have a use case for having different opacity levels depending on the colour scheme then it is possible to achieve this using Xresources.

static char *colors[SchemeLast][4] = {
	/*                       fg         bg         border    */
	[SchemeNorm]         = { "#D9CFC5", "#492B2D", "#492B2D" },
	[SchemeTitleNorm]    = { "#D9CFC5", "#492B2D", "#643B3E" },
	[SchemeTitleSel]     = { "#D9CFC5", "#82363A", "#82363A" },
	[SchemeScratchNorm]  = { "#D9CFC5", "#492B2D", "#643B3E" },
	[SchemeScratchSel]   = { "#D9CFC5", "#82363A", "#82363A" },
	[SchemeHidNorm]      = { "#D9CFC5", "#492B2D", "#000000" },
	[SchemeHidSel]       = { "#D9CFC5", "#82363A", "#000000" },
	[SchemeUrg]          = { "#E0E0E0", "#A23419", "#A23419" },
	[SchemeMarked]       = { "#DDC470", "#724559", "#724559" },
	[SchemeWsNorm]       = { "#D9CFC5", "#492B2D", "#000000" },
	[SchemeWsVisible]    = { "#D9CFC5", "#82363A", "#000000" },
	[SchemeWsSel]        = { "#D9CFC5", "#82363A", "#000000" },
	[SchemeWsOcc]        = { "#D9CFC5", "#492B2D", "#000000" },
};

The colors array defines the colours used in the bar and in the window border.

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

Optionally, the fourth column can define a resource prefix that will be used in relation to loading colour schemes via Xresources. The built-in colour schemes will fall back to internal defaults when it comes to resource prefixes hence they are not included in the configuration above.

Should you need to add your own custom colour schemes then you can do so by expanding on the corresponding enum in dusk.c. Start by searching for "SchemeNorm". There is also a guide that will walk you through that.

/* List of programs to start automatically during startup only. Note that these will not be
 * executed again when doing a restart. */
static const char *const autostart[] = {
//	"st", NULL,
	NULL /* terminate */
};

/* List of programs to start automatically during a restart only. These should usually be short
 * scripts that perform specific operations, e.g. changing a wallpaper. */
static const char *const autorestart[] = {
	NULL /* terminate */
};

The autostart array is a list of programs that are to start automatically alongside the window manager when it initially starts. The autorestart array are specifically for commands that are to be executed following a restart of the window manager.

Refer to the autostart feature.

static const Rule clientrules[] = {
	...
	{ .class = "Xephyr", .flags = NoSwallow|Floating|Centered },
	{ .title = "Event Tester", .flags = NoSwallow },
};

The clientrules settings is a list of application specific rules that should apply when programs start.

Refer to the Client Rules page.

static const BarDef bars[] = {
	/* monitor idx  vert   x     y      w     h     name  */
	{  0,      0,   0,    "0%    0%     100% -1h ", "Primary top" },
	{  0,      1,   0,    "0%    100%   100% -1h ", "Primary bottom" },
	...
};

The bars setting defines the bars that are present on which monitors as well as their size and position.

You generally do not need to make any changes here unless you are specifically looking to experiment with smaller separate bars.

Refer to the Bar topic and the Bar Placement page.

static const BarRule barrules[] = {
	/* monitor  bar    scheme   lpad rpad value  alignment        sizefunc         drawfunc         clickfunc         hoverfunc         name */
	{ -1,       0,     0,       0,   5,   0,     BAR_ALIGN_LEFT,  size_workspaces, draw_workspaces, click_workspaces, hover_workspaces, "workspaces" },
	{ 'A',      0,     0,       5,   5,   0,     BAR_ALIGN_RIGHT, size_systray,    draw_systray,    click_systray,    NULL,             "systray" },
	...
};

While the bars config determines the size and position of the bars the bar rules control which bar modules are included on a bar as well as their placement.

Refer to the Bar topic and the Bar Rules page.

static const WorkspaceRule wsrules[] = {
	/*                                                                     ------------------------------- schemes ------------------------------- ------ icons ------
	   name,  monitor,  pinned,  layout,  mfact,  nmaster,  nstack,  gaps, default,          visible,          selected,         occupied,         def,   vac,  occ,  */
	{  "1",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "1",   "",   "[1]", },
	{  "2",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "2",   "",   "[2]", },
	...
};

The workspace rules defines the workspaces that are available, which monitor they are initially assigned to and whether the workspace is pinned to that monitor.

Additionally the rules specify the icons used for the workspace as well as the initial layout.

Refer to the Workspaces topic for more details.

static const float mfact = 0.50;  /* factor of master area size [0.05..0.95] */

The mfact (master area factor) value controls the size of the master area compared to the stack area in most layouts.

The value is restricted to be between 0.05 to 0.95 (5% to 95%) of the workspace area.

The default value here is used when the workspace rules has an mfact value of -1.

Refer to the setmfact and dragmfact functions.

The cfact (client factor) value controls the size of tiled windows respective to other clients within the same area (master, stack, secondary stack area) in many layouts.

The value defaults to 1.0 for all new clients and there are no configuration options with regards to this.

Not all layout arrangements support client factors.

Refer to the setcfact and dragcfact functions.

The wfact (workspace factor) value controls the size of a workspace respective to other workspaces when viewing more than one at the same time.

The value defaults to 1.0 for all workspaces and there are no configuration options with regards to this.

Refer to the setwfact and dragwfact functions.

static const int nmaster = 1;  /* number of clients in master area */

The nmaster (number of master) value determines the number of clients that are to be placed in the master area of most layouts.

The default value here is used when the workspace rules has an nmaster value of -1.

Refer to the incnmaster function.

static const int nstack = 0;  /* number of clients in primary stack area */

The nstack (number of stack) value determines the number of clients in the primary stack area for dual stack layouts.

The default value here is used when the workspace rules has an nstack value of -1.

Refer to the incnstack function.

static const int enablegaps = 1;  /* whether gaps are enabled by default or not */

The enablegaps value determines whether gaps between tiled windows are shown or not.

The default value here is used when the workspace rules has an gaps value of -1.

Refer to the Gaps topic and the togglegaps function.

/* layout(s) */
static const Layout layouts[] = {
	/* symbol     arrange function, { nmaster, nstack, layout, master axis, stack axis, secondary stack axis, symbol func }, name */
	{ "[]=",      flextile,         { -1, -1, SPLIT_VERTICAL, TOP_TO_BOTTOM, TOP_TO_BOTTOM, 0, NULL }, "tile" },
	{ "|||",      flextile,         { -1, -1, NO_SPLIT, LEFT_TO_RIGHT, LEFT_TO_RIGHT, 0, NULL }, "columns" },
	{ "===",      flextile,         { -1, -1, NO_SPLIT, TOP_TO_BOTTOM, TOP_TO_BOTTOM, 0, NULL }, "rows" },
	{ "[M]",      flextile,         { -1, -1, NO_SPLIT, MONOCLE, MONOCLE, 0, NULL }, "monocle" },
	{ "||=",      flextile,         { -1, -1, SPLIT_VERTICAL, LEFT_TO_RIGHT, TOP_TO_BOTTOM, 0, NULL }, "col" },
	{ ">M>",      flextile,         { -1, -1, FLOATING_MASTER, LEFT_TO_RIGHT, LEFT_TO_RIGHT, 0, NULL }, "floating master" },
	{ "[D]",      flextile,         { -1, -1, SPLIT_VERTICAL, TOP_TO_BOTTOM, MONOCLE, 0, NULL }, "deck" },
	{ "TTT",      flextile,         { -1, -1, SPLIT_HORIZONTAL, LEFT_TO_RIGHT, LEFT_TO_RIGHT, 0, NULL }, "bstack" },
	{ "===",      flextile,         { -1, -1, SPLIT_HORIZONTAL, LEFT_TO_RIGHT, TOP_TO_BOTTOM, 0, NULL }, "bstackhoriz" },
	{ "==#",      flextile,         { -1, -1, SPLIT_HORIZONTAL, TOP_TO_BOTTOM, GAPPLESSGRID_CFACTS, 0, NULL }, "bstackgrid" },
	{ "|M|",      flextile,         { -1, -1, SPLIT_CENTERED_VERTICAL, LEFT_TO_RIGHT, TOP_TO_BOTTOM, TOP_TO_BOTTOM, NULL }, "centeredmaster" },
	{ "-M-",      flextile,         { -1, -1, SPLIT_CENTERED_HORIZONTAL, TOP_TO_BOTTOM, LEFT_TO_RIGHT, LEFT_TO_RIGHT, NULL }, "centeredmaster horiz" },
	{ ":::",      flextile,         { -1, -1, NO_SPLIT, GAPPLESSGRID_CFACTS, GAPPLESSGRID_CFACTS, 0, NULL }, "gappless grid" },
	{ "[\\]",     flextile,         { -1, -1, NO_SPLIT, DWINDLE_CFACTS, DWINDLE_CFACTS, 0, NULL }, "fibonacci dwindle" },
	{ "(@)",      flextile,         { -1, -1, NO_SPLIT, SPIRAL_CFACTS, SPIRAL_CFACTS, 0, NULL }, "fibonacci spiral" },
	{ "[T]",      flextile,         { -1, -1, SPLIT_VERTICAL, LEFT_TO_RIGHT, TATAMI_CFACTS, 0, NULL }, "tatami mats" },
 	{ "><>",      NULL,             { -1, -1 }, "floating" }, /* no layout function means floating behavior */
};

This defines the predefined layouts that are available in the window manager.

For more information about how the symbol is used refer to the LtSymbol bar module.

For the rest refer to the Layout topic.

#define Shift ShiftMask
#define Ctrl ControlMask
#define Alt Mod1Mask
#define AltGr Mod3Mask
#define Super Mod4Mask
#define ShiftGr Mod5Mask

These are merely helper macros that makes keybindings easier to both manage and read.

As an example this allows for Alt to be used instead of Mod1Mask.

/* key definitions */
#define MODKEY Super

The MODKEY macro is the default modifier that is used for most keybindings.

The macro is intended to make things somewhat easier if one wants to change the default modifier key.

#define SCRATCHKEYS(MOD,KEY,CMD) \
	{ KeyPress,   MOD,                      KEY,      togglescratch,     {.v = CMD } }, \
	{ KeyPress,   MOD|Ctrl,                 KEY,      setscratch,        {.v = CMD } }, \
	{ KeyPress,   MOD|Ctrl|Shift,           KEY,      removescratch,     {.v = CMD } }, \

The SCRATCHKEYS macro makes it easier to set up repeating keybindings that are to be the same for all scratchpads.

This is used in the keys section.

	SCRATCHKEYS(MODKEY, XK_w, spcmd1)
	SCRATCHKEYS(MODKEY, XK_e, spcmd2)
	SCRATCHKEYS(MODKEY, XK_r, spcmd3)

The three calls above will each set up the three keybindings as shown in the macro giving a total of nine keybindings.

Refer to the Scratchpads topic for general information about scratchpads.

#define WSKEYS(MOD,KEY,NAME) \
	{ KeyPress,   MOD,                      KEY,      comboviewwsbyname,   {.v = NAME} }, \
	{ KeyPress,   MOD|Alt,                  KEY,      enablewsbyname,      {.v = NAME} }, \
	{ KeyPress,   MOD|Shift,                KEY,      movetowsbyname,      {.v = NAME} }, \
	{ KeyPress,   MOD|Ctrl,                 KEY,      sendtowsbyname,      {.v = NAME} }, \
	{ KeyPress,   MOD|Ctrl|Shift,           KEY,      movealltowsbyname,   {.v = NAME} }, \
	{ KeyPress,   MOD|Ctrl|Alt,             KEY,      moveallfromwsbyname, {.v = NAME} }, \
	{ KeyPress,   MOD|Ctrl|Alt|Shift,       KEY,      swapwsbyname,        {.v = NAME} }, \

The WSKEYS macro makes it easier to set up repeating keybindings that are to be the same for all workspaces.

This is used in the keys section to set up keybindings for nine workspaces.

	WSKEYS(MODKEY, XK_1, "1")
	WSKEYS(MODKEY, XK_2, "2")
	WSKEYS(MODKEY, XK_3, "3")
	...

The nine calls above will each set up the seven keybindings as shown in the macro giving a total of 63 keybindings.

Also note the alternative WSKEYS macro where MOD+1 through 9 brings you to the nth workspace on the current monitor as outlined in this guide.

Refer to the Workspaces topic.

#define STACKKEYS(MOD,ACTION) \
	{ KeyPress,   MOD, XK_j, ACTION, {.i = INC(+1) } }, \
	{ KeyPress,   MOD, XK_k, ACTION, {.i = INC(-1) } }, \
	{ KeyPress,   MOD, XK_s, ACTION, {.i = PREVSEL } }, \
	{ KeyPress,   MOD, XK_w, ACTION, {.i = 1 } }, \
	{ KeyPress,   MOD, XK_e, ACTION, {.i = 2 } }, \
	{ KeyPress,   MOD, XK_a, ACTION, {.i = 3 } }, \
	{ KeyPress,   MOD, XK_z, ACTION, {.i = LASTTILED } },

The STACKKEYS macro makes it easier to set up repeating keybindings that are similar for stack functions.

This is to be set in the keys section, but is not used by default due to the number of keybindings that it consumes.

//	STACKKEYS(AltGr|Ctrl,       stackfocus)
//	STACKKEYS(AltGr|Ctrl|Shift, stackpush)
//	STACKKEYS(AltGr|Shift,      stackswap)

Refer to the stacker page for more details.

/* This relates to the StackerIcons functionality and should mirror the STACKKEYS list above. */
static const StackerIcon stackericons[] = {
	{ "[j] ", {.i = INC(+1) } },
	{ "[k] ", {.i = INC(-1) } },
	{ "[s] ", {.i = PREVSEL } },
	{ "[w] ", {.i = 1 } },
	{ "[e] ", {.i = 2 } },
	{ "[a] ", {.i = 3 } },
	{ "[z] ", {.i = LASTTILED } },
};

The stackericons array complements the stacker utilities by providing keyboard shortcut hints that are added to client window titles where applicable.

Refer to the StackerIcons functionality for more details.

#define SHCMD(cmd) { .v = (const char*[]){ NULL, "/bin/sh", "-c", cmd, NULL } }

The SHCMD macro is primarily intended for programs that need a shell to run and a typical example of this is htop.

While it is perfectly possible to launch non-terminal programs like gimp using this macro the side effect is that you will have a lingering shell process running in the background for every program you launch.

Refer to the CMD macro below instead.

#define CMD(...) { .v = (const char*[]){ NULL, __VA_ARGS__, NULL } }

The CMD macro can make it easier to add keybindings that launch programs within the window manager.

E.g. instead of using variables and spawning programs like this:

static const char *mycmd[] = {"/path/to/mycmd.sh", "-c", "34", NULL };
...
    { KeyPress,   MODKEY,   XK_m,   spawn,   {.v = mycmd } }, // spawn spawn mycmd

you can do it as part of the keybinding like this:

    { KeyPress,   MODKEY,   XK_m,   spawn,   CMD("/path/to/mycmd.sh", "-c", "34") }, // spawn spawn mycmd

See the commands and scratchpad commands sections below for more information on launching programs within the window manager.

/* Spawn command:                 command, argument, argument, ..., NULL */
static const char *termcmd[]  = { "st", NULL };
static const char *dmenucmd[] = {
	"dmenu_run",
	"-fn", dmenufont,
	"-nb", dmenunormbgcolor,
	"-nf", dmenunormfgcolor,
	"-sb", dmenuselbgcolor,
	"-sf", dmenuselfgcolor,
//	"-bb", dmenubordercolor,
	NULL
};

These define programs that can be started directly from the window manager and by default this includes a launcher (dmenu) and a terminal (st), both of which would need to be installed separately.

The commented out line in the dmenucmd command is to specify the border colour of dmenu if you are using a version that supports that argument.

The first value should be NULL for all commands unless they are scratchpad commands.

Refer to the spawn function.

static const char *spcmd1[] = {"w", "st", "-n", "spterm (w)", "-g", "120x34", NULL };
static const char *spcmd2[] = {"e", "st", "-n", "spterm (e)", "-g", "120x34", NULL };
static const char *spcmd3[] = {"r", "st", "-n", "spfm (r)", "-g", "144x41", "-e", "ranger", NULL };

Scratchpad commands are similar to normal commands with the exception that they also have a single character that identifies them as a specific scratchpad. Additionally a client rule is set up per scratchpad to associate the spawned window with the scratchpad.

Note that the predefined scratchpad commands and associated rules and keybindings are merely examples to show how scratchpads can be set up.

Refer to the Scratchpads topic for further configuration details.

static const char *statusclickcmd[] = { "~/bin/statusbar/statusclick.sh", NULL };

Button clicks that fall on top of statuses on the bar are forwarded to an external script defined by the statusclickcmd command.

Refer to the statusclick function for more information on this.

static Key keys[] = {
	/* type       modifier                      key              function                argument */
	{ KeyPress,   MODKEY,                       XK_d,            spawn,                  {.v = dmenucmd } }, // spawn dmenu for launching other programs
	{ KeyPress,   MODKEY,                       XK_Return,       spawn,                  {.v = termcmd } }, // spawn a terminal
	{ KeyPress,   MODKEY|Shift,                 XK_Return,       riospawn,               {.v = termcmd } }, // draw/spawn a terminal
	{ KeyPress,   MODKEY,                       XK_b,            togglebar,              {0} }, // toggles the display of the bar(s) on the current monitor
	...
};

The keys settings is used by the internal key handler to bind keyboard shortcuts to certain function calls.

Refer to the Key Bindings page for more details.

/* button definitions */
/* click can be ClkButton, ClkWorkspaceBar, ClkLtSymbol, ClkStatusText, ClkWinTitle, ClkClientWin, or ClkRootWin */
static Button buttons[] = {
	/* click                     event mask               button          function          argument */
	{ ClkLtSymbol,               0,                       Button1,        setlayout,        {-1} }, // toggles between current and previous layout
	{ ClkLtSymbol,               0,                       Button4,        cyclelayout,      {.i = +1 } }, // cycle through the available layouts
	...
};

The buttons settings is used by the internal key handler to bind mouse button clicks to certain function calls.

Refer to the Button Bindings page for more details.

static const char *ipcsockpath = "/tmp/dusk.sock";

The ipcsockpath setting determines the file name of the socket that is used for IPC (interprocess communication) in the window manager.

In simple terms this is what allows the dusk client communicate with the window manager.

The location of the socket can be changed if need be, but this should normally not be necessary.

static IPCCommand ipccommands[] = {
	IPCCOMMANDS( customlayout, 8, ARG_TYPE_SINT, ARG_TYPE_STR, ARG_TYPE_SINT, ARG_TYPE_SINT, ARG_TYPE_SINT, ARG_TYPE_SINT, ARG_TYPE_SINT, ARG_TYPE_SINT ),
	IPCCOMMAND( changeopacity, ARG_TYPE_FLOAT ),
	IPCCOMMAND( clienttomon, ARG_TYPE_SINT ),
	...
};

The ipccommands setting is a list functions that will be exposed for the dusk client so that they can be called externally.

You only need to be concerned about making changes here if you are adding your own functions to the window manager and want them callable by the dusk client.

The IPCCOMMAND macro needs to know what function is to be called and what argument type is.

The function signature is expected to be the same as that for normal keybindings, i.e.

void <function>(const Arg *arg)

The argument type is needed for parsing and validation reasons.

The IPCCOMMANDS macro can be used for functions that take more than one argument.

While it is possible to create functions that take more than one argument the use cases for this is very limited.

It should be noted that the signature for such a function is perhaps different to what one might naturally expect:

void <function>(const Arg args[], int num_args)

This means that there is a list of arguments and an integer indicating the number of arguments in this list. Arguments can then be referenced for example via args[2].i or be extracted from the list if named argument variables is preferred.

When using the mouse to perform certain operations like moving windows around, resizing windows or changing the master/stack factor then the refresh rate is by default set to 60 frames per second.

In practice this means that the window manager will only pick up mouse cursor movement notifications at that interval. The number 60 is chosen as good middle ground between smooth operation and that it will still perform well on a low spec computer.

By default end users are not expected to change the refresh rate values, but users with a performant machine and monitors with higher refresh rates may want to increase the refresh rate to e.g. 120Hz.

In general setting a higher refresh rate will make certain operations feel more smooth.

The main risk is that if the handling of a mouse movement notification takes longer than the interval at which the window manager picks them up then the window manager may start to lag behind with an increasing backlog of notifications to pick up.

In dusk it is possible to specify (override) the default refresh rate by adding a macro in the config file:

#define GLOBAL_HZ 120

This will, as the name suggests, change the refresh rate of all mouse operations globally.

Some mouse operations may be heavier computation wise and result in lag when setting a higher refresh rate. As such it is possible to specify the refresh rate on a per function basis so that they can be tuned individually.

#define DRAGCFACT_HZ 60
#define DRAGFACT_HZ 40
#define DRAGMFACT_HZ 40
#define DRAGWFACT_HZ 60
#define MOVEMOUSE_HZ 60
#define PLACEMOUSE_HZ 60
#define RESIZEMOUSE_HZ 60
#define SWALLOWMOUSE_HZ 60
#define MARKMOUSE_HZ 60

For reference the above are used in the following places:

lib/dragcfact.c:           if ((ev.xmotion.time - lasttime) <= (1000 / DRAGCFACT_HZ))
lib/dragfact.c:            if ((ev.xmotion.time - lasttime) <= (1000 / DRAGFACT_HZ))
lib/dragmfact.c:           if ((ev.xmotion.time - lasttime) <= (1000 / DRAGMFACT_HZ))
lib/dragwfact.c:           if ((ev.xmotion.time - lasttime) <= (1000 / DRAGWFACT_HZ))
lib/mark.c:                if ((ev.xmotion.time - lasttime) <= (1000 / MARKMOUSE_HZ))
lib/movemouse.c:           if ((ev.xmotion.time - lasttime) <= (1000 / MOVEMOUSE_HZ))
lib/placemouse.c:          if ((ev.xmotion.time - lasttime) <= (1000 / PLACEMOUSE_HZ))
lib/resizemouse.c:         if ((ev.xmotion.time - lasttime) <= (1000 / RESIZEMOUSE_HZ))
lib/swallowmouse.c:        if ((ev.xmotion.time - lasttime) <= (1000 / SWALLOWMOUSE_HZ))