README.md

   1 ![logo](https://github.com/baskerville/bspwm/raw/master/logo/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 via `bspc`.
  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*, and 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 MESSAGE [ARGUMENTS ...]`.
  71
  72 The following messages are handled:
  73
  74     get SETTING
  75         Return the value of the given setting.
  76
  77     set SETTING VALUE
  78         Set the value of the given setting.
  79
  80     list [DESKTOP_NAME]
  81         Output the internal representation of the window tree.
  82
  83     list_desktops [--quiet]
  84         Perform a dump of each desktop for the current monitor.
  85
  86     list_monitors [--quiet]
  87         Perform a dump of each monitor.
  88
  89     list_windows
  90         Return the list of managed windows (i.e. their identifiers).
  91
  92     presel left|right|up|down
  93         Switch to manual mode and select the splitting direction.
  94
  95     cancel
  96         Switch to automatic mode.
  97
  98     ratio VALUE
  99         Set the splitting ratio of the focused window.
 100
 101     pad MONITOR_NAME [TOP_PADDING [RIGHT_PADDING [BOTTOM_PADDING [LEFT_PADDING]]]]
 102         Set the padding of the given monitor.
 103
 104     focus left|right|up|down
 105         Focus the neighbor window situated in the given direction.
 106
 107     shift left|right|up|down
 108         Exchange the current window with the given neighbor.
 109
 110     push left|right|up|down
 111         Push the fence located in the given direction.
 112
 113     pull left|right|up|down
 114         Pull the fence located in the given direction.
 115
 116     cycle next|prev [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 117         Focus the next or previous window matching the given constraints.
 118
 119     nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 120         Focus the nearest window matching the given constraints.
 121
 122     circulate forward|backward
 123         Circulate the leaves in the given direction.
 124
 125     toggle_fullscreen
 126         Toggle the fullscreen state of the current window.
 127
 128     toggle_floating
 129         Toggle the floating state of the current window.
 130
 131     toggle_locked
 132         Toggle the locked state of the current window (locked windows will not respond to the 'close' message).
 133
 134     close
 135         Close the focused window.
 136
 137     kill
 138         Kill the focused window.
 139
 140     send_to DESKTOP_NAME
 141         Send the focused window to the given desktop.
 142
 143     send_to_monitor MONITOR_NAME
 144         Send the focused window to the given monitor.
 145
 146     use DESKTOP_NAME
 147         Select the given desktop.
 148
 149     use_monitor MONITOR_NAME
 150         Select the given monitor.
 151
 152     alternate
 153         Alternate between the current and the last focused window.
 154
 155     alternate_desktop
 156         Alternate between the current and the last focused desktop.
 157
 158     alternate_monitor
 159         Alternate between the current and the last focused monitor.
 160
 161     add DESKTOP_NAME ...
 162         Make new desktops with the given names.
 163
 164     add_in MONITOR_NAME DESKTOP_NAME ...
 165         Make new desktops with the given names in the given monitor.
 166
 167     rename_monitor CURRENT_NAME NEW_NAME
 168         Rename the monitor named CURRENT_NAME to NEW_NAME.
 169
 170     rename CURRENT_NAME NEW_NAME
 171         Rename the desktop named CURRENT_NAME to NEW_NAME.
 172
 173     cycle_monitor next|prev
 174         Select the next or previous monitor.
 175
 176     cycle_desktop next|prev [--skip-free|--skip-occupied]
 177         Select the next or previous desktop.
 178
 179     layout monocle|tiled [DESKTOP_NAME ...]
 180         Set the layout of the given desktops (current if none given).
 181
 182     cycle_layout
 183         Cycle the layout of the current desktop.
 184
 185     rotate clockwise|counter_clockwise|full_cycle
 186         Rotate the tree of the current desktop.
 187
 188     rule PATTERN [DESKTOP_NAME] [floating]
 189         Create a new rule (PATTERN must match the class or instance name).
 190
 191     adopt_orphans
 192         Manage all the unmanaged windows remaining from a previous session.
 193
 194     reload_autostart
 195         Reload the autostart file.
 196
 197     reload_settings
 198         Reload the default settings.
 199
 200     reload
 201         Reload the autostart file and the default settings.
 202
 203     quit
 204         Quit.
 205
 206 ## Settings
 207
 208 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or *#RRGGBB*, booleans are *true* or *false*.
 209
 210     focused_border_color
 211         Color of the main border of a focused window of a focused monitor.
 212
 213     active_border_color
 214         Color of the main border of a focused window of an unfocused monitor.
 215
 216     normal_border_color
 217         Color of the main border of an unfocused window.
 218
 219     inner_border_color
 220         Color of the inner border of a window.
 221
 222     outer_border_color
 223         Color of the outer border of a window.
 224
 225     presel_border_color
 226         Color of the *presel* message feedback.
 227
 228     focused_locked_border_color
 229         Color of the main border of a focused locked window of a focused monitor.
 230
 231     active_locked_border_color
 232         Color of the main border of a focused locked window of an unfocused monitor.
 233
 234     normal_locked_border_color
 235         Color of the main border of an unfocused locked window.
 236
 237     urgent_border_color
 238         Color of the border of an urgent window.
 239
 240     inner_border_width
 241     main_border_width
 242     outer_border_width
 243         Width of the inner, main and outer borders.
 244
 245     window_gap
 246         Value of the gap that separates windows.
 247
 248     {top,right,bottom,left}_padding
 249         Padding space added at the sides of the current monitor.
 250
 251     wm_name
 252         The value that shall be used for the _NET_WM_NAME property of the root window.
 253
 254     button_modifier
 255         The modifier mask used for mouse bindings (possible values: 'shift', 'control', 'lock', 'mod1' ... 'mod5').
 256
 257     numlock_modifier
 258         The modifier holding Num_Lock (cf. xmodmap).
 259
 260     capslock_modifier
 261         The modifier holding Lock.
 262
 263     borderless_monocle
 264         Whether to remove borders for tiled windows in monocle mode.
 265
 266     gapless_monocle
 267         Whether to remove gaps for tiled windows in monocle mode.
 268
 269     focus_follows_mouse
 270         Wether to focus the window under the mouse pointer.
 271
 272     adaptative_raise
 273         Prevent floating windows from being raised when they might cover other floating windows.
 274
 275 ## Mouse Bindings
 276
 277     button_modifier + left mouse button
 278         Move the window under the pointer.
 279
 280     button_modifier + middle mouse button
 281         Focus the window under the pointer.
 282
 283     button_modifier + right mouse button
 284         Resize the window under the pointer (by moving one of its four corners).
 285
 286 ## Key Features
 287
 288 - Configured and controlled through messages
 289 - Multiple monitors support (via *Xinerama*)
 290 - EWMH support (`tint2` works)
 291 - Automatic and manual modes
 292 - Triple window borders
 293
 294 ## Panel
 295
 296 `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
 297
 298 Or any EWMH compliant panel.
 299
 300 ## Required Libraries:
 301
 302 - libxcb
 303 - xcb-util
 304 - xcb-util-wm
 305
 306 ## Installation
 307
 308     make
 309     make install
 310
 311 ## Contributors
 312
 313 - [Ivan Kanakarakis](https://github.com/c00kiemon5ter)