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
set the monitors_locked setting initially 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, then the
windows are inherited by the first new child frame.
C
V / \ C C
V / \ H C / \ C C
H / \ C C
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.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.
list_commands
Lists all available commands.
list_monitors
List currently configured monitors with their
index, area (as rectangle) and currently viewed tag.
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. Syntax
for KEY is defined in keybind. If -F or --all is
given, then all key bindings will be removed.
mousebind BUTTON ACTION
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 the bottom right corner
•
zoom: Resizes the window into all four directions by keeping the center of the
window constant.
E.g.: mousebind Mod1-Button3 zoom
mouseunbind
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:
cycle [ DELTA]
•wmexec openbox
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 [ 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.)
cycle_layout [ DELTA]
Cycles the layout algorithm in the current
frame by DELTA. DELTA defaults to 1. You can find a list of
layout algorithms above.
set_layout LAYOUT
Sets the layout algorithm in the current frame
to LAYOUT. For the list of layouts, check the list of layout algorithms
above.
close
Closes the focused window.
split ALIGN FRACTION
Splits the focused frame into two subframes
with a specified FRACTION between 0 and 1. ALIGN can be
horizontal or vertical (actually it only depends on the first
letter of ALIGN). Example:
focus [ -i|-e] DIRECTION
•split horiz 0.3
•split vertical 0.5
•split h 0.8
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 is going as short as possible
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.
raise [ 0xWINID]
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 '-----''-----'
Raises the specified window, which is
specified by hexadecimal 0xWINID. If no 0xWINID is given, the
focused window will be raised. Its result is only visible in floating
mode.
resize DIRECTION FRACTIONDELTA
Changes the next fraction in specified
DIRECTION by FRACTIONDELTA. DIRECTION is 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 [ -i|-e] DIRECTION
•resize right +0.05
•resize down -0.1
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 focus_follows_shift
is set, then focus stays in the window; otherwise it stays in the frame.
remove
Removes focused frame and merges its windows
to its neighbour frame.
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 occurence 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 window_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 INDEX
Puts focus to monitor with specified
INDEX (as specified by the list_monitors command)
add TAG
Creates a new empty tag named
TAG.
use TAG
Switches the focused monitor to specified
TAG.
use_index INDEX
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. E.g. this cycles
backwards through the tags:
merge_tag TAG [TARGET]
•use_index -1
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 tag named
TAG.
move_index INDEX
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.
add_monitor RECT [TAG [PADUP [PADRIGHT
[PADDOWN [ PADLEFT]]]]]
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. The padding specifies extra space around the monitor
for some statusbars/panels. If no or an empty padding is given, it is set to
0. If no or an empty TAG is given, then any free tag will be chosen.
Example:
remove_monitor INDEX
•add_monitor 1024x768-20+0 mynewtag
16
Removes the monitor with specified
INDEX. Its INDEX can be found out via the list_monitors
command.
move_monitor INDEX RECT [PADUP [PADRIGHT
[PADDOWN [ PADLEFT]]]]
Moves the monitor with specified INDEX
to rectangle RECT. INDEX and RECT are defined as in
remove_monitor and add_monitor. If no or an empty pad is given,
it is not changed.
monitor_rect [[-p] INDEX]
Prints the rectangle of the specified
INDEX in the format: X Y W H If no INDEX 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 INDEX [PADUP [PADRIGHT [PADDOWN
[PADLEFT]]]]
Sets the pad of indexed monitor to the
specified padding. If no or an empty padding is given, it is not
changed.
layout [ TAG]
Prints the layout of TAG in a nice tree
style. Its style is defined by the tree_style setting. If no TAG
is given, current tag is used.
An example output is:
dump [ TAG]
╾─┐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) (splitvertical: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 in partial
written COMMAND with optional ARGS. You usually do not need
this, because there is already tab completion for bash. Example:
emit_hook ARGS ...
•complete 0 m
prints all commands beginning with m
•complete 1 toggle fra
prints all settings beginning with fra that can be toggled
Emits a custom hook to all idling
herbstclients.
tag_status [ MONITOR]
Print a tab separated list of all tags for
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 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, 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
on TAG.
rule [[--] FLAG|[--]CONDITION|[--]CONSEQUENCE ...]
Defines a rule which will be applied to all
new clients. Its behaviour is described in the RULES section.
unrule --all|-F
If --all or -F is passed, then all rules are
removed. (It is not possible yet to remove certain rules)
fullscreen on|off|toggle
Sets or toggles the fullscreen state of the
focused client.
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.
SETTINGS¶
Settings configure the behaviour of herbstluftwm and can be controlled via the set, get and toggle command. 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. window_gap (Integer)The gap between frames 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.
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_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, frames have transparent
backgrounds.
frame_border_width (Integer)
Border width of a frame
raise_on_focus (Integer)
If set, a window is raised if it is focused.
The value of this setting is only noticed in floating mode.
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_active_color (String/Color)
Border color of a focused window.
window_border_normal_color (String/Color)
Border color of an unfocused window.
always_show_frame (Integer)
If set, all frames are displayed. If unset,
only frames with focus or with windows in it are displayed.
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 indizes
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.
focus_follows_shift (Integer)
If set, focus stays in the window, if window
is shifted to another frame. If unset, focus stays in the frame.
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.
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, nothing
will be swapped.
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 ╾│
├╰╼─╮.
X-.root #-.child 0 | #* child 01 | +* child 02 +-.child 1 : #* child 10 : +* child 01
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:•
~ matches if client’s property is matched by the regex
value.
•
= matches if client’s properly string is equal to
value.
•
instance: 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 the pid to the _NET_WM_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.
•
tag: moves the client to tag VALUE.
•
focus: decides whether the client gets the input focus on his tag. The default
is off. 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 contains
of a list of characters; each of them decides in which subtree the window is
inserted.
•
0: insert it in the first subtree
•
1: insert it in the second subtree
•
.: insert it in the subtree that has the focus
•
/: insert it in the subtree that has not the focus
•
pseudotile: sets the pseudotile state of the client. VALUE can be
on, off or toggle.
•
fullscreen: sets the fullscreen flag of the client. VALUE can be
on, off or toggle.
•
not: negates the next CONDITION.
•
!: same as not.
•
once: only apply this rule once (and delete it afterwards).
•
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.
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.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].
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.
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.RESOURCES¶
Gitweb: http://git.cs.fau.de/?p=re06huxa/herbstluftwmCOPYING¶
Copyright 2011-2012 Thorsten Wißmann. All rights reserved.2012-04-13 | herbstluftwm 0.3 |