How to integrate dwmblocks with click support

[bakkeby]

dwmblocks is a standalone piece of software that has to be installed separately.

When it comes to dwmblocks and click support it is worth having some understanding of how the click handling works and how that has evolved over time.

The original statuscmd patch would execute a series of predefined commands as configured in config.h - this is what is now referred to the "nosignal" variants of the statuscmd patch.

When click support for dwmblocks was introduced this used SIGUSR1 kill signals and later this was changed to use SIGRTMIN (real time) kill signals instead - this means that there are two sets of patches out there for both dwm and for dwmblocks and they work differently.

Below are instructions on how to set up both versions.

SIGRTMIN

Building dwmblocks:

• take the original torrinfail dwmblocks as a base
• apply the dwmblocks-statuscmd-20210402-96cbb45.diff patch from the suckless statuscmd page

dwm-flexipatch enable these patches:

• BAR_DWMBLOCKS_PATCH
• BAR_STATUSCMD_PATCH

dwm:

• apply the statuscmd (or statuscmd-status2d version) patch from the suckless statuscmd page

dwmblocks scripts:

• note that these use the $BUTTON environment variable to indicate mouse clicks

SIGUSR1

Building dwmblocks:

• take the original torrinfail dwmblocks as a base
• apply the dwmblocks-statuscmd-b6b0be4.diff patch listed on that page
• or use Luke Smith's build of dwmblocks

dwm-flexipatch enable these patches:

• BAR_DWMBLOCKS_PATCH
• BAR_DWMBLOCKS_SIGUSR1_PATCH
• BAR_STATUSCMD_PATCH

dwm:

• apply the statuscmd (or statuscmd-status2d version) patch from the suckless statuscmd page
• change the sigstatusbar function to use SIGUSR1 signals rather than SIGRTMIN referring to this difference:

  dwm-flexipatch/patch/bar_dwmblocks.c

  Lines 38 to 49 in 96820b2

  	#if BAR_DWMBLOCKS_SIGUSR1_PATCH
  	sv.sival_int = (statussig << 8) | arg->i;
  	if (sigqueue(statuspid, SIGUSR1, sv) == -1) {
  	if (errno == ESRCH) {
  	if (!getstatusbarpid())
  	sigqueue(statuspid, SIGUSR1, sv);
  	}
  	}
  	#else
  	sv.sival_int = arg->i;
  	sigqueue(statuspid, SIGRTMIN+statussig, sv);
  	#endif // BAR_DWMBLOCKS_SIGUSR1_PATCH

dwmblocks scripts:

• note that these use the $BLOCK_BUTTON environment variable to indicate mouse clicks

Configuration

dwm

In general you should not need to make any changes to the configuration in dwm, but here are the options.

You only need to change this if the executable has a name other than "dwmblocks".

dwm-flexipatch/config.def.h

Lines 818 to 819 in 96820b2

	/* This defines the name of the executable that handles the bar (used for signalling purposes) */
	#define STATUSBAR "dwmblocks"

This you only need to change if you are adding support for additional buttons, e.g. 4 and 5 for mouse wheel.

dwm-flexipatch/config.def.h

Lines 1261 to 1263 in 96820b2

	{ ClkStatusText, 0, Button1, sigstatusbar, {.i = 1 } },
	{ ClkStatusText, 0, Button2, sigstatusbar, {.i = 2 } },
	{ ClkStatusText, 0, Button3, sigstatusbar, {.i = 3 } },

The integer value passed here represents the mouse button where 1 is left click, 2 is right click, 3 is middle click, etc. This has nothing to do with the blocks or the signals sent to dwmblocks. If desired one could for example send 71 as the value to indicate that the left mouse button was clicked while shift was held down, which could be used to add special behaviour on the script side.

	{ ClkStatusText,        ShiftMask,           Button1,        sigstatusbar,   {.i = 71 } },

dwmblocks

Blocks are defined as:

