Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BSPWM(1)			 Bspwm Manual			      BSPWM(1)

NAME
       bspwm - Binary space partitioning window	manager

SYNOPSIS
       bspwm [-h|-v|-c CONFIG_PATH]

       bspc DOMAIN [SELECTOR] COMMANDS

       bspc COMMAND [OPTIONS] [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.

COMMON DEFINITIONS
	   DIR	       := north	| west | south | east
	   CYCLE_DIR   := next | prev

SELECTORS
       Selectors are used to select a target node, desktop, or monitor.	A
       selector	can either describe the	target relatively or name it globally.

       Selectors consist of an optional	reference, a descriptor	and any	number
       of non-conflicting modifiers as follows:

	   [REFERENCE#]DESCRIPTOR(.MODIFIER)*

       The relative targets are	computed in relation to	the given reference
       (the default reference value is focused).

       An exclamation mark can be prepended to any modifier in order to
       reverse its meaning.

   Node
       Select a	node.

	   NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|older|newer|focused|pointed|biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active][.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class][.[!]descendant_of][.[!]ancestor_of]

	   STATE := tiled|pseudo_tiled|floating|fullscreen

	   FLAG	:= hidden|sticky|private|locked|urgent

	   LAYER := below|normal|above

	   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 window in the given (cyclic)	direction relative to
	       the reference node.

	   PATH
	       Selects the node	at the given path.

	   last
	       Selects the previously focused node relative to the reference
	       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 window under	the pointer.

	   biggest
	       Selects the biggest window.

	   <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 focused or	unfocused nodes.

	   [!]automatic
	       Only consider nodes in automatic	or manual insertion mode.

	   [!]local
	       Only consider nodes in or not in	the reference desktop.

	   [!]active
	       Only consider nodes in or not in	the active desktop of their
	       monitor.

	   [!]leaf
	       Only consider leaves or internal	nodes.

	   [!]window
	       Only consider nodes that	hold or	don't hold a window.

	   [!](tiled|pseudo_tiled|floating|fullscreen)
	       Only consider windows in	or not in the given state.

	   [!]same_class
	       Only consider windows that have or don't	have the same class as
	       the reference window.

	   [!]descendant_of
	       Only consider nodes that	are or aren't descendants of the
	       reference node.

	   [!]ancestor_of
	       Only consider nodes that	are or aren't ancestors	of the
	       reference node.

	   [!](hidden|sticky|private|locked|urgent)
	       Only consider windows that have or don't	have the given flag
	       set.

	   [!](below|normal|above)
	       Only consider windows in	or not in the given layer.

   Desktop
       Select a	desktop.

	   DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]

       Descriptors
	   CYCLE_DIR
	       Selects the desktop in the given	direction relative to the
	       reference desktop.

	   last
	       Selects the previously focused desktop relative to the
	       reference desktop.

	   older
	       Selects the desktop older than the reference desktop in the
	       history.

	   newer
	       Selects the desktop newer than the reference desktop in the
	       history.

	   focused
	       Selects the currently focused desktop.

	   ^<n>
	       Selects the nth desktop.

	   <desktop_id>
	       Selects the desktop with	the given ID.

	   <desktop_name>
	       Selects the desktop with	the given name.

       Modifiers
	   [!]occupied
	       Only consider occupied or free desktops.

	   [!]focused
	       Only consider focused or	unfocused desktops.

	   [!]urgent
	       Only consider urgent or non urgent desktops.

	   [!]local
	       Only consider inside or outside of the reference	monitor.

   Monitor
       Select a	monitor.

	   MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|focused|primary|^<n>|<monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]

       Descriptors
	   DIR
	       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.

	   last
	       Selects the previously focused monitor relative to the
	       reference monitor.

	   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.

	   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
	   [!]occupied
	       Only consider monitors where the	focused	desktop	is occupied or
	       free.

	   [!]focused
	       Only consider focused or	unfocused monitors.

