README (12897B)
1 swm - Σ Window Manager 2 ====================== 3 swm is [dwm](https://dwm.suckless.org) made less bare-boned and more 4 customizable. 5 6 7 Install & Run 8 ------------- 9 libX11, libXft, and optionally libXinerama are required. Edit config.mk 10 to match your local setup, and then build and install swm with the 11 following command (as root if necessary): 12 13 make install 14 15 The default installation directory is /usr/local/bin. 16 17 You may add the following line to your .xinitrc to start swm using startx: 18 19 exec swm 20 21 But be warned that this new software might not yet be sufficiently 22 crash-proof, so, for now, it's probably better to instead add something 23 like this: 24 25 swm || dwm 26 27 This way a reliable window manager like dwm in this example can take 28 over windows upon abnormal termination of swm. 29 30 swm sends warnings and errors to stderr, so having its stderr logged 31 might sometimes prove helpful. 32 33 34 Quick Start 35 ----------- 36 swm grabs any key with, by default, mod4 as a modifier, which is normally 37 produced by the Super key. This can be changed in config.h. For the 38 rest of the section Super is assumed to be the modifier key for swm. 39 40 - Super+Enter: Spawn st, the suckless terminal. 41 42 - Super+p: Launch other programs with dmenu. 43 44 - Super+Backspace: Close the focused window. 45 46 - Super+{j,k}: Focus the next/previous window. 47 48 - Super+Shift+{j,k}: Shift the focused window. 49 50 - Super+*n*: switch to the *n*th workspace. 51 52 - Super+Shift+*n*: Tag the focused window with tag *n*; usually has the 53 effect of sending the window to the *n*th workspace. 54 55 - Super+{t,m}: Switch to the tiled (a.k.a. right stack) or monocle layout. 56 57 - Super+y: Select from a list of layouts with dmenu; you can even make 58 a new layout using this menu, but more on that later. 59 60 - Super+{i,d}: Increase/Decrease the number of master area windows; if 61 you don't already know the meaning, just try with a few windows in 62 the default layout. 63 64 - Super+{h,l}: Change the portion of master area. 65 66 - Super+f: Toggle whether the focused window is fullscreen. 67 68 - Super+Shift+{q,r}: Quit/Restart swm. 69 70 If you use multiple monitors and don't disable Xinerama, these are 71 also useful: 72 73 - Super+], Super+[: Switch to the next/previous monitor. 74 75 - Super+Shift+], Super+Shift+[: Send the focused window to the 76 next/previous monitor. 77 78 Using the mouse, you can press Super+Button1 to move a window and 79 Super+Button3 to resize. These will make the window floating. You can 80 press Super+Shift+Space to toggle the floating state of a window. 81 82 More can be learnt from config.c. 83 84 85 Configuration 86 ------------- 87 config.c and config.h are provided for configuration. Few options 88 are contained in config.h, and everything else, including key bindings 89 and colors etc. belong to config.c, a small separate compilation unit. 90 This way rebuilding swm after changing key bindings etc. is much more 91 efficient compared to dwm where changing any configuration requires 92 recompilation of the whole program. 93 94 Unlike dwm, key bindings are defined directly inside the key event 95 handler, and mouse button bindings inside the button event handler, 96 instead of arrays searched by the handlers. This different approach is 97 taken for greater flexibility. 98 99 With keybindings defined directly in a function, it's complicated for swm 100 to grab exactly the keys and buttons that are bound like dwm does, so, 101 to be simple, swm grabs any key or button with the configured modifier, 102 but this prevents the modifier from being shared with other graphical 103 programs. This issue is discussed next. 104 105 106 Tips about Modifier Keys 107 ------------------------ 108 The Alt key is probably the handiest modifier key on a typical keyboard, 109 but using it with swm will prevent other graphical program from using it. 110 You may do just that and live with the exclusiveness, or you may stick 111 with using Super, which is generally not used by other graphical programs, 112 if you don't mind the relative inconvenience; these are the two obvious 113 options. But here is a recommended third way: Turn Caps Lock into Super. 114 115 You can turn Caps Lock into Super with this command: 116 117 xmodmap -e 'remove Lock = Caps_Lock' \ 118 -e 'keysym Caps_Lock = Super_L Caps_Lock' 119 120 This will still allow toggling all-caps by pressing Shift+Caps_Lock. 121 Put the command in .xinitrc to automate it. 122 123 If you also would like to use Caps Lock for Escape (sweet for vi users), 124 do the two usages conflict? They don't have to, with the help of 125 [xcape](https://github.com/alols/xcape). The following will make Caps 126 Lock, now a surrogate Super key, function as Escape when pressed and 127 released on its own: 128 129 xcape -e Super_L=Escape 130 131 xcape should be run after the xmodmap command. 132 133 If xcape is used with xmodmap as described above, Shift+Caps_Lock will 134 generate an Escape besides toggling all-caps. You can fix that little 135 problem by changing the xmodmap command above to this: 136 137 xmodmap -e 'remove Lock = Caps_Lock' \ 138 -e 'keysym Caps_Lock = Super_L' \ 139 -e 'keysym Escape = Escape Caps_Lock' 140 141 Be aware that there is a small issue with using Caps Lock as Super: Some 142 keyboards have a problem with certain modifier combinations when using 143 such a surrogate Super key. So you might find it necessary to resort to 144 the original Super key for, e.g., Super+Shift+2. Modifier combinations 145 are typically easier with the original Super key, anyway. 146 147 148 Workspaces & Tags 149 ----------------- 150 There are as many workspaces as there are tags. You can select one 151 workspace at a time, which contains a separate layout and a separate 152 set of tags. Every window can be assigned one or more tags just like 153 in dwm, and a workspace's tag set is used to match windows by tags. 154 Windows matched by the tag set of a workspace belong, non-exclusively, 155 to the workspace. 156 157 To compare, dwm has one layout and one tag set per (logical) monitor, 158 and what feels sort of like switching between workspaces in dwm is 159 actually setting the tag set to comprise only a specific tag. You can 160 put multiple tags in the tag set, but the selected tags are easily 161 lost during switching between tags, making selecting multiple tags a 162 less usable feature. Besides, this design makes things like one layout 163 "per tag" not quite well-defined. So swm slightly enhanced the design to 164 address these problems. Initially, the tag set of each workspace contains 165 a single tag that has the same index as the workspace, making selecting 166 a workspace in swm works much like viewing a specific tag in dwm. 167 168 The array of tags displayed on the status bar is dually used for tags 169 and workspaces. The current workspace is indicated by a bold underline, 170 and the tag set of the workspace and tags of windows are indicated in 171 the same way as indicated in dwm: Tags in the current tag set are colored 172 differently, and tags that are applied to one or more windows are marked, 173 in their upper left corner, by a little square, which is filled if the 174 tag is applied to the focused window and empty otherwise. 175 176 177 Restarting 178 ---------- 179 Taking the dwm approach, you have to rebuild and restart swm for new 180 configurations to take effect. By default you can press Super+Shift+r 181 to restart swm. During restarting, swm executes the command that starts 182 it and uses environment variables (later cleared by the new instance) 183 to pass down certain runtime information, including: 184 185 - The monitor each client belongs to 186 - Order of clients in each monitor 187 - Tags and state (floating/fullscreen/scratchpad) of each client 188 - Tag set and layout in each workspace of each monitor 189 - Whether gaps and bar are shown in each monitor 190 - Each monitor's current workspace 191 - The focused client 192 193 These help provide a seamless transition and make reconfiguration like 194 a breeze. 195 196 197 Status Program 198 -------------- 199 swm runs a status program configured in config.c and uses pipes to connect 200 to the status program's input and output. Every time the status program 201 outputs a line, the line is taken as the new status text and displayed on 202 the status bar. swm talks to the status program by writing to its input. 203 204 This is quite different from how dwm handles status. dwm reads the 205 WM_NAME property of the root window for status text. This simplifies the 206 window manager's main loop, but makes it uneasy for the window manager 207 to talk to the status program, adds a little burden to the status program 208 and is less efficient. 209 210 swm recognizes status text as blocks separated by two or more consecutive 211 spaces. When a block displayed on the status bar is clicked, swm's 212 button event handler by default writes to the status program a line 213 indicating which block is clicked (1 for the rightmost, 2 for the second 214 rightmost, etc.), which button is pressed, and which modifiers are on. 215 Details of what gets written can be found or changed in config.c. 216 217 The status program can be toggled on and off with Super+Shift+s by 218 default. Pressing the key twice has the effect of restarting the status 219 program. By turning the status program off, swm doesn't directly kill 220 it but closes the pipe to its input, and the status program is expected 221 to detect this condition. 222 223 The status program that swm by default is configured to use is 224 [infobar](https://wolog.xyz/repos/infobar). 225 226 227 Scratchpads 228 ----------- 229 Scratchpads are windows, typically floating and centered, that can be 230 handily brought into and out of view. In swm, any window can be marked 231 a scratchpad. Here are the related default key bindings: 232 233 - `Super+'`: Toggle a scratchpad. If visible scratchpads are present, 234 the topmost is hidden; otherwise, the topmost hidden scratchpad 235 (normally the most recently used) is brought into view. If there is 236 no scratchpad at all, a scratchpad terminal is launched. 237 238 - `Super+.`: Cycle through all hidden scratchpads. If the focused window 239 is a scratchpad, it gets replaced by the next hidden scratchpad, if 240 any; otherwise this just brings a hidden scratchpad, if there is one, 241 into view. 242 243 - Super+Shift+Enter: Launch the scratchpad terminal. 244 245 - Super+<backtick>: Toggle whether a window is a scratchpad or not. 246 A floating window gets centered when turned into a scratchpad. 247 248 The basic usage is simply to toggle a scratchpad terminal on and off 249 by pressing `Super+'`, but you're offered convenience to develop more 250 sophisticated usages. 251 252 253 Layout Description Language 254 --------------------------- 255 The layout description language is a tiny language invented for 256 specification of layouts in swm. Most layouts that can be found in 257 dwm and its patches can be described quite well in this language. Here 258 are examples: 259 260 - Right stack (the default tiled layout): 261 262 [*]:.55 [] 263 264 - Monocle: 265 266 () 267 268 - Deck: 269 270 [*]:.55 () 271 272 - Bottom stack: 273 274 [{*}:.55 {}] 275 276 - Fibonacci spiral: 277 278 .62 [.62 -{.62 [.62 ()]}] 279 280 - Fibonacci dwindle: 281 282 .62 [.62 {.62 [.62 ()]}] 283 284 (The last two examples are not actually exact, as the actual layouts 285 described will tile the 5th and subsequent windows in the monocle manner.) 286 287 dwm's notions of master number and master factor are defined more 288 generically in swm. Generally, changing them in swm works the way most 289 dwm users would expect. 290 291 The language is simple enough that you can probably gain intuition 292 from the examples and then figure it out by experimenting (see the next 293 section for an easy method). 294 295 296 dmenu Integration 297 ----------------- 298 First of all, in case you only think of dmenu as a fuzzy single-item 299 selector: You can pick multiple items, and even pick an item multiple 300 times, with Ctrl+Enter while navigating the menu using Ctrl+{n,p}; you 301 can also use dmenu as an input box, where Tab can be used to copy an 302 item, a bit of line editing capability is available, and the input can 303 be confirmed by pressing Shift+Enter. 304 305 In swm, by default, pressing Super+y runs dmenu to give you a menu of 306 layout descriptions to choose from, where you may also write an ad-hoc 307 layout or tweak an existing one. 308 309 swm provides four types of gaps (internal/outer, horizontal/vertical) that 310 are separately settable. Pressing Super+g gives you a menu of options for 311 setting or changing the values of them, where making good use of dmenu 312 will enable you to easily tune them. (But if you just want to toggle 313 gaps off, press Super+Shift+g, and if you want to increase or decrease 314 all gaps, scroll up and down with your mouse while holding Super.) 315 316 vanitygaps, a dwm patch, offers a number of layouts with gaps, but to 317 fully utilize what it offers, a user would need to bind eight keys each for 318 choosing one layout and bind eight keys for increasing and decreasing the 319 four types of gaps. This is a waste of spare keys given the infrequency 320 of most of the actions, and even that doesn't provide as much freedom as 321 swm does. So swm's menus serve to help out such situations by combining 322 many infrequent actions into few menus and allowing doing things more 323 sophisticated in case of need. 324 325 You can easily construct such menus in config.c using convenience 326 functions provided; see config.c for examples.