hiro/bspwm
1
0
Fork 0
mirror of https://github.com/vale981/bspwm synced 2025-03-06 10:11:43 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
bspwm/README.asciidoc
Bastien Dejean 8fd8521322 Rewrite message handling 
The new message syntax:
- Provides 10 commands instead of 60.
- Allows multiple actions to be applied in one call.

The client now returns an non zero exit code when a message fails.

The `is_adjacent` function now handles vacant nodes.
2013-07-12 21:52:02 +02:00

484 lines
11 KiB
Text
Raw Blame History

image:https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png[logo]
:man source: Bspwm
:man version: {revnumber}
:man manual: Bspwm Manual
bspwm(1)
========
Name
----
bspwm - Tiling window manager based on binary space partitioning
Synopsis
--------
*bspwm* [*-h*|*-v*|*-s* 'PANEL_FIFO'|*-p* 'PANEL_PREFIX']
*bspc* 'COMMAND' ['ARGUMENTS']
Description
-----------
*bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
It is controlled and configured via *bspc*.
Options
-------
*-h*::
Print the synopsis and exit.
*-v*::
Print the version and exit.
*-s* 'PANEL_FIFO'::
Write the internal state to the given FIFO.
*-p* 'PANEL_PREFIX'::
Start every line written to the 'PANEL_FIFO' with the given prefix.
Configuration
-------------
*bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.
Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
Example configuration files can be found in the *examples* directory.
Splitting Modes
---------------
New windows are inserted in the tree as close as possible to the focused window.
There is only two splitting modes: 'automatic' and 'manual'.
The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
----
b c
/ \ / \
3 a --> 4 b
^ / \ ^ / \
2 1 3 a
/ \
2 1
+-------------------------+ +-------------------------+
| | | | | |
| | 2 | | | 3 |
| | | | | |
| 3 |------------| --> | 4 |------------|
| ^ | | | ^ | | |
| | 1 | | | 1 | 2 |
| | | | | | |
+-------------------------+ +-------------------------+
----
Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
----
b b
/ \ / \
3 a --> c a
^ / \ / \ / \
2 1 4 3 2 1
^
+-------------------------+ +-------------------------+
| | | | | |
| | 2 | | 4 | 2 |
| | | | ^ | |
| 3 |------------| --> |------------|------------|
| ^ | | | | |
| | 1 | | 3 | 1 |
| | | | | |
+-------------------------+ +-------------------------+
----
Containers
----------
Each monitor contains at least one desktop.
Each desktop contains at most one tree.
Definitions
-----------
----
WINDOW_SEL := (CYCLE|DIR|biggest|focused|last)[.WINDOW_CLASS] | <window_id>
DESKTOP_SEL := (CYCLE|focused|last)[.DESKTOP_CLASS] | <desktop_name>
MONITOR_SEL := (CYCLE|DIR|focused|last)[.DESKTOP_CLASS] | <monitor_name>
DESKTOP_CLASS := [occupied|free]
WINDOW_CLASS := [floating|tiled][.][like|unlike]
DIR := left|right|up|down
CYCLE := next|prev
ROTATE := 90|270|180
FLIP := horizontal|vertical
----
Commands
--------
Window
~~~~~~
General Syntax
^^^^^^^^^^^^^^
window ['WINDOW_SEL'] 'OPTIONS'
Options
^^^^^^^
*-f*, *--focus* ['WINDOW_SEL']::
Focus the selected or given window.
*-d*, *--to-desktop* 'DESKTOP_SEL'::
Send the selected window to the given desktop.
*-m*, *--to-monitor* 'MONITOR_SEL'::
Send the selected window to the given monitor.
*-w*, *--to-window* 'WINDOW_SEL'::
Transplant the selected window to the given window.
*-s*, *--swap* 'WINDOW_SEL'::
Swap the selected window with the given window.
*-p*, *--presel* 'DIR'|cancel::
Preselect the splitting area of the selected window (or cancel the preselection).
*-r*, *--ratio* 'RATIO'::
Set the splitting ratio of the selected window.
*-e*, *--edge* 'DIR' 'RATIO'|pull|push::
Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
*-t*, *--toggle* floating|fullscreen|locked[=on|off]::
Set or toggle the given state for the selected window.
*-c*, *--close*::
Close the selected window.
*-k*, *--kill*::
Kill the selected window.
Desktop
~~~~~~~
General Syntax
^^^^^^^^^^^^^^
desktop ['DESKTOP_SEL'] 'OPTIONS'
Options
^^^^^^^
*-f*, *--focus* ['DESKTOP_SEL']::
Focus the selected or given desktop.
*-m*, *--to-monitor* 'MONITOR_SEL'::
Send the selected desktop to the given monitor.
*-l*, *--layout* 'CYCLE'|monocle|tiled::
Set or cycle the layout of the selected desktop.
*-n*, *--rename* <new_name>::
Rename the selected desktop.
*-r*, *--remove*::
Remove the selected desktop.
*-c*, *--cancel-presel*::
Cancel the preselection of all the windows of the selected desktop.
*-F*, *--flip* 'FLIP'::
Flip the tree of the selected desktop.
*-R*, *--rotate* 'ROTATE'::
Rotate the tree of the selected desktop.
*-B*, *--balance*::
Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
*-C*, *--circulate* forward|backward::
Circulate the leaves of the tree of the selected desktop.
Monitor
~~~~~~~
General Syntax
^^^^^^^^^^^^^^
monitor ['MONITOR_SEL'] 'OPTIONS'
Options
^^^^^^^
*-f*, *--focus* ['MONITOR_SEL']::
Focus the selected or given monitor.
*-a*, *--add-desktops* <name>...::
Create desktops with the given names in the selected monitor.
*-r*, *--remove-desktops* <name>...::
Remove desktops with the given names.
*-p*, *--pad* <top> <right> <bottom> <left>::
Set the padding of the selected monitor.
*-n*, *--rename* <new_name>::
Rename the selected monitor.
Query
~~~~~
General Syntax
^^^^^^^^^^^^^^
query 'OPTIONS'
Options
^^^^^^^
*-W*, *--windows*::
List matching windows.
*-D*, *--desktops*::
List matching desktops.
*-M*, *--monitors*::
List matching monitors.
*-T*, *--tree*::
Print tree rooted at query.
*-H*, *--history*::
Print the history as it relates to the query.
[*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
Constrain matches to the selected monitor, desktop or window.
Restore
~~~~~~~
General Syntax
^^^^^^^^^^^^^^
restore 'OPTIONS'
Options
^^^^^^^
*-T*, *--tree* <file_path>::
Load the desktop trees from the given file.
*-H*, *--history* <file_path>::
Load the focus history from the given file.
Control
~~~~~~~
General Syntax
^^^^^^^^^^^^^^
control 'OPTIONS'
Options
^^^^^^^
*--adopt-orphans* <file_path>::
Manage all the unmanaged windows remaining from a previous session.
*--put-status* <file_path>::
Write the current internal state to the panel FIFO.
*--toggle-visibility*::
Toggle the visibility of all the managed windows.
Pointer
~~~~~~~
General Syntax
^^^^^^^^^^^^^^
pointer 'OPTIONS'
Options
^^^^^^^
*-t*, *--track* <x> <y>::
Pass the pointer root coordinates for the current pointer action.
*-g*, *--grab* focus|move|resize_side|resize_corner::
Perform the given pointer action.
Rule
~~~~
General Syntax
^^^^^^^^^^^^^^
rule 'OPTIONS'
Options
^^^^^^^
*-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
Create a new rule (<pattern> must match the class or instance name).
*-r*, *--rm* <rule_uid>...::
Remove the rules with the given UIDs.
*-l*, *--list* [<pattern>]::
List the rules.
Config
~~~~~~
General Syntax
^^^^^^^^^^^^^^
config <key> [<value>]::
Get or set the value of <key>.
Quit
~~~~
General Syntax
^^^^^^^^^^^^^^
quit [<status>]::
Quit with an optional exit status.
Settings
--------
Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
All the boolean settings are 'false' by default.
'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_locked_border_color'::
Color of the border of a focused locked window of a focused monitor.
'active_locked_border_color'::
Color of the border of a focused locked window of an unfocused monitor.
'normal_locked_border_color'::
Color of the border of an unfocused locked window.
'urgent_border_color'::
Color of the border of an urgent window.
'border_width'::
Window border width.
'window_gap'::
Value of the gap that separates windows.
'split_ratio'::
Default split ratio.
'top_padding'::
'right_padding'::
'bottom_padding'::
'left_padding'::
Padding space added at the sides of the current monitor.
'wm_name'::
The value that shall be used for the '_NET_WM_NAME' property of the root window.
'borderless_monocle'::
Remove borders for tiled windows in monocle mode.
'gapless_monocle'::
Remove gaps for tiled windows in monocle mode.
'focus_follows_pointer'::
Focus the window under the pointer.
'pointer_follows_monitor'::
When focusing a monitor, put the pointer at its center.
'monitor_focus_fallback'::
If the focus message fails, try to focus the nearest monitor in the same direction.
'adaptative_raise'::
Prevent floating windows from being raised when they might cover other floating windows.
'apply_shadow_property'::
Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
'auto_alternate'::
Interpret two consecutive identical *use* messages as an *alternate* message.
'auto_cancel'::
Interpret two consecutive identical *presel* messages as a *cancel* message.
'focus_by_distance'::
Use window or leaf distance for focus movement.
'history_aware_focus'::
Give priority to the focus history when focusing nodes.
Environment Variables
---------------------
'BSPWM_SOCKET'::
The path of the socket used for the communication between *bspc* and *bspwm*.
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').
Key Features
------------
* Configured and controlled through messages.
* Multiple monitors support (via 'RandR').
* EWMH support (*tint2* works).
* Hybrid tiling.
Contributors
------------
* Steven Allen <steven at stebalien.com>
* Thomas Adam <thomas at xteddy.org>
* Ivan Kanakarakis <ivan.kanak at gmail.com>
Author
------
Bastien Dejean <baskerville at lavabit.com>
Mailing List
------------
bspwm at librelist.com
////
vim: set ft=asciidoc:
////
Reference in a new issue View git blame Copy permalink