README.md

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