WINDOW STATES
       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 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 and has no borders. It is send in the
	   ABOVE layer by default.

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.

       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.

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
	       Send the	selected node to the given desktop.

	   -m, --to-monitor MONITOR_SEL
	       Send the	selected node to the given monitor.

	   -n, --to-node NODE_SEL
	       Transplant the selected node to the given node.

	   -s, --swap NODE_SEL
	       Swap the	selected node with the given node.

	   -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.

	   -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.

	   -z, --resize
	   top|left|bottom|right|top_left|top_right|bottom_right|bottom_left
	   dx dy
	       Resize the selected window by moving the	given handle by	dx
	       pixels horizontally and dy pixels vertically.

	   -r, --ratio RATIO|(+|-)PIXELS
	       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	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 [~](tiled|pseudo_tiled|floating|fullscreen)
	       Set the state of	the selected window. If	~ is present and the
	       current state matches the given state, then the argument	is
	       interpreted as the last state.

	   -g, --flag hidden|sticky|private|locked[=on|off]
	       Set or toggle the given flag for	the selected node.

	   -l, --layer below|normal|above
	       Set the stacking	layer of the selected window.

	   -i, --insert-receptacle
	       Insert a	receptacle node	at the selected	node.

	   -c, --close
	       Close the windows rooted	at the selected	node.

	   -k, --kill
	       Kill the	windows	rooted at the selected node.

   Desktop
       General Syntax
	   desktop [DESKTOP_SEL] COMMANDS

	   If DESKTOP_SEL is omitted, focused is assumed.

       COMMANDS
	   -f, --focus [DESKTOP_SEL]
	       Focus the selected or given desktop.

	   -a, --activate [DESKTOP_SEL]
	       Activate	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.

	   -b, --bubble	CYCLE_DIR
	       Bubble the selected desktop in the given	direction.

	   -r, --remove
	       Remove the selected desktop.

   Monitor
       General Syntax
	   monitor [MONITOR_SEL] COMMANDS

	   If MONITOR_SEL is omitted, focused is assumed.

       Commands
	   -f, --focus [MONITOR_SEL]
	       Focus the selected or given monitor.

	   -s, --swap MONITOR_SEL
	       Swap the	selected monitor with the given	monitor.

	   -a, --add-desktops <name>...
	       Create desktops with the	given names in the selected monitor.

	   -o, --reorder-desktops <name>...
	       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.

	   -g, --rectangle WxH+X+Y
	       Set the rectangle of the	selected monitor.

	   -n, --rename	<new_name>
	       Rename the selected monitor.

	   -r, --remove
	       Remove the selected monitor.

   Query
       General Syntax
	   query COMMANDS [OPTIONS]

       Commands
	   The optional	selectors are references.

	   -N, --nodes [NODE_SEL]
	       List the	IDs of the matching nodes.

	   -D, --desktops [DESKTOP_SEL]
	       List the	IDs of the matching desktops.

	   -M, --monitors [MONITOR_SEL]
	       List the	IDs of the matching monitors.

	   -T, --tree
	       Print a JSON representation of the matching item.

       Options
	   -m,--monitor	[MONITOR_SEL], -d,--desktop [DESKTOP_SEL], -n, --node
	   [NODE_SEL]
	       Constrain matches to the	selected monitor, desktop or node. The
	       descriptor can be omitted for -M, -D and	-N.

   Wm
       General Syntax
	   wm COMMANDS

       Commands
	   -d, --dump-state
	       Dump the	current	world state on standard	output.

	   -l, --load-state <file_path>
	       Load a world state from the given file.

	   -a, --add-monitor <name> WxH+X+Y
	       Add a monitor for the given name	and rectangle.

	   -o, --adopt-orphans
	       Manage all the unmanaged	windows	remaining from a previous
	       session.

	   -h, --record-history	on|off
	       Enable or disable the recording of node focus history.

	   -g, --get-status
	       Print the current status	information.

   Rule
       General Syntax
	   rule	COMMANDS

       Commands
	   -a, --add (<class_name>|*)[:(<instance_name>|*)] [-o|--one-shot]
	   [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|node=NODE_SEL]
	   [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO]
	   [(hidden|sticky|private|locked|center|follow|manage|focus|border)=(on|off)]
	       Create a	new rule.

	   -r, --remove
	   ^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)]...
	       Remove the given	rules.

	   -l, --list
	       List the	rules.

   Config
       General Syntax
	   config [-m MONITOR_SEL|-d DESKTOP_SEL|-n NODE_SEL] <key> [<value>]
	       Get or set the value of <key>.

   Subscribe
       General Syntax
	   subscribe (all|report|monitor|desktop|node|...)*
	       Continuously print status information. See the EVENTS section
	       for the detailed	description of each event.

   Quit
       General Syntax
	   quit	[<status>]
	       Quit with an optional exit status.

EXIT CODES
       If the server can't handle a message, bspc will return with a non-zero
       exit code.

SETTINGS
       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
	   External command used to retrieve rule consequences.	The command
	   will	receive	the following arguments: window	ID, class and instance
	   names, monitor, desktop and node selectors. 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.

       borderless_monocle
	   Remove borders of tiled windows for the monocle desktop layout.

       gapless_monocle
	   Remove gaps of tiled	windows	for the	monocle	desktop	layout.

       paddingless_monocle
	   Remove padding space	for the	monocle	desktop	layout.

       single_monocle
	   Set the desktop layout to monocle if	there's	only one tiled window
	   in the tree.

       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
	   Focus a window (or a	monitor) by clicking it.

       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.

       ignore_ewmh_focus
	   Ignore EWMH focus requests coming from applications.

       center_pseudo_tiled
	   Center pseudo tiled windows into their tiling rectangles. Defaults
	   to true.

       honor_size_hints
	   Apply ICCCM window size hints.

       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.

