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 [sxhkd](https://github.com/baskerville/sxhkd).
  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 [sxhkdrc](https://github.com/baskerville/dotfiles/blob/master/sxhkdrc).
  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     list_rules
  99         Return the list of rules.
 100
 101     presel left|right|up|down [SPLIT_RATIO]
 102         Switch to manual mode and select the splitting direction.
 103
 104     cancel
 105         Switch to automatic mode.
 106
 107     ratio VALUE
 108         Set the splitting ratio of the focused window.
 109
 110     pad MONITOR_NAME [TOP_PADDING [RIGHT_PADDING [BOTTOM_PADDING [LEFT_PADDING]]]]
 111         Set the padding of the given monitor.
 112
 113     focus left|right|up|down
 114         Focus the neighbor window situated in the given direction.
 115
 116     shift left|right|up|down
 117         Exchange the current window with the given neighbor.
 118
 119     push left|right|up|down
 120         Push the fence located in the given direction.
 121
 122     pull left|right|up|down
 123         Pull the fence located in the given direction.
 124
 125     cycle next|prev [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 126         Focus the next or previous window matching the given constraints.
 127
 128     nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
 129         Focus the nearest window matching the given constraints.
 130
 131     circulate forward|backward
 132         Circulate the leaves in the given direction.
 133
 134     grab_pointer move|resize|focus
 135         Begin the specified pointer action.
 136
 137     track_pointer ROOT_X ROOT_Y
 138         Pass the pointer root coordinates for the current pointer action.
 139
 140     ungrab_pointer
 141         End the current pointer action.
 142
 143     toggle_fullscreen
 144         Toggle the fullscreen state of the current window.
 145
 146     toggle_floating
 147         Toggle the floating state of the current window.
 148
 149     toggle_locked
 150         Toggle the locked state of the current window (locked windows will not respond to the 'close' message).
 151
 152     toggle_visibility
 153         Toggle the visibility of all the managed windows.
 154
 155     close
 156         Close the focused window.
 157
 158     kill
 159         Kill the focused window.
 160
 161     send_to DESKTOP_NAME [--follow]
 162         Send the focused window to the given desktop.
 163
 164     send_to_monitor MONITOR_NAME [--follow]
 165         Send the focused window to the given monitor.
 166
 167     use DESKTOP_NAME
 168         Select the given desktop.
 169
 170     use_monitor MONITOR_NAME
 171         Select the given monitor.
 172
 173     alternate
 174         Alternate between the current and the last focused window.
 175
 176     alternate_desktop
 177         Alternate between the current and the last focused desktop.
 178
 179     alternate_monitor
 180         Alternate between the current and the last focused monitor.
 181
 182     add DESKTOP_NAME ...
 183         Make new desktops with the given names.
 184
 185     add_in MONITOR_NAME DESKTOP_NAME ...
 186         Make new desktops with the given names in the given monitor.
 187
 188     rename_monitor CURRENT_NAME NEW_NAME
 189         Rename the monitor named CURRENT_NAME to NEW_NAME.
 190
 191     rename CURRENT_NAME NEW_NAME
 192         Rename the desktop named CURRENT_NAME to NEW_NAME.
 193
 194     cycle_monitor next|prev
 195         Select the next or previous monitor.
 196
 197     cycle_desktop next|prev [--skip-free|--skip-occupied]
 198         Select the next or previous desktop.
 199
 200     layout monocle|tiled [DESKTOP_NAME ...]
 201         Set the layout of the given desktops (current if none given).
 202
 203     cycle_layout
 204         Cycle the layout of the current desktop.
 205
 206     rotate clockwise|counter_clockwise|full_cycle
 207         Rotate the tree of the current desktop.
 208
 209     rule PATTERN [DESKTOP_NAME] [floating]
 210         Create a new rule (PATTERN must match the class or instance name).
 211
 212     remove_rule UID ...
 213         Remove the rules with the given UIDs.
 214
 215     adopt_orphans
 216         Manage all the unmanaged windows remaining from a previous session.
 217
 218     reload_autostart
 219         Reload the autostart file.
 220
 221     reload_settings
 222         Reload the default settings.
 223
 224     restore FILE_PATH
 225         Restore the layout of each desktop from the content of FILE_PATH.
 226
 227     quit [EXIT_STATUS]
 228         Quit.
 229
 230 ## Settings
 231
 232 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or *#RRGGBB*, booleans are *true* or *false*.
 233
 234     focused_border_color
 235         Color of the main border of a focused window of a focused monitor.
 236
 237     active_border_color
 238         Color of the main border of a focused window of an unfocused monitor.
 239
 240     normal_border_color
 241         Color of the main border of an unfocused window.
 242
 243     inner_border_color
 244         Color of the inner border of a window.
 245
 246     outer_border_color
 247         Color of the outer border of a window.
 248
 249     presel_border_color
 250         Color of the *presel* message feedback.
 251
 252     focused_locked_border_color
 253         Color of the main border of a focused locked window of a focused monitor.
 254
 255     active_locked_border_color
 256         Color of the main border of a focused locked window of an unfocused monitor.
 257
 258     normal_locked_border_color
 259         Color of the main border of an unfocused locked window.
 260
 261     urgent_border_color
 262         Color of the border of an urgent window.
 263
 264     inner_border_width
 265     main_border_width
 266     outer_border_width
 267         Width of the inner, main and outer borders.
 268
 269     window_gap
 270         Value of the gap that separates windows.
 271
 272     {top,right,bottom,left}_padding
 273         Padding space added at the sides of the current monitor.
 274
 275     wm_name
 276         The value that shall be used for the _NET_WM_NAME property of the root window.
 277
 278     borderless_monocle
 279         Whether to remove borders for tiled windows in monocle mode.
 280
 281     gapless_monocle
 282         Whether to remove gaps for tiled windows in monocle mode.
 283
 284     focus_follows_pointer
 285         Wether to focus the window under the pointer.
 286
 287     adaptative_raise
 288         Prevent floating windows from being raised when they might cover other floating windows.
 289
 290 ## Key Features
 291
 292 - Configured and controlled through messages
 293 - Multiple monitors support (via *Xinerama*)
 294 - EWMH support (`tint2` works)
 295 - Automatic and manual modes
 296 - Triple window borders
 297
 298 ## Panel
 299
 300 Multiple choices:
 301 - `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
 302 - A custom panel if the `-s` flag is used (have a look at the files in `examples/`).
 303 - Any EWMH compliant panel (e.g. `tint2`, `bmpanel2`, etc.).
 304
 305 ## Required Libraries:
 306
 307 - libxcb
 308 - xcb-util
 309 - xcb-util-wm
 310
 311 ## Installation
 312
 313     make
 314     make install
 315
 316 ## Contributors
 317
 318 - [Ivan Kanakarakis](https://github.com/c00kiemon5ter)
 319
 320 ## Mailing List
 321
 322 bspwm *at* librelist *dot* com.