New windows are inserted in the tree as close as possible to the focused window.
-There is only two splitting modes: 'automatic' and 'manual'.
+There are only two splitting modes: 'automatic' and 'manual'.
The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
+-------------------------+ +-------------------------+
----
-Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
+Same action, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
----
b b
PRIMARY_SELECTOR[.MODIFIER]*
-For obvious reasons, neither desktops nor monitors names may be valid
-descriptive selectors.
+For obvious reasons, neither desktop nor monitor names may be valid descriptive
+selectors.
Window
~~~~~~
----
WINDOW_SEL := <window_id>
- | (DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.floating|.tiled][.like|.unlike][.manual|.automatic][.urgent][.local]
+ | (DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.manual|.automatic][.tiled|nontiled][.pseudotiled|.nonpseudotiled][.floating|.nonfloating][.fullscreen|.nonfullscreen][.below|.normal|.above][.local|.foreign][.like|.unlike][.focused|.unfocused][.urgent|.nonurgent][.sticky|.nonsticky][.public|.private][.locked|.unlocked]
----
Primary Selectors
Modifiers
^^^^^^^^^
+tiled::
+ Only consider tiled windows.
+
+nontiled::
+ Only consider tiled windows.
+
+pseudotiled::
+ Only consider pseudo-tiled windows.
+
+nonpseudotiled::
+ Only consider non pseudo-tiled windows.
+
floating::
Only consider floating windows.
-tiled::
- Only consider tiled windows.
+nonfloating::
+ Only consider non floating windows.
-like::
- Only consider windows that have the same class as the current window.
+fullscreen::
+ Only consider fullscreen windows.
-unlike::
- Only consider windows that have a different class than the current window.
+nonfullscreen::
+ Only consider non fullscreen windows.
manual::
Only consider windows in manual splitting mode.
automatic::
Only consider windows in automatic splitting mode.
+focused::
+ Only consider focused windows.
+
+unfocused::
+ Only consider unfocused windows.
+
+below::
+ Only consider windows of the BELOW layer.
+
+normal::
+ Only consider windows of the NORMAL layer.
+
+above::
+ Only consider windows of the ABOVE layer.
+
+like::
+ Only consider windows that have the same class as the current window.
+
+unlike::
+ Only consider windows that have a different class than the current window.
+
local::
Only consider windows of the current desktop.
+foreign::
+ Only consider windows outside of the current desktop.
+
+private::
+ Only consider private windows.
+
+public::
+ Only consider non private windows.
+
urgent::
Only consider urgent windows.
+nonurgent::
+ Only consider non urgent windows.
+
+sticky::
+ Only consider sticky windows.
+
+nonsticky::
+ Only consider non sticky windows.
+
+locked::
+ Only consider locked windows.
+
+unlocked::
+ Only consider non locked windows.
+
Desktop
~~~~~~~
----
DESKTOP_SEL := <desktop_name>
| [MONITOR_SEL:]^<n>
- | (CYCLE_DIR|last|[MONITOR_SEL:]focused|older|newer)[.occupied|.free][.urgent][.local]
+ | (CYCLE_DIR|last|[MONITOR_SEL:]focused|older|newer)[.occupied|.free][.urgent|.nonurgent][.local|.foreign]
----
Primary Selectors
urgent::
Only consider urgent desktops.
+nonurgent::
+ Only consider non urgent desktops.
+
local::
Only consider desktops of the current monitor.
+foreign::
+ Only consider desktops outside of the current monitor.
+
Monitor
~~~~~~~
Window States
-------------
-floating::
- Is above any tiled window and can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
+tiled::
+ Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
pseudo_tiled::
- Has a libre size while being centered in its tiling space.
+ Has an unrestricted size while being centered in its tiling space.
+
+floating::
+ Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
fullscreen::
- Fills its monitor rectangle, is above all the other windows and has no borders.
+ Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
+
+
+Window Flags
+-------------
locked::
Ignores the *close* message.
private::
Tries to keep the same tiling position/size.
+urgent::
+ Has its urgency hint set. This flag is set externally.
+
+
+Stacking Layers
+--------------
+
+There's three stacking layers: BELOW, NORMAL and ABOVE.
+
+In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
+
Commands
--------
*-f*, *--focus* ['WINDOW_SEL']::
Focus the selected or given window.
+*-a*, *--activate* ['WINDOW_SEL']::
+ Activate the selected or given window.
+
*-d*, *--to-desktop* 'DESKTOP_SEL'::
Send the selected window to the given desktop.
*-R*, *--rotate* 'DIR' '90|270|180'::
Rotate the tree holding the edge located in the given direction in relation to the selected window.
-*-t*, *--toggle* floating|fullscreen|pseudo_tiled|locked|sticky|private[=on|off]::
- Set or toggle the given state for the selected window.
+*-t*, *--state* tiled|pseudo_tiled|floating|fullscreen::
+ Set the state of the selected window.
+
+*-g*, *--flag* locked|sticky|private[=on|off]::
+ Set or toggle the given flag for the selected window.
+
+*-l*, *--layer* below|normal|above::
+ Set the stacking layer of the selected window.
*-c*, *--close*::
Close the selected window.
*-s*, *--swap* 'DESKTOP_SEL'::
Swap the selected desktop with the given desktop.
+*-b*, *--bubble* 'CYCLE_DIR'::
+ Bubble the selected desktop in the given direction.
+
*-r*, *--remove*::
Remove the selected desktop.
*-C*, *--circulate* forward|backward::
Circulate the leaves of the tree of the selected desktop.
-*-t*, *--toggle* floating[=on|off]::
- Set or toggle the given state for the selected desktop.
-
Monitor
~~~~~~~
Reorder the desktops of the selected monitor to match the given order.
*-d*, *--reset-desktops* <name>...::
- Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
+ Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops. Incidentally reset the settings of the existing desktops.
*-n*, *--rename* <new_name>::
Rename the selected monitor.
*--record-history* on|off::
Enable or disable the recording of window focus history.
-*--subscribe*::
- Continuously print status informations.
+*--subscribe* (all|report|monitor|desktop|window|...)*::
+ Continuously print status information. See the *EVENTS* section for the detailed description of each event.
*--get-status*::
- Print the current status informations.
+ Print the current status information.
Pointer
~~~~~~~
Options
^^^^^^^
-*-a*, *--add* <class_name>|<instance_name>|* [*-o*|*--one-shot*] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [(floating|fullscreen|pseudo_tiled|locked|sticky|private|center|follow|manage|focus)=(true|false)] [split_dir=DIR]::
+*-a*, *--add* <class_name>|<instance_name>|* [*-o*|*--one-shot*] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO] [(locked|sticky|private|center|follow|manage|focus|border)=(on|off)]::
Create a new rule.
*-r*, *--remove* ^<n>|head|tail|<class_name>|<instance_name>|*...::
Settings
--------
-Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
+Colors are either '#RRGGBB' or http://en.wikipedia.org/wiki/X11_color_names[X color names], booleans are 'true', 'on', 'false' or 'off'.
-All the boolean settings are 'false' by default.
+All the boolean settings are 'false' by default unless stated otherwise.
Global Settings
~~~~~~~~~~~~~~~
'external_rules_command'::
External command used to retrieve rule consequences. The command will receive the the ID of the window being processed as its first argument and the class and instance names as second and third arguments. The output of that command must have the following format: *key1=value1 key2=value2 ...* (the valid key/value pairs are given in the description of the 'rule' command).
+'initial_polarity'::
+ On which child should a new window be attached when adding a window on a single window tree in automatic mode. Accept the following values: *first_child*, *second_child*.
+
'history_aware_focus'::
Give priority to the focus history when focusing nodes.
+'focus_by_distance'::
+ Base focusing on distances between windows.
+
'borderless_monocle'::
- Remove borders for tiled windows in monocle mode.
+ Remove borders of tiled windows for the *monocle* desktop layout.
'gapless_monocle'::
- Remove gaps for tiled windows in monocle mode.
+ Remove gaps of tiled windows for the *monocle* desktop layout.
+
+'leaf_monocle'::
+ Set the desktop layout to *monocle* if there's only one tiled window in the tree.
'focus_follows_pointer'::
Focus the window under the pointer.
+'pointer_follows_focus'::
+ When focusing a window, put the pointer at its center.
+
'pointer_follows_monitor'::
When focusing a monitor, put the pointer at its center.
'auto_alternate'::
- Interpret two consecutive identical *use* messages as an *alternate* message.
+ Interpret consecutive identical *--focus* arguments as the *last* selector for the *monitor* and *desktop* commands.
'auto_cancel'::
- Interpret two consecutive identical *presel* messages as a *cancel* message.
-
-'apply_floating_atom'::
- Set the value of the '_BSPWM_FLOATING_WINDOW' atom of each window according to its floating state.
+ Interpret consecutive identical *--presel* arguments as *--cancel-presel* option.
'ignore_ewmh_focus'::
Ignore EWMH focus requests coming from applications.
-'remove_disabled_monitor'::
+'center_pseudo_tiled'::
+ Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
+
+'remove_disabled_monitors'::
Consider disabled monitors as disconnected.
'remove_unplugged_monitors'::
Remove unplugged monitors.
+'merge_overlapping_monitors'::
+ Merge overlapping monitors (the bigger remains).
+
Monitor and Desktop Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'left_padding'::
Padding space added at the sides of the monitor or desktop.
-Desktop and Window Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Default, Desktop Default and Window Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'border_width'::
Window border width.
-Desktop Settings
-~~~~~~~~~~~~~~~~
+Default and Desktop Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'window_gap'::
Size of the gap that separates windows.
-Status Format
+Events
+------
+
+'report'::
+ See the next section for the description of the format.
+
+'monitor_add <monitor_name> <monitor_id> <monitor_geometry>'::
+ A monitor is added.
+
+'monitor_rename <old_name> <new_name>'::
+ A monitor is renamed.
+
+'monitor_remove <monitor_name>'::
+ A monitor is removed.
+
+'monitor_focus <monitor_name>'::
+ A monitor is focused.
+
+'monitor_geometry <monitor_name> <monitor_geometry>'::
+ The geometry of a monitor changed.
+
+'desktop_add <monitor_name> <desktop_name>'::
+ A desktop is added.
+
+'desktop_rename <monitor_name> <old_name> <new_name>'::
+ A desktop is renamed.
+
+'desktop_remove <monitor_name> <desktop_name>'::
+ A desktop is removed.
+
+'desktop_swap <src_monitor_name> <src_desktop_name> <dst_monitor_name> <dst_desktop_name>'::
+ A desktop is swapped.
+
+'desktop_transfer <src_monitor_name> <src_desktop_name> <dst_monitor_name>'::
+ A desktop is transferred.
+
+'desktop_focus <monitor_name> <desktop_name>'::
+ A desktop is focused.
+
+'desktop_layout <monitor_name> <desktop_name> tiled|monocle'::
+ The layout of a desktop changed.
+
+'window_manage <monitor_name> <desktop_name> <window_id> <ip_id>'::
+ A window is managed.
+
+'window_unmanage <monitor_name> <desktop_name> <window_id>'::
+ A window is unmanaged.
+
+'window_swap <src_monitor_name> <src_desktop_name> <src_window_id> <dst_monitor_name> <dst_desktop_name> <dst_window_id>'::
+ A window is swapped.
+
+'window_transfer <src_monitor_name> <src_desktop_name> <src_window_id> <dst_monitor_name> <dst_desktop_name> <dst_window_id>'::
+ A window is transferred.
+
+'window_focus <monitor_name> <desktop_name> <window_id>'::
+ A window is focused.
+
+'window_activate <monitor_name> <desktop_name> <window_id>'::
+ A window is activated.
+
+'window_geometry <monitor_name> <desktop_name> <window_id> <window_geometry>'::
+ The geometry of a window changed.
+
+'window_state <monitor_name> <desktop_name> <window_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
+ The state of a window changed.
+
+'window_flag <monitor_name> <desktop_name> <window_id> sticky|private|locked|urgent on|off'::
+ One of the flags of a window changed.
+
+'window_layer <monitor_name> <desktop_name> <window_id> below|normal|above'::
+ The layer of a window changed.
+
+Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
+
+Report Format
-------------
-Status informations are composed of items separated by colons.
+Each report event message is composed of items separated by colons.
Each item has the form '<type><value>' where '<type>' is the first character of the item.
'u<desktop_name>'::
Urgent unfocused desktop.
-'L(tiled|monocle)'::
- Layout of the focused desktop of the focused monitor.
+'L(T|M)'::
+ Layout of the focused desktop of a monitor.
Environment Variables
---------------------
'BSPWM_SOCKET'::
- The path of the socket used for the communication between *bspc* and *bspwm*. If it isn't defined, then the following path is used: '/tmp/bspwm<display_name>-socket'.
+ The path of the socket used for the communication between *bspc* and *bspwm*. If it isn't defined, then the following path is used: '/tmp/bspwm<host_name>_<display_number>_<screen_number>-socket'.
Panels
------
* 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').
+* A custom panel (have a look at the files in 'examples/panel').
Key Features
------------
* Configured and controlled through messages.
-* Multiple monitors support (via 'RandR').
-* EWMH support (*tint2* works).
+* Multiple monitors support.
+* EWMH support.
* Hybrid tiling.
Contributors
projects / bspwm.git / blobdiff