FLAG := hidden|sticky|private|locked|marked|urgent
LAYER := below|normal|above
SPLIT_TYPE := horizontal|vertical
PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
JUMP := first|1|second|2|brother|parent|DIR
----
Descriptors
^^^^^^^^^^^
'DIR'::
Selects the window in the given (spacial) direction relative to the reference node.
'CYCLE_DIR'::
Selects the node in the given (cyclic) direction relative to the reference node within a depth-first in-order traversal of the tree.
'PATH'::
Selects the node at the given path.
any::
Selects the first node that matches the given selectors.
first_ancestor::
Selects the first ancestor of the reference node that matches the given selectors.
last::
Selects the previously focused node relative to the reference node.
newest::
Selects the newest node in the history of the focused node.
older::
Selects the node older than the reference node in the history.
newer::
Selects the node newer than the reference node in the history.
focused::
Selects the currently focused node.
pointed::
Selects the leaf under the pointer.
biggest::
Selects the biggest leaf.
smallest::
Selects the smallest leaf.
<node_id>::
Selects the node with the given ID.
Path Jumps
^^^^^^^^^^
The initial node is the focused node (or the root if the path starts with '/') of the reference desktop (or the selected desktop if the path has a 'DESKTOP_SEL' prefix).
1|first::
Jumps to the first child.
2|second::
Jumps to the second child.
brother::
Jumps to the brother node.
parent::
Jumps to the parent node.
'DIR'::
Jumps to the node holding the edge in the given direction.
Modifiers
^^^^^^^^^
[!]focused::
Only consider the focused node.
[!]active::
Only consider nodes that are the focused node of their desktop.
[!]automatic::
Only consider nodes in automatic insertion mode. See also *--presel-dir* under *Node* in the *DOMAINS* section below.
[!]local::
Only consider nodes in the reference desktop.
[!]leaf::
Only consider leaf nodes.
[!]window::
Only consider nodes that hold a window.
[!](tiled|pseudo_tiled|floating|fullscreen)::
Only consider windows in the given state.
[!]same_class::
Only consider windows that have the same class as the reference window.
[!]descendant_of::
Only consider nodes that are descendants of the reference node.
[!]ancestor_of::
Only consider nodes that are ancestors of the reference node.
[!](hidden|sticky|private|locked|marked|urgent)::
Only consider windows that have the given flag set.
Selects the monitor in the given (spacial) direction relative to the reference monitor.
'CYCLE_DIR'::
Selects the monitor in the given (cyclic) direction relative to the reference monitor.
any::
Selects the first monitor that matches the given selectors.
last::
Selects the previously focused monitor relative to the reference monitor.
newest::
Selects the newest monitor in the history of the focused monitors.
older::
Selects the monitor older than the reference monitor in the history.
newer::
Selects the monitor newer than the reference monitor in the history.
focused::
Selects the currently focused monitor.
pointed::
Selects the monitor under the pointer.
primary::
Selects the primary monitor.
^<n>::
Selects the nth monitor.
<monitor_id>::
Selects the monitor with the given ID.
<monitor_name>::
Selects the monitor with the given name.
Modifiers
^^^^^^^^^
[!]focused::
Only consider the focused monitor.
[!]occupied::
Only consider monitors where the focused desktop is occupied.
Window States
-------------
tiled::
Its size and position are determined by the window tree.
pseudo_tiled::
A tiled window that automatically shrinks but doesn't stretch beyond its floating size.
floating::
Can be moved/resized freely. Although it doesn't use any tiling space, it is still part of the window tree.
fullscreen::
Fills its monitor rectangle and has no borders.
Node Flags
----------
hidden::
Is hidden and doesn't occupy any tiling space.
sticky::
Stays in the focused desktop of its monitor.
private::
Tries to keep the same tiling position/size.
locked::
Ignores the *node --close* message.
marked::
Is marked (useful for deferred actions). A marked node becomes unmarked after being sent on a preselected node.
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 < floating < fullscreen.
Receptacles
-----------
A leaf node that doesn't hold any window is called a receptacle. When a node is inserted on a receptacle in automatic mode, it will replace the receptacle. A receptacle can be inserted on a node, preselected and killed. Receptacles can therefore be used to build a tree whose leaves are receptacles. Using the appropriate rules, one can then send windows on the leaves of this tree. This feature is used in 'examples/receptacles' to store and recreate layouts.
Domains
-------
Node
~~~~
General Syntax
^^^^^^^^^^^^^^
node ['NODE_SEL'] 'COMMANDS'
If 'NODE_SEL' is omitted, *focused* is assumed.
Commands
^^^^^^^^
*-f*, *--focus* ['NODE_SEL']::
Focus the selected or given node.
*-a*, *--activate* ['NODE_SEL']::
Activate the selected or given node.
*-d*, *--to-desktop* 'DESKTOP_SEL' [*--follow*]::
Send the selected node to the given desktop. If *--follow* is passed, the focused node will stay focused.
*-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
Send the selected node to the given monitor. If *--follow* is passed, the focused node will stay focused.
*-n*, *--to-node* 'NODE_SEL' [*--follow*]::
Send the selected node on the given node. If *--follow* is passed, the focused node will stay focused.
*-s*, *--swap* 'NODE_SEL' [*--follow*]::
Swap the selected node with the given node. If *--follow* is passed, the focused node will stay focused.
*-p*, *--presel-dir* \[~]'DIR'|cancel::
Preselect the splitting area of the selected node (or cancel the preselection). If *~* is prepended to 'DIR' and the current preselection direction matches 'DIR', then the argument is interpreted as *cancel*. A node with a preselected area is said to be in "manual insertion mode".
*-o*, *--presel-ratio* 'RATIO'::
Set the splitting ratio of the preselection area.
*-v*, *--move* 'dx' 'dy'::
Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.
Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
*-R*, *--rotate* '90|270|180'::
Rotate the tree rooted at the selected node.
*-F*, *--flip* 'horizontal|vertical'::
Flip the tree rooted at selected node.
*-E*, *--equalize*::
Reset the split ratios of the tree rooted at the selected node to their default value.
*-B*, *--balance*::
Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
*-C*, *--circulate* forward|backward::
Circulate the windows of the tree rooted at the selected node.
*-t*, *--state* \~|\[~]'STATE'::
Set the state of the selected window. If *\~* is present and the current state matches 'STATE', then the argument is interpreted as its last state. If the argument is just *~* with 'STATE' omitted, then the state of the selected window is set to its last state.
Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
All the boolean settings are 'false' by default unless stated otherwise.
Global Settings
~~~~~~~~~~~~~~~
'normal_border_color'::
Color of the border of an unfocused window.
'active_border_color'::
Color of the border of a focused window of an unfocused monitor.
'focused_border_color'::
Color of the border of a focused window of a focused monitor.
'presel_feedback_color'::
Color of the *node --presel-{dir,ratio}* message feedback area.
'split_ratio'::
Default split ratio.
'status_prefix'::
Prefix prepended to each of the status lines.
'external_rules_command'::
Absolute path to the command used to retrieve rule consequences. The command will receive the following arguments: window ID, class name, instance name, and intermediate consequences. 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).
'automatic_scheme'::
The insertion scheme used when the insertion point is in automatic mode. Accept the following values: *longest_side*, *alternate*, *spiral*.
'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*.
'directional_focus_tightness'::
The tightness of the algorithm used to decide whether a window is on the 'DIR' side of another window. Accept the following values: *high*, *low*.
'removal_adjustment'::
Adjust the brother when unlinking a node from the tree in accordance with the automatic insertion scheme.
'presel_feedback'::
Draw the preselection feedback area. Defaults to 'true'.
'borderless_monocle'::
Remove borders of tiled windows for the *monocle* desktop layout.
'gapless_monocle'::
Remove gaps of tiled windows for the *monocle* desktop layout.
'top_monocle_padding'::
'right_monocle_padding'::
'bottom_monocle_padding'::
'left_monocle_padding'::
Padding space added at the sides of the screen for the *monocle* desktop layout.
'single_monocle'::
Set the desktop layout to *monocle* if there's only one tiled window in the tree.
'borderless_singleton'::
Remove borders of the only window on the only monitor regardless its layout.
'pointer_motion_interval'::
The minimum interval, in milliseconds, between two motion notify events.
'pointer_modifier'::
Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.
'pointer_action1'::
'pointer_action2'::
'pointer_action3'::
Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
'click_to_focus'::
Button used for focusing a window (or a monitor). The possible values are: *button1*, *button2*, *button3*, *any*, *none*. Defaults to *button1*.
'swallow_first_click'::
Don't replay the click that makes a window focused if 'click_to_focus' isn't *none*.
'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.
'mapping_events_count'::
Handle the next *mapping_events_count* mapping notify events. A negative value implies that every event needs to be handled.
'ignore_ewmh_focus'::
Ignore EWMH focus requests coming from applications.
'ignore_ewmh_fullscreen'::
Block the fullscreen state transitions that originate from an EWMH request. The possible values are: *none*, *all*, or a comma separated list of the following values: *enter*, *exit*.
'ignore_ewmh_struts'::
Ignore strut hinting from clients requesting to reserve space (i.e. task bars).
'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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'top_padding'::
'right_padding'::
'bottom_padding'::
'left_padding'::
Padding space added at the sides of the monitor or desktop.
Desktop Settings
~~~~~~~~~~~~~~~~
'window_gap'::
Size of the gap that separates windows.
Node Settings
~~~~~~~~~~~~~
'border_width'::
Window border width.
'honor_size_hints'::
If 'true', apply ICCCM window size hints to all windows. If 'floating', only apply them to floating and pseudo tiled windows. If 'tiled', only apply them to tiled windows. If 'false', don't apply them. Defaults to 'false'.
Pointer Bindings
----------------
'click_to_focus'::
Focus the window (or the monitor) under the pointer if the value isn't *none*.
'pointer_modifier' + 'button1'::
Move the window under the pointer.
'pointer_modifier' + 'button2'::
Resize the window under the pointer by dragging the nearest side.
'pointer_modifier' + 'button3'::
Resize the window under the pointer by dragging the nearest corner.
The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.
Events
------
'report'::
See the next section for the description of the format.
The path of the socket used for the communication between *tspc* and *tspwm*. If it isn't defined, then the following path is used: '/tmp/tspwm<host_name>_<display_number>_<screen_number>-socket'.
