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/doc/bspwm.1.txt
Bastien Dejean a75979be62 Implement tags
2013-10-05 22:32:40 +02:00

692 lines
16 KiB
Text
Raw Blame History

:man source: Bspwm
:man version: {revnumber}
:man manual: Bspwm Manual
bspwm(1)
========
Name
----
bspwm - Binary space partitioning window manager
Synopsis
--------
*bspwm* [*-h*|*-v*|*-c* 'CONFIG_PATH'|*-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.
*-c* 'CONFIG_PATH'::
Use the given configuration file.
*-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* has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
The default configuration file is '$XDG_CONFIG_HOME/bspwm/bspwmrc'.
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.
Common Definitions
------------------
----
DIR := left | right | up | down
CYCLE_DIR := next | prev
----
Selectors
---------
Selectors are used to select a target window, desktop, or monitor. A selector
can either describe the target relatively or name it globally.
Descriptive (relative) selectors consist of a primary selector and any number
of non-conflicting modifiers as follows:
PRIMARY_SELECTOR[.MODIFIER]*
For obvious reasons, neither desktops nor monitors names may be valid
descriptive selectors.
Window
~~~~~~
Select a window.
----
WINDOW_SEL := <window_id>
| (DIR|CYCLE_DIR|biggest|last|focused)[.floating|.tiled][.like|.unlike][.automatic|.manual][.urgent|.nonurgent]
----
Primary Selectors
^^^^^^^^^^^^^^^^^
'DIR'::
Selects the window in the given (spacial) direction relative to the active
window.
'CYCLE_DIR'::
Selects the window in the given (cyclic) direction.
biggest::
Selects the biggest window on the current desktop.
last::
Selects the previously focused window.
focused::
Selects the currently focused window.
Modifiers
^^^^^^^^^
floating::
Only consider floating windows.
tiled::
Only consider tiled windows.
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.
automatic::
Only consider windows in automatic splitting mode.
manual::
Only consider windows in manual splitting mode (see *--presel*).
urgent::
Only consider urgent windows.
nonurgent::
Only consider nonurgent windows.
Desktop
~~~~~~~
Select a desktop.
----
DESKTOP_SEL := <desktop_name>
| ^<n>
| (CYCLE_DIR|last|focused)[.occupied|.free][.urgent|.nonurgent]
----
Primary Selectors
^^^^^^^^^^^^^^^^^
<desktop_name>::
Selects the desktop with the given name.
^<n>::
Selects the nth desktop.
'CYCLE_DIR'::
Selects the desktop in the given direction relative to the active desktop.
last::
Selects the previously focused desktop.
focused::
Selects the currently focused desktop.
Modifiers
^^^^^^^^^
occupied::
Only consider occupied desktops.
free::
Only consider free desktops.
urgent::
Only consider urgent desktops.
nonurgent::
Only consider nonurgent desktops.
Monitor
~~~~~~~
Select a monitor.
----
MONITOR_SEL := <monitor_name>
| ^<n>
| (DIR|CYCLE_DIR|last|primary|focused)[.occupied|.free]
----
Primary Selectors
^^^^^^^^^^^^^^^^^
<monitor_name>::
Selects the monitor with the given name.
^<n>::
Selects the nth monitor.
'DIR'::
Selects the monitor in the given (spacial) direction relative to the active monitor.
'CYCLE_DIR'::
Selects the monitor in the given (cyclic) direction relative to the active monitor.
primary::
Selects the primary monitor.
last::
Selects the previously focused monitor.
focused::
Selects the currently focused monitor.
Modifiers
^^^^^^^^^
occupied::
Only consider monitors where the focused desktop is occupied.
free::
Only consider monitors where the focused desktop is free.
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 (0 < 'RATIO' < 1).
*-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.
*-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|locked|sticky[=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_DIR'|monocle|tiled::
Set or cycle the layout of the selected desktop.
*-n*, *--rename* <new_name>::
Rename the selected desktop.
*-s*, *--swap* 'DESKTOP_SEL'::
Swap the selected desktop with the given desktop.
*-r*, *--remove*::
Remove the selected desktop.
*-c*, *--cancel-presel*::
Cancel the preselection of all the windows of the selected desktop.
*-F*, *--flip* 'horizontal|vertical'::
Flip the tree of the selected desktop.
*-R*, *--rotate* '90|270|180'::
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.
*-n*, *--rename* <new_name>::
Rename the selected monitor.
*-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.
*-s*, *--swap* 'MONITOR_SEL'::
Swap the selected monitor with the given monitor.
Tag
~~~
General Syntax
^^^^^^^^^^^^^^
tag 'OPTIONS'
Options
^^^^^^^
*-l*, *--list*::
List the tags.
*-a*, *--add* <name>...::
Create tags with the given names.
*-r*, *--remove* <name>|^<n>...::
Remove tags with the given names or indexes.
*-e*, *--enumerate-tags* <name>...::
Rename, add or remove tags depending on whether the number of given names is equal, superior or inferior to the number of existing tags.
*-d*, *--desktop* 'DESKTOP_SEL'::
Select the given desktop as target for the *-s* and *-t* options.
*-w*, *--window* 'WINDOW_SEL'::
Select the given window as target for the *-s* and *-t* options.
*-s*, *--set-tags* (<name>|^<n>...)|all::
Set the tags of the selected object.
*-t*, *--toggle-tags* (<name>|^<n>)[=on|off]...::
Toggle the tags of the selected object.
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.
*-S*, *--stack*::
Print the window stacking order.
[*-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.
*-S*, *--stack* <file_path>::
Load the window stacking order from the given file.
Control
~~~~~~~
General Syntax
^^^^^^^^^^^^^^
control 'OPTIONS'
Options
^^^^^^^
*--adopt-orphans*::
Manage all the unmanaged windows remaining from a previous session.
*--put-status*::
Write the current internal state to the panel FIFO.
*--toggle-visibility*::
Toggle the visibility of all the 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' [--follow]] [--tags <name>|^<n>[,...]][--floating] [--fullscreen] [--locked] [--sticky] [--focus] [--unmanage] [--one-shot]::
Create a new rule (<pattern> must match the class or instance name).
*-r*, *--remove* <rule_uid>|tail|head...::
Remove the rules with the given UIDs.
*-l*, *--list* [<pattern>]::
List the rules.
Config
~~~~~~
General Syntax
^^^^^^^^^^^^^^
config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'] <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.
Global Settings
~~~~~~~~~~~~~~~
'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.
'focused_sticky_border_color'::
Color of the border of a focused sticky window of a focused monitor.
'normal_sticky_border_color'::
Color of the border of an unfocused sticky window.
'urgent_border_color'::
Color of the border of an urgent window.
'split_ratio'::
Default split ratio.
'growth_factor'::
Intensity of the growth involved in pulling or pushing an edge.
'history_aware_focus'::
Give priority to the focus history when focusing nodes.
'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.
'auto_alternate'::
Interpret two consecutive identical *use* messages as an *alternate* message.
'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.
'honor_ewmh_focus'::
Honor EWMH requests to focus a window.
Monitor Settings
~~~~~~~~~~~~~~~~
'top_padding'::
'right_padding'::
'bottom_padding'::
'left_padding'::
Padding space added at the sides of the monitor.
Desktop Settings
~~~~~~~~~~~~~~~~
'window_gap'::
Size of the gap that separates windows.
'border_width'::
Window border width.
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-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').
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 <nihilhill at gmail.com>
Mailing List
------------
bspwm at librelist.com
////
vim: set ft=asciidoc:
////
Reference in a new issue View git blame Copy permalink