POINTER	BINDINGS
       button1
	   Focus the window under the pointer if click_to_focus	is set.

       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.

       monitor_add _monitor_id_	_monitor_name_ _monitor_geometry_
	   A monitor is	added.

       monitor_rename _monitor_id_ _old_name_ _new_name_
	   A monitor is	renamed.

       monitor_remove _monitor_id_
	   A monitor is	removed.

       monitor_swap _src_monitor_id_ _dst_monitor_id_
	   A monitor is	swapped.

       monitor_focus _monitor_id_
	   A monitor is	focused.

       monitor_geometry	_monitor_id_ _monitor_geometry_
	   The geometry	of a monitor changed.

       desktop_add _monitor_id_	_desktop_id_ _desktop_name_
	   A desktop is	added.

       desktop_rename _monitor_id_ _desktop_id_	_old_name_ _new_name_
	   A desktop is	renamed.

       desktop_remove _monitor_id_ _desktop_id_
	   A desktop is	removed.

       desktop_swap _src_monitor_id_ _src_desktop_id_ _dst_monitor_id_
       _dst_desktop_id_
	   A desktop is	swapped.

       desktop_transfer	_src_monitor_id_ _src_desktop_id_ _dst_monitor_id_
	   A desktop is	transferred.

       desktop_focus _monitor_id_ _desktop_id_
	   A desktop is	focused.

       desktop_activate	_monitor_id_ _desktop_id_
	   A desktop is	activated.

       desktop_layout _monitor_id_ _desktop_id_	tiled|monocle
	   The layout of a desktop changed.

       node_manage _monitor_id_	_desktop_id_ _node_id_ _ip_id_
	   A window is managed.

       node_unmanage _monitor_id_ _desktop_id_ _node_id_
	   A window is unmanaged.

       node_swap _src_monitor_id_ _src_desktop_id_ _src_node_id_
       _dst_monitor_id_	_dst_desktop_id_ _dst_node_id_
	   A node is swapped.

       node_transfer _src_monitor_id_ _src_desktop_id_ _src_node_id_
       _dst_monitor_id_	_dst_desktop_id_ _dst_node_id_
	   A node is transferred.

       node_focus _monitor_id_ _desktop_id_ _node_id_
	   A node is focused.

       node_activate _monitor_id_ _desktop_id_ _node_id_
	   A node is activated.

       node_presel _monitor_id_	_desktop_id_ _node_id_ (dir DIR|ratio
       RATIO|cancel)
	   A node is preselected.

       node_stack _node_id_1_ below|above _node_id_2_
	   A node is stacked below or above another node.

       node_geometry _monitor_id_ _desktop_id_ _node_id_ _node_geometry_
	   The geometry	of a window changed.

       node_state _monitor_id_ _desktop_id_ _node_id_
       tiled|pseudo_tiled|floating|fullscreen on|off
	   The state of	a window changed.

       node_flag _monitor_id_ _desktop_id_ _node_id_
       hidden|sticky|private|locked|urgent on|off
	   One of the flags of a node changed.

       node_layer _monitor_id_ _desktop_id_ _node_id_ below|normal|above
	   The layer of	a window changed.

       pointer_action _monitor_id_ _desktop_id_	_node_id_
       move|resize_corner|resize_side begin|end
	   A pointer action occured.

       Please note that	bspwm initializes monitors before it reads messages on
       its socket, therefore the initial monitor events	can't be received.

REPORT FORMAT
       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.

       M_monitor_name_
	   Focused monitor.

       m_monitor_name_
	   Unfocused monitor.

       O_desktop_name_
	   Occupied focused desktop.

       o_desktop_name_
	   Occupied unfocused desktop.

       F_desktop_name_
	   Free	focused	desktop.

       f_desktop_name_
	   Free	unfocused desktop.

       U_desktop_name_
	   Urgent focused desktop.

       u_desktop_name_
	   Urgent unfocused desktop.

       L(T|M)
	   Layout of the focused desktop of a monitor.

       T(T|P|F|=|@)
	   State of the	focused	node of	a focused desktop.

       G(S?P?L?)
	   Active flags	of the focused node of a focused desktop.

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_host_name___display_number___screen_number_-socket.

CONTRIBUTORS
       o   Steven Allen	<steven	at stebalien.com>

       o   Thomas Adam <thomas at xteddy.org>

       o   Ivan	Kanakarakis <ivan.kanak	at gmail.com>

AUTHOR
       Bastien Dejean <nihilhill at gmail.com>

Bspwm 0.9.2			  10/30/2016			      BSPWM(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMON DEFINITIONS | SELECTORS | WINDOW STATES | NODE FLAGS | STACKING LAYERS | DOMAINS | EXIT CODES | SETTINGS | POINTER BINDINGS | EVENTS | REPORT FORMAT | ENVIRONMENT VARIABLES | CONTRIBUTORS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bspwm&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help