static const Block blocks[] = {
    /*Icon*/ /*Command*/                               /*Interval*/ /*Signal*/
    {"",     "/path/to/volume.sh",                        1,          4},
    {"",     "/path/to/date.sh",                          1,          3},
    {"",     "/path/to/cputemp.sh",                       1,          2},
    {"",     "/path/to/die.sh",                          30,          1},
};

The command is either an inline command or more commonly referring to a shell script when click handling is involved. Make sure that your shell scripts are marked as being executable. The interval represents how often the command should run, in seconds, while the signal is used in relation to force updating a particular block. In a patched dwmblocks the signal value is included at the start of each block in the final output string and is later stripped out by dwm for display purposes, but are taken into account when determining which block the user clicked on.

A signal with value of 0 means no signal, which ultimately means no click support. Make sure to use unique signals for each of your blocks and values less than 30 (which is the space character).

The delim setting defines the delimiter used between blocks. The delimLen represents the length of the delimiter which for some reason is not derived at runtime.

static char delim[] = " | ";
static unsigned int delimLen = 5;

Example dwmblocks script with click support:

#!/bin/sh

if [ ! -z $BUTTON ]; then
    case ${BUTTON} in
    1) notify-send -t 3000 "$(date)" & ;;
    *) notify-send -t 2000 "clock ${BUTTON}" & ;;
    esac
fi

echo "$(date +%T)"

The catch all notify-send is by no means necessary, but is convenient when testing button clicks.

To force-update a specific block as part of a script, e.g. to have the bar update when the volume changes, a kill signal will have to be sent to dwmblocks.

pkill -RTMIN+2 dwmblocks

The 2 above refers to the update signal as configured in dwmblocks, so if the block has an update signal of 6 then use -RTMIN+6.

Common issues

Here are some common issues in relation to using dwmblocks.

When combined with status2d - the status is cut off or dwm crashing

dwmblocks by default outputs a status that is capped at 50 characters, refer to this line in dwmblocks.c. Increase this as you see fit.

#define CMDLENGTH		50

Note that the status2d patch for dwm has poor handling of incomplete markup which can result in dwm crashing when trying to create colours that are invalid.

Blocks unrelated to the block that was clicked goes missing until the next update

This can happen if a block (script) was executing when the kill signal related to the mouse click was received by dwmblocks. It is unclear whether this has something to do with using SIGRTMIN signals rather than SIGUSR1, but Luke Smith's build of dwmblocks seems to not have this issue.

Clicks are not working

There are many cogs in play here so this could be due to a lot of things, e.g.

• not having a patched dwmblocks that can handle signals
• using a SIGUSR1 version of dwmblocks with a SIGRTMIN version of dwm or vice versa
• not using the right environment variable ($BLOCK_BUTTON or $BUTTON) in dwmblocks scripts depending on whether the SIGUSR1 or SIGRTMIN patch was used
• not having set an update signal for the script in dwmblocks' blocks configuration
• having duplicate update signals in dwmblocks' blocks configuration (causes only the first block to trigger)
• having changed the values for the sigstatusbar button handlers in dwm config to something that the dwmblocks script does not handle

Note that update signals are essentially inserted as control characters in the dwmblocks output and some signals such as 10 (newline) and 13 (carriage return) may potentially cause issues depending on how the text is handled, but in general this should not be an issue. Try other signals if in doubt and refer to an ASCII table for what the control characters actually mean.

Clicks are misaligned

This typically happens when one tries to incorporate other patches that affect the position of the status and not having discrepancies between what the drawbar function draws and what the buttonpress function calculates having been drawn. Keep in mind that the bar is drawn in full in one go which means that it draws the status on the right, then it draws the tags on the left, the layout symbol and then the window titles. The buttonpress function tries to calculate what the user clicked on by going through the same process by calculating the width of each tag, etc.

Users most commonly have these kind of issues when trying to incorporate the systray or barpadding patches as these affects the width of the bar. You break it, you buy it.