1## Description 2 3*bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree. 4 5It only responds to X events, and the messages it receives on a dedicated socket. 6 7*bspc* is a program that writes messages on *bspwm*'s socket. 8 9*bspwm* doesn't handle any keyboard or pointer inputs: a third party program (e.g. *sxhkd*) is needed in order to translate keyboard and pointer events to *bspc* invocations. 10 11The outlined architecture is the following: 12 13``` 14 PROCESS SOCKET 15sxhkd --------> bspc <------> bspwm 16``` 17 18## Configuration 19 20The default configuration file is `$XDG_CONFIG_HOME/bspwm/bspwmrc`: this is simply a shell script that calls *bspc*. 21 22An argument is passed to that script to indicate whether is was executed after a restart (`$1 -gt 0`) or not (`$1 -eq 0`). 23 24Keyboard and pointer bindings are defined with [sxhkd](https://github.com/baskerville/sxhkd). 25 26Example configuration files can be found in the [examples](examples) directory. 27 28## Monitors, desktops and windows 29 30*bspwm* holds a list of monitors. 31 32A monitor is just a rectangle that contains desktops. 33 34A desktop is just a pointer to a tree. 35 36Monitors only show the tree of one desktop at a time (their focused desktop). 37 38The tree is a partition of a monitor's rectangle into smaller rectangular regions. 39 40Each node in a tree either has zero or two children. 41 42Each internal node is responsible for splitting a rectangle in half. 43 44A split is defined by two parameters: the type (horizontal or vertical) and the ratio (a real number *r* such that *0 < r < 1*). 45 46Each leaf node holds exactly one window. 47 48## Insertion modes 49 50When *bspwm* receives a new window, it inserts it into a window tree at the specified insertion point (a leaf) using the insertion mode specified for that insertion point. 51 52The insertion mode tells *bspwm* how it should alter the tree in order to insert new windows on a given insertion point. 53 54By default the insertion point is the focused window and its insertion mode is *automatic*. 55 56### Manual mode 57 58The user can specify a region in the insertion point where the next new window should appear by sending a *node -p|--presel-dir DIR* message to *bspwm*. 59 60The *DIR* argument allows to specify how the insertion point should be split (horizontally or vertically) and if the new window should be the first or the second child of the new internal node (the insertion point will become its *brother*). 61 62After doing so the insertion point goes into *manual* mode. 63 64Let's consider the following scenario: 65 66``` 67 a a a 68 / \ / \ / \ 69 1 b ---> c b ---> c b 70 ^ / \ / \ / \ / \ / \ 71 2 3 4 1 2 3 d 1 2 3 72 ^ / \ 73 5 4 74 ^ 75 76+-----------------------+ +-----------------------+ +-----------------------+ 77| | | | | | | | | | 78| | 2 | | 4 | 2 | | 5 | 4 | 2 | 79| | | | ^ | | | ^ | | | 80| 1 |-----------| |-----------|-----------| |-----------|-----------| 81| ^ | | | | | | | | 82| | 3 | | 1 | 3 | | 1 | 3 | 83| | | | | | | | | 84+-----------------------+ +-----------------------+ +-----------------------+ 85 86 X Y Z 87``` 88 89In state *X*, the insertion point is *1*. 90 91We send the following message to *bspwm*: *node -p north*. 92 93Then add a new window: *4*, this leads to state *Y*: the new internal node, *c* becomes *a*'s first child. 94 95Finally we send another message: *node -p west* and add window *5*. 96 97The ratio of the preselection (that ends up being the ratio of the split of the new internal node) can be changed with the *node -o|--presel-ratio* message. 98 99### Automatic mode 100 101The *automatic* mode, as opposed to the *manual* mode, doesn't require any user choice. The way the new window is inserted is determined by the value of the automatic scheme and the initial polarity settings. 102 103#### Longest side scheme 104 105When the value of the automatic scheme is `longest_side`, the window will be attached as if the insertion point was in manual mode and the split direction was chosen based on the dimensions of the tiling rectangle and the initial polarity. 106 107Let's consider the following scenario, where the initial polarity is set to `second_child`: 108 109``` 110 1 a a 111 ^ / \ / \ 112 ---> 1 2 ---> 1 b 113 ^ / \ 114 2 3 115 ^ 116 117 +-----------------------+ +-----------------------+ +-----------------------+ 118 | | | | | | | | 119 | | | | | | | 2 | 120 | | | | | | | | 121 | 1 | | 1 | 2 | | 1 |-----------| 122 | ^ | | | ^ | | | | 123 | | | | | | | 3 | 124 | | | | | | | ^ | 125 +-----------------------+ +-----------------------+ +-----------------------+ 126 127 X Y Z 128``` 129 130In state *X*, a new window is added. 131 132Since *1* is wide, it gets split vertically and *2* is added as *a*'s second child given the initial polarity. 133 134This leads to *Y* where we insert window *3*. *2* is tall and is therefore split horizontally. *3* is once again added as *b*'s second child. 135 136#### Alternate scheme 137 138When the value of the automatic scheme is `alternate`, the window will be attached as if the insertion point was in manual mode and the split direction was chosen based on the split type of the insertion point's parent and the initial polarity. If the parent is split horizontally, the insertion point will be split vertically and vice versa. 139 140#### Spiral scheme 141 142When the value of the automatic scheme is `spiral`, the window will *take the space* of the insertion point. 143 144Let's dive into the details with the following scenario: 145 146``` 147 a a a 148 / \ / \ / \ 149 1 b ---> 1 c ---> 1 d 150 / \ / \ / \ 151 2 3 4 b 5 c 152 ^ ^ / \ ^ / \ 153 3 2 b 4 154 / \ 155 3 2 156 157 +-----------------------+ +-----------------------+ +-----------------------+ 158 | | | | | | | | | 159 | | 2 | | | 4 | | | 5 | 160 | | ^ | | | ^ | | | ^ | 161 | 1 |-----------| | 1 |-----------| | 1 |-----------| 162 | | | | | | | | | 3 | | 163 | | 3 | | | 3 | 2 | | |-----| 4 | 164 | | | | | | | | | 2 | | 165 +-----------------------+ +-----------------------+ +-----------------------+ 166 167 X Y Z 168``` 169 170In state *X*, the insertion point, *2* is in automatic mode. 171 172When we add a new window, *4*, the whole tree rooted at *b* is reattached, as the second child of a new internal node, *c*. 173 174The splitting parameters of *b* (type: *horizontal*, ratio: *½*) are copied to *c* and *b* is rotated by 90° clockwise. 175 176The tiling rectangle of *4* in state *Y* is equal to the tiling rectangle of *2* in state *X*. 177 178Then the insertion of *5*, with *4* as insertion point, leads to *Z*. 179 180The *spiral* automatic scheme generates window spirals that rotate clockwise (resp. anti-clockwise) if the insertion point is the first (resp. second) child of its parent. 181 182 183## Supported protocols and standards 184 185- The RandR and Xinerama protocols. 186- A subset of the EWMH and ICCCM standards. 187 188## Community 189 190Want to get in touch with other *bspwm* users or you need help? Join us on our: 191 192- Subreddit at [r/bspwm](https://www.reddit.com/r/bspwm/). 193- IRC channel at `#bspwm` on `chat.freenode.net` (maintained by [@dannycolin](https://github.com/dannycolin) / sdk on IRC). 194