README.md

   1 ![logo](https://github.com/baskerville/bspwm/raw/master/resources/bspwm_logo.png)
   2
   3 ## Description
   4
   5 `bspwm` is a tiling window manager based on binary space partitioning.
   6
   7 The windows are represented as the leaves of a binary tree.
   8
   9 ## Configuration
  10
  11 `bspwm` have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  12
  13 Those messages are sent through the `bspc` program.
  14
  15 If the `BSPWM_SOCKET` environment variable is defined, it will be used as the socket path, otherwise `/tmp/bspwm-socket` is used.
  16
  17 The recommended way of defining keyboard shortcuts is to use `xbindkeys`.
  18
  19 The only way to configure `bspwm` is by sending *set* messages via the client, hence `bspwm`'s configuration file is an executable called `autostart` which lives in `$XDG_CONFIG_HOME/bspwm/`.
  20
  21 Example configurations: [autostart](https://github.com/baskerville/bin/blob/master/bspwm_autostart) and [xbindkeysrc](https://github.com/baskerville/dotfiles/blob/master/xbindkeysrc).
  22
  23 ## Splitting Modes
  24
  25 There is only two splitting modes: *automatic* and *manual*.
  26
  27 The default mode is *automatic*. The *manual* mode is entered by sending a *presel* message.
  28
  29 Example: insertion of a new node (number 4) into the given tree in
  30 *automatic* mode:
  31
  32                      b                                   c
  33                     / \                                 / \
  34                    3   a              -->              4   b
  35                    ^  / \                              ^  / \
  36                      2   1                               3   a
  37                                                             / \
  38                                                            2   1
  39         +-------------------------+         +-------------------------+
  40         |            |            |         |            |            |
  41         |            |     2      |         |            |     3      |
  42         |            |            |         |            |            |
  43         |     3      |------------|   -->   |     4      |------------|
  44         |     ^      |            |         |     ^      |     |      |
  45         |            |     1      |         |            |  1  |  2   |
  46         |            |            |         |            |     |      |
  47         +-------------------------+         +-------------------------+
  48
  49 Same departure, but the mode is *manual*, a `presel up` message
  50 was sent beforehand:
  51
  52                      b                                   b
  53                     / \                                 / \
  54                    3   a              -->              c   a
  55                    ^  / \                             / \ / \
  56                      2   1                           4  3 2  1
  57                                                      ^
  58         +-------------------------+         +-------------------------+
  59         |            |            |         |            |            |
  60         |            |     2      |         |     4      |     2      |
  61         |            |            |         |     ^      |            |
  62         |     3      |------------|   -->   |------------|------------|
  63         |     ^      |            |         |            |            |
  64         |            |     1      |         |     3      |     1      |
  65         |            |            |         |            |            |
  66         +-------------------------+         +-------------------------+
  67
  68 ## Messages
  69
  70 The syntax for the client is `bspc COMMAND ARGUMENTS...`.
  71
  72 The following messages are handled:
  73
  74     quit
  75         Quit.
  76
  77     get SETTING
  78         Return the value of the given setting.
  79
  80     set SETTING VALUE
  81         Set the value of the given setting.
  82
  83     dump
  84         Output the internal representation of the window tree.
  85
  86     list
  87         Perform a dump of each desktop.
  88
  89     windows
  90         Return the list of managed windows (i.e. their identifiers).
  91
  92     close
  93         Close the focused window.
  94
  95     kill
  96         Kill the focused window.
  97
  98     presel DIR
  99         Switch to manual mode and select the splitting direction.
 100
 101     ratio VALUE
 102         Set the splitting ratio of the focused window.
 103
 104     cancel
 105         Switch to automatic mode.
 106
 107     focus DIR
 108         Focus the neighbor node situated in the given direction.
 109
 110     shift DIR
 111         Focus the neighbor node situated in the given direction.
 112
 113     push DIR
 114         Push the fence located in the given direction.
 115
 116     pull DIR
 117         Pull the fence located in the given direction.
 118
 119     nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 120         Focus the nearest leaf matching the given constraints.
 121
 122     cycle CYC [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 123         Focus the next or previous window in the list of leaves.
 124
 125     rotate ROT
 126         Rotate the tree of the current desktop.
 127
 128     magnetise COR
 129         Move all the fences toward the given corner.
 130
 131     send_to DESKTOP_NAME
 132         Send the focused window to the given desktop.
 133
 134     use DESKTOP_NAME
 135         Select the given desktop.
 136
 137     alternate_focus
 138         Alternate between the current and the last focused window.
 139
 140     alternate
 141         Alternate between the current and the last focused desktop.
 142
 143     add DESKTOP_NAME
 144         Make a new desktop with the given name.
 145
 146     rename CURRENT_NAME NEW_NAME
 147         Rename the desktop named CURRENT_NAME to NEW_NAME.
 148
 149     cycle_desktop CYC
 150         Select the next or previous desktop.
 151
 152     layout LYT
 153         Set the layout of the current desktop to LYT.
 154
 155     cycle_layout
 156         Cycle the layout of the current desktop.
 157
 158     toggle_fullscreen
 159         Toggle the fullscreen state of the current window.
 160
 161     toggle_floating
 162         Toggle the floating state of the current window.
 163
 164     toggle_locked
 165         Toggle the locked state of the current window (locked windows will not respond to the 'close' command).
 166
 167     rule PATTERN floating
 168         Make a new rule that will float the windows whose class name or instance name equals PATTERN.
 169
 170     reload_autostart
 171         Reload the autostart file.
 172
 173     reload_settings
 174         Reload the default settings.
 175
 176     reload
 177         Reload the autostart file and the default settings.
 178
 179 Where
 180
 181     DIR = left|right|up|down
 182     CYC = next|prev
 183     ROT = clockwise|counter_clockwise|full_cycle
 184     COR = top_left|top_right|bottom_left|bottom_right
 185     LYT = monocle|tiled
 186
 187 ## Settings
 188
 189 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or '#RRGGBB', booleans are 'true' or 'false'.
 190
 191     active_border_color
 192         Color of the main border of a focused window.
 193
 194     normal_border_color
 195         Color of the main border of an unfocused window.
 196
 197     inner_border_color
 198         Color of the inner border of a window.
 199
 200     outer_border_color
 201         Color of the outer border of a window.
 202
 203     presel_border_color
 204         Color of the *presel* message feedback.
 205
 206     active_locked_border_color
 207         Color of the main border of a focused locked window.
 208
 209     normal_locked_border_color
 210         Color of the main border of an unfocused locked window.
 211
 212     urgent_border_color
 213         Color of the border of an urgent window.
 214
 215     inner_border_width
 216     main_border_width
 217     outer_border_width
 218         Width of the inner, main and outer borders.
 219
 220     window_gap
 221         Value of the gap that separates windows.
 222
 223     top_padding
 224     bottom_padding
 225     left_padding
 226     right_padding
 227         Padding space added at the sides of the screen.
 228
 229     wm_name
 230         The value that shall be used for the _NET_WM_NAME property of the root window.
 231
 232     borderless_monocle
 233         Whether to remove borders for tiled windows in monocle mode.
 234
 235 ## Mouse Bindings
 236
 237     M4 + Left Button
 238         Move the window under the pointer.
 239
 240     M4 + Middle Button
 241         Focus the window under the pointer.
 242
 243     M4 + Middle Button
 244         Resize the window under the pointer (by moving one of its four corners).
 245
 246 Where *M4* is the fourth modifier mask (generally bound to *Super*).
 247
 248 ## Panel
 249
 250 `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
 251
 252 ## Required Libraries:
 253
 254 libxcb, xcb-util, xcb-util-wm.
 255
 256 ## Installation
 257
 258     make
 259     make install
 260