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