-
-
## Description
-`bspwm` is a tiling window manager based on binary space partitioning.
+*bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
-The windows are represented as the leaves of a binary tree.
+It only responds to X events, and the messages it receives on a dedicated socket.
-## Configuration
+*bspc* is a program that writes messages on *bspwm*'s socket.
-`bspwm` have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
+*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.
-Those messages are sent through the `bspc` program.
+The outlined architecture is the following:
-Therefore, the `BSPWM_SOCKET` environment variable must be defined and indicate the path to where the socket will be created.
+```
+ PROCESS SOCKET
+sxhkd --------> bspc <------> bspwm
+```
-The recommended way of defining keyboard shortcuts, is to use `xbindkeys`.
+## Configuration
-Configuration files must be placed in `$XDG_CONFIG_HOME/bspwm/`.
+The default configuration file is `$XDG_CONFIG_HOME/bspwm/bspwmrc`: this is simply a shell script that calls *bspc*.
-In that directory, `bspwmrc` (written in Lua) will be sourced and `autostart` executed.
+An argument is passed to that script to indicate whether is was executed after a restart (`$1 -gt 0`) or not (`$1 -eq 0`).
-Example configurations: [bspwmrc](https://github.com/baskerville/dotfiles/blob/master/bspwmrc), [autostart](https://github.com/baskerville/bin/blob/master/bspwm_autostart) and [xbindkeysrc](https://github.com/baskerville/dotfiles/blob/master/xbindkeysrc)
+Keyboard and pointer bindings are defined with [sxhkd](https://github.com/baskerville/sxhkd).
-## Splitting Modes
+Example configuration files can be found in the [examples](examples) directory.
-There is only two splitting modes: *automatic* and *manual*.
+## Monitors, desktops and windows
-The default mode is *automatic*. The *manual* mode is entered by sending a *presel* message.
+*bspwm* holds a list of monitors.
- Example: insertion of a new node (number 4) into the given tree in
- *automatic* mode:
+A monitor is just a rectangle that contains desktops.
- b c
- / \ / \
- 3 a --> 4 b
- ^ / \ ^ / \
- 2 1 3 a
- / \
- 2 1
- +-------------------------+ +-------------------------+
- | | | | | |
- | | 2 | | | 3 |
- | | | | | |
- | 3 |------------| --> | 4 |------------|
- | ^ | | | ^ | | |
- | | 1 | | | 1 | 2 |
- | | | | | | |
- +-------------------------+ +-------------------------+
+A desktop is just a pointer to a tree.
- Same departure, but the mode is *manual*, a `presel up` message
- was sent beforehand:
+Monitors only show the tree of one desktop at a time (their focused desktop).
- b b
- / \ / \
- 3 a --> c a
- ^ / \ / \ / \
- 2 1 4 3 2 1
- ^
- +-------------------------+ +-------------------------+
- | | | | | |
- | | 2 | | 4 | 2 |
- | | | | ^ | |
- | 3 |------------| --> |------------|------------|
- | ^ | | | | |
- | | 1 | | 3 | 1 |
- | | | | | |
- +-------------------------+ +-------------------------+
+The tree is a partition of a monitor's rectangle into smaller rectangular regions.
-## Messages
+Each node in a tree either has zero or two children.
-The syntax for the client is `bspc COMMAND ARGUMENTS...`.
+Each internal node is responsible for splitting a rectangle in half.
-The following messages are handled:
+A split is defined by two parameters: the type (horizontal or vertical) and the ratio (a real number *r* such that *0 < r < 1*).
- quit
- Quit.
+Each leaf node holds exactly one window.
- get SETTING
- Return the value of the given setting.
+## Insertion modes
- set SETTING VALUE
- Set the value of the given setting.
+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.
- dump
- Output the internal representation of the window tree.
+The insertion mode tells *bspwm* how it should alter the tree in order to insert new windows on a given insertion point.
- list
- Perform a dump of each desktop.
+By default the insertion point is the focused window and its insertion mode is *automatic*.
- windows
- Return the list of managed windows (i.e. their identifiers).
+### Manual mode
- close
- Close the focused window.
+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*.
- presel DIR
- Switch to manual mode and select the splitting direction.
+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*).
- ratio VALUE
- Set the splitting ratio of the focused window.
+After doing so the insertion point goes into *manual* mode.
- cancel
- Switch to automatic mode.
+Let's consider the following scenario:
- focus DIR
- Focus the neighbor node situated in the given direction.
+```
+ a a a
+ / \ / \ / \
+ 1 b ---> c b ---> c b
+ ^ / \ / \ / \ / \ / \
+ 2 3 4 1 2 3 d 1 2 3
+ ^ / \
+ 5 4
+ ^
- shift DIR
- Focus the neighbor node situated in the given direction.
++-----------------------+ +-----------------------+ +-----------------------+
+| | | | | | | | | |
+| | 2 | | 4 | 2 | | 5 | 4 | 2 |
+| | | | ^ | | | ^ | | |
+| 1 |-----------| |-----------|-----------| |-----------|-----------|
+| ^ | | | | | | | |
+| | 3 | | 1 | 3 | | 1 | 3 |
+| | | | | | | | |
++-----------------------+ +-----------------------+ +-----------------------+
- push DIR
- Push the fence located in the given direction.
+ X Y Z
+```
- pull DIR
- Pull the fence located in the given direction.
+In state *X*, the insertion point is *1*.
- cycle CYC [--skip-floating|--skip-tiled]
- Focus the next or previous window in the list of leaves.
+We send the following message to *bspwm*: *node -p north*.
- rotate ROT
- Rotate the tree of the current desktop.
+Then add a new window: *4*, this leads to state *Y*: the new internal node, *c* becomes *a*'s first child.
- send_to DESKTOP_NAME
- Send the focused window to the given desktop.
+Finally we send another message: *node -p west* and add window *5*.
- use DESKTOP_NAME
- Select the given desktop.
-
- alternate
- Alternate between the current and the last focused desktop.
+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.
- add DESKTOP_NAME
- Make a new desktop with the given name.
+### Automatic mode
- rename CURRENT_NAME NEW_NAME
- Rename the desktop named CURRENT_NAME to NEW_NAME.
+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.
- cycle_desktop CYC
- Select the next or previous desktop.
-
- layout LYT
- Set the layout of the current desktop to LYT.
+#### Longest side scheme
- toggle_fullscreen
- Toggle the fullscreen state of the current window.
+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.
- toggle_floating
- Toggle the floating state of the current window.
+Let's consider the following scenario, where the initial polarity is set to `second_child`:
- toggle_locked
- Toggle the locked state of the current window (locked windows will not respond to the 'close' command).
+```
+ 1 a a
+ ^ / \ / \
+ ---> 1 2 ---> 1 b
+ ^ / \
+ 2 3
+ ^
- rule PATTERN floating
- Make a new rule that will floats the windows whose class name or instance name matches PATTERN.
+ +-----------------------+ +-----------------------+ +-----------------------+
+ | | | | | | | |
+ | | | | | | | 2 |
+ | | | | | | | |
+ | 1 | | 1 | 2 | | 1 |-----------|
+ | ^ | | | ^ | | | |
+ | | | | | | | 3 |
+ | | | | | | | ^ |
+ +-----------------------+ +-----------------------+ +-----------------------+
- reload_autostart
- Reload the autostart file.
+ X Y Z
+```
- reload_settings
- Reload the settings file.
+In state *X*, a new window is added.
- reload
- Reload the autostart and the settings file.
+Since *1* is wide, it gets split vertically and *2* is added as *a*'s second child given the initial polarity.
-Where
+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.
- DIR = left|right|up|down
- CYC = next|prev
- ROT = clockwise|counter_clockwise|full_cycle
- LYT = monocle|tiled
+#### Alternate scheme
-## Settings
+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.
-Colors are either X color names or '#RRGGBB'.
+#### Spiral scheme
- active_border_color
- Color of the main border of a focused window.
+When the value of the automatic scheme is `spiral`, the window will *take the space* of the insertion point.
- normal_border_color
- Color of the main border of an unfocused window.
-
- inner_border_color
- Color of the inner border of a window.
+Let's dive into the details with the following scenario:
- outer_border_color
- Color of the outer border of a window.
-
- presel_border_color
- Color of the *presel* message feedback.
+```
+ a a a
+ / \ / \ / \
+ 1 b ---> 1 c ---> 1 d
+ / \ / \ / \
+ 2 3 4 b 5 c
+ ^ ^ / \ ^ / \
+ 3 2 b 4
+ / \
+ 3 2
- active_locked_border_color
- Color of the main border of a focused locked window.
+ +-----------------------+ +-----------------------+ +-----------------------+
+ | | | | | | | | |
+ | | 2 | | | 4 | | | 5 |
+ | | ^ | | | ^ | | | ^ |
+ | 1 |-----------| | 1 |-----------| | 1 |-----------|
+ | | | | | | | | | 3 | |
+ | | 3 | | | 3 | 2 | | |-----| 4 |
+ | | | | | | | | | 2 | |
+ +-----------------------+ +-----------------------+ +-----------------------+
- normal_locked_border_color
- Color of the main border of an unfocused locked window.
+ X Y Z
+```
- urgent_border_color
- Color of the border of an urgent window.
+In state *X*, the insertion point, *2* is in automatic mode.
- inner_border_width
- main_border_width
- outer_border_width
- Width of the inner, main and outer borders.
+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*.
- window_gap
- Value of the gap that separates windows.
+The splitting parameters of *b* (type: *horizontal*, ratio: *½*) are copied to *c* and *b* is rotated by 90° clockwise.
- top_padding
- bottom_padding
- left_padding
- right_padding
- Padding space added at the sides of the screen.
+The tiling rectangle of *4* in state *Y* is equal to the tiling rectangle of *2* in state *X*.
- wm_name
- The value that shall be used for the _NET_WM_NAME property of the root window.
+Then the insertion of *5*, with *4* as insertion point, leads to *Z*.
-## Mouse Bindings
+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.
- M4 + Left Button
- Move the window under the pointer.
- M4 + Middle Button
- Focus the window under the pointer.
+## Supported protocols and standards
- M4 + Middle Button
- Resize the window under the pointer (by moving one of its four corners).
+- The RandR and Xinerama protocols.
+- A subset of the EWMH and ICCCM standards.
-Where *M4* is the fourth modifier mask (generally bound to *Super*).
+## Community
-## Requirements
+Want to get in touch with other *bspwm* users or you need help? Join us on our:
-- XCB.
-- Lua.
+- Subreddit at [r/bspwm](https://www.reddit.com/r/bspwm/).
+- IRC channel at `#bspwm` on `irc.libera.chat` (maintained by [@dannycolin](https://github.com/dannycolin) / sdk on IRC).
+- Matrix room at https://matrix.to/#/#bspwm:matrix.org
projects / bspwm.git / blobdiff