COMMANDS¶
herbstluftwm is controlled by internal commands, which can
be executed via herbstclient(1) or via keybindings.
quit
Quits 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.
help [OBJECT|ATTRIBUTE]
Print help on a given object or attribute. For example:
•help clients.focus
•help monitors
•help types.color
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.
Warning
Tabs within command parameters are not escaped!
list_clients
[--tag=TAG|--monitor=MONITOR]
[--frame=FRAME_PATH|--floating|--tiling]
[--title]
Lists the window ids of all clients on the given
TAG or MONITOR (or the current if unspecified). In addition to
that, one can restrict to clients in a specific frame (--frame=) or to
tiled or floated clients. The output is one line per client; if --title
is given, then in addition to every client’s window id, its window
title is printed in the same line.
lock
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:
•keybind Mod4+Ctrl+q quit
•keybind Mod1-i toggle always_show_frame
•keybind Mod1-Shift-space cycle_layout -1
keyunbind KEY|-F|--all
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
ACTION must be one of the following actions:
•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.:
•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
drag WINID ACTION
Starts dragging the specified client window WINID
with the specified ACTION (see mousebind). E.g. drag '' resize
starts resizing the focused window.
mouseunbind
Removes all mouse bindings.
spawn EXECUTABLE [ARGS ...]
Spawns an
EXECUTABLE with its
ARGS. For
details see
man 3 execvp. Example:
•spawn xterm -e man 3 execvp
wmexec [WINDOWMANAGER [ARGS ...]]
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:
•wmexec openbox
chain SEPARATOR [COMMANDS ...]
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:
•This will only create a tag called
"foo,":
chain , add foo, use foo
•Separator "." defined, but
"," is used:
chain . add foo , use foo
and SEPARATOR [COMMANDS ...]
"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 or cycles through the clients in the floating layer if that is
focused. 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 non-minimized windows and frames on
the current tag. DIRECTION = 1 means forward (default value),
DIRECTION = -1 means backward, DIRECTION = 0 has no effect. If
there are multiple windows within one frame, then it acts similar to the
cycle command. If --skip-invisible is given, then this only
cycles through all visible windows and skips invisible windows in the max
layout (the flag only affects invisible windows in the max layout; minimized
windows are always skipped). After each focus change, 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. This is done
by finding the first occurrence of the current layout in
LAYOUTS and
picking the next layout according to
DELTA. If the current layout
doesn’t occur in
LAYOUTS, the first entry is picked. Example:
•cycle_layout -1
•cycle_layout 1 vertical grid
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 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. In floating mode, this acts as the close command.
close_and_remove
Closes the focused window and removes the current frame
if no other window is present in that frame. In floating mode, this acts as
the close command.
split ALIGN [FRACTION [FRAMEINDEX]]
Splits the focused frame (or the frame specified by
FRAMEINDEX, see the section
frame index) into two subframes with
a specified
FRACTION between 0 and 1 which defaults to 0.5.
ALIGN is one of
•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 focused frame will stay focused. One special
ALIGN mode is explode, which splits the frame in such a way
that the window focus, window sizes, and positions are kept as much as
possible (so the default FRACTION is not always 0.5, unlike for the
other ALIGN modes). Example:
•split explode
•split bottom 0.5
•split horiz 0.3
•split vertical 0.5
•split h
•split top 0.2 '' (splits the root frame)
focus [-i|-e] DIRECTION
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: H,0 Screen: ┌─────┐┌─────┐ (before)
╱ ╲ │ B ││ C │
╱ ╲ └─────┘└─────┘
V,1 V,0 ┌─────┐┌─────┐
╱ ╲ ╱ ╲ │ A* ││ D │
B A* C D └─────┘└─────┘
Tree: H,1 Screen: ┌─────┐┌─────┐ (after focus right)
╱ ╲ │ B ││ C* │
╱ ╲ └─────┘└─────┘
V,1 V,0 ┌─────┐┌─────┐
╱ ╲ ╱ ╲ │ A ││ D │
B A 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 managed or unmanaged window. Managed
windows are only moved within the tag’s stack (as reported by the
stack command), and unmanaged windows are raised globally, i.e. are
raised above all managed windows. See the section on WINDOW IDS on how to
reference a certain window. Its result is only visible for floating windows
and unmanaged windows.
lower WINID
Lowers the specified managed or unmanaged window,
analogously to the raise command: managed windows are lowered within
the stack of floating windows (with no effect for tiled windows) and unmanaged
windows are moved below all managed windows (for example, it can be used to
lower desktop windows).
jumpto WINID
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. Floating windows are brought to the current tag, but keep their
floating state. See the section on WINDOW IDS on how to reference a certain
window.
resize DIRECTION [FRACTIONDELTA]
Changes the size of the focused frame in the specified
DIRECTION by
FRACTIONDELTA (which defaults to 0.02 if none is
supplied).
DIRECTION behaves as specified at the
focus command.
If a floating window is focused, it grows towards next edge, i.e. either the
edge of the next window or the monitor edge in the specified
DIRECTION
(
FRACTIONDELTA is ignored in that case). Example:
•resize right +0.05
•resize down -0.1
shift_edge [-i|-e] DIRECTION
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. If the window cannot be moved and the setting
focus_crosses_monitor_boundaries is activated, then the window is moved
to the monitor in the specified DIRECTION.
shift_to_monitor MONITOR
Moves the focused window to the tag on the specified
MONITOR. See the MONITORS section, how to address a monitor.
remove
Removes focused frame and merges its windows to its
closest 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.
mirror [vertical|horizontal|both]
Mirrors the layout on the focused tag vertically,
horizontally, or both; the default is horizontal. This command only
manipulates the alignment of frames, not the content of them.
set NAME VALUE
Sets the specified setting NAME to VALUE.
Allowed values for boolean settings are on or true for on,
off or false for off, toggle to toggle its 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 a boolean
setting.
cycle_value PATH VALUES ...
Cycles value of the attribute
PATH 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. For
compatibility reasons,
PATH can also be the name of a setting.
Examples:
•cycle_value settings.frame_gap 0 5 10 15
•cycle_value theme.active.inner_color red green
blue
•the command cycle_layout +1 is equivalent
to cycle_value tags.focus.tiling.focused_frame.algorithm
cycle_monitor [DELTA]
Cycles monitor focused by DELTA. DELTA
defaults to 1.
focus_monitor MONITOR
Puts focus to the specified monitor. See the MONITORS
section, how to address a 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_index -1 --skip-visible
use_previous
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.
•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:
┌──────┐ ┌──────┐
│ │ └──────┘
│ ┌───┼───┐ ┌─┐┌───┐┌──┐
│ │ │ │ disjoin │ ││ ││ │
└──┼───┘ │ ─────────> └─┘└───┘└──┘
│ │ ┌───────┐
└───────┘ └───────┘
set_monitors RECTS ...
Sets the list of monitors
exactly to the list of
given rectangles:
•The i’th existing monitor is moved to the
i’th given RECT
•New monitors are created if there are more
RECTS than monitors
•Existing monitors are deleted if there are more
monitors than RECTS
detect_monitors
-l|--list|--list-all|--no-disjoin
Sets the list of monitors to the physically available
monitors. If both Xinerama and xrandr are 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 physical monitors is printed. So hc detect_monitors is equivalent
to the bash command hc set_monitors $(hc disjoin_rects $(hc detect_monitors
-l)).
If --list-all is passed, then it is printed which
multimonitor detection (xinerama, xrandr) has which set of physical
monitors.
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:
•add_monitor 1024x768-20+0 mynewtag main
remove_monitor MONITOR
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:
╾─┐ horizontal 50% selection=1
├─╼ vertical: 0xe00009
└─┐ vertical 50% selection=0
├─╼ vertical: 0xa00009 [FOCUS]
└─╼ vertical: 0x1000009
dump [TAG [INDEX]]
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:
(split horizontal:0.500000:1
(clients vertical:0 0xe00009)
(split vertical:0.500000:1
(clients vertical:0 0xa00009)
(clients vertical:0 0x1000009)))
load [TAG] LAYOUT
Loads a given LAYOUT description to specified
TAG or current tag if no TAG is given.
Caution
LAYOUT is exactly one parameter. If you are calling it
manually from your shell or from a script, quote it properly!
complete POSITION [COMMAND ARGS ...]
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, zsh and fish. Example:
•complete 0 m
prints all commands beginning with m
•complete 1 toggle fra
prints all settings beginning with fra that can be toggled
complete_shell POSITION [COMMAND ARGS
...]
Behaves like
complete with the following extras,
useful for completion on posix shells:
•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.
emit_hook NAME ARGS ...
Emits a custom hook NAME 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
Warning
If you use a tab in one of the tag names, then tag_status is
probably quite useless for you.
floating [[TAG]
on|off|toggle|status]
Changes specified TAG to floating/tiling mode or
prints its 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.
apply_rules WINID|--all
Apply the rules to the specified window WINID. If
--all is passed, then the rules are applied to all clients.
apply_tmp_rule WINID|--all
[RULEDESCRIPTION...]
Apply the rule RULEDESCRIPTION to one particular
client WINID or all clients (--all) without adding the rule to
the rule list. The RULEDESCRIPTION specifies a rule consisting of
conditions and consequences as one would pass it to the rule command as
described in the RULES section. This allows testing rules before adding
them. Running apply_tmp_rule only applies the particular rule given in the
arguments and ignores the existing rules.
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.
attr_type ATTRIBUTE
Print the type of the specified ATTRIBUTE.
new_attr
bool|color|int|string|uint PATH
[VALUE]
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_. If VALUE is supplied, then it is
written to the attribute (if this fails the attribute still remains).
watch PATH
Watch the value of the given attribute
PATH.
Whenever the value changes from
OLDVALUE to
NEWVALUE, a hook is
emitted:
attribute_changed PATH OLDVALUE NEWVALUE
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:
•substitute MYTITLE clients.focus.title echo
MYTITLE
Prints the title of the currently focused window.
sprintf IDENTIFIER FORMAT [FORMATARG ...]
COMMAND [CMDARGS ...]
Replaces all exact occurrences of
IDENTIFIER in
COMMAND and its
CMDARGS by the string specified by
FORMAT. The
FORMAT string may contain several placeholders,
similar to the
printf(1) command:
•%s inserts an attribute value whose path is given
by the string value of the next FORMATARG
•%c ("constant") inserts the next
FORMATARG without modification.
•%% stands for a plain %
The replaced command with its arguments then is executed.
Examples:
•sprintf STR title=%s clients.focus.title echo STR
Prints the title of the currently focused window prepended by
title=.
•sprintf X "%c %s tags" "there
are" tags.count echo X
Prints there are N tags with N replaced by the number of tags.
•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.
•substitute X tags.count sprintf Y
"number=%c" X echo Y
has the same output as
sprintf Y "number=%s" tags.count echo Y
(Note how the %c changes to %s)
foreach IDENTIFIER OBJECT COMMAND
[ARGS ...]
For each child of the given
OBJECT the
COMMAND is called with its
ARGS, where the
IDENTIFIER is
replaced by the path of the child. The exit code is the exit code of the
command executed last. Examples:
•foreach T tags.by-name. echo T
Prints:
tags.by-name.1
tags.by-name.2
tags.by-name.3
[...]
•Note that foreach only iterates over children,
but not over attributes, so foreach S settings echo S prints nothing, since
the settings object has only attributes but no child objects.
•foreach C clients. echo C prints the object paths
of all clients, but the focused client twice, because it is mentioned in
clients. twice: by window id and as clients.focus.
mktemp [bool|int|string|uint]
IDENTIFIER COMMAND [ARGS ...]
Creates a temporary attribute with the given type and
replaces all occurrences of IDENTIFIER in COMMAND and
ARGS 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 comparison method
OPERATOR. If the comparison 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:
substitute FC tags.focus.frame_count \
compare tags.focus.client_count gt FC
It returns success if there are more clients on the focused tag
than frames.
getenv NAME
Gets the value of the environment variable
NAME.
setenv NAME VALUE
Set the value of the environment variable NAME to
VALUE. See the export command for a convenience wrapper.
unsetenv NAME
Unsets the environment variable NAME.
export NAME=VALUE
Set the value of the environment variable NAME to
VALUE. The syntax is the same as for export in unix shells (notice that
there is a =). Intuitively, if you forgot to run export FOO=BAR before
starting herbstluftwm, you can run herbstclient export FOO=BAR from within
your herbstluftwm session for the same effect. The export command is the same
as the setenv command with different syntax.
SETTINGS¶
Settings configure the behaviour of herbstluftwm and can be
controlled via the set, get and toggle commands. The
following list mentions all settings and their type. The settings can also
be accessed via the object tree (see the section OBJECTS).
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 than
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 from 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 (Boolean)
If set, commands focus and shift cross monitor
boundaries. If there is no client in the direction given to focus, then the
monitor in the specified direction is focused. Similarly, if shift cannot move
a window within a tag, the window is moved to the neighbour monitor in the
desired direction.
raise_on_focus (Boolean)
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 (Boolean)
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 (Boolean)
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. Warning: This only
exists for compatibility reasons; it is only an alias for the attribute
theme.border_width.
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. Warning: This only exists for compatibility reasons;
it is only an alias for the attribute theme.inner_width.
window_border_active_color (String/Color)
Border color of a focused window. Warning: This
only exists for compatibility reasons; it is only an alias for the attribute
theme.active.color.
window_border_normal_color (String/Color)
Border color of an unfocused window. Warning: This
only exists for compatibility reasons; it is only an alias for the attribute
theme.normal.color.
window_border_urgent_color (String/Color)
Border color of an unfocused but urgent window.
Warning: This only exists for compatibility reasons; it is only an
alias for the attribute theme.urgent.color.
window_border_inner_color (String/Color)
Color of the inner border of a window. Warning:
This only exists for compatibility reasons; it is only an alias for the
attribute theme.inner_color.
always_show_frame (Boolean)
If set, all frames are displayed. If unset, only frames
with focus or with windows in them 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 (LayoutAlgorithm)
Name of the layout algorithm, which is used if a new
frame is created (on a new tag or by a non-trivial split). See above for the
list of layout algorithms.
default_direction_external_only (Boolean)
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 (Boolean)
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.
hide_covered_windows (Boolean)
If activated, windows are explicitly hidden when they are
covered by another window in a frame with max layout. This only has a visible
effect if a compositor is used. If activated, shadows do not stack up and
transparent windows show the wallpaper behind them instead of the other
clients in the max layout.
smart_frame_surroundings (Boolean)
If set, frame borders and gaps will be removed when
there’s no ambiguity regarding the focused frame.
smart_window_surroundings (Boolean)
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 (Boolean)
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 (Boolean)
If set, only pagers and taskbars are allowed to change
the focus. If unset, all applications can request a focus change.
monitors_locked (Unsigned 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 (Boolean)
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 (Boolean)
If set, detect_monitors is automatically executed every
time a monitor is connected, disconnected or resized.
auto_detect_panels (Boolean)
If set, EWMH panels are automatically detected and
reserve space at the side of the monitors they are on (via pad attributes of
each monitor). This setting is activated per default.
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:
X-.
#-. child 0
| #-* child 00
| +-* child 01
+-. child 1
: #-* child 10
: +-* child 11
Useful values for tree_style are: ╾│
├└╼─┐ or -| |'--. or ╾│
├╰╼─╮.
wmname (String)
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:
•cycle_value wmname herbstluftwm LG3D
pseudotile_center_threshold (Integer)
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 (Integer)
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 is released.
verbose (Boolean)
If set, verbose output is logged to herbstluftwm’s
stderr. The default value is controlled by the --verbose command line
flag.
RULES¶
Rules are used to change default properties for certain clients
when they appear or when the apply_rules command is called. 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:
rule
[[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE
...]
Each rule consists of a list of FLAGs, CONDITIONs,
CONSEQUENCEs and, optionally, a LABEL. (each of them can be
optionally prefixed with two dashes (--) to provide a more
iptables(8)-like feeling).
Each rule can be given a custom label by specifying the
LABEL property:
•[--]label=VALUE
If multiple labels are specified, the last one in the list will be
applied. If no label is given, then the rule will be given an integer name
that represents the index of the rule since the last unrule -F
command (which is triggered in the default autostart).
Tip
Rule labels default to an incremental index. These default labels
are unique, unless you assign a different rule a custom integer
LABEL. Default labels can be captured with the printlabel
flag.
If a new client appears, herbstluftwm tries to apply each rule to
this new client as follows: If each CONDITION of this rule matches
against this client, then every CONSEQUENCE is executed. (If there
are no conditions given, then this rule is executed for each client)
Each CONDITION consists of a property name, an
operator and a value. Valid operators are:
•~ matches if client’s property is
matched by the regex value.
•= matches if client’s property
string is equal to value.
Valid properties are:
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 _NET_WM_PID
to the pid itself).
pgid
this client’s process group id. Since the pgid of
a window is derived from its pid the same restrictions apply as above.
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. If
_NET_WM_WINDOW_TYPE has multiple entries, then only the first entry is used
here.
windowrole
matches the WM_WINDOW_ROLE property of a window if it is
set by the window.
Each CONSEQUENCE consists of a NAME=VALUE
pair. Valid NAMES are:
tag
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 in its
tag. The default is off. VALUE is a boolean (on or
off).
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 is a boolean
(on or off).
manage
decides whether the client will be managed or not. The
default is on. VALUE is a boolean (on or
off).
index
moves the window to a specified index in the tree.
VALUE is a frame index.
floating
sets the floating state of the client. VALUE is a
boolean.
pseudotile
sets the pseudotile state of the client. VALUE is
a boolean.
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 is a boolean; 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
is a boolean, it defaults to on.
fullscreen
sets the fullscreen flag of the client. VALUE is a
boolean.
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 a client (see explanation in
OBJECTS).
keys_inactive
sets a regex that determines which key bindings are
inactive for a client (see explanation in OBJECTS).
floatplacement
changes the floating position of a window. The
VALUE can be one of the following:
•none does not change the placement at all
•center centers the window on the monitor
•smart tries to place it with as little overlap to
other floating windows as possible. If there are multiple options with the
least overlap, then the position with the least overlap to tiling windows is
chosen.
floating_geometry
Sets the client’s floating_geometry attribute. The
VALUE is a rectangle, interpreted relatively to the monitor. If
floatplacement is also specified for the client (possibly by another rule),
then only the size of the floating_geometry is used. In order to force the
position from the geometry, it is necessary to add floatplacement=none.
A rule’s behaviour can be configured by some special
FLAGS:
•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.
Examples:
•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.
OBJECTS¶
The object tree is a collection of objects with attributes similar
to /sys known from the Linux kernel. Many entities (like tags, monitors,
clients, ...) have objects to access their attributes directly. The tree is
printed by the object_tree command and looks more or less as follows:
$ herbstclient object_tree
╾─┐
├─┐ tags
│ ├─┐ by-name
│ │ ├─╼ 1
│ │ ...
│ │ └─╼ 9
│ └─╼ focus
├─┐ clients
│ ├─╼ 0x1400022
│ └─╼ focus
└─┐ monitors
├─╼ by-name
└─╼ focus
To print a subtree starting at a certain object, pass the
PATH of the object to object_tree. The object PATH is the path
using the separator . (dot), e.g. tags.by-name:
$ herbstclient object_tree tags.by-name.
╾─┐ tags.by-name.
├─╼ 1
├─╼ 2
...
└─╼ 9
To query all attributes and children of a object, pass its
PATH to attr:
$ herbstclient attr tags.
2 children:
by-name.
focus.
1 attributes:
.---- type
| .-- writable
V V
u - count = 9
$ herbstclient attr tags.focus.
0 children.
6 attributes:
.---- type
| .-- writable
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
This already gives an intuition of the output: attr first lists
the names of the child objects and then all attributes, telling for each
attribute:
•its type
•b for boolean
•c for color
•i for integer
•r for regex
•s for string
•u for unsigned integer
•if it is writable by the user: w if yes, -
else.
•the name of the attribute
•its current value (only quoted for strings)
To get the unquoted value of a certain attribute, address the
attribute using the same syntax as for object paths and pass it to attr or
get_attr:
$ 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
To change a writable attribute value pass the new value to attr or
to set_attr:
$ 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
More information on an attribute or object is given by the help
command:
$ herbstclient help clients.focus
Just look around to get a feeling what is there. The entry point
is a root object that has the following child objects:
clients:¶
The managed windows. For every (managed) window id there is an
entry here.
•dragged: the object of a client which is
currently dragged by the mouse, if any. See the documentation of the mousebind
command for examples. For attributes and children, see clients.focus
•
focus: the focused client (only exists if
a client is focused). a managed window
•string class: the class of it
(second entry in WM_CLASS)
•Rectangle content_geometry: the
geometry of the application content, that is, not taking the decoration into
account. Also, this is the last window geometry that was reported to the
client application.
•bool ewmhnotify = true: if the
client is told about its state via ewmh
•bool ewmhrequests = true: if ewmh
requests are permitted for this client
•bool floating = false: whether this
client is floated above the tiled clients.
•Rectangle floating_geometry = 0:
the geometry of the client content if the client is in floating mode. The
position is relative to the monitor and does not take the window decoration
into account.
•bool fullscreen = false: whether
this client covers all other windows and panels on its monitor.
•string instance: the instance of it
(first entry in WM_CLASS)
•regex keymask = "": A
regular expression that is matched against the string representation of all
key bindings (as they are printed by list_keybinds). While this client is
focused, only bindings that match the expression will be active. Any other
bindings will be disabled. The default keymask is an empty string (), which
does not disable any keybinding.
•regex keys_inactive = "":
A regular expression that describes which keybindings are inactive while the
client is focused. If a key combination is pressed and its string
representation (as given by list_keybinds) matches the regex, then the key
press is propagated to the client.
•bool minimized = false: whether
this client is minimized (also called iconified).
•int pgid = -1
•int pid = -1: the process id of it
(-1 if unset).
•bool pseudotile = false: if
activated, the client always has its floating window size, even if it is in
tiling mode.
•bool sizehints_floating = true: if
sizehints for this client should be respected in floating mode
•bool sizehints_tiling = false: if
sizehints for this client should be respected in tiling mode
•string tag: the name of the tag
it’s currently on.
•string title = "": its
window title
•bool urgent = false: the urgency
state (also known as: demands attention)
•bool visible = visible_already:
whether this client is rendered currently
•string winid = "": its
window id (as a hexadecimal number with 0x prefix)
•parent_frame: the frame contaning this
client if the client is tiled. For attributes and children, see
tags.focus.tiling.root
monitors:¶
Every monitor is a rectangular part of the screen on which a tag
is shown. These monitors may or may not match the actual outputs. This has
an entry INDEX for each monitor with index INDEX.
•uint count
•by-name: This has an entry name for
every object with the given name. If an object has an empty name then
it is not listed here.
•
focus: the focused monitor. The monitor is
a rectangular part on the screen that holds precisely one tag at a time. The
pad attributes reserve space on the monitor’s edge for panels, so this
space (given in number of pixels) is never occupied by tiled clients.
•Rectangle geometry = rect_: the
outer geometry of the monitor
•uint index = 0: the
monitor’s index (starts at index 0)
•bool lock_tag = false: if
activated, then it it is not possible to switch this monitor to a different
tag.
•string name = "": the
monitor’s name (can be empty)
•int pad_down = 0: space for panels
at the monitor’s lower edge
•int pad_left = 0: space for panels
at the monitor’s left edge
•int pad_right = 0: space for panels
at the monitor’s right edge
•int pad_up = 0: space for panels at
the monitor’s upper edge
•string tag: the name of the tag
viewed here
panels:¶
For every panel window, there is an entry with the panel’s
window id here.
•uint count
•
0xWindowID: a panel is an unmanaged window
that reserves space at the edge of the monitor it is on. The space depends on
the _NET_WM_STRUT defined by the panel. If it is however not defined
explicitly, then the amount of reserved space is inferred from the window
geometry.
•string class: the window class
(second entry of WM_CLASS)
•Rectangle geometry: the size and
position of the window
•string instance: the window
instance (first entry of WM_CLASS)
•WindowID winid = winid: the ID of
the panel window
settings:¶
This has an attribute for each setting. Many settings are wrappers
around attributes and only exist for compatibility.
•bool always_show_frame =
false
•bool auto_detect_monitors =
false
•bool auto_detect_panels =
true
•bool
default_direction_external_only = false
•LayoutAlgorithm
default_frame_layout = vertical
•bool
focus_crosses_monitor_boundaries = true
•bool focus_follows_mouse =
false
•bool focus_stealing_prevention =
true
•int frame_active_opacity =
100
•color frame_bg_active_color =
black
•color frame_bg_normal_color =
black
•bool frame_bg_transparent =
false
•color frame_border_active_color =
red
•color frame_border_inner_color =
black
•int frame_border_inner_width =
0
•color frame_border_normal_color =
blue
•int frame_border_width = 2
•int frame_gap = 5
•int frame_normal_opacity =
100
•int frame_padding = 0
•int frame_transparent_width =
0
•bool gapless_grid = true
•bool hide_covered_windows =
false
•uint monitors_locked = 0
•int mouse_recenter_gap = 0
•int pseudotile_center_threshold =
10
•bool raise_on_click = true
•bool raise_on_focus = false
•bool raise_on_focus_temporarily =
false
•bool smart_frame_surroundings =
false
•bool smart_window_surroundings =
false
•int snap_distance = 10
•int snap_gap = 5
•bool swap_monitors_to_get_tag =
true
•string tree_style = "*|
+`--."
•bool update_dragged_clients =
false
•bool verbose = false
•color
window_border_active_color
•color
window_border_inner_color
•int window_border_inner_width
•color
window_border_normal_color
•color
window_border_urgent_color
•int window_border_width
•int window_gap = 0
•string wmname = herbstluftwm
The tags (or virtual desktops or workspaces). This contains an
entry index for each tag with the given index.
•uint count
•by-name: For attributes and children, see
monitors.by-name
•
focus: the object of the focused tag,
equivalently, the tag on the focused monitor.
•int client_count: the number of
clients on this tag
•int curframe_wcount: number of
clients in the selected frame
•int curframe_windex: index of the
focused client in the selected frame
•bool floating = false: if the
entire tag is set to floating mode
•bool floating_focused = false: if
the floating layer is focused (otherwise the tiling layer is)
•int frame_count: the number of
frames on this tag
•uint index = 0: index of this tag
(the first index is 0)
•string name = name_: name of the
tag (must be non-empty)
•int urgent_count: the number of
urgent clients on this tag
•bool visible = false: if this tag
is shown on some monitor
•focused_client: For attributes and
children, see clients.focus
•
tiling:
•focused_frame: The focused frame (leaf) in
this frame tree. For attributes and children, see tags.focus.tiling.root
•
root can be a frame leaf.
•LayoutAlgorithm algorithm
•int client_count
•string index
•int selection
•
root can be a frame split.
•decimal fraction
•string index
•int selection
•SplitAlign split_type
•0 can be a frame leaf. For attributes and
children, see tags.focus.tiling.root
•0 can be a frame split. For attributes and
children, see tags.focus.tiling.root
•1 can be a frame leaf. For attributes and
children, see tags.focus.tiling.root
•1 can be a frame split. For attributes and
children, see tags.focus.tiling.root
theme:¶
inner_color/inner_width
╻ outer_color/outer_width
│ ╻
│ │
┌────╴│╶─────────────────┷─────┐ ⎫ border_width
│ │ color │ ⎬ + title_height
│ ┌──┷─────────────────────┐ │ ⎭ + padding_top
│ │====================....│ │
│ │== window content ==....│ │
│ │====================..╾──────── background_color
│ │........................│ │
│ └────────────────────────┘ │ ⎱ border_width +
└──────────────────────────────┘ ⎰ padding_bottom
Setting an attribute of the theme object just propagates the value
to the respective attribute of the tiling and the floating object.
•color background_color =
black
•uint border_width = 0
•color color = black
•color inner_color = black
•uint inner_width = 0
•color outer_color = black
•uint outer_width = 0
•uint padding_bottom = 0
•uint padding_left = 0
•uint padding_right = 0
•uint padding_top = 0
•string reset: writing this resets
all attributes to a default value
•bool tight_decoration = false
•color title_color = black
•font title_font = fixed
•uint title_height = 0
•
active: configures the decoration of the
focused client.
•color background_color =
black
•uint border_width = 0
•color color = black
•color inner_color = black
•uint inner_width = 0
•color outer_color = black
•uint outer_width = 0
•uint padding_bottom = 0
•uint padding_left = 0
•uint padding_right = 0
•uint padding_top = 0
•string reset: writing this resets
all attributes to a default value
•bool tight_decoration = false
•color title_color = black
•font title_font = fixed
•uint title_height = 0
•
floating: behaves analogously to tiling.
•color background_color =
black
•uint border_width = 0
•color color = black
•color inner_color = black
•uint inner_width = 0
•color outer_color = black
•uint outer_width = 0
•uint padding_bottom = 0
•uint padding_left = 0
•uint padding_right = 0
•uint padding_top = 0
•string reset: writing this resets
all attributes to a default value
•bool tight_decoration = false
•color title_color = black
•font title_font = fixed
•uint title_height = 0
•active: configures the decoration of the
focused client. For attributes and children, see theme.active
•normal: the default decoration scheme for
clients. For attributes and children, see theme.active
•urgent: configures the decoration of
urgent clients. For attributes and children, see theme.active
•fullscreen: configures clients in
fullscreen state. For attributes and children, see theme.floating
•minimal: configures clients with minimal
decorations triggered by smart_window_surroundings. For attributes and
children, see theme.floating
•normal: the default decoration scheme for
clients. For attributes and children, see theme.active
•tiling: configures the decoration of tiled
clients, setting one of its attributes propagates the respective attribute of
the active, normal and urgent child objects. For attributes and children, see
theme.floating
•urgent: configures the decoration of
urgent clients. For attributes and children, see theme.active
types:¶
This lists the types that are used for attributes and command
arguments.
•
bool: Type representing boolean values,
i.e. an
on or
off state, with aliases
true and
false. When writing to a boolean value, one can also specify
toggle in order to alter its value.
•string fullname: the full and
unique name of this type
•string shortname: A short
(one-character long) name of this type which is used in the output of the
attr command
•
color: Type representing colors. A color
can be defined in one of the following formats:
1.#RRGGBB where R, G, B are hexidecimal digits (0-9,
A-F), and RR, GG, BB represent the values for red, green, blue.
2.#RRGGBBAA represents a color with alpha-value AA. The
alpha value 00 is fully transparent and FF is fully
opaque/intransparent.
3.a common color name like red, blue,
orange, etc. For attributes and children, see types.bool
•decimal: Fixed precision decimal numbers,
e.g. 0.34. For attributes and children, see types.bool
•
font: A font specification (font family
with modifiers regarding size, weight, etc.) in one of the following formats:
•Fontconfig description. This supports antialiased
fonts, for example:
•Dejavu Sans:pixelsize=12
•Bitstream Vera Sans:size=12:bold
•X logical font description (XLFD), as provided by
the xfontsel tool. No antialiasing is supported here, but this is usually
superior for bitmap fonts. For example:
•-*-fixed-medium-r-*-*-13-*-*-*-*-*-*-* for
a standard bitmap font available on most systems. For attributes and children,
see types.bool
•int: Type representing signed integers.
When overwriting an integer, you can increase or decrease its value relatively
by writing +=N or -=N where N is an integer. So for example,
writing +=3 to an attribute increases its value by 3. For attributes
and children, see types.bool
•names: A fixed set of names, depending on
the context, e.g. names of layout algorithms or the split type of a non-leaf
frame (which is only horizontal or vertical). For attributes and
children, see types.bool
•rectangle: A rectangle on the screen
consisting of a size and the position on the screen. The format is WxH+X+Y
where W is the width, H is the height, and X and Y are the coordinates of the
top left corner of the rectangle: X is the number of pixels to the left screen
edge and Y is the number of pixels to the top screen edge. (if X or Y is
negative, then the + turns into -). For example: 800x600+800+0 or
400x200-10+30. For attributes and children, see types.bool
•string: Type representing normal text. For
attributes and children, see types.bool
•uint: Type representing unsigned (i.e.
non-negative) integers. When overwriting an integer, you can increase or
decrease its value relatively by writing +=N or -=N where N is
an integer. For attributes and children, see types.bool
•windowid: The window id is the number of a
window. This can be a managed window (i.e. client) or an unmanaged window
(e.g. a panel, a menu, or a desktop window). The default format is 0xHEX where
HEX is a hexadecimal number (digits 0-9 and a-f) but it can also be specified
in the decimal system (base 10), or as an octal number (with prefix 0 and base
8). When a window id is printed, it is always printed in the 0xHEX format and
without any leading zeroes. For attributes and children, see types.bool
watchers:¶
•uint count: the number of
attributes that are watched
