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     close
  84         Close the focused window.
  85
  86     kill
  87         Kill the focused window.
  88
  89     list
  90         Output the internal representation of the window tree.
  91
  92     list_desktops [--quiet]
  93         Perform a dump of each desktop for the current monitor.
  94
  95     list_monitors [--quiet]
  96         Perform a dump of each monitor.
  97
  98     list_windows
  99         Return the list of managed windows (i.e. their identifiers).
 100
 101     presel left|right|up|down
 102         Switch to manual mode and select the splitting direction.
 103
 104     cancel
 105         Switch to automatic mode.
 106
 107     ratio VALUE
 108         Set the splitting ratio of the focused window.
 109
 110     focus left|right|up|down
 111         Focus the neighbor node situated in the given direction.
 112
 113     shift left|right|up|down
 114         Focus the neighbor node situated in the given direction.
 115
 116     push left|right|up|down
 117         Push the fence located in the given direction.
 118
 119     pull left|right|up|down
 120         Pull the fence located in the given direction.
 121
 122     cycle next|prev [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 123         Focus the next or previous window in the list of leaves.
 124
 125     nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 126         Focus the nearest leaf matching the given constraints.
 127
 128     rotate clockwise|counter_clockwise|full_cycle
 129         Rotate the tree of the current desktop.
 130
 131     magnetise top_left|top_right|bottom_left|bottom_right
 132         Move all the fences toward the given corner.
 133
 134     send_to DESKTOP_NAME
 135         Send the focused window to the given desktop.
 136
 137     send_to_monitor MONITOR_NAME
 138         Send the focused window to the given monitor.
 139
 140     use DESKTOP_NAME
 141         Select the given desktop.
 142
 143     use_monitor MONITOR_NAME
 144         Select the given monitor.
 145
 146     alternate
 147         Alternate between the current and the last focused window.
 148
 149     alternate_desktop
 150         Alternate between the current and the last focused desktop.
 151
 152     alternate_monitor
 153         Alternate between the current and the last focused monitor.
 154
 155     add DESKTOP_NAME ...
 156         Make new desktops with the given names.
 157
 158     add_in MONITOR_NAME DESKTOP_NAME ...
 159         Make new desktops with the given names in the given monitor.
 160
 161     rename_monitor CURRENT_NAME NEW_NAME
 162         Rename the monitor named CURRENT_NAME to NEW_NAME.
 163
 164     rename CURRENT_NAME NEW_NAME
 165         Rename the desktop named CURRENT_NAME to NEW_NAME.
 166
 167     cycle_monitor next|prev
 168         Select the next or previous monitor.
 169
 170     cycle_desktop next|prev [--skip-free|--skip-occupied]
 171         Select the next or previous desktop.
 172
 173     layout monocle|tiled
 174         Set the layout of the current desktop.
 175
 176     cycle_layout
 177         Cycle the layout of the current desktop.
 178
 179     toggle_fullscreen
 180         Toggle the fullscreen state of the current window.
 181
 182     toggle_floating
 183         Toggle the floating state of the current window.
 184
 185     toggle_locked
 186         Toggle the locked state of the current window (locked windows will not respond to the 'close' command).
 187
 188     rule PATTERN floating
 189         Make a new rule that will float the windows whose class name or instance name equals PATTERN.
 190
 191     reload_autostart
 192         Reload the autostart file.
 193
 194     reload_settings
 195         Reload the default settings.
 196
 197     reload
 198         Reload the autostart file and the default settings.
 199
 200 ## Settings
 201
 202 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or '#RRGGBB', booleans are 'true' or 'false'.
 203
 204     focused_border_color
 205         Color of the main border of a focused window of a focused monitor.
 206
 207     active_border_color
 208         Color of the main border of a focused window of an unfocused monitor.
 209
 210     normal_border_color
 211         Color of the main border of an unfocused window.
 212
 213     inner_border_color
 214         Color of the inner border of a window.
 215
 216     outer_border_color
 217         Color of the outer border of a window.
 218
 219     presel_border_color
 220         Color of the *presel* message feedback.
 221
 222     focused_locked_border_color
 223         Color of the main border of a focused locked window of a focused monitor.
 224
 225     active_locked_border_color
 226         Color of the main border of a focused locked window of an unfocused monitor.
 227
 228     normal_locked_border_color
 229         Color of the main border of an unfocused locked window.
 230
 231     urgent_border_color
 232         Color of the border of an urgent window.
 233
 234     inner_border_width
 235     main_border_width
 236     outer_border_width
 237         Width of the inner, main and outer borders.
 238
 239     window_gap
 240         Value of the gap that separates windows.
 241
 242     top_padding
 243     bottom_padding
 244     left_padding
 245     right_padding
 246         Padding space added at the sides of the screen.
 247
 248     wm_name
 249         The value that shall be used for the _NET_WM_NAME property of the root window.
 250
 251     button_modifier
 252         The modifier mask used for mouse bindings (possible values: 'mod1' ... 'mod5').
 253
 254     borderless_monocle
 255         Whether to remove borders for tiled windows in monocle mode.
 256
 257     focus_follows_mouse
 258         Wether to focus the window under the mouse pointer.
 259
 260 ## Mouse Bindings
 261
 262     button_modifier + left mouse button
 263         Move the window under the pointer.
 264
 265     button_modifier + middle mouse button
 266         Focus the window under the pointer.
 267
 268     button_modifier + right mouse button
 269         Resize the window under the pointer (by moving one of its four corners).
 270
 271 ## Panel
 272
 273 `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
 274
 275 ## Required Libraries:
 276
 277 libxcb, xcb-util, xcb-util-wm.
 278
 279 ## Installation
 280
 281     make
 282     make install