-
+
+
+## Synopsis
+
+ bspwm [-h|-v|-s PANEL_FIFO|-p PANEL_PREFIX]
+
+ bspc MESSAGE [ARGUMENTS] [OPTIONS]
## Description
-`bspwm` is a tiling window manager based on binary space partitioning.
+`bspwm` is a tiling window manager where each window is represented as the leaf of a binary tree.
-The windows are represented as the leaves of a binary tree.
+It is controlled and configured via `bspc`.
## Configuration
`bspwm` have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
-Those messages are sent through the `bspc` program.
-
-If the `BSPWM_SOCKET` environment variable is defined, it will be used as the socket path, otherwise `/tmp/bspwm-socket` is used.
+Its configuration file is `$XDG_CONFIG_HOME/bspwm/autostart`.
-The recommended way of defining keyboard shortcuts is to use `xbindkeys`.
+Keyboard and pointer bindings are defined through [sxhkd](https://github.com/baskerville/sxhkd).
-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/`.
-
-Example configurations: [autostart](https://github.com/baskerville/bin/blob/master/bspwm_autostart) and [xbindkeysrc](https://github.com/baskerville/dotfiles/blob/master/xbindkeysrc).
+Example configuration files can be found in the `examples` directory.
## Splitting Modes
| | | | | | |
+-------------------------+ +-------------------------+
-Same departure, but the mode is *manual*, a `presel up` message
+Same departure, but the mode is *manual*, and a `presel up` message
was sent beforehand:
b b
## Messages
-The syntax for the client is `bspc COMMAND ARGUMENTS...`.
+The syntax for the client is `bspc MESSAGE [ARGUMENTS ...]`.
The following messages are handled:
- quit
- Quit.
+- `get SETTING` — Return the value of the given setting.
+
+- `set SETTING VALUE` — Set the value of the given setting.
+
+- `list [DESKTOP_NAME]` — Output the internal representation of the window tree.
+
+- `list_desktops [--quiet]` — Perform a dump of each desktop for the current monitor.
+
+- `list_monitors [--quiet]` — Perform a dump of each monitor.
+
+- `list_history [DESKTOP_NAME]` — Return the node focus history.
+
+- `list_windows` — Return the list of managed windows (i.e. their identifiers).
+
+- `list_rules` — Return the list of rules.
+
+- `presel left|right|up|down [SPLIT_RATIO]` — Switch to manual mode and select the splitting direction.
+
+- `cancel` — Switch to automatic mode.
- get SETTING
- Return the value of the given setting.
+- `ratio VALUE` — Set the splitting ratio of the focused window.
- set SETTING VALUE
- Set the value of the given setting.
+- `pad MONITOR_NAME [TOP_PADDING [RIGHT_PADDING [BOTTOM_PADDING [LEFT_PADDING]]]]` — Set the padding of the given monitor.
- dump
- Output the internal representation of the window tree.
+- `focus left|right|up|down` — Focus the neighbor window situated in the given direction.
- list_monitors [--quiet]
- Perform a dump of each monitor.
+- `shift left|right|up|down` — Exchange the current window with the given neighbor.
- list [--quiet]
- Perform a dump of each desktop for the current monitor.
+- `swap [biggest|smallest]` — Swap the focused window with the biggest/smallest window or with the last focused window if no arguments are given.
- windows
- Return the list of managed windows (i.e. their identifiers).
+- `push left|right|up|down` — Push the fence located in the given direction.
- close
- Close the focused window.
+- `pull left|right|up|down` — Pull the fence located in the given direction.
- kill
- Kill the focused window.
+- `cycle next|prev [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]` — Focus the next or previous window matching the given constraints.
- presel DIR
- Switch to manual mode and select the splitting direction.
+- `nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]` — Focus the nearest window matching the given constraints.
- ratio VALUE
- Set the splitting ratio of the focused window.
+- `circulate forward|backward` — Circulate the leaves in the given direction.
- cancel
- Switch to automatic mode.
+- `grab_pointer focus|move|resize_side|resize_corner` — Begin the specified pointer action.
- focus DIR
- Focus the neighbor node situated in the given direction.
+- `track_pointer ROOT_X ROOT_Y` — Pass the pointer root coordinates for the current pointer action.
- shift DIR
- Focus the neighbor node situated in the given direction.
+- `ungrab_pointer` — End the current pointer action.
- push DIR
- Push the fence located in the given direction.
+- `toggle_fullscreen` — Toggle the fullscreen state of the current window.
- pull DIR
- Pull the fence located in the given direction.
+- `toggle_floating` — Toggle the floating state of the current window.
- nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
- Focus the nearest leaf matching the given constraints.
+- `toggle_locked` — Toggle the locked state of the current window (locked windows will not respond to the `close` message).
- cycle CYC [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]
- Focus the next or previous window in the list of leaves.
+- `toggle_visibility` — Toggle the visibility of all the managed windows.
- rotate ROT
- Rotate the tree of the current desktop.
+- `close` — Close the focused window.
- magnetise COR
- Move all the fences toward the given corner.
+- `kill` — Kill the focused window.
- send_to_monitor MONITOR_NAME
- Send the focused window to the given monitor.
+- `send_to DESKTOP_NAME [--follow]` — Send the focused window to the given desktop.
- send_to DESKTOP_NAME
- Send the focused window to the given desktop.
+- `drop_to next|prev [--follow]` — Send the focused window to the next or previous desktop.
- use_monitor MONITOR_NAME
- Select the given monitor.
+- `send_to_monitor MONITOR_NAME [--follow]` — Send the focused window to the given monitor.
- use DESKTOP_NAME
- Select the given desktop.
+- `drop_to_monitor next|prev [--follow]` — Send the focused window to the next or previous monitor.
- alternate
- Alternate between the current and the last focused window.
+- `use DESKTOP_NAME` — Select the given desktop.
- alternate_desktop
- Alternate between the current and the last focused desktop.
+- `use_monitor MONITOR_NAME` — Select the given monitor.
- alternate_monitor
- Alternate between the current and the last focused monitor.
+- `alternate` — Alternate between the current and the last focused window.
- add_in MONITOR_NAME DESKTOP_NAME ...
- Make new desktops with the given names in the given monitor.
+- `alternate_desktop` — Alternate between the current and the last focused desktop.
- add DESKTOP_NAME ...
- Make new desktops with the given names.
+- `alternate_monitor` — Alternate between the current and the last focused monitor.
- rename_monitor CURRENT_NAME NEW_NAME
- Rename the monitor named CURRENT_NAME to NEW_NAME.
+- `add DESKTOP_NAME ...` — Make new desktops with the given names.
- rename CURRENT_NAME NEW_NAME
- Rename the desktop named CURRENT_NAME to NEW_NAME.
+- `add_in MONITOR_NAME DESKTOP_NAME ...` — Make new desktops with the given names in the given monitor.
- cycle_monitor CYC
- Select the next or previous monitor.
+- `rename_monitor CURRENT_NAME NEW_NAME` — Rename the monitor named `CURRENT_NAME` to `NEW_NAME`.
- cycle_desktop CYC
- Select the next or previous desktop.
-
- layout LYT
- Set the layout of the current desktop to LYT.
+- `rename CURRENT_NAME NEW_NAME` — Rename the desktop named `CURRENT_NAME` to `NEW_NAME`.
- cycle_layout
- Cycle the layout of the current desktop.
+- `cycle_monitor next|prev` — Select the next or previous monitor.
- toggle_fullscreen
- Toggle the fullscreen state of the current window.
+- `cycle_desktop next|prev [--skip-free|--skip-occupied]` — Select the next or previous desktop.
- toggle_floating
- Toggle the floating state of the current window.
+- `layout monocle|tiled [DESKTOP_NAME ...]` — Set the layout of the given desktops (current if none given).
- toggle_locked
- Toggle the locked state of the current window (locked windows will not respond to the 'close' command).
+- `cycle_layout` — Cycle the layout of the current desktop.
- rule PATTERN floating
- Make a new rule that will float the windows whose class name or instance name equals PATTERN.
+- `rotate clockwise|counter_clockwise|full_cycle` — Rotate the window tree.
- reload_autostart
- Reload the autostart file.
+- `flip horizontal|vertical` — Flip the window tree.
- reload_settings
- Reload the default settings.
+- `balance` — Adjust the split ratios so that all windows occupy the same area.
- reload
- Reload the autostart file and the default settings.
+- `rule PATTERN [DESKTOP_NAME] [floating] [follow]` — Create a new rule (`PATTERN` must match the class or instance name).
-Where
+- `remove_rule UID ...` — Remove the rules with the given UIDs.
- DIR = left|right|up|down
- CYC = next|prev
- ROT = clockwise|counter_clockwise|full_cycle
- COR = top_left|top_right|bottom_left|bottom_right
- LYT = monocle|tiled
+- `put_status` — Output the current state to the panel fifo.
+
+- `adopt_orphans` — Manage all the unmanaged windows remaining from a previous session.
+
+- `restore FILE_PATH` — Restore the layout of each desktop from the content of `FILE_PATH`.
+
+- `quit [EXIT_STATUS]` — Quit.
## Settings
-Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or '#RRGGBB', booleans are 'true' or 'false'.
+Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or *#RRGGBB*, booleans are *true* or *false*.
+
+- `focused_border_color` — Color of the border of a focused window of a focused monitor.
+
+- `active_border_color` — Color of the border of a focused window of an unfocused monitor.
+
+- `normal_border_color` — Color of the border of an unfocused window.
+
+- `presel_border_color` — Color of the `presel` message feedback.
- focused_border_color
- Color of the main border of a focused window of a focused monitor.
+- `focused_locked_border_color` — Color of the border of a focused locked window of a focused monitor.
- active_border_color
- Color of the main border of a focused window of an unfocused monitor.
+- `active_locked_border_color` — Color of the border of a focused locked window of an unfocused monitor.
- normal_border_color
- Color of the main border of an unfocused window.
-
- inner_border_color
- Color of the inner border of a window.
+- `normal_locked_border_color` — Color of the border of an unfocused locked window.
- outer_border_color
- Color of the outer border of a window.
-
- presel_border_color
- Color of the *presel* message feedback.
+- `urgent_border_color` — Color of the border of an urgent window.
- focused_locked_border_color
- Color of the main border of a focused locked window of a focused monitor.
+- `border_width` — Window border width.
- active_locked_border_color
- Color of the main border of a focused locked window of an unfocused monitor.
+- `window_gap` — Value of the gap that separates windows.
- normal_locked_border_color
- Color of the main border of an unfocused locked window.
+- `split_ratio` — Default split ratio.
- urgent_border_color
- Color of the border of an urgent window.
+- `{top,right,bottom,left}_padding` — Padding space added at the sides of the current monitor.
- inner_border_width
- main_border_width
- outer_border_width
- Width of the inner, main and outer borders.
+- `wm_name` — The value that shall be used for the `_NET_WM_NAME` property of the root window.
- window_gap
- Value of the gap that separates windows.
+- `borderless_monocle` — Whether to remove borders for tiled windows in monocle mode.
- top_padding
- bottom_padding
- left_padding
- right_padding
- Padding space added at the sides of the screen.
+- `gapless_monocle` — Whether to remove gaps for tiled windows in monocle mode.
- wm_name
- The value that shall be used for the _NET_WM_NAME property of the root window.
+- `focus_follows_pointer` — Whether to focus the window under the pointer.
- borderless_monocle
- Whether to remove borders for tiled windows in monocle mode.
+- `adaptative_raise` — Prevent floating windows from being raised when they might cover other floating windows.
- focus_follows_mouse
- Wether to focus the window under the mouse pointer.
+- `apply_shadow_property` — Enable shadows for floating windows via the `_COMPTON_SHADOW` property.
-## Mouse Bindings
+- `auto_alternate` — Whether to interpret two consecutive identical `use` messages as an `alternate` message.
- M4 + Left Button
- Move the window under the pointer.
+## Environment Variables
- M4 + Middle Button
- Focus the window under the pointer.
+- `BSPWM_SOCKET` — The path of the socket used for the communication between `bspc` and `bspwm`.
- M4 + Middle Button
- Resize the window under the pointer (by moving one of its four corners).
+## Key Features
-Where *M4* is the fourth modifier mask (generally bound to *Super*).
+- Configured and controlled through messages.
+- Multiple monitors support (via *Xinerama*).
+- EWMH support (`tint2` works).
+- Automatic and manual modes.
-## Panel
+## Panels
-`dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
+- Any EWMH compliant panel (e.g. `tint2`, `bmpanel2`, etc.).
+- A custom panel if the `-s` flag is used (have a look at the files in `examples/panel`).
+- `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
## Required Libraries:
-libxcb, xcb-util, xcb-util-wm.
+- libxcb
+- xcb-util
+- xcb-util-wm
## Installation
make
make install
+## Contributors
+
+- [Ivan Kanakarakis](https://github.com/c00kiemon5ter)
+
+- [Thomas Adam](https://github.com/ThomasAdam)
+
+## Mailing List
+
+bspwm *at* librelist *dot* com.
+
+## License
+
+BSD.
projects / bspwm.git / blobdiff