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