1HERBSTLUFTWM(1) HERBSTLUFTWM(1)
2
6 herbstluftwm - a manual tiling window manager for X
7
9 herbstluftwm [OPTION ...]
10
12 Starts the herbstluftwm window manager on DISPLAY. It also listens for
13 calls from herbstclient(1) and executes them. The list of available
14 COMMANDS is listed below.
15 OPTION can be:
17 -v, --version
19 print version and exit
20 -h, --help
22 print a short help and exit
23 -c, --autostart PATH
25 use PATH as autostart file instead of the one in $XDG_CONFIG_HOME
26 --replace
28 Replace existing window manager.
29 -l, --locked
31 Initially set the monitors_locked setting to 1
32 --exit-on-xerror
34 Make herbstluftwm exit whenever xlib reports an error. This may
35 only be activated for automated testing and never for actual
36 sessions.
37 --no-transparency
39 Disable true transparency.
40 --no-tag-import
42 Do not preserve the tags (virtual desktops) from a previous running
43 window manager.
44 --verbose
46 print verbose information to stderr. This can be switched at
47 run-time by the verbose setting.
48 This manual documents the scripting and configuration interface. For a
50 more verbose introduction see herbstluftwm-tutorial(7).
51
53 The basic tiling concept is that the layout is represented by a binary
54 tree. On startup you see one big frame across the entire screen. A
55 frame fulfills exactly one of the following conditions:
56 1. Frame contains windows:
58 It shows some clients and arranges them. The available layout
60 algorithms are:
61 • vertical - clients are placed below each other
63 • horizontal - clients are placed next to each other
65 • max - all clients are maximized in this frame
67 • grid - clients are arranged in an almost quadratic grid
69 2. Frame is split into subframes:
71 It is split into exactly two subframes in a configurable fraction
73 either in a vertical or horizontal way. So it produces two frames
74 which fulfill the same conditions (new frames always are about to
75 contain windows). If you split a frame that already contains
76 windows, the windows are inherited by the first new child frame.
77 If a new window appears, it is put in the currently focused frame. Only
79 the leaves of the frame tree can be focused.
80 A frame can be removed, it is then merged with its neighbour frame. Due
82 to the layout structure of a binary tree, each frame (i.e. node in
83 binary tree) has exactly one neighbour.
84 The analogy to a binary tree is explained the best way with a small
86 example: On startup you have a simple binary tree, with one frame that
87 can contain clients:
88 C
90 When splitting it (e.g. with the command split vertical 0.5) you will
92 get this:
93 V
95 / \
96 C C
97 You also can split the left frame horizontally and you will get:
99 V
101 / \
102 H C
103 / \
104 C C
105 If you change the focus to the client on the right and remove this
107 frame, it will be merged with the left subtree and you will get:
108 H
110 / \
111 C C
112 The layout command prints the current layout of all tags as a tree.
114
116 The exact position of a frame in the layout tree may be described by
117 its index which is just a string of characters. The lookup algorithm
118 starts at the root frame and interprets the index string character by
119 character as follows:
120 • 0: select the first subtree
122 • 1: select the second subtree
124 • .: select the subtree having the focus
126 • /: select the subtree not having the focus
128 • @: select the frame having the focus. In contrast to ., this passes
130 multiple layers all down to the focused leaf of the frame tree.
131 • p: select the parent tree
133 • e: finds a suitable empty frame: if the focused frame is not empty,
135 this selects the closest frame that is empty (in any subtree)
136 For example:
138 • An empty string refers to the root frame
140 • 00 refers to the first subtree of the first subtree of the root
142 frame.
143 • 1e refers to the first empty frame in the second subtree.
145 • /@ refers to the focused frame within the unfocused "half" of the
147 frame tree
148 • @p/ refers to the sibling of the focused frame
150
152 Tags are very similar to workspaces, virtual desktops or window groups.
153 Each tag has one layout. There is a list of tags. You can add or remove
154 tags dynamically.
155
157 Monitors in herbstluftwm are totally independent of the actual physical
158 screens. This means you can for example split your screen in two
159 virtual monitors to view two tags at once on a big screen.
160 Each monitor displays exactly one tag on a specified rectangle on the
162 screen.
163 Each monitor may have a name, which can be set via add_monitor and
165 rename_monitor. It can be unset with the rename_monitor command. A
166 monitor name is an arbitrary non-empty string which must not start with
167 +, - or any digit.
168 A monitor can be referenced in different ways:
170 • by its absolute index as listed in the list_monitors command.
172 • by its relative index: a + or - followed by a delta, e.g.: +3
174 • by its relative position to the focused monitor. -l denotes the
176 monitor left of the focused monitor, -r right of, -u above of, and
177 -d below of, respectively.
178 • by "" (an empty string) which represents the current monitor.
180 • by its name.
182
184 herbstluftwm is controlled by internal commands, which can be executed
185 via herbstclient(1) or via keybindings.
186 quit
188 Quits herbstluftwm.
189 reload
191 Executes the autostart file.
192 version
194 Prints the version of the running herbstluftwm instance.
195 echo [ARGS ...]
197 Prints all given ARGS separated by a single space and a newline
198 afterwards.
199 true
201 Ignores all arguments and always returns success, i.e. 0.
202 false
204 Ignores all arguments and always returns failure, i.e. 1.
205 help [OBJECT|ATTRIBUTE]
207 Print help on a given object or attribute. For example:
208 • help clients.focus
210 • help monitors
212 • help types.color
214 list_commands
216 Lists all available commands.
217 list_monitors
219 List currently configured monitors with their index, area (as
220 rectangle), name (if named) and currently viewed tag.
221 list_rules
223 Lists all active rules. Each line consists of all the parameters
224 the rule was called with, plus its label, separated by tabs.
225 list_keybinds
227 Lists all bound keys with their associated command. Each line
228 consists of one key combination and the command with its parameters
229 separated by tabs.
230 Warning
232 Tabs within command parameters are not escaped!
233 list_clients [--tag=TAG|--monitor=MONITOR]
235 [--frame=FRAME_PATH|--floating|--tiling] [--title]
236 Lists the window ids of all clients on the given TAG or MONITOR (or
237 the current if unspecified). In addition to that, one can restrict
238 to clients in a specific frame (--frame=) or to tiled or floated
239 clients. The output is one line per client; if --title is given,
240 then in addition to every client’s window id, its window title is
241 printed in the same line.
242 lock
244 Increases the monitors_locked setting. Use this if you want to do
245 multiple window actions at once (i.e. without repainting between
246 the single steps). See also: unlock
247 unlock
249 Decreases the monitors_locked setting. If monitors_locked is
250 changed to 0, then all monitors are repainted again. See also: lock
251 keybind KEY COMMAND [ARGS ...]
253 Adds a key binding. If there is already a binding for this KEY, it
254 will be overwritten. When KEY is pressed, the internal COMMAND
255 (with its ARGS) is executed. A key binding is a (possibly empty)
256 list of modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super,
257 Control/Ctrl, Shift) and one key (see keysymdef.h for a list of
258 keys). Modifiers and the key are concatenated with - or + as
259 separator. If KEY is prefixed with Release- then the keybinding is
260 only active during the corresponding key release event: that is, in
261 order to run the key binding for Release-Mod1-Shift-p one needs to
262 first press Mod1-Shift-p and then release p. Examples:
263 • keybind Mod4+Ctrl+q quit
265 • keybind Mod4-Shift-d attr clients.focus.decorated toggle
267 • keybind Mod1-Shift-space cycle_layout -1
269 • keybind Release-Mod4-Shift-p spawn scrot takes a screenshot
271 when the p is released while Mod4 and Shift are still pressed.
272 keyunbind KEY|-F|--all
274 Removes the key binding for KEY. The syntax for KEY is defined in
275 keybind. If -F or --all is given, then all key bindings will be
276 removed.
277 mousebind BUTTON ACTION [COMMAND ...]
279 Adds a mouse binding for the floating mode. When BUTTON is pressed,
280 the specified ACTION will be performed. BUTTON has a similar
281 syntax to the KEY argument of keybind: It consists of a list of
282 modifiers (separated by - or +, valid modifiers are listed in the
283 description of keybind) and exactly one button name:
284 • B1 or Button1
286 • B2 or Button2
288 • B3 or Button3
290 • B4 or Button4
292 • B5 or Button5
294 ACTION must be one of the following actions:
296 • move: Moves the window by dragging the cursor.
298 • resize: Resizes the window by dragging a corner.
300 • zoom: Resizes the window into all four directions while keeping
302 the center of the window constant.
303 • call: Only calls the specified COMMAND while client.dragged
305 links to the client on which the BUTTON has been performed.
306 While an ACTION is performed, client.dragged is the client which is
308 dragged. E.g.:
309 • mousebind Mod1-Button3 zoom
311 • mousebind Mod1-B4 call substitute WID clients.dragged.winid
313 spawn transset-df --inc -i WID 0.05
314 • mousebind Mod1-B5 call substitute WID clients.dragged.winid
316 spawn transset-df --dec -i WID -m 0.2 0.05
317 drag WINID ACTION
319 Starts dragging the specified client window WINID with the
320 specified ACTION (see mousebind). E.g. drag '' resize starts
321 resizing the focused window.
322 mouseunbind
324 Removes all mouse bindings.
325 spawn EXECUTABLE [ARGS ...]
327 Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp.
328 Example:
329 • spawn xterm -e man 3 execvp
331 wmexec [WINDOWMANAGER [ARGS ...]]
333 Executes the WINDOWMANAGER with its ARGS. This is useful to switch
334 the window manager in the running session without restarting the
335 session. If no or an invalid WINDOWMANAGER is given, then
336 herbstluftwm is restarted. For details see man 3 execvp. Example:
337 • wmexec openbox
339 chain SEPARATOR [COMMANDS ...]
341 chain expects a SEPARATOR and a list of COMMANDS with arguments.
342 The commands have to be separated by the specified SEPARATOR. The
343 SEPARATOR can by any word and only is recognized as the separator
344 between commands if it exactly matches SEPARATOR. "chain" outputs
345 the appended outputs of all commands and returns the exit code of
346 the last executed command. Examples are:
347 • Create a tag called "foo" and directly use it:
349 chain , add foo , use foo
351 • Rotate the layout clockwise:
353 chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
355 Counterexamples are:
357 • This will only create a tag called "foo,":
359 chain , add foo, use foo
361 • Separator "." defined, but "," is used:
363 chain . add foo , use foo
365 and SEPARATOR [COMMANDS ...]
367 "and" behaves like the chain command but only executes the
368 specified COMMANDS while the commands return the exit code 0.
369 or SEPARATOR [COMMANDS ...]
371 "or" behaves like the chain command but only executes the specified
372 COMMANDS until one command returns the exit code 0.
373 ! COMMAND
375 "!" executes the provided command, but inverts its return value. If
376 the provided command returns a nonzero, "!" returns a 0, if the
377 command returns a zero, "!" returns a 1.
378 try COMMAND
380 "try" executes the provided command, prints its output, but always
381 returns success, i.e. 0.
382 silent COMMAND
384 "silent" executes the provided command, but discards its output and
385 only returns its exit code.
386 focus_nth INDEX
388 Focuses the nth window in a frame. The first window has INDEX 0. If
389 INDEX is negative or greater than the last window index, then the
390 last window is focused.
391 cycle [DELTA]
393 Cycles the selection within the current frame by DELTA or cycles
394 through the clients in the floating layer if that is focused. If
395 DELTA is omitted, DELTA = 1 will be used. DELTA can be negative;
396 DELTA = -1 means: cycle in the opposite direction by 1.
397 cycle_all [--skip-invisible] [DIRECTION]
399 Cycles through all non-minimized windows and frames on the current
400 tag. DIRECTION = 1 means forward (default value), DIRECTION = -1
401 means backward, DIRECTION = 0 has no effect. If there are multiple
402 windows within one frame, then it acts similar to the cycle
403 command. If --skip-invisible is given, then this only cycles
404 through all visible windows and skips invisible windows in the max
405 layout (the flag only affects invisible windows in the max layout;
406 minimized windows are always skipped). After each focus change, the
407 focused window is raised.
408 cycle_frame [DIRECTION]
410 Cycles through all frames on the current tag. DIRECTION = 1 means
411 forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
412 effect. DIRECTION defaults to 1.
413 cycle_layout [DELTA [LAYOUTS ...]]
415 Cycles the layout algorithm in the current frame by DELTA. DELTA
416 defaults to 1. You can find a list of layout algorithms above. If a
417 list of LAYOUTS is given, cycle_layout will cycle through those
418 instead of the default layout algorithm list. This is done by
419 finding the first occurrence of the current layout in LAYOUTS and
420 picking the next layout according to DELTA. If the current layout
421 doesn’t occur in LAYOUTS, the first entry is picked. Example:
422 • cycle_layout -1
424 • cycle_layout 1 vertical grid
426 set_layout LAYOUT
428 Sets the layout algorithm in the current frame to LAYOUT. For the
429 list of layouts, check the list of layout algorithms above.
430 close WINID
432 Closes the specified window gracefully or the focused window if
433 none is given explicitly. See the section on WINDOW IDS how to
434 reference a certain window.
435 close_or_remove
437 Closes the focused window or removes the current frame if no window
438 is focused. In floating mode, this acts as the close command.
439 close_and_remove
441 Closes the focused window and removes the current frame if no other
442 window is present in that frame. In floating mode, this acts as the
443 close command.
444 split ALIGN [FRACTION [FRAMEINDEX]]
446 Splits the focused frame (or the frame specified by FRAMEINDEX, see
447 the section frame index) into two subframes with a specified
448 FRACTION between 0 and 1 which defaults to 0.5. ALIGN is one of
449 • top
452 • bottom (= vertical)
454 • left
456 • right (= horizontal)
458 • explode
460 • auto (split along longest side)
462 It specifies which of the two halves will be empty after the
464 split. The other half will be occupied by the currently focused
465 frame. After splitting, the originally focused frame will stay
466 focused. One special ALIGN mode is explode, which splits the
467 frame in such a way that the window focus, window sizes, and
468 positions are kept as much as possible (so the default FRACTION
469 is not always 0.5, unlike for the other ALIGN modes). Example:
470 • split explode
472 • split bottom 0.5
474 • split horiz 0.3
476 • split vertical 0.5
478 • split h
480 • split top 0.2 '' (splits the root frame)
482 focus [-i|-e|--level=LEVEL] DIRECTION
484 Moves the focus from current frame to the next frame or client in
485 DIRECTION which is in:
486 • l[eft]
489 • r[ight]
491 • u[p]
493 • d[own]
495 If there is no client within this frame or LEVEL is frame, then the
497 next frame in specified DIRECTION will be focused. If LEVEL is
498 visible or default_direction_external_only is unset, then the next
499 client in DIRECTION can also be within the same frame, but has to
500 be visible. For tabs LEVEL, the next client may be hidden in a
501 tabbed_max layout. With all any client within a max layout maybe
502 selected before focusing the next frame. The flag -i is an alias
503 for --level=visible and -e for --level=frame.
504 The direction between frames is defined as follows: The focus is in
507 a leaf of the binary tree. Each inner node in the tree remembers
508 the last focus direction (child 0 or child 1). The algorithm uses
509 the shortest possible way from the leaf (the currently focused
510 frame) to the root until it is possible to change focus in the
511 specified DIRECTION. From there the focus goes back to the leaf.
512 Example: The focus is at frame A. After executing focus right focus
515 will be at frame C.
516 Tree: H,0 Screen: ┌─────┐┌─────┐ (before)
518 ╱ ╲ │ B ││ C │
519 ╱ ╲ └─────┘└─────┘
520 V,1 V,0 ┌─────┐┌─────┐
521 ╱ ╲ ╱ ╲ │ A* ││ D │
522 B A* C D └─────┘└─────┘
523 Tree: H,1 Screen: ┌─────┐┌─────┐ (after focus right)
525 ╱ ╲ │ B ││ C* │
526 ╱ ╲ └─────┘└─────┘
527 V,1 V,0 ┌─────┐┌─────┐
528 ╱ ╲ ╱ ╲ │ A ││ D │
529 B A C* D └─────┘└─────┘
530 If the currently focused client is floated, then the next floating
532 window in the specified direction is focused and raised.
533 If focus_crosses_monitor_boundaries is set and no client or frame
535 is found in the specified DIRECTION, then the next monitor in that
536 DIRECTION is focused.
537 focus_edge [-i|-e] DIRECTION
539 Focuses the window on the edge of the tag in the specified
540 DIRECTION. The DIRECTIONS and -e behave as specified at the focus
541 command.
542 If -i (internal) is given or default_direction_external_only is
545 unset, then the window on the edge of the tag will be focused.
546 Else, only the frame on the edge of the tag will be focused, and
547 the window that was last focused in that frame will be focused.
548 raise WINID
550 Raises the specified managed or unmanaged window. Managed windows
551 are only moved within the tag’s stack (as reported by the stack
552 command), and unmanaged windows are raised globally, i.e. are
553 raised above all managed windows. See the section on WINDOW IDS on
554 how to reference a certain window. Its result is only visible for
555 floating windows and unmanaged windows.
556 lower WINID
558 Lowers the specified managed or unmanaged window, analogously to
559 the raise command: managed windows are lowered within the stack of
560 floating windows (with no effect for tiled windows) and unmanaged
561 windows are moved below all managed windows (for example, it can be
562 used to lower desktop windows).
563 jumpto WINID
565 Puts the focus to the specified window. See the section on WINDOW
566 IDS on how to reference a certain window.
567 bring WINID
569 Moves the specified window to the current frame and focuses it.
570 Floating windows are brought to the current tag, but keep their
571 floating state. See the section on WINDOW IDS on how to reference a
572 certain window.
573 resize DIRECTION [FRACTIONDELTA]
575 Changes the size of the focused frame in the specified DIRECTION by
576 FRACTIONDELTA (which defaults to 0.02 if none is supplied).
577 DIRECTION behaves as specified at the focus command. If a floating
578 window is focused, it grows towards next edge, i.e. either the edge
579 of the next window or the monitor edge in the specified DIRECTION
580 (FRACTIONDELTA is ignored in that case). Example:
581 • resize right +0.05
583 • resize down -0.1
585 shift_edge [-i|-e] DIRECTION
587 Shifts the focused window to the the edge of a tag in the specified
588 DIRECTION. The DIRECTIONS behave as specified at the focus command
589 and -i and -e behave as specified at the focus_edge command.
590 shift [-i|-e] DIRECTION
592 Shifts the focused window to the next frame in the specified
593 DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
594 focus command. If the focused client is floated instead of being
595 tiled, then client is shifted to the next window or screen edge. If
596 the window cannot be moved and the setting
597 focus_crosses_monitor_boundaries is activated, then the window is
598 moved to the monitor in the specified DIRECTION.
599 shift_to_monitor MONITOR
601 Moves the focused window to the tag on the specified MONITOR. See
602 the MONITORS section, how to address a monitor.
603 remove
605 Removes focused frame and merges its windows to its closest
606 neighbour frame.
607 rotate
609 Rotates the layout on the focused tag counterclockwise by 90
610 degrees. This only manipulates the alignment of frames, not the
611 content of them.
612 mirror [vertical|horizontal|both]
614 Mirrors the layout on the focused tag vertically, horizontally, or
615 both; the default is horizontal. This command only manipulates the
616 alignment of frames, not the content of them.
617 set NAME VALUE
619 Sets the specified setting NAME to VALUE. Allowed values for
620 boolean settings are on or true for on, off or false for off,
621 toggle to toggle its value. All settings are listed in the section
622 below.
623 get NAME
625 Prints the value of setting NAME. All settings are listed in the
626 section below.
627 toggle NAME
629 Toggles the setting NAME if it’s a boolean setting.
630 cycle_value PATH VALUES ...
632 Cycles value of the attribute PATH through VALUES: I.e. it searches
633 the first occurrence of the current value in VALUES and changes the
634 value to the next in the list or to the first one if the end is
635 reached or current value wasn’t found. For compatibility reasons,
636 PATH can also be the name of a setting. Examples:
637 • cycle_value settings.frame_gap 0 5 10 15
639 • cycle_value theme.active.inner_color red green blue
641 • the command cycle_layout +1 is equivalent to cycle_value
643 tags.focus.tiling.focused_frame.algorithm
644 cycle_monitor [DELTA]
646 Cycles monitor focused by DELTA. DELTA defaults to 1.
647 focus_monitor MONITOR
649 Puts focus to the specified monitor. See the MONITORS section, how
650 to address a monitor.
651 add TAG
653 Creates a new empty tag named TAG.
654 use TAG
656 Switches the focused monitor to specified TAG.
657 use_index INDEX [--skip-visible]
659 Switches the focused monitor to the TAG with the specified INDEX.
660 If INDEX starts with + or -, then INDEX is treated relative to the
661 current TAG. If --skip-visible is passed and INDEX is relative,
662 then tags that are already visible on a monitor are skipped. E.g.
663 this cycles backwards through the tags:
664 • use_index -1 --skip-visible
666 use_previous
668 Switches the focused monitor to the previously viewed tag.
669 merge_tag TAG [TARGET]
671 Removes tag named TAG and moves all its windows to tag TARGET. If
672 TARGET is omitted, the focused tag will be used.
673 rename OLDTAG NEWTAG
675 Renames tag named OLDTAG to NEWTAG.
676 move TAG
678 Moves the focused window to the tag named TAG.
679 move_index INDEX [--skip-visible]
681 Moves the focused window to the tag specified by INDEX. Analogical
682 to the argument for use_index: If INDEX starts with + or -, then it
683 is treated relative. If --skip-visible is passed with a relative
684 index, then already visible tags are skipped.
685 lock_tag [MONITOR]
687 Lock the tag switching on the specified monitor. If no argument is
688 given, the currently focused monitor is used. When the tag
689 switching is disabled for a monitor, the commands use and use_index
690 have no effect when executed there. When swap_monitors_to_get_tag
691 is enabled, switching to a tag which is located on a locked
692 monitor, switches to that monitor instead of stealing it from
693 there. The lock state of a monitor is indicated by "[LOCKED]" in
694 the list_monitors output.
695 unlock_tag [MONITOR]
697 Re-enables the tag switching on the specified monitor. If no
698 argument is given, the currently focused monitor is used. This is
699 the reverse operation to lock_tag and has no further side effects
700 but removing this lock.
701 disjoin_rects RECTS ...
703 Takes a list of rectangles and splits them into smaller pieces
704 until all rectangles are disjoint, the result rectangles are
705 printed line by line. This command does not modify the current list
706 of monitors! So this can be useful in combination with the
707 set_monitors command.
708 • E.g. disjoin_rects 600x400+0+0 600x400+300+250 prints this:
710 300x150+300+250
712 600x250+0+0
713 300x150+0+250
714 300x150+600+250
715 600x250+300+400
716 • In the above example two monitors are split into 5 monitors,
718 which graphically means:
719 ┌──────┐ ┌──────┐
721 │ │ └──────┘
722 │ ┌───┼───┐ ┌─┐┌───┐┌──┐
723 │ │ │ │ disjoin │ ││ ││ │
724 └──┼───┘ │ ─────────> └─┘└───┘└──┘
725 │ │ ┌───────┐
726 └───────┘ └───────┘
727 set_monitors RECTS ...
729 Sets the list of monitors exactly to the list of given rectangles:
730 • The i’th existing monitor is moved to the i’th given RECT
732 • New monitors are created if there are more RECTS than monitors
734 • Existing monitors are deleted if there are more monitors than
736 RECTS
737 detect_monitors -l|--list|--list-all|--no-disjoin
739 Sets the list of monitors to the physically available monitors. If
740 both Xinerama and xrandr are missing, it will fall back to one
741 monitor across the entire screen. If the detected monitors overlap,
742 the will be split into more monitors that are disjoint but cover
743 the same area using disjoin_rects.
744 If -l or --list is passed, the list of rectangles of detected
746 physical monitors is printed. So hc detect_monitors is equivalent
747 to the bash command hc set_monitors $(hc disjoin_rects $(hc
748 detect_monitors -l)).
749 If --list-all is passed, then it is printed which multimonitor
751 detection (xinerama, xrandr) has which set of physical monitors.
752 add_monitor RECT [TAG [NAME]]
754 Adds a monitor on the specified rectangle RECT and displays TAG on
755 it. TAG currently must not be displayed on any other monitor.
756 RECT is a string of the form WxH±X±Y. If no or an empty TAG is
757 given, then any free tag will be chosen. If a NAME is given, you
758 can reference to this monitor by its name instead of using an
759 index. Example:
760 • add_monitor 1024x768-20+0 mynewtag main
762 remove_monitor MONITOR
764 Removes the specified monitor.
765 move_monitor MONITOR RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
767 Moves the specified monitor to rectangle RECT. RECT is defined as
768 in add_monitor. If no or an empty pad is given, it is not changed.
769 raise_monitor [MONITOR]
771 Raises the specified monitor or the current one if MONITOR is
772 omitted.
773 rename_monitor MONITOR NAME
775 (Re)names an already existing monitor. If NAME is empty, it removes
776 the monitor’s name.
777 stack
779 Prints the stack of monitors with the visible tags and their layers
780 as a tree. The order of the printed stack is top to bottom. The
781 style is configured by the tree_style setting.
782 monitor_rect [[-p] MONITOR]
784 Prints the rectangle of the specified monitor in the format: X Y W
785 H If no MONITOR or cur is given, then the current monitor is used.
786 If -p is supplied, then the remaining rect without the pad around
787 this monitor is printed.
788 pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
790 Sets the pad of specified monitor to the specified padding. If no
791 or an empty padding is given, it is not changed.
792 list_padding [MONITOR]
794 Lists the padding of the specified monitor, or the currently
795 focused monitor if no monitor is given.
796 layout [TAG [INDEX]]
798 Prints the layout of frame with INDEX on TAG, in a nice tree style.
799 Its style is defined by the tree_style setting. If no TAG is given,
800 the current tag is used. If no INDEX is given, the root frame is
801 used. To specify INDEX without specifying TAG (i.e. use current
802 tag), pass an empty string as TAG.
803 An example output is:
805 ╾─┐ horizontal 50% selection=1
807 ├─╼ vertical: 0xe00009
808 └─┐ vertical 50% selection=0
809 ├─╼ vertical: 0xa00009 [FOCUS]
810 └─╼ vertical: 0x1000009
811 dump [TAG [INDEX]]
813 Prints the same information as the layout command but in a machine
814 readable format. Its output can be read back with the load command.
815 An example output (formatted afterwards) is:
817 (split horizontal:0.500000:1
819 (clients vertical:0 0xe00009)
820 (split vertical:0.500000:1
821 (clients vertical:0 0xa00009)
822 (clients vertical:0 0x1000009)))
823 load [TAG] LAYOUT
825 Loads a given LAYOUT description to specified TAG or current tag if
826 no TAG is given.
827 Caution
829 LAYOUT is exactly one parameter. If you are calling it manually
830 from your shell or from a script, quote it properly!
831 complete POSITION [COMMAND ARGS ...]
833 Prints the result of tab completion for the partial COMMAND with
834 optional ARGS. You usually do not need this, because there is
835 already tab completion for bash, zsh and fish. Example:
836 • complete 0 m
838 prints all commands beginning with m
840 • complete 1 toggle fra
842 prints all settings beginning with fra that can be toggled
844 complete_shell POSITION [COMMAND ARGS ...]
846 Behaves like complete with the following extras, useful for
847 completion on posix shells:
848 • Escape sequences are removed in COMMAND and ARGS.
850 • A space is appended to each full completion result.
852 • Special characters will be escaped in the output.
854 emit_hook NAME ARGS ...
856 Emits a custom hook NAME to all idling herbstclients.
857 tag_status [MONITOR]
859 Print a tab separated list of all tags for the specified MONITOR
860 index. If no MONITOR index is given, the focused monitor is used.
861 Each tag name is prefixed with one char, which indicates its state:
862 • . the tag is empty
864 • : the tag is not empty
866 • + the tag is viewed on the specified MONITOR, but this monitor
868 is not focused.
869 • # the tag is viewed on the specified MONITOR and it is focused.
871 • - the tag is viewed on a different MONITOR, but this monitor is
873 not focused.
874 • % the tag is viewed on a different MONITOR and it is focused.
876 • ! the tag contains an urgent window
878 Warning
880 If you use a tab in one of the tag names, then tag_status is
881 probably quite useless for you.
882 floating [[TAG] on|off|toggle|status]
884 Changes specified TAG to floating/tiling mode or prints its current
885 status. If no TAG is given, the current tag is used. If no argument
886 is given, floating mode is toggled. If status is given, then on or
887 off is printed, depending of the floating state of TAG.
888 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
890 Defines a rule which will be applied to all new clients. Its
891 behaviour is described in the RULES section.
892 unrule LABEL|--all|-F
894 Removes all rules named LABEL. If --all or -F is passed, then all
895 rules are removed.
896 apply_rules WINID|--all
898 Apply the rules to the specified window WINID. If --all is passed,
899 then the rules are applied to all clients.
900 apply_tmp_rule WINID|--all [RULEDESCRIPTION...]
902 Apply the rule RULEDESCRIPTION to one particular client WINID or
903 all clients (--all) without adding the rule to the rule list. The
904 RULEDESCRIPTION specifies a rule consisting of conditions and
905 consequences as one would pass it to the rule command as described
906 in the RULES section. This allows testing rules before adding them.
907 Running apply_tmp_rule only applies the particular rule given in
908 the arguments and ignores the existing rules.
909 fullscreen [on|off|toggle]
911 Sets or toggles the fullscreen state of the focused client. If no
912 argument is given, fullscreen mode is toggled.
913 pseudotile [on|off|toggle]
915 Sets or toggles the pseudotile state of the focused client. If a
916 client is pseudotiled, then in tiling mode the client is only moved
917 but not resized - the client size will stay the floating size. The
918 only reason to resize the client is to ensure that it fits into its
919 tile. If no argument is given, pseudotile mode is toggled.
920 object_tree [PATH]
922 Prints the tree of objects. If the object path PATH is given, only
923 the subtree starting at PATH is printed. See the OBJECTS section
924 for more details.
925 attr [PATH [NEWVALUE]
927 Prints the children and attributes of the given object addressed by
928 PATH. If PATH is an attribute, then print the attribute value. If
929 NEWVALUE is given, assign NEWVALUE to the attribute given by PATH.
930 See the OBJECTS section for more details.
931 get_attr ATTRIBUTE
933 Print the value of the specified ATTRIBUTE as described in the
934 OBJECTS section.
935 set_attr ATTRIBUTE NEWVALUE
937 Assign NEWVALUE to the specified ATTRIBUTE as described in the
938 OBJECTS section.
939 attr_type ATTRIBUTE
941 Print the type of the specified ATTRIBUTE.
942 new_attr bool|color|int|string|uint PATH [VALUE]
944 Creates a new attribute with the name and in the object specified
945 by PATH. Its type is specified by the first argument. The attribute
946 name has to begin with my_. If VALUE is supplied, then it is
947 written to the attribute (if this fails the attribute still
948 remains).
949 watch PATH
951 Watch the value of the given attribute PATH. Whenever the value
952 changes from OLDVALUE to NEWVALUE, a hook is emitted:
953 attribute_changed PATH OLDVALUE NEWVALUE
955 remove_attr PATH
957 Removes the user defined attribute PATH.
958 substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
960 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
961 ARGS by the value of the ATTRIBUTE. Note that the COMMAND also is
962 replaced by the attribute value if it equals IDENTIFIER. The
963 replaced command with its arguments then is executed. Example:
964 • substitute MYTITLE clients.focus.title echo MYTITLE
966 Prints the title of the currently focused window.
968 sprintf IDENTIFIER FORMAT [FORMATARG ...] COMMAND [CMDARGS ...]
970 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
971 CMDARGS by the string specified by FORMAT. The FORMAT string may
972 contain several placeholders, similar to the printf(1) command:
973 • %s inserts an attribute value whose path is given by the string
975 value of the next FORMATARG
976 • %c ("constant") inserts the next FORMATARG without
978 modification.
979 • %{ATTR} inserts the current value of the attribute ATTR. The
981 path ATTR can itself contain format placeholders. This can be
982 used to compose attribute paths at run time, e.g. in a foreach
983 loop.
984 • %% stands for a plain %
986 The replaced command with its arguments then is executed. Examples:
988 • sprintf STR title=%s clients.focus.title echo STR
990 Prints the title of the currently focused window prepended by
992 title=.
993 • sprintf X "%c %s tags" "there are" tags.count echo X
995 Prints there are N tags with N replaced by the number of tags.
997 • sprintf X tag=%s tags.focus.name rule once X
999 Moves the next client that appears to the tag that is currently
1001 focused.
1002 • sprintf X %s/%s tags.focus.index tags.count echo X
1004 Tells which tag is focused and how many tags there are
1006 • sprintf l somelongstring echo l l l
1008 Prints somelongstring three times, separated by spaces.
1010 • sprintf VALUE "%{%c.client_count}" tags.0 echo VALUE
1012 Prints the number of clients on the tag with index 0
1014 • foreach --filter-name="[0-9]*" T tags. sprintf S
1016 "%{%c.client_count}" T echo T S
1017 Prints the number of clients for each tag.
1019 • substitute X tags.count sprintf Y "number=%c" X echo Y
1021 has the same output as
1023 sprintf Y "number=%s" tags.count echo Y
1025 (Note how the %c changes to %s)
1027 foreach IDENTIFIER OBJECT [--recursive] [--unique]
1029 [--filter-name=REGEX] COMMAND [ARGS ...]
1030 For each child of the given OBJECT the COMMAND is called with its
1031 ARGS, where the IDENTIFIER is replaced by the path of the child.
1032 The options are:
1033 • --filter-name=REGEX consider children whose name match the
1035 specified REGEX.
1036 • --unique do not print duplicates (some objects can be reached
1038 via multiple paths, such as clients.focus)
1039 • --recursive print OBJECT and all its children of arbitrary
1041 depth in breadth-first search order. This implicitly activates
1042 --unique.
1043 The exit code is the exit code of the command executed last.
1045 Examples:
1046 • foreach T tags.by-name. echo T
1048 Prints:
1050 tags.by-name.1
1052 tags.by-name.2
1053 tags.by-name.3
1054 [...]
1055 • Note that foreach only iterates over children, but not over
1057 attributes, so foreach S settings echo S prints nothing, since
1058 the settings object has only attributes but no child objects.
1059 • foreach C clients. echo C prints the object paths of all
1061 clients, but the focused client twice, because it is mentioned
1062 in clients. twice: by window id and as clients.focus.
1063 • foreach F tags.focus.tiling.root. --recursive echo F prints the
1065 object paths of all frames on the focused tag.
1066 mktemp [bool|int|string|uint] IDENTIFIER COMMAND [ARGS ...]
1068 Creates a temporary attribute with the given type and replaces all
1069 occurrences of IDENTIFIER in COMMAND and ARGS by the path of the
1070 temporary attribute. The replaced command with its arguments is
1071 executed then. The exit status of COMMAND is returned.
1072 compare ATTRIBUTE OPERATOR VALUE
1074 Compares the value of ATTRIBUTE with VALUE using the comparison
1075 method OPERATOR. If the comparison succeeds, it returns 0, else 1.
1076 The operators are:
1077 • =: ATTRIBUTE's value equals VALUE
1079 • !=: ATTRIBUTE's value does not equal VALUE
1081 • le: ATTRIBUTE's value <= VALUE
1083 • lt: ATTRIBUTE's value < VALUE
1085 • ge: ATTRIBUTE's value >= VALUE
1087 • gt: ATTRIBUTE's value > VALUE
1089 The OPERATORs le,lt,ge,gt can only be used if ATTRIBUTE is of the
1091 type integer or unsigned integer. Note that the first parameter
1092 must always be an attribute and the second a constant value. If you
1093 want to compare two attributes, use the substitute command:
1094 substitute FC tags.focus.frame_count \
1096 compare tags.focus.client_count gt FC
1097 It returns success if there are more clients on the focused tag
1099 than frames.
1100 getenv NAME
1102 Gets the value of the environment variable NAME.
1103 setenv NAME VALUE
1105 Set the value of the environment variable NAME to VALUE. See the
1106 export command for a convenience wrapper.
1107 unsetenv NAME
1109 Unsets the environment variable NAME.
1110 export NAME=VALUE
1112 Set the value of the environment variable NAME to VALUE. The syntax
1113 is the same as for export in unix shells (notice that there is a
1114 =). Intuitively, if you forgot to run export FOO=BAR before
1115 starting herbstluftwm, you can run herbstclient export FOO=BAR from
1116 within your herbstluftwm session for the same effect. The export
1117 command is the same as the setenv command with different syntax.
1118
1120 Rules are used to change default properties for certain clients when
1121 they appear or when the apply_rules command is called. Each rule
1122 matches against a certain subset of all clients and defines a set of
1123 properties for them (called CONSEQUENCEs). A rule can be defined with
1124 this command:
1125 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
1127 Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
1129 optionally, a LABEL. (each of them can be optionally prefixed with two
1130 dashes (--) to provide a more iptables(8)-like feeling).
1131 Each rule can be given a custom label by specifying the LABEL property:
1133 • [--]label=VALUE
1135 If multiple labels are specified, the last one in the list will be
1137 applied. If no label is given, then the rule will be given an integer
1138 name that represents the index of the rule since the last unrule -F
1139 command (which is triggered in the default autostart).
1140 Tip
1142 Rule labels default to an incremental index. These default labels
1143 are unique, unless you assign a different rule a custom integer
1144 LABEL. Default labels can be captured with the printlabel flag.
1145 If a new client appears, herbstluftwm tries to apply each rule to this
1147 new client as follows: If each CONDITION of this rule matches against
1148 this client, then every CONSEQUENCE is executed. (If there are no
1149 conditions given, then this rule is executed for each client)
1150 Each CONDITION consists of a property name, an operator and a value.
1152 Valid operators are:
1153 • ~ matches if client’s property is matched by the regex value.
1155 • = matches if client’s property string is equal to value.
1157 Valid properties are:
1159 instance
1161 the first entry in client’s WM_CLASS.
1162 class
1164 the second entry in client’s WM_CLASS.
1165 title
1167 client’s window title.
1168 pid
1170 the client’s process id (Warning: the pid is not available for
1171 every client. This only matches if the client sets _NET_WM_PID to
1172 the pid itself).
1173 pgid
1175 this client’s process group id. Since the pgid of a window is
1176 derived from its pid the same restrictions apply as above.
1177 maxage
1179 matches if the age of the rule measured in seconds does not exceed
1180 value. This condition only can be used with the = operator. If
1181 maxage already is exceeded (and never will match again), then this
1182 rule is removed. (With this you can build rules that only live for
1183 a certain time.)
1184 windowtype
1186 matches the _NET_WM_WINDOW_TYPE property of a window. If
1187 _NET_WM_WINDOW_TYPE has multiple entries, then only the first entry
1188 is used here.
1189 windowrole
1191 matches the WM_WINDOW_ROLE property of a window if it is set by the
1192 window.
1193 fixedsize (no parameter)
1195 matches if the window does not allow being resized (i.e. if the
1196 minimum size matches the maximum size). This condition does not
1197 take a parameter. Example:
1198 hc rule fixedsize floating=on
1201 Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:
1203 tag
1205 moves the client to tag VALUE.
1206 monitor
1208 moves the client to the tag on monitor VALUE. If the tag
1209 consequence was also specified, and switchtag is set for the
1210 client, move the client to that tag, then display that tag on
1211 monitor VALUE. If the tag consequence was specified, but switchtag
1212 was not, ignore this consequence.
1213 focus
1215 decides whether the client gets the input focus in its tag. The
1216 default is off. VALUE is a boolean (on or off).
1217 switchtag
1219 if focus is activated and the client is put to a not focused tag,
1220 then switchtag tells whether the client’s tag will be shown or not.
1221 If the tag is shown on any monitor but is not focused, the client’s
1222 tag only is brought to the current monitor if
1223 swap_monitors_to_get_tag is activated. VALUE is a boolean (on or
1224 off).
1225 manage
1227 decides whether the client will be managed or not. The default is
1228 on. VALUE is a boolean (on or off).
1229 index
1231 moves the window to a specified index in the tree. VALUE is a
1232 frame index.
1233 floating
1235 sets the floating state of the client. VALUE is a boolean.
1236 pseudotile
1238 sets the pseudotile state of the client. VALUE is a boolean.
1239 ewmhrequests
1241 sets whether the window state (the fullscreen state and the demands
1242 attention flag) can be changed by the application via ewmh itself.
1243 This does not affect the initial fullscreen state requested by the
1244 window. VALUE is a boolean; it defaults to on.
1245 ewmhnotify
1247 sets whether hlwm should let the client know about EMWH changes
1248 (currently only the fullscreen state). If this is set, applications
1249 do not change to their fullscreen-mode while still being
1250 fullscreen. VALUE is a boolean, it defaults to on.
1251 fullscreen
1253 sets the fullscreen flag of the client. VALUE is a boolean.
1254 hook
1256 emits the custom hook rule VALUE WINID when this rule is triggered
1257 by a new window with the id WINID. This consequence can be used
1258 multiple times, which will cause a hook to be emitted for each
1259 occurrence of a hook consequence.
1260 keymask
1262 sets the keymask for a client (see the keymask attribute
1263 documentation).
1264 keys_inactive
1266 sets a regex that determines which key bindings are inactive for a
1267 client (see the keys_inactive attribute documentation).
1268 floatplacement
1270 changes the floating position of a window. The VALUE can be one of
1271 the following:
1272 • none does not change the placement at all
1274 • center centers the window on the monitor
1276 • smart tries to place it with as little overlap to other
1278 floating windows as possible. If there are multiple options
1279 with the least overlap, then the position with the least
1280 overlap to tiling windows is chosen.
1281 floating_geometry
1283 Sets the client’s floating_geometry attribute. The VALUE is a
1284 rectangle, interpreted relatively to the monitor. If floatplacement
1285 is also specified for the client (possibly by another rule), then
1286 only the size of the floating_geometry is used. In order to force
1287 the position from the geometry, it is necessary to add
1288 floatplacement=none.
1289 A rule’s behaviour can be configured by some special FLAGS:
1291 • not: negates the next CONDITION.
1293 • !: same as not.
1295 • once: only apply this rule once (and delete it afterwards).
1297 • printlabel: prints the label of the newly created rule to stdout.
1299 • prepend: prepend the rule to the list of rules instead of appending
1301 it. So its consequences may be overwritten by already existing
1302 rules.
1303 Examples:
1305 • rule --class=Netscape --tag=6 --focus=off
1307 Moves all Netscape instances to tag 6, but doesn’t give focus to
1309 them.
1310 • rule not class~.*[Tt]erm tag=2
1312 Moves all clients to tag 2, if their class does not end with term
1314 or Term.
1315 • rule class=Thunderbird index=/0
1317 Insert all Thunderbird instances in the tree that has no focus and
1319 there in the first child.
1320 • rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
1322 Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE
1324 correctly.
1325
1327 Several commands accept a window as reference, e.g. close. The syntax
1328 is as follows:
1329 • an empty string — or missing argument — references the currently
1331 focused window.
1332 • urgent references some window that is urgent.
1334 • 0xHEXID — where HEXID is some hexadecimal number — references the
1336 window with hexadecimal X11 window id HEXID.
1337 • longest-minimized references the minimized window on the focused
1339 tag that has been minimized for the longest time.
1340 • latest-minimized references the minimized window on the focused tag
1342 that has been minimized most recently.
1343 • DECID — where DECID is some decimal number — references the window
1345 with the decimal X11 window id DECID.
1346
1348 The object tree is a collection of objects with attributes similar to
1349 /sys known from the Linux kernel. Many entities (like tags, monitors,
1350 clients, ...) have objects to access their attributes directly. The
1351 tree is printed by the object_tree command and looks more or less as
1352 follows:
1353 $ herbstclient object_tree
1355 ╾─┐
1356 ├─┐ tags
1357 │ ├─┐ by-name
1358 │ │ ├─╼ 1
1359 │ │ ...
1360 │ │ └─╼ 9
1361 │ └─╼ focus
1362 ├─┐ clients
1363 │ ├─╼ 0x1400022
1364 │ └─╼ focus
1365 └─┐ monitors
1366 ├─╼ by-name
1367 └─╼ focus
1368 To print a subtree starting at a certain object, pass the PATH of the
1370 object to object_tree. The object PATH is the path using the separator
1371 . (dot), e.g. tags.by-name:
1372 $ herbstclient object_tree tags.by-name.
1374 ╾─┐ tags.by-name.
1375 ├─╼ 1
1376 ├─╼ 2
1377 ...
1378 └─╼ 9
1379 To query all attributes and children of a object, pass its PATH to
1381 attr:
1382 $ herbstclient attr tags.
1384 2 children:
1385 by-name.
1386 focus.
1387 1 attributes:
1389 .---- type
1390 | .-- writable
1391 V V
1392 u - count = 9
1393 $ herbstclient attr tags.focus.
1395 0 children.
1396 6 attributes:
1397 .---- type
1398 | .-- writable
1399 V V
1400 s w name = "1"
1401 b w floating = false
1402 i - frame_count = 2
1403 i - client_count = 1
1404 i - curframe_windex = 0
1405 i - curframe_wcount = 1
1406 This already gives an intuition of the output: attr first lists the
1408 names of the child objects and then all attributes, telling for each
1409 attribute:
1410 • its type
1412 • b for boolean
1414 • c for color
1416 • i for integer
1418 • r for regex
1420 • s for string
1422 • u for unsigned integer
1424 • if it is writable by the user: w if yes, - else.
1426 • the name of the attribute
1428 • its current value (only quoted for strings)
1430 To get the unquoted value of a certain attribute, address the attribute
1432 using the same syntax as for object paths and pass it to attr or
1433 get_attr:
1434 $ herbstclient attr clients.focus.title
1436 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1437 $ herbstclient get_attr clients.focus.title
1438 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1439 To change a writable attribute value pass the new value to attr or to
1441 set_attr:
1442 $ herbstclient attr tags.focus.floating
1444 false
1445 $ herbstclient attr tags.focus.floating true
1446 $ herbstclient attr tags.focus.floating
1447 true
1448 $ herbstclient set_attr tags.focus.floating false
1449 $ herbstclient attr tags.focus.floating
1450 false
1451 More information on an attribute or object is given by the help
1453 command:
1454 $ herbstclient help clients.focus
1456 Just look around to get a feeling what is there. The entry point is a
1458 root object that has the following child objects:
1459 autostart:
1461 • string global_path = globalAutostart: Path of the system-wide
1462 autostart, used as a fallback.
1463 • int last_status = 0: the exit status of the last autostart run. if
1465 the autostart is still running, then this status corresponds to the
1466 exit status of the previous autostart invocation.
1467 • string path = autostartFromCmdLine: Custom path to the user’s
1469 autostart path. If it is empty, then the autostart in
1470 $XDG_CONFIG_HOME or $HOME is used.
1471 • uint pid = 0: the process id of the last autostart invocation. Even
1473 if the autostart is not running anymore, its pid is still present
1474 here.
1475 • bool running = false: whether the autostart process (with pid) is
1477 still running.
1478 clients:
1480 The managed windows. For every (managed) window id there is an entry
1481 here.
1482 • dragged: the object of a client which is currently dragged by the
1484 mouse, if any. See the documentation of the mousebind command for
1485 examples. For attributes and children, see clients.focus
1486 • focus: the focused client (only exists if a client is focused). a
1488 managed window
1489 • string class: the class of it (second entry in WM_CLASS)
1491 • Rectangle content_geometry: the geometry of the application
1493 content, that is, not taking the decoration into account. Also,
1494 this is the last window geometry that was reported to the
1495 client application.
1496 • bool decorated = true: whether window border and title are
1498 drawn
1499 • Rectangle decoration_geometry: the geometry of the client,
1501 taking the window decoration into account. The position is the
1502 global window position, that is, relative to the top left
1503 corner of the entire screen
1504 • bool ewmhnotify = true: if the client is told about its state
1506 via ewmh
1507 • bool ewmhrequests = true: if ewmh requests are permitted for
1509 this client
1510 • bool floating = false: whether this client is set as a
1512 (single-window) floating client. If set, the client is floated
1513 above the tiled clients.
1514 • bool floating_effectively = false: whether this client is in
1516 the floating state currently. This is the case if the client’s
1517 tag is set to floating mode or if the client itself is set as
1518 floating. Its value is also indicated via the X11 properties
1519 HLWM_FLOATING_WINDOW and HLWM_TILING_WINDOW.
1520 • Rectangle floating_geometry = 0: the geometry of the client
1522 content if the client is in floating mode. The position is
1523 relative to the monitor and does not take the window decoration
1524 into account.
1525 • bool fullscreen = false: whether this client covers all other
1527 windows and panels on its monitor.
1528 • string instance: the instance of it (first entry in WM_CLASS)
1530 • regex keymask = "": A regular expression that is matched
1532 against the string representation of all key bindings (as they
1533 are printed by list_keybinds). While this client is focused,
1534 only bindings that match the expression will be active. Any
1535 other bindings will be disabled. The default keymask is an
1536 empty string (), which does not disable any keybinding.
1537 • regex keys_inactive = "": A regular expression that describes
1539 which keybindings are inactive while the client is focused. If
1540 a key combination is pressed and its string representation (as
1541 given by list_keybinds) matches the regex, then the key press
1542 is propagated to the client.
1543 • bool minimized = false: whether this client is minimized (also
1545 called iconified).
1546 • int pgid = -1
1548 • int pid = -1: the process id of it (-1 if unset).
1550 • bool pseudotile = false: if activated, the client always has
1552 its floating window size, even if it is in tiling mode.
1553 • bool sizehints_floating = true: if sizehints for this client
1555 should be respected in floating mode
1556 • bool sizehints_tiling = false: if sizehints for this client
1558 should be respected in tiling mode
1559 • string tag: the name of the tag it’s currently on.
1561 • string title = "": its window title
1563 • bool urgent = false: the urgency state (also known as: demands
1565 attention). The focused client can not be urgent.
1566 • bool visible = visible_already: whether this client is rendered
1568 currently
1569 • string winid = "": its window id (as a hexadecimal number with
1571 0x prefix)
1572 • parent_frame: the frame contaning this client if the client is
1574 tiled. For attributes and children, see tags.focus.tiling.root
1575 monitors:
1577 Every monitor is a rectangular part of the screen on which a tag is
1578 shown. These monitors may or may not match the actual outputs. This has
1579 an entry INDEX for each monitor with index INDEX.
1580 • uint count
1582 • by-name: This has an entry name for every object with the given
1584 name. If an object has an empty name then it is not listed here.
1585 • focus: the focused monitor. The monitor is a rectangular part on
1587 the screen that holds precisely one tag at a time. The pad
1588 attributes reserve space on the monitor’s edge for panels, so this
1589 space (given in number of pixels) is never occupied by tiled
1590 clients.
1591 • Rectangle content_geometry: the inner geometry of the monitor,
1593 i.e. the geometry with the pads deducted from all sides. This
1594 is the area floating and tiled client windows are placed.
1595 • Rectangle geometry = rect_: the outer geometry of the monitor
1597 • uint index = 0: the monitor’s index (starts at index 0)
1599 • bool lock_tag = false: if activated, then it it is not possible
1601 to switch this monitor to a different tag.
1602 • string name = "": the monitor’s name (can be empty)
1604 • int pad_down = 0: space for panels at the monitor’s lower edge
1606 • int pad_left = 0: space for panels at the monitor’s left edge
1608 • int pad_right = 0: space for panels at the monitor’s right edge
1610 • int pad_up = 0: space for panels at the monitor’s upper edge
1612 • string tag: the name of the tag viewed here
1614 panels:
1616 For every panel window, there is an entry with the panel’s window id
1617 here.
1618 • uint count
1620 • 0xWindowID: a panel is an unmanaged window that reserves space at
1622 the edge of the monitor it is on. The space depends on the
1623 _NET_WM_STRUT defined by the panel. If it is however not defined
1624 explicitly, then the amount of reserved space is inferred from the
1625 window geometry.
1626 • string class: the window class (second entry of WM_CLASS)
1628 • Rectangle geometry: the size and position of the window
1630 • string instance: the window instance (first entry of WM_CLASS)
1632 • WindowID winid = winid: the ID of the panel window
1634 settings:
1636 Settings configure the general behaviour of herbstluftwm and can be
1637 controlled via the set, get and toggle commands. The settings. object
1638 has an attribute for each setting. Many settings are wrappers around
1639 attributes and only remain for compatibility.
1640 • bool always_show_frame = false: DEPRECATED, use
1642 show_frame_decorations instead. Setting this corresponds to focused
1643 in show_frame_decorations.
1644 • bool auto_detect_monitors = false: If set, detect_monitors is
1646 automatically executed every time a monitor is connected,
1647 disconnected or resized.
1648 • bool auto_detect_panels = true: If set, EWMH panels are
1650 automatically detected and reserve space at the side of the
1651 monitors they are on (via pad attributes of each monitor). This
1652 setting is activated per default.
1653 • bool default_direction_external_only = false: This setting controls
1655 the behaviour of focus and shift if no -e or -i argument is given.
1656 If set, then focus and shift changes the focused frame even if
1657 there are other clients in this frame in the specified DIRECTION.
1658 Else, a client within current frame is selected if it is in the
1659 specified DIRECTION.
1660 • LayoutAlgorithm default_frame_layout = vertical: Name of the layout
1662 algorithm, which is used if a new frame is created (on a new tag or
1663 by a non-trivial split). See above for the list of layout
1664 algorithms.
1665 • string ellipsis = ...: string to append when window or tab titles
1667 are shortened to fit in the available space.
1668 • bool focus_crosses_monitor_boundaries = true: If set, commands
1670 focus and shift cross monitor boundaries. If there is no client in
1671 the direction given to focus, then the monitor in the specified
1672 direction is focused. Similarly, if shift cannot move a window
1673 within a tag, the window is moved to the neighbour monitor in the
1674 desired direction.
1675 • bool focus_follows_mouse = false: If set and a window is focused by
1677 mouse cursor, this window is focused (this feature is also known as
1678 sloppy focus). If unset, you need to click to change the window
1679 focus by mouse.
1680 If another window is hidden by the focus change (e.g. when having
1683 pseudotiled windows in the max layout) then an extra click is
1684 required to change the focus.
1685 • bool focus_stealing_prevention = true: If set, only pagers and
1687 taskbars are allowed to change the focus. If unset, all
1688 applications can request a focus change.
1689 • int frame_active_opacity = 100: Focused frame opacity in percent.
1691 Requires a running compositing manager to take actual effect.
1692 • color frame_bg_active_color = black: The fill color of a focused
1694 frame.
1695 • color frame_bg_normal_color = black: The fill color of an unfocused
1697 frame (It is only visible if non-focused frames are configured to
1698 be visible, see show_frame_decorations).
1699 • bool frame_bg_transparent = false: If set, the background of frames
1701 are transparent. That means a rectangle is cut out from the inner
1702 such that only the frame border and a stripe of width
1703 frame_transparent_width can be seen. Use frame_active_opacity and
1704 frame_normal_opacity for real transparency.
1705 • color frame_border_active_color = red: The border color of a
1707 focused frame.
1708 • color frame_border_inner_color = black: The color of the inner
1710 border of a frame.
1711 • int frame_border_inner_width = 0: The width of the inner border of
1713 a frame. Must be less than frame_border_width, since it does not
1714 add to the frame border width but is a part of it.
1715 • color frame_border_normal_color = blue: The border color of an
1717 unfocused frame.
1718 • int frame_border_width = 2: Border width of a frame.
1720 • int frame_gap = 5: The gap between frames in the tiling mode.
1722 • int frame_normal_opacity = 100: Unfocused frame opacity in percent.
1724 Requires a running compositing manager to take actual effect.
1725 • int frame_padding = 0: The padding within a frame in the tiling
1727 mode, i.e. the space between the border of a frame and the windows
1728 within it.
1729 • int frame_transparent_width = 0: Specifies the width of the
1731 remaining frame colored with frame_bg_active_color if
1732 frame_bg_transparent is set.
1733 • bool gapless_grid = true: This setting affects the size of the last
1735 client in a frame that is arranged by grid layout. If set, then the
1736 last client always fills the gap within this frame. If unset, then
1737 the last client has the same size as all other clients in this
1738 frame.
1739 • bool hide_covered_windows = false: If activated, windows are
1741 explicitly hidden when they are covered by another window in a
1742 frame with max layout. This only has a visible effect if a
1743 compositor is used. If activated, shadows do not stack up and
1744 transparent windows show the wallpaper behind them instead of the
1745 other clients in the max layout.
1746 • uint monitors_locked = 0: If greater than 0, then the clients on
1748 all monitors aren’t moved or resized anymore. If it is set to 0,
1749 then the arranging of monitors is enabled again, and all monitors
1750 are rearranged if their content has changed in the meantime. You
1751 should not change this setting manually due to concurrency issues;
1752 use the commands lock and unlock instead.
1753 • int mouse_recenter_gap = 0: Specifies the gap around a monitor. If
1755 the monitor is selected and the mouse position would be restored
1756 into this gap, it is set to the center of the monitor. This is
1757 useful, when the monitor was left via mouse movement, but is
1758 reselected by keyboard. If the gap is 0 (default), the mouse is
1759 never recentered.
1760 • int pseudotile_center_threshold = 10: If greater than 0, it
1762 specifies the least distance between a centered pseudotile window
1763 and the border of the frame or tile it is assigned to. If this
1764 distance is lower than pseudotile_center_threshold, it is aligned
1765 to the top left of the client’s tile.
1766 • bool raise_on_click = true: If set, a window is raised if it is
1768 clicked. The value of this setting is only noticed in floating
1769 mode.
1770 • bool raise_on_focus = false: If set, a window is raised if it is
1772 focused. The value of this setting is only used in floating mode.
1773 • bool raise_on_focus_temporarily = false: If set, a window is raised
1775 temporarily if it is focused on its tag. Temporarily in this case
1776 means that the window will return to its previous stacking position
1777 if another window is focused.
1778 • ShowFrameDecorations show_frame_decorations = focused_if_multiple:
1780 This controls, which frame decorations are shown at all.
1781 • none shows no frame decorations at all,
1783 • nonempty shows decorations of frames that have client windows,
1785 • if_multiple shows decorations on the tags with at least two
1787 frames,
1788 • if_empty shows decorations of frames that have no client
1790 windows,
1791 • focused shows the decoration of focused and nonempty frames,
1793 • focused_if_multiple shows decorations of focused and non-empty
1795 frames on tags with at least two frames.
1796 • SmartFrameSurroundings smart_frame_surroundings = off: If set to
1798 hide_all, frame borders and gaps will be removed when there is no
1799 ambiguity regarding the focused frame. If set to hide_gaps, only
1800 frame gaps will be removed when there is no ambiguity regarding the
1801 focused frame. Turn off to always show frame borders and gaps.
1802 • bool smart_window_surroundings = false: If set, window borders and
1804 gaps will be removed and minimal when there’s no ambiguity
1805 regarding the focused window. This minimal window decoration can be
1806 configured by the theme.minimal object.
1807 • int snap_distance = 10: If a client is dragged in floating mode,
1809 then it snaps to neighbour clients if the distance between them is
1810 smaller than snap_distance.
1811 • int snap_gap = 5: Specifies the remaining gap if a dragged client
1813 snaps to an edge in floating mode. If snap_gap is set to 0, no gap
1814 will remain.
1815 • bool swap_monitors_to_get_tag = true: If set: If you want to view a
1817 tag, that already is viewed on another monitor, then the monitor
1818 contents will be swapped and you see the wanted tag on the focused
1819 monitor. If not set, the other monitor is focused if it shows the
1820 desired tag.
1821 • bool tabbed_max = true: if activated, multiple windows in a frame
1823 with the max layout algorithm are drawn as tabs.
1824 • string tree_style = "*| +`--.": It contains the chars that are used
1826 to print a nice ascii tree. It must contain at least 8 characters.
1827 e.g. X|:#+*-. produces a tree like:
1828 X-.
1830 #-. child 0
1831 | #-* child 00
1832 | +-* child 01
1833 +-. child 1
1834 : #-* child 10
1835 : +-* child 11
1836 Useful values for tree_style are: ╾│ ├└╼─┐ or -| |'--. or ╾│
1838 ├╰╼─╮.
1839 • bool update_dragged_clients = false: If set, a client's window
1841 content is resized immediately during resizing it with the mouse.
1842 If unset, the client's content is resized after the mouse button is
1843 released.
1844 • bool verbose = false: If set, verbose output is logged to
1846 herbstluftwm’s stderr. The default value is controlled by the
1847 --verbose command line flag.
1848 • color window_border_active_color: Border color of a focused window.
1850 Warning: This only exists for compatibility reasons; it is only an
1853 alias for the attribute theme.active.color.
1854 • color window_border_inner_color: Color of the inner border of a
1856 window. Warning: This only exists for compatibility reasons; it is
1857 only an alias for the attribute theme.inner_color.
1858 • int window_border_inner_width: The width of the inner border of a
1860 window. Must be less than window_border_width, since it does not
1861 add to the window border width but is a part of it.
1862 Warning: This only exists for compatibility reasons; it is only an
1865 alias for the attribute theme.inner_width.
1866 • color window_border_normal_color: Border color of an unfocused
1868 window.
1869 Warning: This only exists for compatibility reasons; it is only an
1872 alias for the attribute theme.normal.color.
1873 • color window_border_urgent_color: Border color of an unfocused but
1875 urgent window.
1876 Warning: This only exists for compatibility reasons; it is only an
1879 alias for the attribute theme.urgent.color.
1880 • int window_border_width: Border width of a window.
1882 Warning: This only exists for compatibility reasons; it is only an
1885 alias for the attribute theme.border_width.
1886 • int window_gap = 0: The gap between windows within one frame in the
1888 tiling mode.
1889 • string wmname = herbstluftwm: It controls the value of the
1891 _NET_WM_NAME property on the root window, which specifies the name
1892 of the running window manager. The value of this setting is not
1893 updated if the actual _NET_WM_NAME property on the root window is
1894 changed externally. Example usage:
1895 • cycle_value wmname herbstluftwm LG3D
1899 tags:
1901 The tags (or virtual desktops or workspaces). This contains an entry
1902 index for each tag with the given index.
1903 • uint count
1905 • by-name: For attributes and children, see monitors.by-name
1907 • focus: the object of the focused tag, equivalently, the tag on the
1909 focused monitor.
1910 • bool at_end = false: all tags with this property activated will
1913 be kept at the end of the tag list. Usually, this property is
1914 set for special purpose tags like scratchpads.
1915 • int client_count: the number of clients on this tag
1917 • int curframe_wcount: number of clients in the selected frame
1919 • int curframe_windex: index of the focused client in the
1921 selected frame
1922 • bool floating = false: if the entire tag is set to floating
1924 mode
1925 • bool floating_focused = false: if the floating layer is focused
1927 (otherwise the tiling layer is)
1928 • int frame_count: the number of frames on this tag
1930 • uint index = 0: index of this tag (the first index is 0)
1932 • string name = name_: name of the tag (must be non-empty)
1934 • int urgent_count: the number of urgent clients on this tag
1936 • bool visible = false: if this tag is shown on some monitor
1938 • focused_client: For attributes and children, see clients.focus
1940 • tiling:
1942 • focused_frame: The focused frame (leaf) in this frame tree.
1945 For attributes and children, see tags.focus.tiling.root
1946 • root can be a frame leaf.
1948 • LayoutAlgorithm algorithm
1951 • int client_count
1953 • Rectangle content_geometry: the geometry of the frame’s
1955 contents, i.e. of the area filled by child frames or
1956 client windows.
1957 • string index: A string containing only 0 and 1 that
1959 describes the position of the frame in the tree. The
1960 empty string denotes the root frame. Appending 0
1961 (respectively 1) to a frame index yields the frame
1962 index of the first (respectively second) subtree.
1963 • int selection
1965 • root can be a frame split.
1967 • Rectangle content_geometry: the geometry of the frame’s
1970 contents, i.e. of the area filled by child frames or
1971 client windows.
1972 • decimal fraction
1974 • string index: A string containing only 0 and 1 that
1976 describes the position of the frame in the tree. The
1977 empty string denotes the root frame. Appending 0
1978 (respectively 1) to a frame index yields the frame
1979 index of the first (respectively second) subtree.
1980 • int selection
1982 • SplitAlign split_type
1984 • 0 can be a frame leaf. For attributes and children, see
1986 tags.focus.tiling.root
1987 • 0 can be a frame split. For attributes and children,
1989 see tags.focus.tiling.root
1990 • 1 can be a frame leaf. For attributes and children, see
1992 tags.focus.tiling.root
1993 • 1 can be a frame split. For attributes and children,
1995 see tags.focus.tiling.root
1996 theme:
1998 inner_color/inner_width
1999 ╻ outer_color/outer_width
2000 │ ╻
2001 │ │
2002 ┌────╴│╶─────────────────┷─────┐ ⎫ border_width
2003 │ │ color │ ⎬ + title_height + title_depth
2004 │ ┌──┷─────────────────────┐ │ ⎭ + padding_top
2005 │ │====================....│ │
2006 │ │== window content ==....│ │
2007 │ │====================..╾──────── background_color
2008 │ │........................│ │
2009 │ └────────────────────────┘ │ ⎱ border_width +
2010 └──────────────────────────────┘ ⎰ padding_bottom
2011 Setting an attribute of the theme object just propagates the value to
2013 the respective attribute of the tiling and the floating object. If the
2014 title area is divided into tabs, then the not selected tabs can be
2015 styled using the tab_... attributes. If these attributes are empty,
2016 then the colors are taken from the theme of the client to which the tab
2017 refers to.
2018 • color background_color = black: color behind window contents
2020 visible on resize
2021 • uint border_width = 0: the base width of the border
2023 • color color = black: the basic background color of the border
2025 • color inner_color = black: color of the inner border
2027 • uint inner_width = 0: width of the border around the clients
2029 content
2030 • color outer_color = black: color of the outer border
2032 • uint outer_width = 0: width of an border close to the edge
2034 • uint padding_bottom = 0: additional border width on the bottom
2036 • uint padding_left = 0: additional border width on the left
2038 • uint padding_right = 0: additional border width on the right
2040 • uint padding_top = 0: additional border width on the top
2042 • string reset: writing this resets all attributes to a default value
2044 • MaybeColor tab_color = Inherit: if non-empty, the color of
2046 non-urgent and unfocused tabs
2047 • MaybeColor tab_outer_color = Inherit: if non-empty, the outer
2049 border color of non-urgent and unfocused tabs; if empty, the colors
2050 are taken from the tab’sclient decoration settings.
2051 • MaybeULong tab_outer_width = Inherit: if non-empty, the outer
2053 border width of non-urgent and unfocused tabs
2054 • MaybeColor tab_title_color = Inherit: if non-empty, the title color
2056 of non-urgent and unfocused tabs
2057 • bool tight_decoration = false: specifies whether the size hints
2059 also affect the window decoration or only the window contents of
2060 tiled clients (requires enabled sizehints_tiling)
2061 • TextAlign title_align = left: the horizontal alignment of the title
2063 within the tab or title bar. The value is one of: left, center,
2064 right
2065 • color title_color = black
2067 • int title_depth = 0: the space below the baseline of the window
2069 title
2070 • font title_font = fixed
2072 • uint title_height = 0
2074 • TitleWhen title_when = always: when to show the window title:
2076 always, never, if the the client is in a tabbed scenario like a max
2077 frame (one_tab), if there are multiple_tabs to be shown.
2078 • active: configures the decoration of the focused client.
2080 • color background_color = black: color behind window contents
2083 visible on resize
2084 • uint border_width = 0: the base width of the border
2086 • color color = black: the basic background color of the border
2088 • color inner_color = black: color of the inner border
2090 • uint inner_width = 0: width of the border around the clients
2092 content
2093 • color outer_color = black: color of the outer border
2095 • uint outer_width = 0: width of an border close to the edge
2097 • uint padding_bottom = 0: additional border width on the bottom
2099 • uint padding_left = 0: additional border width on the left
2101 • uint padding_right = 0: additional border width on the right
2103 • uint padding_top = 0: additional border width on the top
2105 • string reset: writing this resets all attributes to a default
2107 value
2108 • MaybeColor tab_color = Inherit: if non-empty, the color of
2110 non-urgent and unfocused tabs
2111 • MaybeColor tab_outer_color = Inherit: if non-empty, the outer
2113 border color of non-urgent and unfocused tabs; if empty, the
2114 colors are taken from the tab’sclient decoration settings.
2115 • MaybeULong tab_outer_width = Inherit: if non-empty, the outer
2117 border width of non-urgent and unfocused tabs
2118 • MaybeColor tab_title_color = Inherit: if non-empty, the title
2120 color of non-urgent and unfocused tabs
2121 • bool tight_decoration = false: specifies whether the size hints
2123 also affect the window decoration or only the window contents
2124 of tiled clients (requires enabled sizehints_tiling)
2125 • TextAlign title_align = left: the horizontal alignment of the
2127 title within the tab or title bar. The value is one of: left,
2128 center, right
2129 • color title_color = black
2131 • int title_depth = 0: the space below the baseline of the window
2133 title
2134 • font title_font = fixed
2136 • uint title_height = 0
2138 • TitleWhen title_when = always: when to show the window title:
2140 always, never, if the the client is in a tabbed scenario like a
2141 max frame (one_tab), if there are multiple_tabs to be shown.
2142 • floating: behaves analogously to tiling.
2144 • color background_color = black: color behind window contents
2147 visible on resize
2148 • uint border_width = 0: the base width of the border
2150 • color color = black: the basic background color of the border
2152 • color inner_color = black: color of the inner border
2154 • uint inner_width = 0: width of the border around the clients
2156 content
2157 • color outer_color = black: color of the outer border
2159 • uint outer_width = 0: width of an border close to the edge
2161 • uint padding_bottom = 0: additional border width on the bottom
2163 • uint padding_left = 0: additional border width on the left
2165 • uint padding_right = 0: additional border width on the right
2167 • uint padding_top = 0: additional border width on the top
2169 • string reset: writing this resets all attributes to a default
2171 value
2172 • MaybeColor tab_color = Inherit: if non-empty, the color of
2174 non-urgent and unfocused tabs
2175 • MaybeColor tab_outer_color = Inherit: if non-empty, the outer
2177 border color of non-urgent and unfocused tabs; if empty, the
2178 colors are taken from the tab’sclient decoration settings.
2179 • MaybeULong tab_outer_width = Inherit: if non-empty, the outer
2181 border width of non-urgent and unfocused tabs
2182 • MaybeColor tab_title_color = Inherit: if non-empty, the title
2184 color of non-urgent and unfocused tabs
2185 • bool tight_decoration = false: specifies whether the size hints
2187 also affect the window decoration or only the window contents
2188 of tiled clients (requires enabled sizehints_tiling)
2189 • TextAlign title_align = left: the horizontal alignment of the
2191 title within the tab or title bar. The value is one of: left,
2192 center, right
2193 • color title_color = black
2195 • int title_depth = 0: the space below the baseline of the window
2197 title
2198 • font title_font = fixed
2200 • uint title_height = 0
2202 • TitleWhen title_when = always: when to show the window title:
2204 always, never, if the the client is in a tabbed scenario like a
2205 max frame (one_tab), if there are multiple_tabs to be shown.
2206 • active: configures the decoration of the focused client. For
2208 attributes and children, see theme.active
2209 • normal: the default decoration scheme for clients. For
2211 attributes and children, see theme.active
2212 • urgent: configures the decoration of urgent clients. For
2214 attributes and children, see theme.active
2215 • fullscreen: configures clients in fullscreen state. For attributes
2217 and children, see theme.floating
2218 • minimal: configures clients with minimal decorations triggered by
2220 smart_window_surroundings. For attributes and children, see
2221 theme.floating
2222 • normal: the default decoration scheme for clients. For attributes
2224 and children, see theme.active
2225 • tiling: configures the decoration of tiled clients, setting one of
2227 its attributes propagates the respective attribute of the active,
2228 normal and urgent child objects. For attributes and children, see
2229 theme.floating
2230 • urgent: configures the decoration of urgent clients. For attributes
2232 and children, see theme.active
2233 types:
2235 This lists the types that are used for attributes and command
2236 arguments.
2237 • bool: Type representing boolean values, i.e. an on or off state,
2239 with aliases true and false. When writing to a boolean value, one
2240 can also specify toggle in order to alter its value.
2241 • string fullname: the full and unique name of this type
2244 • string shortname: A short (one-character long) name of this
2246 type which is used in the output of the attr command
2247 • color: Type representing colors. A color can be defined in one of
2249 the following formats:
2250 1. #RRGGBB where R, G, B are hexidecimal digits (0-9, A-F), and
2252 RR, GG, BB represent the values for red, green, blue.
2253 2. #RRGGBBAA represents a color with alpha-value AA. The alpha
2255 value 00 is fully transparent and FF is fully
2256 opaque/intransparent.
2257 3. a common color name like red, blue, orange, etc. For attributes
2259 and children, see types.bool
2260 • decimal: Fixed precision decimal numbers, e.g. 0.34. For attributes
2262 and children, see types.bool
2263 • font: A font specification (font family with modifiers regarding
2265 size, weight, etc.) in one of the following formats:
2266 • Fontconfig description. This supports antialiased fonts, for
2270 example:
2271 • Dejavu Sans:pixelsize=12
2273 • Bitstream Vera Sans:size=12:bold
2275 • X logical font description (XLFD), as provided by the xfontsel
2277 tool. No antialiasing is supported here, but this is usually
2278 superior for bitmap fonts. For example:
2279 • -*-fixed-medium-r-*-*-13-*-*-*-*-*-*-* for a standard
2281 bitmap font available on most systems. For attributes and
2282 children, see types.bool
2283 • int: Type representing signed integers. When overwriting an
2285 integer, you can increase or decrease its value relatively by
2286 writing +=N or -=N where N is an integer. So for example, writing
2287 +=3 to an attribute increases its value by 3. For attributes and
2288 children, see types.bool
2289 • names: A fixed set of names, depending on the context, e.g. names
2291 of layout algorithms or the split type of a non-leaf frame (which
2292 is only horizontal or vertical). For attributes and children, see
2293 types.bool
2294 • rectangle: A rectangle on the screen consisting of a size and the
2296 position on the screen. The format is WxH+X+Y where W is the width,
2297 H is the height, and X and Y are the coordinates of the top left
2298 corner of the rectangle: X is the number of pixels to the left
2299 screen edge and Y is the number of pixels to the top screen edge.
2300 (if X or Y is negative, then the + turns into -). For example:
2301 800x600+800+0 or 400x200-10+30. For attributes and children, see
2302 types.bool
2303 • regex: A POSIX extended regular expression. Note that when passing
2305 a regex on the command line, additional quoting can be necessary.
2306 For explanations and examples, see section 9.4.6 of the
2307 documentation:
2308 https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04_06.
2309 For attributes and children, see types.bool
2310 • string: Type representing normal text. For attributes and children,
2312 see types.bool
2313 • uint: Type representing unsigned (i.e. non-negative) integers. When
2315 overwriting an integer, you can increase or decrease its value
2316 relatively by writing +=N or -=N where N is an integer. For
2317 attributes and children, see types.bool
2318 • windowid: The window id is the number of a window. This can be a
2320 managed window (i.e. client) or an unmanaged window (e.g. a panel,
2321 a menu, or a desktop window). The default format is 0xHEX where HEX
2322 is a hexadecimal number (digits 0-9 and a-f) but it can also be
2323 specified in the decimal system (base 10), or as an octal number
2324 (with prefix 0 and base 8). When a window id is printed, it is
2325 always printed in the 0xHEX format and without any leading zeroes.
2326 For attributes and children, see types.bool
2327 watchers:
2329 • uint count: the number of attributes that are watched
2330
2332 There is no configuration file but an autostart file, which is executed
2333 on startup. It is also executed on command reload. If not specified by
2334 the --autostart argument, autostart file is located at
2335 $XDG_CONFIG_HOME/herbstluftwm/autostart or at
2336 ~/.config/herbstluftwm/autostart. Normally it consists of a few
2337 herbstclient calls. If executing the autostart file in a user’s home
2338 fails the global autostart file (mostly placed at
2339 /etc/xdg/herbstluftwm/autostart) is executed as a fallback.
2340 For a quick install, copy the default autostart file to
2342 ~/.config/herbstluftwm/.
2343
2345 On special events, herbstluftwm emits some hooks (with parameters). You
2346 can receive or wait for them with herbstclient(1). Also custom hooks
2347 can be emitted with the emit_hook command. The following hooks are
2348 emitted by herbstluftwm itself:
2349 attribute_changed PATH OLDVALUE NEWVALUE
2351 The attribute PATH was changed from OLDVALUE to NEWVALUE. Requires
2352 that the attribute PATH has been passed to the watch command
2353 before.
2354 fullscreen [on|off] WINID
2356 The fullscreen state of window WINID was changed to [on|off].
2357 tag_changed TAG MONITOR
2359 The tag TAG was selected on MONITOR.
2360 focus_changed WINID TITLE
2362 The window WINID was focused. Its window title is TITLE.
2363 window_title_changed WINID TITLE
2365 The title of the focused window was changed. Its window id is WINID
2366 and its new title is TITLE.
2367 tag_flags
2369 The flags (i.e. urgent or filled state) have been changed.
2370 tag_added TAG
2372 A tag named TAG was added.
2373 tag_removed TAG
2375 The tag named TAG was removed.
2376 tag_renamed OLD NEW
2378 The tag name changed from OLD to NEW.
2379 urgent [on|off] WINID
2381 The urgent state of client with given WINID has been changed to
2382 [on|off].
2383 rule NAME WINID
2385 A window with the id WINID appeared which triggered a rule with the
2386 consequence hook=NAME.
2387 There are also other useful hooks, which never will be emitted by
2389 herbstluftwm itself, but which can be emitted with the emit_hook
2390 command:
2391 quit_panel
2393 Tells a panel to quit. The default panel.sh quits on this hook.
2394 Many scripts are using this hook.
2395 reload
2397 Tells all daemons that the autostart file is reloaded — and tells
2398 them to quit. This hook should be emitted in the first line of
2399 every autostart file.
2400
2402 Every tag has its own stack of clients that are on this tag. Similar to
2403 the EWMH specification each tag stack contains several layers, which
2404 are from top to bottom:
2405 • the focused client (if raise_on_focus_temporarily is enabled)
2407 • clients in fullscreen
2409 • normal clients
2411 • frame decorations
2413 All monitors are managed in one large stack which only consists of the
2415 stacks of the visible tags put above each other. The stacking order of
2416 these monitors is independent from their indices and can be modified
2417 using the raise_monitor command. The current stack is illustrated by
2418 the stack command.
2419
2421 As far as possible, herbstluftwm tries to be EWMH compliant. That
2422 includes:
2423 • Information about tag names and client lists is provided.
2425 • Desktop windows from desktop environments are not managed and kept
2427 below the other windows.
2428 • Client requests like getting focused are only processed if the
2430 setting focus_stealing_prevention is disabled.
2431 Moreover, herbstluftwm sets the X11 properties HLWM_FLOATING_WINDOW and
2433 HLWM_TILING_WINDOW to indicate whether a window is in floating or
2434 tiling mode, that is, the value of the client’s floating_effectively
2435 attribute.
2436
2438 DISPLAY
2439 Specifies the DISPLAY to use.
2440
2442 The following files are used by herbstluftwm:
2443 • autostart, see section AUTOSTART FILE.
2445
2447 Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
2448 wmexec fails.
2449
2451 See the herbstluftwm Github issues:
2452 https://github.com/herbstluftwm/herbstluftwm/issues
2453
2455 Feel free to join the IRC channel #herbstluftwm on irc.libera.chat.
2456
2458 herbstluftwm was written by Thorsten Wißmann. All contributors are
2459 listed in the herbstluftwm distribution AUTHORS file.
2460
2462 Homepage: http://herbstluftwm.org
2463 Github page: http://github.com/herbstluftwm/herbstluftwm
2465 Patch submission and bug reporting:
2467 hlwm@lists.herbstluftwm.org
2469
2471 Copyright 2011-2020 Thorsten Wißmann. All rights reserved.
2472 This software is licensed under the "Simplified BSD License". See
2474 LICENSE for details.
2475 herbstluftwm 0.9.5 2022-07-30 HERBSTLUFTWM(1)