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 Therefore, the `BSPWM_SOCKET` environment variable **must** be defined and indicate the path to where the socket will be created.
  16
  17 The recommended way of defining keyboard shortcuts, is to use `xbindkeys`.
  18
  19 Configuration files must be placed in `$XDG_CONFIG_HOME/bspwm/`.
  20
  21 In that directory, `bspwmrc` (written in Lua) will be sourced and `autostart` executed.
  22
  23 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)
  24
  25 ## Splitting Modes
  26
  27 There is only two splitting modes: *automatic* and *manual*.
  28
  29 The default mode is *automatic*. The *manual* mode is entered by sending a *presel* message.
  30
  31         Example: insertion of a new node (number 4) into the given tree in
  32         *automatic* mode:
  33
  34                      b                                   c
  35                     / \                                 / \
  36                    3   a              -->              4   b
  37                    ^  / \                              ^  / \
  38                      2   1                               3   a
  39                                                             / \
  40                                                            2   1
  41         +-------------------------+         +-------------------------+
  42         |            |            |         |            |            |
  43         |            |     2      |         |            |     3      |
  44         |            |            |         |            |            |
  45         |     3      |------------|   -->   |     4      |------------|
  46         |     ^      |            |         |     ^      |     |      |
  47         |            |     1      |         |            |  1  |  2   |
  48         |            |            |         |            |     |      |
  49         +-------------------------+         +-------------------------+
  50
  51         Same departure, but the mode is *manual*, a `presel up` message
  52         was sent beforehand:
  53
  54                      b                                   b
  55                     / \                                 / \
  56                    3   a              -->              c   a
  57                    ^  / \                             / \ / \
  58                      2   1                           4  3 2  1
  59                                                      ^
  60         +-------------------------+         +-------------------------+
  61         |            |            |         |            |            |
  62         |            |     2      |         |     4      |     2      |
  63         |            |            |         |     ^      |            |
  64         |     3      |------------|   -->   |------------|------------|
  65         |     ^      |            |         |            |            |
  66         |            |     1      |         |     3      |     1      |
  67         |            |            |         |            |            |
  68         +-------------------------+         +-------------------------+
  69
  70 ## Messages
  71
  72 The syntax for the client is `bspc COMMAND ARGUMENTS...`.
  73
  74 The following messages are handled:
  75
  76     quit
  77         Quit.
  78
  79     get SETTING
  80         Return the value of the given setting.
  81
  82     set SETTING VALUE
  83         Set the value of the given setting.
  84
  85     dump
  86         Output the internal representation of the window tree.
  87
  88     list
  89         Perform a dump of each desktop.
  90
  91     windows
  92         Return the list of managed windows (i.e. their identifiers).
  93
  94     close
  95         Close the focused window.
  96
  97     presel DIR
  98         Switch to manual mode and select the splitting direction.
  99
 100     ratio VALUE
 101         Set the splitting ratio of the focused window.
 102
 103     cancel
 104         Switch to automatic mode.
 105
 106     focus DIR
 107         Focus the neighbor node situated in the given direction.
 108
 109     shift DIR
 110         Focus the neighbor node situated in the given direction.
 111
 112     push DIR
 113         Push the fence located in the given direction.
 114
 115     pull DIR
 116         Pull the fence located in the given direction.
 117
 118     cycle CYC [--skip-floating|--skip-tiled]
 119         Focus the next or previous window in the list of leaves.
 120
 121     rotate ROT
 122         Rotate the tree of the current desktop.
 123
 124     send_to DESKTOP_NAME
 125         Send the focused window to the given desktop.
 126
 127     use DESKTOP_NAME
 128         Select the given desktop.
 129
 130     alternate
 131         Alternate between the current and the last focused desktop.
 132
 133     add DESKTOP_NAME
 134         Make a new desktop with the given name.
 135
 136     rename CURRENT_NAME NEW_NAME
 137         Rename the desktop named CURRENT_NAME to NEW_NAME.
 138
 139     cycle_desktop CYC
 140         Select the next or previous desktop.
 141
 142     layout LYT
 143         Set the layout of the current desktop to LYT.
 144
 145     toggle_fullscreen
 146         Toggle the fullscreen state of the current window.
 147
 148     toggle_floating
 149         Toggle the floating state of the current window.
 150
 151     toggle_locked
 152         Toggle the locked state of the current window (locked windows will not respond to the 'close' command).
 153
 154     rule PATTERN floating
 155         Make a new rule that will floats the windows whose class name or instance name matches PATTERN.
 156
 157     reload_autostart
 158         Reload the autostart file.
 159
 160     reload_settings
 161         Reload the settings file.
 162
 163     reload
 164         Reload the autostart and the settings file.
 165
 166 Where
 167
 168     DIR = left|right|up|down
 169     CYC = next|prev
 170     ROT = clockwise|counter_clockwise|full_cycle
 171     LYT = monocle|tiled
 172
 173 ## Settings
 174
 175 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or '#RRGGBB'.
 176
 177     active_border_color
 178         Color of the main border of a focused window.
 179
 180     normal_border_color
 181         Color of the main border of an unfocused window.
 182
 183     inner_border_color
 184         Color of the inner border of a window.
 185
 186     outer_border_color
 187         Color of the outer border of a window.
 188
 189     presel_border_color
 190         Color of the *presel* message feedback.
 191
 192     active_locked_border_color
 193         Color of the main border of a focused locked window.
 194
 195     normal_locked_border_color
 196         Color of the main border of an unfocused locked window.
 197
 198     urgent_border_color
 199         Color of the border of an urgent window.
 200
 201     inner_border_width
 202     main_border_width
 203     outer_border_width
 204         Width of the inner, main and outer borders.
 205
 206     window_gap
 207         Value of the gap that separates windows.
 208
 209     top_padding
 210     bottom_padding
 211     left_padding
 212     right_padding
 213         Padding space added at the sides of the screen.
 214
 215     wm_name
 216         The value that shall be used for the _NET_WM_NAME property of the root window.
 217
 218 ## Mouse Bindings
 219
 220     M4 + Left Button
 221         Move the window under the pointer.
 222
 223     M4 + Middle Button
 224         Focus the window under the pointer.
 225
 226     M4 + Middle Button
 227         Resize the window under the pointer (by moving one of its four corners).
 228
 229 Where *M4* is the fourth modifier mask (generally bound to *Super*).
 230
 231 ## Required Libraries:
 232
 233 libxcb, xcb-util-wm, lua.
 234
 235 ## Installation
 236
 237     make
 238     make install
 239