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 Configuration files (`bspwmrc` and `autostart`) must be placed in `$XDG_CONFIG_HOME/bspwm/`.
  20
  21 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)
  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     presel DIR
  96         Switch to manual mode and select the splitting direction.
  97
  98     ratio VALUE
  99         Set the splitting ratio of the focused window.
 100
 101     cancel
 102         Switch to automatic mode.
 103
 104     focus DIR
 105         Focus the neighbor node situated in the given direction.
 106
 107     shift DIR
 108         Focus the neighbor node situated in the given direction.
 109
 110     push DIR
 111         Push the fence located in the given direction.
 112
 113     pull DIR
 114         Pull the fence located in the given direction.
 115
 116     cycle CYC [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 117         Focus the next or previous window in the list of leaves.
 118
 119     rotate ROT
 120         Rotate the tree of the current desktop.
 121
 122     magnetise COR
 123         Move all the fences toward the given corner.
 124
 125     send_to DESKTOP_NAME
 126         Send the focused window to the given desktop.
 127
 128     use DESKTOP_NAME
 129         Select the given desktop.
 130
 131     alternate
 132         Alternate between the current and the last focused desktop.
 133
 134     add DESKTOP_NAME
 135         Make a new desktop with the given name.
 136
 137     rename CURRENT_NAME NEW_NAME
 138         Rename the desktop named CURRENT_NAME to NEW_NAME.
 139
 140     cycle_desktop CYC
 141         Select the next or previous desktop.
 142
 143     layout LYT
 144         Set the layout of the current desktop to LYT.
 145
 146     toggle_fullscreen
 147         Toggle the fullscreen state of the current window.
 148
 149     toggle_floating
 150         Toggle the floating state of the current window.
 151
 152     toggle_locked
 153         Toggle the locked state of the current window (locked windows will not respond to the 'close' command).
 154
 155     rule PATTERN floating
 156         Make a new rule that will floats the windows whose class name or instance name matches PATTERN.
 157
 158     reload_autostart
 159         Reload the autostart file.
 160
 161     reload_settings
 162         Reload the settings file.
 163
 164     reload
 165         Reload the autostart and the settings file.
 166
 167 Where
 168
 169     DIR = left|right|up|down
 170     CYC = next|prev
 171     ROT = clockwise|counter_clockwise|full_cycle
 172     COR = top_left|top_right|bottom_left|bottom_right
 173     LYT = monocle|tiled
 174
 175 ## Settings
 176
 177 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or '#RRGGBB'.
 178
 179     active_border_color
 180         Color of the main border of a focused window.
 181
 182     normal_border_color
 183         Color of the main border of an unfocused window.
 184
 185     inner_border_color
 186         Color of the inner border of a window.
 187
 188     outer_border_color
 189         Color of the outer border of a window.
 190
 191     presel_border_color
 192         Color of the *presel* message feedback.
 193
 194     active_locked_border_color
 195         Color of the main border of a focused locked window.
 196
 197     normal_locked_border_color
 198         Color of the main border of an unfocused locked window.
 199
 200     urgent_border_color
 201         Color of the border of an urgent window.
 202
 203     inner_border_width
 204     main_border_width
 205     outer_border_width
 206         Width of the inner, main and outer borders.
 207
 208     window_gap
 209         Value of the gap that separates windows.
 210
 211     top_padding
 212     bottom_padding
 213     left_padding
 214     right_padding
 215         Padding space added at the sides of the screen.
 216
 217     wm_name
 218         The value that shall be used for the _NET_WM_NAME property of the root window.
 219
 220 ## Mouse Bindings
 221
 222     M4 + Left Button
 223         Move the window under the pointer.
 224
 225     M4 + Middle Button
 226         Focus the window under the pointer.
 227
 228     M4 + Middle Button
 229         Resize the window under the pointer (by moving one of its four corners).
 230
 231 Where *M4* is the fourth modifier mask (generally bound to *Super*).
 232
 233 ## Required Libraries:
 234
 235 libxcb, xcb-util-wm, lua.
 236
 237 ## Installation
 238
 239     make
 240     make install
 241