README.md
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