README.md

   1 ![logo](https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png)
   2
   3 ## Synopsis
   4
   5     bspwm [-h|-v|-s PANEL_FIFO|-p PANEL_PREFIX]
   6
   7     bspc MESSAGE [ARGUMENTS] [OPTIONS]
   8
   9 ## Description
  10
  11 `bspwm` is a tiling window manager where each window is represented as the leaf of a binary tree.
  12
  13 It is controlled and configured via `bspc`.
  14
  15 ## Configuration
  16
  17 `bspwm` have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  18
  19 Its configuration file is `$XDG_CONFIG_HOME/bspwm/autostart`.
  20
  21 Keyboard and pointer bindings are defined through [sxhkd](https://github.com/baskerville/sxhkd).
  22
  23 Example configuration files can be found in the `examples` directory.
  24
  25 ## Splitting Modes
  26
  27 There is only two splitting modes: *automatic* and *manual*.
  28
  29 The default mode is *automatic*. The *manual* mode is entered by sending a *presel* message.
  30
  31 Example: insertion of a new node (number 4) into the given tree in
  32 *automatic* mode:
  33
  34                      b                                   c
  35                     / \                                 / \
  36                    3   a              -->              4   b
  37                    ^  / \                              ^  / \
  38                      2   1                               3   a
  39                                                             / \
  40                                                            2   1
  41         +-------------------------+         +-------------------------+
  42         |            |            |         |            |            |
  43         |            |     2      |         |            |     3      |
  44         |            |            |         |            |            |
  45         |     3      |------------|   -->   |     4      |------------|
  46         |     ^      |            |         |     ^      |     |      |
  47         |            |     1      |         |            |  1  |  2   |
  48         |            |            |         |            |     |      |
  49         +-------------------------+         +-------------------------+
  50
  51 Same departure, but the mode is *manual*, and a `presel up` message
  52 was sent beforehand:
  53
  54                      b                                   b
  55                     / \                                 / \
  56                    3   a              -->              c   a
  57                    ^  / \                             / \ / \
  58                      2   1                           4  3 2  1
  59                                                      ^
  60         +-------------------------+         +-------------------------+
  61         |            |            |         |            |            |
  62         |            |     2      |         |     4      |     2      |
  63         |            |            |         |     ^      |            |
  64         |     3      |------------|   -->   |------------|------------|
  65         |     ^      |            |         |            |            |
  66         |            |     1      |         |     3      |     1      |
  67         |            |            |         |            |            |
  68         +-------------------------+         +-------------------------+
  69
  70 ## Messages
  71
  72 The syntax for the client is `bspc MESSAGE [ARGUMENTS ...]`.
  73
  74 The following messages are handled:
  75
  76 - `get SETTING` — Return the value of the given setting.
  77
  78 - `set SETTING VALUE` — Set the value of the given setting.
  79
  80 - `list [DESKTOP_NAME]` — Output the internal representation of the window tree.
  81
  82 - `list_desktops [--quiet]` — Perform a dump of each desktop for the current monitor.
  83
  84 - `list_monitors [--quiet]` — Perform a dump of each monitor.
  85
  86 - `list_history` — Return the node focus history of each desktop.
  87
  88 - `list_windows` — Return the list of managed windows (i.e. their identifiers).
  89
  90 - `list_rules` — Return the list of rules.
  91
  92 - `presel left|right|up|down [SPLIT_RATIO]` — Switch to manual mode and select the splitting direction.
  93
  94 - `cancel` — Switch to automatic mode.
  95
  96 - `ratio VALUE` — Set the splitting ratio of the focused window.
  97
  98 - `pad MONITOR_NAME [TOP_PADDING [RIGHT_PADDING [BOTTOM_PADDING [LEFT_PADDING]]]]` — Set the padding of the given monitor.
  99
 100 - `focus left|right|up|down` — Focus the neighbor window situated in the given direction.
 101
 102 - `shift left|right|up|down` — Exchange the current window with the given neighbor.
 103
 104 - `swap [--swap-focus|--keep-focus]` — Swap the focused window the last focused window.
 105
 106 - `push left|right|up|down` — Push the fence located in the given direction.
 107
 108 - `pull left|right|up|down` — Pull the fence located in the given direction.
 109
 110 - `cycle next|prev [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]` — Focus the next or previous window matching the given constraints.
 111
 112 - `nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]` — Focus the nearest window matching the given constraints.
 113
 114 - `biggest` — Return the ID of the biggest tiled window.
 115
 116 - `circulate forward|backward` — Circulate the leaves in the given direction.
 117
 118 - `grab_pointer focus|move|resize_side|resize_corner` — Begin the specified pointer action.
 119
 120 - `track_pointer ROOT_X ROOT_Y` — Pass the pointer root coordinates for the current pointer action.
 121
 122 - `ungrab_pointer` — End the current pointer action.
 123
 124 - `toggle_fullscreen` — Toggle the fullscreen state of the current window.
 125
 126 - `toggle_floating` — Toggle the floating state of the current window.
 127
 128 - `toggle_locked` — Toggle the locked state of the current window (locked windows will not respond to the `close` message).
 129
 130 - `toggle_visibility` — Toggle the visibility of all the managed windows.
 131
 132 - `close` — Close the focused window.
 133
 134 - `kill` — Kill the focused window.
 135
 136 - `send_to DESKTOP_NAME [--follow]` — Send the focused window to the given desktop.
 137
 138 - `drop_to next|prev [--follow]` — Send the focused window to the next or previous desktop.
 139
 140 - `send_to_monitor MONITOR_NAME [--follow]` — Send the focused window to the given monitor.
 141
 142 - `drop_to_monitor next|prev [--follow]` — Send the focused window to the next or previous monitor.
 143
 144 - `use DESKTOP_NAME` — Select the given desktop.
 145
 146 - `use_monitor MONITOR_NAME` — Select the given monitor.
 147
 148 - `alternate` — Alternate between the current and the last focused window.
 149
 150 - `alternate_desktop` — Alternate between the current and the last focused desktop.
 151
 152 - `alternate_monitor` — Alternate between the current and the last focused monitor.
 153
 154 - `add DESKTOP_NAME ...` — Make new desktops with the given names.
 155
 156 - `add_in MONITOR_NAME DESKTOP_NAME ...` — Make new desktops with the given names in the given monitor.
 157
 158 - `rename_monitor CURRENT_NAME NEW_NAME` — Rename the monitor named `CURRENT_NAME` to `NEW_NAME`.
 159
 160 - `rename CURRENT_NAME NEW_NAME` — Rename the desktop named `CURRENT_NAME` to `NEW_NAME`.
 161
 162 - `remove_desktop DESKTOP_NAME ...` — Remove the given desktops.
 163
 164 - `cycle_monitor next|prev` — Select the next or previous monitor.
 165
 166 - `cycle_desktop next|prev [--skip-free|--skip-occupied]` — Select the next or previous desktop.
 167
 168 - `layout monocle|tiled [DESKTOP_NAME ...]` — Set the layout of the given desktops (current if none given).
 169
 170 - `cycle_layout` — Cycle the layout of the current desktop.
 171
 172 - `rotate clockwise|counter_clockwise|full_cycle` — Rotate the window tree.
 173
 174 - `flip horizontal|vertical` — Flip the window tree.
 175
 176 - `balance` — Adjust the split ratios so that all windows occupy the same area.
 177
 178 - `rule PATTERN [DESKTOP_NAME] [floating] [follow]` — Create a new rule (`PATTERN` must match the class or instance name).
 179
 180 - `remove_rule UID ...` — Remove the rules with the given UIDs.
 181
 182 - `put_status` — Output the current state to the panel fifo.
 183
 184 - `adopt_orphans` — Manage all the unmanaged windows remaining from a previous session.
 185
 186 - `restore_layout FILE_PATH` — Restore the layout of each desktop from the content of `FILE_PATH`.
 187
 188 - `restore_history FILE_PATH` — Restore the history of each desktop from the content of `FILE_PATH`.
 189
 190 - `quit [EXIT_STATUS]` — Quit.
 191
 192 ## Settings
 193
 194 Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or *#RRGGBB*, booleans are *true* or *false*.
 195
 196 - `focused_border_color` — Color of the border of a focused window of a focused monitor.
 197
 198 - `active_border_color` — Color of the border of a focused window of an unfocused monitor.
 199
 200 - `normal_border_color` — Color of the border of an unfocused window.
 201
 202 - `presel_border_color` — Color of the `presel` message feedback.
 203
 204 - `focused_locked_border_color` — Color of the border of a focused locked window of a focused monitor.
 205
 206 - `active_locked_border_color` — Color of the border of a focused locked window of an unfocused monitor.
 207
 208 - `normal_locked_border_color` — Color of the border of an unfocused locked window.
 209
 210 - `urgent_border_color` — Color of the border of an urgent window.
 211
 212 - `border_width` — Window border width.
 213
 214 - `window_gap` — Value of the gap that separates windows.
 215
 216 - `split_ratio` — Default split ratio.
 217
 218 - `{top,right,bottom,left}_padding` — Padding space added at the sides of the current monitor.
 219
 220 - `wm_name` — The value that shall be used for the `_NET_WM_NAME` property of the root window.
 221
 222 - `borderless_monocle` — Whether to remove borders for tiled windows in monocle mode.
 223
 224 - `gapless_monocle` — Whether to remove gaps for tiled windows in monocle mode.
 225
 226 - `focus_follows_pointer` — Whether to focus the window under the pointer.
 227
 228 - `adaptative_raise` — Prevent floating windows from being raised when they might cover other floating windows.
 229
 230 - `apply_shadow_property` — Enable shadows for floating windows via the `_COMPTON_SHADOW` property.
 231
 232 - `auto_alternate` — Whether to interpret two consecutive identical `use` messages as an `alternate` message.
 233
 234 - `focus_by_distance` — Whether to use window or leaf distance for focus movement.
 235
 236 ## Environment Variables
 237
 238 - `BSPWM_SOCKET` — The path of the socket used for the communication between `bspc` and `bspwm`.
 239
 240 ## Key Features
 241
 242 - Configured and controlled through messages.
 243 - Multiple monitors support (via *Xinerama*).
 244 - EWMH support (`tint2` works).
 245 - Automatic and manual modes.
 246
 247 ## Panels
 248
 249 - Any EWMH compliant panel (e.g. `tint2`, `bmpanel2`, etc.).
 250 - A custom panel if the `-s` flag is used (have a look at the files in `examples/panel`).
 251 - `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
 252
 253 ## Required Libraries:
 254
 255 - libxcb
 256 - xcb-util
 257 - xcb-util-wm
 258
 259 ## Installation
 260
 261     make
 262     make install
 263
 264 ## Contributors
 265
 266 - [Ivan Kanakarakis](https://github.com/c00kiemon5ter)
 267
 268 - [Thomas Adam](https://github.com/ThomasAdam)
 269
 270 ## Mailing List
 271
 272 bspwm *at* librelist *dot* com.
 273
 274 ## License
 275
 276 BSD.