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