README.md (5733B)
1 # dwmblocks-async 2 3 A [`dwm`](https://dwm.suckless.org) status bar that has a modular, async 4 design, so it is always responsive. Imagine `i3blocks`, but for `dwm`. 5 6  7 8 ## Features 9 10 - [Modular](#modifying-the-blocks) 11 - Lightweight 12 - [Suckless](https://suckless.org/philosophy) 13 - Blocks: 14 - [Clickable](#clickable-blocks) 15 - Loaded asynchronously 16 - [Updates can be externally triggered](#signalling-changes) 17 - Compatible with `i3blocks` scripts 18 19 > Additionally, this build of `dwmblocks` is more optimized and fixes the 20 > flickering of the status bar when scrolling. 21 22 ## Why `dwmblocks`? 23 24 In `dwm`, you have to set the status bar through an infinite loop, like so: 25 26 ```sh 27 while :; do 28 xsetroot -name "$(date)" 29 sleep 30 30 done 31 ``` 32 33 This is inefficient when running multiple commands that need to be updated at 34 different frequencies. For example, to display an unread mail count and a clock 35 in the status bar: 36 37 ```sh 38 while :; do 39 xsetroot -name "$(mailCount) $(date)" 40 sleep 60 41 done 42 ``` 43 44 Both are executed at the same rate, which is wasteful. Ideally, the mail 45 counter would be updated every thirty minutes, since there's a limit to the 46 number of requests I can make using Gmail's APIs (as a free user). 47 48 `dwmblocks` allows you to divide the status bar into multiple blocks, each of 49 which can be updated at its own interval. This effectively addresses the 50 previous issue, because the commands in a block are only executed once within 51 that time frame. 52 53 ## Why `dwmblocks-async`? 54 55 The magic of `dwmblocks-async` is in the `async` part. Since vanilla 56 `dwmblocks` executes the commands of each block sequentially, it leads to 57 annoying freezes. In cases where one block takes several seconds to execute, 58 like in the mail and date blocks example from above, the delay is clearly 59 visible. Fire up a new instance of `dwmblocks` and you'll see! 60 61 With `dwmblocks-async`, the computer executes each block asynchronously 62 (simultaneously). 63 64 ## Installation 65 66 Clone this repository, modify `config.h` appropriately, then compile the 67 program: 68 69 ```sh 70 git clone https://github.com/UtkarshVerma/dwmblocks-async.git 71 cd dwmblocks-async 72 vi config.h 73 sudo make install 74 ``` 75 76 ## Usage 77 78 To set `dwmblocks-async` as your status bar, you need to run it as a background 79 process on startup. One way is to add the following to `~/.xinitrc`: 80 81 ```sh 82 # The binary of `dwmblocks-async` is named `dwmblocks` 83 dwmblocks & 84 ``` 85 86 ### Modifying the blocks 87 88 You can define your status bar blocks in `config.h`: 89 90 ```c 91 #define BLOCKS(X) \ 92 ... 93 X(" ", "wpctl get-volume @DEFAULT_AUDIO_SINK@ | cut -d' ' -f2", 0, 5) \ 94 X(" ", "date '+%H:%M:%S'", 1, 1) \ 95 ... 96 ``` 97 98 Each block has the following properties: 99 100 | Property | Description | 101 | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | 102 | Icon | An icon you wish to prepend to your block output. | 103 | Command | The command you wish to execute in your block. | 104 | Update interval | Time in seconds, after which you want the block to update. If `0`, the block will never be updated. | 105 | Update signal | Signal to be used for triggering the block. Must be a positive integer. If `0`, a signal won't be set up for the block and it will be unclickable. | 106 107 Apart from defining the blocks, features can be toggled through `config.h`: 108 109 ```c 110 // String used to delimit block outputs in the status. 111 #define DELIMITER " " 112 113 // Maximum number of Unicode characters that a block can output. 114 #define MAX_BLOCK_OUTPUT_LENGTH 45 115 116 // Control whether blocks are clickable. 117 #define CLICKABLE_BLOCKS 1 118 119 // Control whether a leading delimiter should be prepended to the status. 120 #define LEADING_DELIMITER 0 121 122 // Control whether a trailing delimiter should be appended to the status. 123 #define TRAILING_DELIMITER 0 124 ``` 125 126 ### Signalling changes 127 128 Most status bars constantly rerun all scripts every few seconds. This is an 129 option here, but a superior choice is to give your block a signal through which 130 you can indicate it to update on relevant event, rather than have it rerun 131 idly. 132 133 For example, the volume block has the update signal `5` by default. I run 134 `kill -39 $(pidof dwmblocks)` alongside my volume shortcuts in `dwm` to only 135 update it when relevant. Just add `34` to your signal number! You could also 136 run `pkill -RTMIN+5 dwmblocks`, but it's slower. 137 138 To refresh all the blocks, run `kill -10 $(pidof dwmblocks)` or 139 `pkill -SIGUSR1 dwmblocks`. 140 141 > All blocks must have different signal numbers! 142 143 ### Clickable blocks 144 145 Like `i3blocks`, this build allows you to build in additional actions into your 146 scripts in response to click events. You can check out 147 [my status bar scripts](https://github.com/UtkarshVerma/dotfiles/tree/main/.local/bin/statusbar) 148 as references for using the `$BLOCK_BUTTON` variable. 149 150 To use this feature, define the `CLICKABLE_BLOCKS` feature macro in your 151 `config.h`: 152 153 ```c 154 #define CLICKABLE_BLOCKS 1 155 ``` 156 157 Apart from that, you need `dwm` to be patched with 158 [statuscmd](https://dwm.suckless.org/patches/statuscmd/). 159 160 ## Credits 161 162 This work would not have been possible without 163 [Luke's build of dwmblocks](https://github.com/LukeSmithxyz/dwmblocks) and 164 [Daniel Bylinka's statuscmd patch](https://dwm.suckless.org/patches/statuscmd/).