doc/bspwm.1.txt

   1 :man source:   Bspwm
   2 :man version:  {revnumber}
   3 :man manual:   Bspwm Manual
   4
   5 bspwm(1)
   6 ========
   7
   8 Name
   9 ----
  10
  11 bspwm - Tiling window manager based on binary space partitioning
  12
  13 Synopsis
  14 --------
  15
  16 *bspwm* [*-h*|*-v*|*-s* _PANEL_FIFO_|*-p* _PANEL_PREFIX_]
  17
  18 *bspc* _MESSAGE_ [_ARGUMENTS_] [_OPTIONS_]
  19
  20 Description
  21 -----------
  22
  23 *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
  24
  25 It is controlled and configured via *bspc*.
  26
  27 Configuration
  28 -------------
  29
  30 *bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  31
  32 Its configuration file is _$XDG_CONFIG_HOME/bspwm/autostart_.
  33
  34 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
  35
  36 Example configuration files can be found in the *examples* directory.
  37
  38 Splitting Modes
  39 ---------------
  40
  41 There is only two splitting modes: _automatic_ and _manual_.
  42
  43 The default mode is _automatic_. The _manual_ mode is entered by sending a *presel* message.
  44
  45 Example: insertion of a new node (number 4) into the given tree in _automatic_ mode:
  46
  47 ----
  48               b                                   c
  49              / \                                 / \
  50             3   a              -->              4   b
  51             ^  / \                              ^  / \
  52               2   1                               3   a
  53                                                      / \
  54                                                     2   1
  55  +-------------------------+         +-------------------------+
  56  |            |            |         |            |            |
  57  |            |     2      |         |            |     3      |
  58  |            |            |         |            |            |
  59  |     3      |------------|   -->   |     4      |------------|
  60  |     ^      |            |         |     ^      |     |      |
  61  |            |     1      |         |            |  1  |  2   |
  62  |            |            |         |            |     |      |
  63  +-------------------------+         +-------------------------+
  64 ----
  65
  66 Same departure, but the mode is _manual_, and a *presel* _up_ message was sent beforehand:
  67
  68 ----
  69              b                                   b
  70             / \                                 / \
  71            3   a              -->              c   a
  72            ^  / \                             / \ / \
  73              2   1                           4  3 2  1
  74                                              ^
  75 +-------------------------+         +-------------------------+
  76 |            |            |         |            |            |
  77 |            |     2      |         |     4      |     2      |
  78 |            |            |         |     ^      |            |
  79 |     3      |------------|   -->   |------------|------------|
  80 |     ^      |            |         |            |            |
  81 |            |     1      |         |     3      |     1      |
  82 |            |            |         |            |            |
  83 +-------------------------+         +-------------------------+
  84 ----
  85
  86 Containers
  87 ----------
  88
  89 Each monitor contains at least one desktop.
  90
  91 Each desktop contains at most one tree.
  92
  93 Messages
  94 --------
  95
  96
  97 *get* _SETTING_::
  98     Return the value of the given setting.
  99
 100 *set* _SETTING_ _VALUE_::
 101     Set the value of the given setting.
 102
 103 *list* [_DESKTOP_NAME_]::
 104     Output the internal representation of the window tree.
 105
 106 *list_desktops* [*--quiet*]::
 107     Perform a dump of each desktop for the current monitor.
 108
 109 *list_monitors* [*--quiet*]::
 110     Perform a dump of each monitor.
 111
 112 *list_history*::
 113     Return the node focus history of each desktop.
 114
 115 *list_windows*::
 116     Return the list of managed windows (i.e. their identifiers).
 117
 118 *list_rules*::
 119     Return the list of rules.
 120
 121 *presel* _left_|_right_|_up_|_down_ [_SPLIT_RATIO_]::
 122     Switch to manual mode and select the splitting direction.
 123
 124 *cancel* [*--all*]::
 125     Switch to automatic mode.
 126
 127 *ratio* _VALUE_::
 128     Set the splitting ratio of the focused window.
 129
 130 *pad* _MONITOR_NAME_ [_TOP_PADDING_ [_RIGHT_PADDING_ [_BOTTOM_PADDING_ [_LEFT_PADDING_]]]]::
 131     Set the padding of the given monitor.
 132
 133 *focus* _left_|_right_|_up_|_down_::
 134     Focus the neighbor window situated in the given direction.
 135
 136 *shift* _left_|_right_|_up_|_down_::
 137     Exchange the current window with the given neighbor.
 138
 139 *swap* [*--keep-focus*]::
 140     Swap the focused window with the last focused window.
 141
 142 *push* _left_|_right_|_up_|_down_::
 143     Push the fence located in the given direction.
 144
 145 *pull* _left_|_right_|_up_|_down_::
 146     Pull the fence located in the given direction.
 147
 148 *fence_ratio* _left_|_right_|_up_|_down_ _RATIO_::
 149     Set the splitting ratio of the fence located in the given direction.
 150
 151 *cycle* _next_|_prev_ [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
 152     Focus the next or previous window matching the given constraints.
 153
 154 *nearest* _older_|_newer_ [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
 155     Focus the nearest window matching the given constraints.
 156
 157 *biggest*::
 158     Return the ID of the biggest tiled window.
 159
 160 *circulate* _forward_|_backward_::
 161     Circulate the leaves in the given direction.
 162
 163 *grab_pointer* _focus_|_move_|_resize_side_|_resize_corner_::
 164     Begin the specified pointer action.
 165
 166 *track_pointer* _ROOT_X_ _ROOT_Y_::
 167     Pass the pointer root coordinates for the current pointer action.
 168
 169 *toggle_fullscreen*::
 170     Toggle the fullscreen state of the current window.
 171
 172 *toggle_floating*::
 173     Toggle the floating state of the current window.
 174
 175 *toggle_locked*::
 176     Toggle the locked state of the current window (locked windows will not respond to the *close* message).
 177
 178 *toggle_visibility*::
 179     Toggle the visibility of all the managed windows.
 180
 181 *close*::
 182     Close the focused window.
 183
 184 *kill*::
 185     Kill the focused window.
 186
 187 *send_to* _DESKTOP_NAME_ [*--follow*]::
 188     Send the focused window to the given desktop.
 189
 190 *drop_to* _next_|_prev_ [*--follow*]::
 191     Send the focused window to the next or previous desktop.
 192
 193 *send_to_monitor* _MONITOR_NAME_ [*--follow*]::
 194     Send the focused window to the given monitor.
 195
 196 *drop_to_monitor* _next_|_prev_ [*--follow*]::
 197     Send the focused window to the next or previous monitor.
 198
 199 *use* _DESKTOP_NAME_::
 200     Select the given desktop.
 201
 202 *use_monitor* _MONITOR_NAME_::
 203     Select the given monitor.
 204
 205 *focus_monitor* _left_|_right_|_up_|_down_::
 206     Focus the nearest monitor in the given direction.
 207
 208 *alternate*::
 209     Alternate between the current and the last focused window.
 210
 211 *alternate_desktop*::
 212     Alternate between the current and the last focused desktop.
 213
 214 *alternate_monitor*::
 215     Alternate between the current and the last focused monitor.
 216
 217 *add* _DESKTOP_NAME_ ...::
 218     Make new desktops with the given names.
 219
 220 *add_in* _MONITOR_NAME_ _DESKTOP_NAME_ ...::
 221     Make new desktops with the given names in the given monitor.
 222
 223 *rename_monitor* _CURRENT_NAME_ _NEW_NAME_::
 224     Rename the monitor named _CURRENT_NAME_ to _NEW_NAME_.
 225
 226 *rename* _CURRENT_NAME_ _NEW_NAME_::
 227     Rename the desktop named _CURRENT_NAME_ to _NEW_NAME_.
 228
 229 *remove_desktop* _DESKTOP_NAME_ ...::
 230     Remove the given desktops.
 231
 232 *send_desktop_to* _MONITOR_NAME_ [*--follow*]::
 233     Send the current desktop to the given monitor.
 234
 235 *cycle_monitor* _next_|_prev_::
 236     Select the next or previous monitor.
 237
 238 *cycle_desktop* _next_|_prev_ [*--skip-free*|*--skip-occupied*]::
 239     Select the next or previous desktop.
 240
 241 *layout* _monocle_|_tiled_ [_DESKTOP_NAME_ ...]::
 242     Set the layout of the given desktops (current if none given).
 243
 244 *cycle_layout*::
 245     Cycle the layout of the current desktop.
 246
 247 *rotate* _clockwise_|_counter_clockwise_|_full_cycle_::
 248     Rotate the window tree.
 249
 250 *flip* _horizontal_|_vertical_::
 251     Flip the window tree.
 252
 253 *balance*::
 254     Adjust the split ratios so that all windows occupy the same area.
 255
 256 *rule* _PATTERN_ [_DESKTOP_NAME_] [_floating_] [_follow_]::
 257     Create a new rule (_PATTERN_ must match the class or instance name).
 258
 259 *remove_rule* _UID_ ...::
 260     Remove the rules with the given _UIDs_.
 261
 262 *put_status*::
 263     Output the current state to the panel fifo.
 264
 265 *adopt_orphans*::
 266     Manage all the unmanaged windows remaining from a previous session.
 267
 268 *restore_layout* _FILE_PATH_::
 269     Restore the layout of each desktop from the content of _FILE_PATH_.
 270
 271 *restore_history* _FILE_PATH_::
 272     Restore the history of each desktop from the content of _FILE_PATH_.
 273
 274 *quit* [_EXIT_STATUS_]::
 275     Quit.
 276
 277 Settings
 278 --------
 279 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or _#RRGGBB_, booleans are _true_ or _false_.
 280
 281 All the boolean settings are _false_ by default.
 282
 283
 284 _focused_border_color_::
 285     Color of the border of a focused window of a focused monitor.
 286
 287 _active_border_color_::
 288     Color of the border of a focused window of an unfocused monitor.
 289
 290 _normal_border_color_::
 291     Color of the border of an unfocused window.
 292
 293 _presel_border_color_::
 294     Color of the *presel* message feedback.
 295
 296 _focused_locked_border_color_::
 297     Color of the border of a focused locked window of a focused monitor.
 298
 299 _active_locked_border_color_::
 300     Color of the border of a focused locked window of an unfocused monitor.
 301
 302 _normal_locked_border_color_::
 303     Color of the border of an unfocused locked window.
 304
 305 _urgent_border_color_::
 306     Color of the border of an urgent window.
 307
 308 _border_width_::
 309     Window border width.
 310
 311 _window_gap_::
 312     Value of the gap that separates windows.
 313
 314 _split_ratio_::
 315     Default split ratio.
 316
 317 _top_padding_, _right_padding_, _bottom_padding_, _left_padding_::
 318     Padding space added at the sides of the current monitor.
 319
 320 _wm_name_::
 321     The value that shall be used for the '_NET_WM_NAME' property of the root window.
 322
 323 _borderless_monocle_::
 324     Remove borders for tiled windows in monocle mode.
 325
 326 _gapless_monocle_::
 327     Remove gaps for tiled windows in monocle mode.
 328
 329 _focus_follows_pointer_::
 330     Focus the window under the pointer.
 331
 332 _pointer_follows_monitor_::
 333     When focusing a monitor, put the pointer at its center.
 334
 335 _monitor_focus_fallback_::
 336     If the focus message fails, try to focus the nearest monitor in the same direction.
 337
 338 _adaptative_raise_::
 339     Prevent floating windows from being raised when they might cover other floating windows.
 340
 341 _apply_shadow_property_::
 342     Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
 343
 344 _auto_alternate_::
 345     Interpret two consecutive identical *use* messages as an *alternate* message.
 346
 347 _focus_by_distance_::
 348     Use window or leaf distance for focus movement.
 349
 350 _history_aware_focus_::
 351     Give priority to the focus history when focusing nodes.
 352
 353 Environment Variables
 354 ---------------------
 355
 356 _BSPWM_SOCKET_::
 357   The path of the socket used for the communication between *bspc* and *bspwm*.
 358
 359 Panels
 360 ------
 361
 362 * Any EWMH compliant panel (e.g.: _tint2_, _bmpanel2_, etc.).
 363 * A custom panel if the _-s_ flag is used (have a look at the files in _examples/panel_).
 364
 365 Key Features
 366 ------------
 367
 368 * Configured and controlled through messages.
 369 * Multiple monitors support (via _RandR_).
 370 * EWMH support (*tint2* works).
 371 * Automatic and manual modes.
 372
 373 Contributors
 374 ------------
 375
 376 * Steven Allen <steven at stebalien.com>
 377 * Thomas Adam <thomas at xteddy.org>
 378 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 379
 380 Author
 381 ------
 382
 383 Bastien Dejean <baskerville at lavabit.com>
 384
 385 Mailing List
 386 ------------
 387
 388 bspwm at librelist.com
 389
 390 ////
 391 vim: set ft=asciidoc:
 392 ////