other versions
- wheezy 0.3-1
- wheezy-backports 0.6.2-1~bpo70+1
- jessie 0.6.2-1
- jessie-backports 0.7.0-1~bpo8+1
- testing 0.7.0-1
- unstable 0.7.0-1
HERBSTLUFTWM(1) | HERBSTLUFTWM(1) |
NAME¶
herbstluftwm - a manual tiling window manager for XSYNOPSIS¶
herbstluftwm [OPTION ...]DESCRIPTION¶
Starts the herbstluftwm window manager on DISPLAY. It also listens for calls from herbstclient(1) and executes them. The list of available COMMANDS is listed below.use PATH as autostart file instead of
the one in $XDG_CONFIG_HOME
-v, --version
print version and exit
-l, --locked
Initially set the monitors_locked setting to
1
--verbose
print verbose information to stderr
TILING ALGORITHM¶
The basic tiling concept is that the layout is represented by a binary tree. On startup you see one big frame across the entire screen. A frame fulfills exactly one of the following conditions: 1.Frame contains windows:
It shows some clients and arranges them. The current layout algorithms are:
•0: vertical - clients are placed
below each other
•1: horizontal - clients are
placed next to each other
•2: max - all clients are
maximized in this frame
•3: grid - clients are arranged
in an almost quadratic grid
2.Frame is split into subframes:
It is split into exactly two subframes in a configurable fraction
either in a vertical or horizontal way. So it produces two frames which
fulfill the same conditions (new frames always are about to contain
windows). If you split a frame that already contains windows, the
windows are inherited by the first new child frame.
C
V / \ C C
V / \ H C / \ C C
H / \ C C
FRAME INDEX¶
The exact position of a frame in the layout tree may be described by its index which is just a string of characters. The lookup algorithm starts at the root frame and selects one of its two subtrees according to the each character in the index.•
0: select the first subtree
•
1: select the second subtree
•
.: select the subtree having the focus
•
/: select the subtree not having the focus
TAGS¶
Tags are very similar to workspaces, virtual desktops or window groups. Each tag has one layout. There is a list of tags. You can add or remove tags dynamically.MONITORS¶
Monitors in herbstluftwm are totally independent of the actual physical screens. This means you can for example split your screen in two virtual monitors to view two tags at once on a big screen.•by its absolute index as listed in the
list_monitors command.
•by its relative index: a + or -
followed by a delta, e.g.: +3
•by its relative position to the focused
monitor. -l denotes the monitor left of the focused monitor, -r right of, -u
above of, and -d below of, respectively.
•by "" (an empty string) which
represents the current monitor.
•by its name.
COMMANDS¶
herbstluftwm is controlled by internal commands, which can be executed via herbstclient(1) or via keybindings. quitQuits herbstluftwm.
reload
Executes the autostart file.
version
Prints the version of the running herbstluftwm
instance.
echo [ ARGS ...]
Prints all given ARGS separated by a
single space and a newline afterwards.
true
Ignores all arguments and always returns
success, i.e. 0.
false
Ignores all arguments and always returns
failure, i.e. 1.
list_commands
Lists all available commands.
list_monitors
List currently configured monitors with their
index, area (as rectangle), name (if named) and currently viewed tag.
list_rules
Lists all active rules. Each line consists of
all the parameters the rule was called with, plus its label, separated by
tabs.
list_keybinds
Lists all bound keys with their associated
command. Each line consists of one key combination and the command with its
parameters separated by tabs.
Increases the monitors_locked setting.
Use this if you want to do multiple window actions at once (i.e. without
repainting between the single steps). See also: unlock
unlock
Decreases the monitors_locked setting.
If monitors_locked is changed to 0, then all monitors are repainted
again. See also: lock
keybind KEY COMMAND [ARGS ...]
Adds a key binding. When KEY is
pressed, the internal COMMAND (with its ARGS) is executed. A key
binding is a (possibly empty) list of modifiers (Mod1, Mod2, Mod3, Mod4, Mod5,
Alt, Super, Control/Ctrl, Shift) and one key (see keysymdef.h for a list of
keys). Modifiers and the key are concatenated with - or + as
separator. If there is already a binding for this KEY, it will be
overwritten. Examples:
keyunbind KEY|-F|--all
•keybind Mod4+Ctrl+q quit
•keybind Mod1-i toggle
always_show_frame
•keybind Mod1-Shift-space cycle_layout
-1
Removes the key binding for KEY. The
syntax for KEY is defined in keybind. If -F or
--all is given, then all key bindings will be removed.
mousebind BUTTON ACTION [COMMAND ...]
Adds a mouse binding for the floating mode.
When BUTTON is pressed, the specified ACTION will be performed.
BUTTON has a similar syntax to the KEY argument of keybind: It
consists of a list of modifiers (separated by - or +, valid
modifiers are listed in the description of keybind) and exactly one
button name:
•
B1 or Button1
•
B2 or Button2
•
B3 or Button3
•
B4 or Button4
•
B5 or Button5
•
move: Moves the window by dragging the cursor.
•
resize: Resizes the window by dragging a corner.
•
zoom: Resizes the window into all four directions while keeping the center of
the window constant.
•
call: Only calls the specified COMMAND while client.dragged links to the
client on which the BUTTON has been performed.
While an ACTION is performed,
client.dragged is the client which is dragged. E.g.:
mouseunbind
•
mousebind Mod1-Button3 zoom
•
mousebind Mod1-B4 call substitute WID clients.dragged.winid spawn transset-df
--inc -i WID 0.05
•
mousebind Mod1-B5 call substitute WID clients.dragged.winid spawn transset-df
--dec -i WID -m 0.2 0.05
Removes all mouse bindings.
spawn EXECUTABLE [ARGS ...]
Spawns an EXECUTABLE with its
ARGS. For details see man 3 execvp. Example:
wmexec [ WINDOWMANAGER [ARGS ...]]
•spawn xterm -e man 3 execvp
Executes the WINDOWMANAGER with its
ARGS. This is useful to switch the window manager in the running
session without restarting the session. If no or an invalid
WINDOWMANAGER is given, then herbstluftwm is restarted. For details see
man 3 execvp. Example:
chain SEPARATOR [COMMANDS ...]
•wmexec openbox
chain expects a SEPARATOR and a list of
COMMANDS with arguments. The commands have to be separated by the
specified SEPARATOR. The SEPARATOR can by any word and only is
recognized as the separator between commands if it exactly matches
SEPARATOR. "chain" outputs the appended outputs of all
commands and returns the exit code of the last executed command. Examples are:
•Create a tag called "foo" and
directly use it:
chain , add foo , use foo
•Rotate the layout clockwise:
chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
Counterexamples are:
and SEPARATOR [COMMANDS ...]
•This will only create a tag called
"foo,":
chain , add foo, use foo
•Separator "." defined, but
"," is used:
chain . add foo , use foo
"and" behaves like the chain command
but only executes the specified COMMANDS while the commands return the
exit code 0.
or SEPARATOR [COMMANDS ...]
"or" behaves like the chain command
but only executes the specified COMMANDS until one command returns the
exit code 0.
! COMMAND
"!" executes the provided command,
but inverts its return value. If the provided command returns a nonzero,
"!" returns a 0, if the command returns a zero, "!"
returns a 1.
try COMMAND
"try" executes the provided command,
prints its output, but always returns success, i.e. 0.
silent COMMAND
"silent" executes the provided
command, but discards its output and only returns its exit code.
focus_nth INDEX
Focuses the nth window in a frame. The first
window has INDEX 0. If INDEX is negative or greater than the
last window index, then the last window is focused.
cycle [ DELTA]
Cycles the selection within the current frame
by DELTA. If DELTA is omitted, DELTA = 1 will be used.
DELTA can be negative; DELTA = -1 means: cycle in the opposite
direction by 1.
cycle_all [ --skip-invisible] [DIRECTION]
Cycles through all windows and frames on the
current tag. DIRECTION = 1 means forward, DIRECTION = -1 means
backward, DIRECTION = 0 has no effect. DIRECTION defaults to 1.
If there are multiple windows within on frame, then it acts similar to the
cycle command. (The cycle_all command focuses the next/previous
leave in the layout tree.). If --skip-invisible is given, then
this only cycles through all visible windows and skips invisible windows in
the max layout. The focused window is raised.
cycle_frame [ DIRECTION]
Cycles through all frames on the current tag.
DIRECTION = 1 means forward, DIRECTION = -1 means backward,
DIRECTION = 0 has no effect. DIRECTION defaults to 1.
cycle_layout [ DELTA [LAYOUTS ...]]
Cycles the layout algorithm in the current
frame by DELTA. DELTA defaults to 1. You can find a list of
layout algorithms above. If a list of LAYOUTS is given, cycle_layout
will cycle through those instead of the default layout algorithm list. Each
layout name should occur at most once. Example:
set_layout LAYOUT
•cycle_layout -1
•cycle_layout 1 vertical grid
Sets the layout algorithm in the current frame
to LAYOUT. For the list of layouts, check the list of layout algorithms
above.
close WINID
Closes the specified window gracefully or the
focused window if none is given explicitly. See the section on WINDOW IDS how
to reference a certain window.
close_or_remove
Closes the focused window or removes the
current frame if no window is focused.
split ALIGN [FRACTION]
Splits the focused frame into two subframes
with a specified FRACTION between 0 and 1 which defaults to 0.5.
ALIGN is one of
focus [ -i|-e] DIRECTION
•
top
•
bottom (= vertical)
•
left,
•
right (= horizontal)
•
explode
•
auto (split along longest side)
It specifies which of the two halves will be empty after the split. The other
half will be occupied by the currently focused frame. After splitting, the
originally focuse frame will stay focused. One special ALIGN mode is
explode, which splits the frame in such a way that the window sizes and
positions are kept as much as possible. If no FRACTION is given to
explode mode an optimal fraction is picked automatically.
Example:
•split explode
•split bottom 0.5
•split horiz 0.3
•split vertical 0.5
•split h
Moves the focus from current frame to the next
frame or client in DIRECTION which is in:
•l[eft]
•r[ight]
•u[p]
•d[own]
If -i (internal) is given or
default_direction_external_only is unset, then the next client in
DIRECTION can also be within the same frame. If there is no client
within this frame or -e (external) is given, then the next frame in
specified DIRECTION will be focused.
The direction between frames is defined as follows: The focus is in a leaf of
the binary tree. Each inner node in the tree remembers the last focus
direction (child 0 or child 1). The algorithm uses the shortest possible way
from the leaf (the currently focused frame) to the root until it is possible
to change focus in the specified DIRECTION. From there the focus goes
back to the leaf.
Example: The focus is at frame A. After executing focus right focus will
be at frame C.
Tree: V,0 Screen: .-----..-----. (before) / \ | B || C | / \ '-----''-----' H,1 H,0 .-----..-----. / \ / \ | A* || D | A* B C D '-----''-----' Tree: V,0 Screen: .-----..-----. (after focus right) / \ | B || C* | / \ '-----''-----' H,1 H,0 .-----..-----. / \ / \ | A || D | A B C* D '-----''-----'
If the currently focused client is floated,
then the next floating window in the specified direction is focused and
raised.
If focus_crosses_monitor_boundaries is
set and no client or frame is found in the specified DIRECTION, then
the next monitor in that DIRECTION is focused.
focus_edge [ -i|-e] DIRECTION
Focuses the window on the edge of the tag in
the specified DIRECTION. The DIRECTIONS and -e behave as
specified at the focus command.
If -i (internal) is given or default_direction_external_only is unset,
then the window on the edge of the tag will be focused. Else, only the frame
on the edge of the tag will be focused, and the window that was last focused
in that frame will be focused.
raise WINID
Raises the specified window. See the section
on WINDOW IDS on how to reference a certain window. Its result is only visible
in floating mode.
Puts the focus to the specified window. See
the section on WINDOW IDS on how to reference a certain window.
bring WINID
Moves the specified window to the current
frame and focuses it. See the section on WINDOW IDS on how to reference a
certain window.
resize DIRECTION FRACTIONDELTA
Changes the next fraction in specified
DIRECTION by FRACTIONDELTA. DIRECTION behaves as
specified at the focus command. You should not omit the sign -
or +, because in future versions, the behaviour may change if the sign
is omitted. Example:
shift_edge [ -i|-e] DIRECTION
•resize right +0.05
•resize down -0.1
Shifts the focused window to the the edge of a
tag in the specified DIRECTION. The DIRECTIONS behave as
specified at the focus command and -i and -e behave as
specified at the focus_edge command.
shift [ -i|-e] DIRECTION
Shifts the focused window to the next frame in
the specified DIRECTION. The DIRECTIONS and -i|-e
behave as specified at the focus command. If the focused client is
floated instead of being tiled, then client is shifted to the next window or
screen edge.
shift_to_monitor MONITOR
Moves the focused window to the tag on the
specified MONITOR.
remove
Removes focused frame and merges its windows
to its neighbour frame.
rotate
Rotates the layout on the focused tag
counterclockwise by 90 degrees. This only manipulates the alignment of frames,
not the content of them.
set NAME VALUE
Sets the specified setting NAME to
VALUE. All SETTINGS are listed in the section below.
get NAME
Prints the value of setting NAME. All
SETTINGS are listed in the section below.
toggle NAME
Toggles the setting NAME if it’s
an integer setting: If its value is unequal to 0, it becomes 0; else its
previous value (which was unequal to 0) is restored.
cycle_value NAME VALUES ...
Cycles value of the setting NAME
through VALUES: I.e. it searches the first occurrence of the current
value in VALUES and changes the value to the next in the list or to the
first one if the end is reached or current value wasn’t found. Example:
cycle_monitor [ DELTA]
•cycle_value frame_gap 0 5 10 15
•cycle_value frame_bg_normal_color red
green blue
Cycles monitor focused by DELTA.
DELTA defaults to 1.
focus_monitor MONITOR
Puts focus to the specified monitor.
add TAG
Creates a new empty tag named
TAG.
use TAG
Switches the focused monitor to specified
TAG.
use_index INDEX [--skip-visible]
Switches the focused monitor to the TAG
with the specified INDEX. If INDEX starts with + or -, then
INDEX is treated relative to the current TAG. If
--skip-visible is passed and INDEX is relative, then tags that
are already visible on a monitor are skipped. E.g. this cycles backwards
through the tags:
use_previous
•use_index -1 --skip-visible
Switches the focused monitor to the previously
viewed tag.
merge_tag TAG [TARGET]
Removes tag named TAG and moves all its
windows to tag TARGET. If TARGET is omitted, the focused tag
will be used.
rename OLDTAG NEWTAG
Renames tag named OLDTAG to
NEWTAG.
move TAG
Moves the focused window to the tag named
TAG.
move_index INDEX [--skip-visible]
Moves the focused window to the tag specified
by INDEX. Analogical to the argument for use_index: If
INDEX starts with + or -, then it is treated relative. If
--skip-visible is passed with a relative index, then already visible
tags are skipped.
lock_tag [ MONITOR]
Lock the tag switching on the specified
monitor. If no argument is given, the currently focused monitor is used. When
the tag switching is disabled for a monitor, the commands use and
use_index have no effect when executed there. When
swap_monitors_to_get_tag is enabled, switching to a tag which is
located on a locked monitor, switches to that monitor instead of stealing it
from there. The lock state of a monitor is indicated by "[LOCKED]"
in the list_monitors output.
unlock_tag [ MONITOR]
Re-enables the tag switching on the specified
monitor. If no argument is given, the currently focused monitor is used. This
is the reverse operation to lock_tag and has no further side effects
but removing this lock.
disjoin_rects RECTS ...
Takes a list of rectangles and splits them
into smaller pieces until all rectangles are disjoint, the result rectangles
are printed line by line. This command does not modify the current list of
monitors! So this can be useful in combination with the set_monitors command.
set_monitors RECTS ...
•E.g. disjoin_rects 600x400+0+0
600x400+300+250 prints this:
300x150+300+250 600x250+0+0 300x150+0+250 300x150+600+250 600x250+300+400
•In the above example two monitors are
split into 5 monitors, which graphically means:
11111111 11111111 1 222222222 333222224444 1 2 1 2 disjoin 3 32 24 4 11121111 2 --------> 333222224444 2 2 555555555 222222222 555555555
Sets the list of monitors exactly to
the list of given rectangles:
detect_monitors -l|--list|--no-disjoin
•The i’th existing monitor is
moved to the i’th given RECT
•New monitors are created if there are
more RECTS then monitors
•Existing monitors are deleted if there
are more monitors then RECTS
Sets the list of monitors to the available
Xinerama monitors. If the Xinerama extension is missing, it will fall back to
one monitor across the entire screen. If the detected monitors overlap, the
will be split into more monitors that are disjoint but cover the same area
using disjoin_rects.
If -l or --list is passed, the list of rectangles of detected
pyhsical monitors is printed. So hc detect_monitors is equivalent to the bash
command hc set_monitors $(hc disjoin_rects $(hc detect_monitors -l)).
add_monitor RECT [TAG [NAME]]
Adds a monitor on the specified rectangle
RECT and displays TAG on it. TAG currently must not be
displayed on any other monitor. RECT is a string of the form
WxH±X±Y. If no or an empty TAG is given, then any free
tag will be chosen. If a NAME is given, you can reference to this
monitor by its name instead of using an index. Example:
remove_monitor MONITOR
•add_monitor 1024x768-20+0 mynewtag
main
Removes the specified monitor.
move_monitor MONITOR RECT [PADUP [PADRIGHT
[PADDOWN [ PADLEFT]]]]
Moves the specified monitor to rectangle
RECT. RECT is defined as in add_monitor. If no or an
empty pad is given, it is not changed.
raise_monitor [ MONITOR]
Raises the specified monitor or the current
one if MONITOR is omitted.
rename_monitor MONITOR NAME
(Re)names an already existing monitor. If
NAME is empty, it removes the monitor’s name.
stack
Prints the stack of monitors with the visible
tags and their layers as a tree. The order of the printed stack is top to
bottom. The style is configured by the tree_style setting.
monitor_rect [[-p] MONITOR]
Prints the rectangle of the specified monitor
in the format: X Y W H If no MONITOR or cur is given,
then the current monitor is used. If -p is supplied, then the remaining
rect without the pad around this monitor is printed.
pad MONITOR [PADUP [PADRIGHT [PADDOWN
[PADLEFT]]]]
Sets the pad of specified monitor to the
specified padding. If no or an empty padding is given, it is not
changed.
list_padding [ MONITOR]
Lists the padding of the specified monitor, or
the currently focused monitor if no monitor is given.
layout [ TAG [INDEX]]
Prints the layout of frame with INDEX
on TAG, in a nice tree style. Its style is defined by the
tree_style setting. If no TAG is given, the current tag is used.
If no INDEX is given, the root frame is used. To specify INDEX
without specifying TAG (i.e. use current tag), pass an empty string as
TAG.
An example output is:
dump [ TAG [INDEX]]
╾─┐ horizontal 50% selection=1 ├─╼ vertical: 0xe00009 └─┐ vertical 50% selection=0 ├─╼ vertical: 0xa00009 [FOCUS] └─╼ vertical: 0x1000009
Prints the same information as the
layout command but in a machine readable format. Its output can be read
back with the load command.
An example output (formatted afterwards) is:
load [ TAG] LAYOUT
(split horizontal:0.500000:1 (clients vertical:0 0xe00009) (split vertical:0.500000:1 (clients vertical:0 0xa00009) (clients vertical:0 0x1000009)))
Loads a given LAYOUT description to
specified TAG or current tag if no TAG is given.
Prints the result of tab completion for the
partial COMMAND with optional ARGS. You usually do not need
this, because there is already tab completion for bash. Example:
complete_shell POSITION [COMMAND ARGS ...]
•complete 0 m
prints all commands beginning with m
•complete 1 toggle fra
prints all settings beginning with fra that can be toggled
Behaves like complete with the
following extras, useful for completion on posix shells:
emit_hook ARGS ...
•Escape sequences are removed in
COMMAND and ARGS.
•A space is appended to each full
completion result.
•Special characters will be escaped in
the output.
Emits a custom hook to all idling
herbstclients.
tag_status [ MONITOR]
Print a tab separated list of all tags for the
specified MONITOR index. If no MONITOR index is given, the
focused monitor is used. Each tag name is prefixed with one char, which
indicates its state:
•
. the tag is empty
•
: the tag is not empty
•
+ the tag is viewed on the specified MONITOR, but this monitor is
not focused.
•
# the tag is viewed on the specified MONITOR and it is
focused.
•
- the tag is viewed on a different MONITOR, but this monitor is
not focused.
•
% the tag is viewed on a different MONITOR and it is
focused.
•
! the tag contains an urgent window
Changes the current tag to floating/tiling
mode on specified TAG or prints it current status. If no TAG is
given, the current tag is used. If no argument is given, floating mode is
toggled. If status is given, then on or off is printed,
depending of the floating state of TAG.
rule [[--]
FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
Defines a rule which will be applied to all
new clients. Its behaviour is described in the RULES section.
unrule LABEL|--all|-F
Removes all rules named LABEL. If --all
or -F is passed, then all rules are removed.
fullscreen [ on|off|toggle]
Sets or toggles the fullscreen state of the
focused client. If no argument is given, fullscreen mode is toggled.
pseudotile [ on|off|toggle]
Sets or toggles the pseudotile state of the
focused client. If a client is pseudotiled, then in tiling mode the client is
only moved but not resized - the client size will stay the floating size. The
only reason to resize the client is to ensure that it fits into its tile. If
no argument is given, pseudotile mode is toggled.
object_tree [ PATH]
Prints the tree of objects. If the object path
PATH is given, only the subtree starting at PATH is printed. See
the OBJECTS section for more details.
attr [ PATH [NEWVALUE]
Prints the children and attributes of the
given object addressed by PATH. If PATH is an attribute, then
print the attribute value. If NEWVALUE is given, assign NEWVALUE
to the attribute given by PATH. See the OBJECTS section for more
details.
get_attr ATTRIBUTE
Print the value of the specified
ATTRIBUTE as described in the OBJECTS section.
set_attr ATTRIBUTE NEWVALUE
Assign NEWVALUE to the specified
ATTRIBUTE as described in the OBJECTS section.
new_attr [ bool|color|int|string|uint]
PATH
Creates a new attribute with the name and in
the object specified by PATH. Its type is specified by the first
argument. The attribute name has to begin with my_.
remove_attr PATH
Removes the user defined attribute
PATH.
substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
Replaces all exact occurrences of
IDENTIFIER in COMMAND and its ARGS by the value of the
ATTRIBUTE. Note that the COMMAND also is replaced by the
attribute value if it equals IDENTIFIER. The replaced command with its
arguments then is executed. Example:
sprintf IDENTIFIER FORMAT [ATTRIBUTES ...] COMMAND
[ARGS ...]
•
substitute MYTITLE clients.focus.title echo MYTITLE
Prints the title of the currently focused window.
Replaces all exact occurrences of
IDENTIFIER in COMMAND and its ARGS by the string
specified by FORMAT. Each %s in FORMAT stands for the value of
the next attribute in ATTRIBUTES, similar to the printf(1)
command. The replaced command with its arguments then is executed. Examples:
mktemp [ bool|int|string|uint] IDENTIFIER
COMMAND [ ARGS ...]
•
sprintf STR title=%s clients.focus.title echo STR
Prints the title of the currently focused window prepended by title=.
•
sprintf X tag=%s tags.focus.name rule once X
Moves the next client that appears to the tag that is currently focused.
•
sprintf X %s/%s tags.focus.index tags.count echo X
Tells which tag is focused and how many tags there are
•
sprintf l somelongstring echo l l l
Prints somelongstring three times, separated by spaces.
Creates a temporary attribute with the given
type and replaces all occurrences of IDENTIFIER in COMMAND and
ARGS by by the path of the temporary attribute. The replaced command
with its arguments is executed then. The exit status of COMMAND is
returned.
compare ATTRIBUTE OPERATOR VALUE
Compares the value of ATTRIBUTE with
VALUE using the comparation method OPERATOR. If the comparation
succeeds, it returns 0, else 1. The operators are:
•
=: ATTRIBUTE's value equals VALUE
•
!=: ATTRIBUTE's value does not equal VALUE
•
le: ATTRIBUTE's value <= VALUE
•
lt: ATTRIBUTE's value < VALUE
•
ge: ATTRIBUTE's value >= VALUE
•
gt: ATTRIBUTE's value > VALUE
The OPERATORs
le,lt,ge, gt can only be used if ATTRIBUTE
is of the type integer or unsigned integer. Note that the first parameter must
always be an attribute and the second a constant value. If you want to compare
two attributes, use the substitute command:
It returns success if there are more clients on the focused tag than
frames.
getenv NAME
substitute FC tags.focus.frame_count \ compare tags.focus.client_count gt FC
Gets the value of the environment variable
NAME.
setenv NAME VALUE
Set the value of the environment variable
NAME to VALUE.
unsetenv NAME
Unsets the environment variable
NAME.
SETTINGS¶
Settings configure the behaviour of herbstluftwm and can be controlled via the set, get and toggle commands. There are two types of settings: Strings and integer values. An integer value is set, if its value is 1 or another value unequal to 0. An integer value is unset, if its value is 0. frame_gap (Integer)The gap between frames in the tiling
mode.
frame_padding (Integer)
The padding within a frame in the tiling mode,
i.e. the space between the border of a frame and the windows within it.
window_gap (Integer)
The gap between windows within one frame in
the tiling mode.
snap_distance (Integer)
If a client is dragged in floating mode, then
it snaps to neighbour clients if the distance between them is smaller then
snap_distance.
snap_gap (Integer)
Specifies the remaining gap if a dragged
client snaps to an edge in floating mode. If snap_gap is set to 0, no gap will
remain.
mouse_recenter_gap (Integer)
Specifies the gap around a monitor. If the
monitor is selected and the mouse position would be restored into this gap, it
is set to the center of the monitor. This is useful, when the monitor was left
via mouse movement, but is reselected by keyboard. If the gap is 0 (default),
the mouse is never recentered.
frame_border_active_color (String/Color)
The border color of a focused frame.
frame_border_normal_color (String/Color)
The border color of an unfocused frame.
frame_border_inner_color (String/Color)
The color of the inner border of a
frame.
frame_bg_active_color (String/Color)
The fill color of a focused frame.
frame_bg_normal_color (String/Color)
The fill color of an unfocused frame (It is
only visible if always_show_frame is set).
frame_bg_transparent (Integer)
If set, the background of frames are
transparent. That means a rectangle is cut out frome the inner such that only
the frame border and a stripe of width frame_transparent_width can be
seen. Use frame_active_opacity and frame_normal_opacity for real
transparency.
frame_transparent_width (Integer)
Specifies the width of the remaining frame
colored with frame_bg_active_color if frame_bg_transparent is
set.
frame_border_width (Integer)
Border width of a frame.
frame_border_inner_width (Integer)
The width of the inner border of a frame. Must
be less than frame_border_width, since it does not add to the frame border
width but is a part of it.
focus_crosses_monitor_boundaries (Integer)
If set, the focus command crosses monitor
boundaries. If there is no client in the direction given to focus, then the
monitor in the specified direction is focused.
raise_on_focus (Integer)
If set, a window is raised if it is focused.
The value of this setting is only used in floating mode.
raise_on_focus_temporarily (Integer)
If set, a window is raised temporarily if it
is focused on its tag. Temporarily in this case means that the window will
return to its previous stacking position if another window is focused.
raise_on_click (Integer)
If set, a window is raised if it is clicked.
The value of this setting is only noticed in floating mode.
window_border_width (Integer)
Border width of a window.
window_border_inner_width (Integer)
The width of the inner border of a window.
Must be less than window_border_width, since it does not add to the window
border width but is a part of it.
window_border_active_color (String/Color)
Border color of a focused window.
window_border_normal_color (String/Color)
Border color of an unfocused window.
window_border_urgent_color (String/Color)
Border color of an unfocused but urgent
window.
window_border_inner_color (String/Color)
Color of the inner border of a window.
always_show_frame (Integer)
If set, all frames are displayed. If unset,
only frames with focus or with windows in it are displayed.
frame_active_opacity (Integer)
Focused frame opacity in percent. Requires a
running compositing manager to take actual effect.
frame_normal_opacity (Integer)
Unfocused frame opacity in percent. Requires a
running compositing manager to take actual effect.
default_frame_layout (Integer)
Index of the frame layout, which is used if a
new frame is created (by split or on a new tag). For a list of valid indices
and their meanings, check the list of layout algorithms above.
default_direction_external_only (Integer)
This setting controls the behaviour of focus
and shift if no -e or -i argument is given. if set, then focus
and shift changes the focused frame even if there are other clients in this
frame in the specified DIRECTION. Else, a client within current frame
is selected if it is in the specified DIRECTION.
gapless_grid (Integer)
This setting affects the size of the last
client in a frame that is arranged by grid layout. If set, then the last
client always fills the gap within this frame. If unset, then the last client
has the same size as all other clients in this frame.
smart_frame_surroundings (Integer)
If set, frame borders and gaps will be removed
when there’s no ambiguity regarding the focused frame.
smart_window_surroundings (Integer)
If set, window borders and gaps will be
removed and minimal when there’s no ambiguity regarding the focused
window. This minimal window decoration can be configured by the theme.minimal
object.
focus_follows_mouse (Integer)
If set and a window is focused by mouse
cursor, this window is focused (this feature is also known as sloppy focus).
If unset, you need to click to change the window focus by mouse.
If another window is hidden by the focus change (e.g. when having pseudotiled
windows in the max layout) then an extra click is required to change the
focus.
focus_stealing_prevention (Integer)
If set, only pagers and taskbars are allowed
to change the focus. If unset, all applications can request a focus
change.
monitors_locked (Integer)
If greater than 0, then the clients on all
monitors aren’t moved or resized anymore. If it is set to 0, then the
arranging of monitors is enabled again, and all monitors are rearranged if
their content has changed in the meantime. You should not change this setting
manually due to concurrency issues; use the commands lock and
unlock instead.
swap_monitors_to_get_tag (Integer)
If set: If you want to view a tag, that
already is viewed on another monitor, then the monitor contents will be
swapped and you see the wanted tag on the focused monitor. If not set, the
other monitor is focused if it shows the desired tag.
auto_detect_monitors (Integer)
If set, detect_monitors is automatically
executed every time a monitor is connected, disconnected or resized.
tree_style (String)
It contains the chars that are used to print a
nice ascii tree. It must contain at least 8 characters. e.g. X|:#+*-. produces
a tree like:
Useful values for tree_style are: ╾│
├└╼─┐ or -| |'--. or ╾│
├╰╼─╮.
wmname (String)
X-.root #-. child 0 | #-* child 01 | +-* child 02 +-. child 1 : #-* child 10 : +-* child 01
It controls the value of the _NET_WM_NAME
property on the root window, which specifies the name of the running window
manager. The value of this setting is not updated if the actual _NET_WM_NAME
property on the root window is changed externally. Example usage:
pseudotile_center_threshold (Int)
•cycle_value wmname herbstluftwm
LG3D
If greater than 0, it specifies the least
distance between a centered pseudotile window and the border of the frame or
tile it is assigned to. If this distance is lower than
pseudotile_center_threshold, it is aligned to the top left of the
client’s tile.
update_dragged_clients (Int)
If set, a client’s window content is
resized immediately during resizing it with the mouse. If unset, the
client’s content is resized after the mouse button are released.
RULES¶
Rules are used to change default properties for certain clients when they appear. Each rule matches against a certain subset of all clients and defines a set of properties for them (called CONSEQUENCEs). A rule can be defined with this command:•
[--]label= VALUE
•
~ matches if client’s property is matched by the regex
value.
•
= matches if client’s properly string is equal to
value.
the first entry in client’s
WM_CLASS.
class
the second entry in client’s
WM_CLASS.
title
client’s window title.
pid
the client’s process id (Warning: the
pid is not available for every client. This only matches if the client sets
_NET_WM_PID to the pid itself).
maxage
matches if the age of the rule measured in
seconds does not exceed value. This condition only can be used with the
= operator. If maxage already is exceeded (and never will match again), then
this rule is removed. (With this you can build rules that only live for a
certain time.)
windowtype
matches the _NET_WM_WINDOW_TYPE property of a
window.
windowrole
matches the WM_WINDOW_ROLE property of a
window if it is set by the window.
moves the client to tag VALUE.
monitor
moves the client to the tag on monitor
VALUE. If the tag consequence was also specified, and switchtag is set
for the client, move the client to that tag, then display that tag on monitor
VALUE. If the tag consequence was specified, but switchtag was not,
ignore this consequence.
focus
decides whether the client gets the input
focus on his tag. The default is off. VALUE can be on,
off or toggle.
switchtag
if focus is activated and the client is put to
a not focused tag, then switchtag tells whether the client’s tag will be
shown or not. If the tag is shown on any monitor but is not focused, the
client’s tag only is brought to the current monitor if
swap_monitors_to_get_tag is activated. VALUE can be on,
off or toggle.
manage
decides whether the client will be managed or
not. The default is on. VALUE can be on, off or
toggle.
index
moves the window to a specified index in the
tree. VALUE is a frame index.
pseudotile
sets the pseudotile state of the client.
VALUE can be on, off or toggle.
ewmhrequests
sets whether the window state (the fullscreen
state and the demands attention flag) can be changed by the application via
ewmh itself. This does not affect the initial fullscreen state requested by
the window. VALUE can be on, off or toggle, it
defaults to on.
ewmhnotify
sets whether hlwm should let the client know
about EMWH changes (currently only the fullscreen state). If this is set,
applications do not change to their fullscreen-mode while still being
fullscreen. VALUE can be on, off or toggle, it
defaults to on.
fullscreen
sets the fullscreen flag of the client.
VALUE can be on, off or toggle.
hook
emits the custom hook rule VALUE
WINID when this rule is triggered by a new window with the id
WINID. This consequence can be used multiple times, which will cause a
hook to be emitted for each occurrence of a hook consequence.
keymask
Sets the keymask for an client. A keymask is
an regular expression that is matched against the string represenation (see
list_keybinds). If it matches the keybinding is active when this client is
focused, otherwise it is disabled. The default keymask is an empty string
(""), which does not disable any keybinding.
•
not: negates the next CONDITION.
•
!: same as not.
•
once: only apply this rule once (and delete it afterwards).
•
printlabel: prints the label of the newly created rule to stdout.
•
prepend: prepend the rule to the list of rules instead of appending it. So its
consequences may be overwritten by already existing rules.
•
rule --class=Netscape --tag=6 --focus=off
Moves all Netscape instances to tag 6, but doesn’t give focus to
them.
•
rule not class~.*[Tt]erm tag=2
Moves all clients to tag 2, if their class does not end with term or Term.
•
rule class=Thunderbird index=/0
Insert all Thunderbird instances in the tree that has no focus and there in the
first child.
•
rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE correctly.
WINDOW IDS¶
Several commands accept a window as reference, e.g. close. The syntax is as follows:•an empty string — or missing
argument — references the currently focused window.
•
urgent references some window that is urgent.
•
0x HEXID — where HEXID is some hexadecimal number —
references the window with hexadecimal X11 window id is HEXID.
•
DECID — where DECID is some decimal number —
references the window with the decimal X11 window id DECID.
OBJECTS¶
$ herbstclient object_tree ╾─┐ ├─┐ tags │ ├─┐ by-name │ │ ├─╼ 1 │ │ ... │ │ └─╼ 9 │ └─╼ focus ├─┐ clients │ ├─╼ 0x1400022 │ └─╼ focus └─┐ monitors ├─╼ by-name └─╼ focus
$ herbstclient object_tree tags.by-name. ╾─┐ tags.by-name. ├─╼ 1 ├─╼ 2 ... └─╼ 9
$ herbstclient attr tags. 2 children: by-name. focus. 1 attributes: .---- type | .-- writeable V V u - count = 9 $ herbstclient attr tags.focus. 0 children. 6 attributes: .---- type | .-- writeable V V s w name = "1" b w floating = false i - frame_count = 2 i - client_count = 1 i - curframe_windex = 0 i - curframe_wcount = 1
•its type
•
s for string
•
i for integer
•
b for boolean
•
u for unsigned integer
•if it is writeable by the user: w if
yes, - else.
•the name of the attribute
•its current value (only quoted for
strings)
$ herbstclient attr clients.focus.title herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM $ herbstclient get_attr clients.focus.title herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
$ herbstclient attr tags.focus.floating false $ herbstclient attr tags.focus.floating true $ herbstclient attr tags.focus.floating true $ herbstclient set_attr tags.focus.floating false $ herbstclient attr tags.focus.floating false
•
tags: subtree for tags.
u - count | number of tags |
•
by-name
•
TAG: a object for each tag with the name TAG
s w name | name of the tag |
b w floating | if it is in floating mode |
i - index | index of this tag |
i - frame_count | number of frames |
i - client_count | number of clients on this tag |
i - curframe_windex | index of the focused client in the select frame |
i - curframe_wcount | number of clients in the selected frame |
•
focus: the object of the focused tag
•
clients
•
WINID: a object for each client with its WINID
s - winid | its window id |
s - title | its window title |
s - tag | the tag it’s currently on |
i - pid | the process id of it (-1 if unset) |
s - class | the class of it (second entry in WM_CLASS) |
s - instance | the instance of it (first entry in WM_CLASS) |
b w fullscreen | |
b w pseudotile | |
b w ewmhrequests | if ewmh requests are permitted for this client |
b w ewmhnotify | if the client is told about its state via ewmh |
b w urgent | its urgent state |
b w sizehints_tiling | if sizehints for this client should be respected in tiling mode |
b w sizehints_flaoting | if sizehints for this client should be respected in floating mode |
•
focus: the object of the focused client, if any
•
dragged: the object of a client which is dragged by the mouse, if any. See the
documentation of the mousebind command for examples.
•
monitors
u - count | number of monitors |
•
INDEX: a object for each monitor with its INDEX
•
by-name
•
NAME: a object for each named monitor
s - name | its name |
i - index | its index |
s - tag | the tag currently viewed on it |
b - lock_tag |
•
focus: the object of the focused monitor
•
settings has an attribute for each setting. See SETTINGS for a
list.
•
theme has attributes to configure the window decorations. theme and many of its
child objects have the following attributes
Setting an attribute of the theme object just propagates the value to the
respective attribute of the tiling and the floating object.
i w border_width | the base width of the border |
i w padding_top | additional border width on the top |
i w padding_right | on the right |
i w padding_bottom | on the bottom |
i w padding_left | and on the left of the border |
c w color | the basic background color of the border |
i w inner_width | width of the border around the clients content |
c w inner_color | its color |
i w outer_width | width of an additional border close to the edge |
c w outer_color | its color |
c w background_color | color behind window contents visible on resize |
s w reset | Writing this resets all attributes to a default value |
inner_color/inner_width ╻ outer_color/outer_width │ ╻ │ │ ┌────╴│╶─────────────────┷─────┐ ⎫ border_width │ │ color │ ⎬ + │ ┌──┷─────────────────────┐ │ ⎭ padding_top │ │====================....│ │ │ │== window content ==....│ │ │ │====================..╾──────── background_color │ │........................│ │ │ └────────────────────────┘ │ ⎱ border_width + └──────────────────────────────┘ ⎰ padding_bottom
•
tiling configures the decoration of tiled clients, setting one of its attributes
propagates the respective attribute of the active, normal and urgent child
objects.
•
active configures the decoration of focused and tiled clients
•
normal configures the decoration of unfocused and tiled clients
•
urgent configures the decoration of urgent and tiled clients
•
floating behaves analogously to tiling
•
minimal behaves analogously to tiling and configures those minimal decorations
triggered by smart_window_surroundings.
•
active propagates the attribute values to tiling.active and
floating.active
•
normal propagates the attribute values to tiling.normal and
floating.normal
•
urgent propagates the attribute values to tiling.urgent and
floating.urgent
AUTOSTART FILE¶
There is no configuration file but an autostart file, which is executed on startup. It is also executed on command reload. If not specified by the --autostart argument, autostart file is located at $XDG_CONFIG_HOME/herbstluftwm/autostart or at ~/.config/herbstluftwm/autostart. Normally it consists of a few herbstclient calls. If executing the autostart file in a user’s home fails the global autostart file (mostly placed at /etc/xdg/herbstluftwm/autostart) is executed as a fallback.HOOKS¶
On special events, herbstluftwm emits some hooks (with parameters). You can receive or wait for them with herbstclient(1). Also custom hooks can be emitted with the emit_hook command. The following hooks are emitted by herbstluftwm itself: fullscreen [on|off] WINID STATEThe fullscreen state of window WINID
was changed to [on|off].
tag_changed TAG MONITOR
The tag TAG was selected on
MONITOR.
focus_changed WINID TITLE
The window WINID was focused. Its
window title is TITLE.
window_title_changed WINID TITLE
The title of the focused window was
changed. Its window id is WINID and its new title is
TITLE.
tag_flags
The flags (i.e. urgent or filled state) have
been changed.
tag_added TAG
A tag named TAG was added.
tag_removed TAG
The tag named TAG was removed.
urgent [on|off] WINID
The urgent state of client with given
WINID has been changed to [on|off].
rule NAME WINID
A window with the id WINID appeared
which triggerd a rule with the consequence hook= NAME.
Tells a panel to quit. The default panel.sh
quits on this hook. Many scripts are using this hook.
reload
Tells all daemons that the autostart
file is reloaded — and tells them to quit. This hook should be
emitted in the first line of every autostart file.
STACKING¶
Every tag has its own stack of clients that are on this tag. Similar to the EWMH specification each tag stack contains several layers, which are from top to bottom:•the focused client (if
raise_on_focus_temporarily is enabled)
•clients in fullscreen
•normal clients
•frame decorations
ENVIRONMENT VARIABLES¶
DISPLAYSpecifies the DISPLAY to use.
EXIT STATUS¶
Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if wmexec fails.BUGS¶
See the herbstluftwm distribution BUGS file.COMMUNITY¶
Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.AUTHOR¶
herbstluftwm was written by Thorsten Wißmann. All contributors are listed in the herbstluftwm distribution AUTHORS file.RESOURCES¶
Homepage: http://herbstluftwm.orghlwm@lists.herbstluftwm.org
COPYING¶
Copyright 2011-2014 Thorsten Wißmann. All rights reserved.2014-05-03 | herbstluftwm 0.6.2 |