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