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. When KEY is pressed, the internal COMMAND (with
254 its ARGS) is executed. A key binding is a (possibly empty) list of
255 modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl,
256 Shift) and one key (see keysymdef.h for a list of keys). Modifiers
257 and the key are concatenated with - or + as separator. If there is
258 already a binding for this KEY, it will be overwritten. Examples:
259 • keybind Mod4+Ctrl+q quit
261 • keybind Mod1-i toggle always_show_frame
263 • keybind Mod1-Shift-space cycle_layout -1
265 keyunbind KEY|-F|--all
267 Removes the key binding for KEY. The syntax for KEY is defined in
268 keybind. If -F or --all is given, then all key bindings will be
269 removed.
270 mousebind BUTTON ACTION [COMMAND ...]
272 Adds a mouse binding for the floating mode. When BUTTON is pressed,
273 the specified ACTION will be performed. BUTTON has a similar
274 syntax to the KEY argument of keybind: It consists of a list of
275 modifiers (separated by - or +, valid modifiers are listed in the
276 description of keybind) and exactly one button name:
277 • B1 or Button1
279 • B2 or Button2
281 • B3 or Button3
283 • B4 or Button4
285 • B5 or Button5
287 ACTION must be one of the following actions:
289 • move: Moves the window by dragging the cursor.
291 • resize: Resizes the window by dragging a corner.
293 • zoom: Resizes the window into all four directions while keeping
295 the center of the window constant.
296 • call: Only calls the specified COMMAND while client.dragged
298 links to the client on which the BUTTON has been performed.
299 While an ACTION is performed, client.dragged is the client which is
301 dragged. E.g.:
302 • mousebind Mod1-Button3 zoom
304 • mousebind Mod1-B4 call substitute WID clients.dragged.winid
306 spawn transset-df --inc -i WID 0.05
307 • mousebind Mod1-B5 call substitute WID clients.dragged.winid
309 spawn transset-df --dec -i WID -m 0.2 0.05
310 drag WINID ACTION
312 Starts dragging the specified client window WINID with the
313 specified ACTION (see mousebind). E.g. drag '' resize starts
314 resizing the focused window.
315 mouseunbind
317 Removes all mouse bindings.
318 spawn EXECUTABLE [ARGS ...]
320 Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp.
321 Example:
322 • spawn xterm -e man 3 execvp
324 wmexec [WINDOWMANAGER [ARGS ...]]
326 Executes the WINDOWMANAGER with its ARGS. This is useful to switch
327 the window manager in the running session without restarting the
328 session. If no or an invalid WINDOWMANAGER is given, then
329 herbstluftwm is restarted. For details see man 3 execvp. Example:
330 • wmexec openbox
332 chain SEPARATOR [COMMANDS ...]
334 chain expects a SEPARATOR and a list of COMMANDS with arguments.
335 The commands have to be separated by the specified SEPARATOR. The
336 SEPARATOR can by any word and only is recognized as the separator
337 between commands if it exactly matches SEPARATOR. "chain" outputs
338 the appended outputs of all commands and returns the exit code of
339 the last executed command. Examples are:
340 • Create a tag called "foo" and directly use it:
342 chain , add foo , use foo
344 • Rotate the layout clockwise:
346 chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
348 Counterexamples are:
350 • This will only create a tag called "foo,":
352 chain , add foo, use foo
354 • Separator "." defined, but "," is used:
356 chain . add foo , use foo
358 and SEPARATOR [COMMANDS ...]
360 "and" behaves like the chain command but only executes the
361 specified COMMANDS while the commands return the exit code 0.
362 or SEPARATOR [COMMANDS ...]
364 "or" behaves like the chain command but only executes the specified
365 COMMANDS until one command returns the exit code 0.
366 ! COMMAND
368 "!" executes the provided command, but inverts its return value. If
369 the provided command returns a nonzero, "!" returns a 0, if the
370 command returns a zero, "!" returns a 1.
371 try COMMAND
373 "try" executes the provided command, prints its output, but always
374 returns success, i.e. 0.
375 silent COMMAND
377 "silent" executes the provided command, but discards its output and
378 only returns its exit code.
379 focus_nth INDEX
381 Focuses the nth window in a frame. The first window has INDEX 0. If
382 INDEX is negative or greater than the last window index, then the
383 last window is focused.
384 cycle [DELTA]
386 Cycles the selection within the current frame by DELTA or cycles
387 through the clients in the floating layer if that is focused. If
388 DELTA is omitted, DELTA = 1 will be used. DELTA can be negative;
389 DELTA = -1 means: cycle in the opposite direction by 1.
390 cycle_all [--skip-invisible] [DIRECTION]
392 Cycles through all non-minimized windows and frames on the current
393 tag. DIRECTION = 1 means forward (default value), DIRECTION = -1
394 means backward, DIRECTION = 0 has no effect. If there are multiple
395 windows within one frame, then it acts similar to the cycle
396 command. If --skip-invisible is given, then this only cycles
397 through all visible windows and skips invisible windows in the max
398 layout (the flag only affects invisible windows in the max layout;
399 minimized windows are always skipped). After each focus change, the
400 focused window is raised.
401 cycle_frame [DIRECTION]
403 Cycles through all frames on the current tag. DIRECTION = 1 means
404 forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
405 effect. DIRECTION defaults to 1.
406 cycle_layout [DELTA [LAYOUTS ...]]
408 Cycles the layout algorithm in the current frame by DELTA. DELTA
409 defaults to 1. You can find a list of layout algorithms above. If a
410 list of LAYOUTS is given, cycle_layout will cycle through those
411 instead of the default layout algorithm list. This is done by
412 finding the first occurrence of the current layout in LAYOUTS and
413 picking the next layout according to DELTA. If the current layout
414 doesn’t occur in LAYOUTS, the first entry is picked. Example:
415 • cycle_layout -1
417 • cycle_layout 1 vertical grid
419 set_layout LAYOUT
421 Sets the layout algorithm in the current frame to LAYOUT. For the
422 list of layouts, check the list of layout algorithms above.
423 close WINID
425 Closes the specified window gracefully or the focused window if
426 none is given explicitly. See the section on WINDOW IDS how to
427 reference a certain window.
428 close_or_remove
430 Closes the focused window or removes the current frame if no window
431 is focused. In floating mode, this acts as the close command.
432 close_and_remove
434 Closes the focused window and removes the current frame if no other
435 window is present in that frame. In floating mode, this acts as the
436 close command.
437 split ALIGN [FRACTION [FRAMEINDEX]]
439 Splits the focused frame (or the frame specified by FRAMEINDEX, see
440 the section frame index) into two subframes with a specified
441 FRACTION between 0 and 1 which defaults to 0.5. ALIGN is one of
442 • top
445 • bottom (= vertical)
447 • left
449 • right (= horizontal)
451 • explode
453 • auto (split along longest side)
455 It specifies which of the two halves will be empty after the
457 split. The other half will be occupied by the currently focused
458 frame. After splitting, the originally focused frame will stay
459 focused. One special ALIGN mode is explode, which splits the
460 frame in such a way that the window focus, window sizes, and
461 positions are kept as much as possible (so the default FRACTION
462 is not always 0.5, unlike for the other ALIGN modes). Example:
463 • split explode
465 • split bottom 0.5
467 • split horiz 0.3
469 • split vertical 0.5
471 • split h
473 • split top 0.2 '' (splits the root frame)
475 focus [-i|-e|--level=LEVEL] DIRECTION
477 Moves the focus from current frame to the next frame or client in
478 DIRECTION which is in:
479 • l[eft]
482 • r[ight]
484 • u[p]
486 • d[own]
488 If there is no client within this frame or LEVEL is frame, then the
490 next frame in specified DIRECTION will be focused. If LEVEL is
491 visible or default_direction_external_only is unset, then the next
492 client in DIRECTION can also be within the same frame, but has to
493 be visible. For tabs LEVEL, the next client may be hidden in a
494 tabbed_max layout. With all any client within a max layout maybe
495 selected before focusing the next frame. The flag -i is an alias
496 for --level=visible and -e for --level=frame.
497 The direction between frames is defined as follows: The focus is in
500 a leaf of the binary tree. Each inner node in the tree remembers
501 the last focus direction (child 0 or child 1). The algorithm uses
502 the shortest possible way from the leaf (the currently focused
503 frame) to the root until it is possible to change focus in the
504 specified DIRECTION. From there the focus goes back to the leaf.
505 Example: The focus is at frame A. After executing focus right focus
508 will be at frame C.
509 Tree: H,0 Screen: ┌─────┐┌─────┐ (before)
511 ╱ ╲ │ B ││ C │
512 ╱ ╲ └─────┘└─────┘
513 V,1 V,0 ┌─────┐┌─────┐
514 ╱ ╲ ╱ ╲ │ A* ││ D │
515 B A* C D └─────┘└─────┘
516 Tree: H,1 Screen: ┌─────┐┌─────┐ (after focus right)
518 ╱ ╲ │ B ││ C* │
519 ╱ ╲ └─────┘└─────┘
520 V,1 V,0 ┌─────┐┌─────┐
521 ╱ ╲ ╱ ╲ │ A ││ D │
522 B A C* D └─────┘└─────┘
523 If the currently focused client is floated, then the next floating
525 window in the specified direction is focused and raised.
526 If focus_crosses_monitor_boundaries is set and no client or frame
528 is found in the specified DIRECTION, then the next monitor in that
529 DIRECTION is focused.
530 focus_edge [-i|-e] DIRECTION
532 Focuses the window on the edge of the tag in the specified
533 DIRECTION. The DIRECTIONS and -e behave as specified at the focus
534 command.
535 If -i (internal) is given or default_direction_external_only is
538 unset, then the window on the edge of the tag will be focused.
539 Else, only the frame on the edge of the tag will be focused, and
540 the window that was last focused in that frame will be focused.
541 raise WINID
543 Raises the specified managed or unmanaged window. Managed windows
544 are only moved within the tag’s stack (as reported by the stack
545 command), and unmanaged windows are raised globally, i.e. are
546 raised above all managed windows. See the section on WINDOW IDS on
547 how to reference a certain window. Its result is only visible for
548 floating windows and unmanaged windows.
549 lower WINID
551 Lowers the specified managed or unmanaged window, analogously to
552 the raise command: managed windows are lowered within the stack of
553 floating windows (with no effect for tiled windows) and unmanaged
554 windows are moved below all managed windows (for example, it can be
555 used to lower desktop windows).
556 jumpto WINID
558 Puts the focus to the specified window. See the section on WINDOW
559 IDS on how to reference a certain window.
560 bring WINID
562 Moves the specified window to the current frame and focuses it.
563 Floating windows are brought to the current tag, but keep their
564 floating state. See the section on WINDOW IDS on how to reference a
565 certain window.
566 resize DIRECTION [FRACTIONDELTA]
568 Changes the size of the focused frame in the specified DIRECTION by
569 FRACTIONDELTA (which defaults to 0.02 if none is supplied).
570 DIRECTION behaves as specified at the focus command. If a floating
571 window is focused, it grows towards next edge, i.e. either the edge
572 of the next window or the monitor edge in the specified DIRECTION
573 (FRACTIONDELTA is ignored in that case). Example:
574 • resize right +0.05
576 • resize down -0.1
578 shift_edge [-i|-e] DIRECTION
580 Shifts the focused window to the the edge of a tag in the specified
581 DIRECTION. The DIRECTIONS behave as specified at the focus command
582 and -i and -e behave as specified at the focus_edge command.
583 shift [-i|-e] DIRECTION
585 Shifts the focused window to the next frame in the specified
586 DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
587 focus command. If the focused client is floated instead of being
588 tiled, then client is shifted to the next window or screen edge. If
589 the window cannot be moved and the setting
590 focus_crosses_monitor_boundaries is activated, then the window is
591 moved to the monitor in the specified DIRECTION.
592 shift_to_monitor MONITOR
594 Moves the focused window to the tag on the specified MONITOR. See
595 the MONITORS section, how to address a monitor.
596 remove
598 Removes focused frame and merges its windows to its closest
599 neighbour frame.
600 rotate
602 Rotates the layout on the focused tag counterclockwise by 90
603 degrees. This only manipulates the alignment of frames, not the
604 content of them.
605 mirror [vertical|horizontal|both]
607 Mirrors the layout on the focused tag vertically, horizontally, or
608 both; the default is horizontal. This command only manipulates the
609 alignment of frames, not the content of them.
610 set NAME VALUE
612 Sets the specified setting NAME to VALUE. Allowed values for
613 boolean settings are on or true for on, off or false for off,
614 toggle to toggle its value. All settings are listed in the section
615 below.
616 get NAME
618 Prints the value of setting NAME. All settings are listed in the
619 section below.
620 toggle NAME
622 Toggles the setting NAME if it’s a boolean setting.
623 cycle_value PATH VALUES ...
625 Cycles value of the attribute PATH through VALUES: I.e. it searches
626 the first occurrence of the current value in VALUES and changes the
627 value to the next in the list or to the first one if the end is
628 reached or current value wasn’t found. For compatibility reasons,
629 PATH can also be the name of a setting. Examples:
630 • cycle_value settings.frame_gap 0 5 10 15
632 • cycle_value theme.active.inner_color red green blue
634 • the command cycle_layout +1 is equivalent to cycle_value
636 tags.focus.tiling.focused_frame.algorithm
637 cycle_monitor [DELTA]
639 Cycles monitor focused by DELTA. DELTA defaults to 1.
640 focus_monitor MONITOR
642 Puts focus to the specified monitor. See the MONITORS section, how
643 to address a monitor.
644 add TAG
646 Creates a new empty tag named TAG.
647 use TAG
649 Switches the focused monitor to specified TAG.
650 use_index INDEX [--skip-visible]
652 Switches the focused monitor to the TAG with the specified INDEX.
653 If INDEX starts with + or -, then INDEX is treated relative to the
654 current TAG. If --skip-visible is passed and INDEX is relative,
655 then tags that are already visible on a monitor are skipped. E.g.
656 this cycles backwards through the tags:
657 • use_index -1 --skip-visible
659 use_previous
661 Switches the focused monitor to the previously viewed tag.
662 merge_tag TAG [TARGET]
664 Removes tag named TAG and moves all its windows to tag TARGET. If
665 TARGET is omitted, the focused tag will be used.
666 rename OLDTAG NEWTAG
668 Renames tag named OLDTAG to NEWTAG.
669 move TAG
671 Moves the focused window to the tag named TAG.
672 move_index INDEX [--skip-visible]
674 Moves the focused window to the tag specified by INDEX. Analogical
675 to the argument for use_index: If INDEX starts with + or -, then it
676 is treated relative. If --skip-visible is passed with a relative
677 index, then already visible tags are skipped.
678 lock_tag [MONITOR]
680 Lock the tag switching on the specified monitor. If no argument is
681 given, the currently focused monitor is used. When the tag
682 switching is disabled for a monitor, the commands use and use_index
683 have no effect when executed there. When swap_monitors_to_get_tag
684 is enabled, switching to a tag which is located on a locked
685 monitor, switches to that monitor instead of stealing it from
686 there. The lock state of a monitor is indicated by "[LOCKED]" in
687 the list_monitors output.
688 unlock_tag [MONITOR]
690 Re-enables the tag switching on the specified monitor. If no
691 argument is given, the currently focused monitor is used. This is
692 the reverse operation to lock_tag and has no further side effects
693 but removing this lock.
694 disjoin_rects RECTS ...
696 Takes a list of rectangles and splits them into smaller pieces
697 until all rectangles are disjoint, the result rectangles are
698 printed line by line. This command does not modify the current list
699 of monitors! So this can be useful in combination with the
700 set_monitors command.
701 • E.g. disjoin_rects 600x400+0+0 600x400+300+250 prints this:
703 300x150+300+250
705 600x250+0+0
706 300x150+0+250
707 300x150+600+250
708 600x250+300+400
709 • In the above example two monitors are split into 5 monitors,
711 which graphically means:
712 ┌──────┐ ┌──────┐
714 │ │ └──────┘
715 │ ┌───┼───┐ ┌─┐┌───┐┌──┐
716 │ │ │ │ disjoin │ ││ ││ │
717 └──┼───┘ │ ─────────> └─┘└───┘└──┘
718 │ │ ┌───────┐
719 └───────┘ └───────┘
720 set_monitors RECTS ...
722 Sets the list of monitors exactly to the list of given rectangles:
723 • The i’th existing monitor is moved to the i’th given RECT
725 • New monitors are created if there are more RECTS than monitors
727 • Existing monitors are deleted if there are more monitors than
729 RECTS
730 detect_monitors -l|--list|--list-all|--no-disjoin
732 Sets the list of monitors to the physically available monitors. If
733 both Xinerama and xrandr are missing, it will fall back to one
734 monitor across the entire screen. If the detected monitors overlap,
735 the will be split into more monitors that are disjoint but cover
736 the same area using disjoin_rects.
737 If -l or --list is passed, the list of rectangles of detected
739 physical monitors is printed. So hc detect_monitors is equivalent
740 to the bash command hc set_monitors $(hc disjoin_rects $(hc
741 detect_monitors -l)).
742 If --list-all is passed, then it is printed which multimonitor
744 detection (xinerama, xrandr) has which set of physical monitors.
745 add_monitor RECT [TAG [NAME]]
747 Adds a monitor on the specified rectangle RECT and displays TAG on
748 it. TAG currently must not be displayed on any other monitor.
749 RECT is a string of the form WxH±X±Y. If no or an empty TAG is
750 given, then any free tag will be chosen. If a NAME is given, you
751 can reference to this monitor by its name instead of using an
752 index. Example:
753 • add_monitor 1024x768-20+0 mynewtag main
755 remove_monitor MONITOR
757 Removes the specified monitor.
758 move_monitor MONITOR RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
760 Moves the specified monitor to rectangle RECT. RECT is defined as
761 in add_monitor. If no or an empty pad is given, it is not changed.
762 raise_monitor [MONITOR]
764 Raises the specified monitor or the current one if MONITOR is
765 omitted.
766 rename_monitor MONITOR NAME
768 (Re)names an already existing monitor. If NAME is empty, it removes
769 the monitor’s name.
770 stack
772 Prints the stack of monitors with the visible tags and their layers
773 as a tree. The order of the printed stack is top to bottom. The
774 style is configured by the tree_style setting.
775 monitor_rect [[-p] MONITOR]
777 Prints the rectangle of the specified monitor in the format: X Y W
778 H If no MONITOR or cur is given, then the current monitor is used.
779 If -p is supplied, then the remaining rect without the pad around
780 this monitor is printed.
781 pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
783 Sets the pad of specified monitor to the specified padding. If no
784 or an empty padding is given, it is not changed.
785 list_padding [MONITOR]
787 Lists the padding of the specified monitor, or the currently
788 focused monitor if no monitor is given.
789 layout [TAG [INDEX]]
791 Prints the layout of frame with INDEX on TAG, in a nice tree style.
792 Its style is defined by the tree_style setting. If no TAG is given,
793 the current tag is used. If no INDEX is given, the root frame is
794 used. To specify INDEX without specifying TAG (i.e. use current
795 tag), pass an empty string as TAG.
796 An example output is:
798 ╾─┐ horizontal 50% selection=1
800 ├─╼ vertical: 0xe00009
801 └─┐ vertical 50% selection=0
802 ├─╼ vertical: 0xa00009 [FOCUS]
803 └─╼ vertical: 0x1000009
804 dump [TAG [INDEX]]
806 Prints the same information as the layout command but in a machine
807 readable format. Its output can be read back with the load command.
808 An example output (formatted afterwards) is:
810 (split horizontal:0.500000:1
812 (clients vertical:0 0xe00009)
813 (split vertical:0.500000:1
814 (clients vertical:0 0xa00009)
815 (clients vertical:0 0x1000009)))
816 load [TAG] LAYOUT
818 Loads a given LAYOUT description to specified TAG or current tag if
819 no TAG is given.
820 Caution
822 LAYOUT is exactly one parameter. If you are calling it manually
823 from your shell or from a script, quote it properly!
824 complete POSITION [COMMAND ARGS ...]
826 Prints the result of tab completion for the partial COMMAND with
827 optional ARGS. You usually do not need this, because there is
828 already tab completion for bash, zsh and fish. Example:
829 • complete 0 m
831 prints all commands beginning with m
833 • complete 1 toggle fra
835 prints all settings beginning with fra that can be toggled
837 complete_shell POSITION [COMMAND ARGS ...]
839 Behaves like complete with the following extras, useful for
840 completion on posix shells:
841 • Escape sequences are removed in COMMAND and ARGS.
843 • A space is appended to each full completion result.
845 • Special characters will be escaped in the output.
847 emit_hook NAME ARGS ...
849 Emits a custom hook NAME to all idling herbstclients.
850 tag_status [MONITOR]
852 Print a tab separated list of all tags for the specified MONITOR
853 index. If no MONITOR index is given, the focused monitor is used.
854 Each tag name is prefixed with one char, which indicates its state:
855 • . the tag is empty
857 • : the tag is not empty
859 • + the tag is viewed on the specified MONITOR, but this monitor
861 is not focused.
862 • # the tag is viewed on the specified MONITOR and it is focused.
864 • - the tag is viewed on a different MONITOR, but this monitor is
866 not focused.
867 • % the tag is viewed on a different MONITOR and it is focused.
869 • ! the tag contains an urgent window
871 Warning
873 If you use a tab in one of the tag names, then tag_status is
874 probably quite useless for you.
875 floating [[TAG] on|off|toggle|status]
877 Changes specified TAG to floating/tiling mode or prints its current
878 status. If no TAG is given, the current tag is used. If no argument
879 is given, floating mode is toggled. If status is given, then on or
880 off is printed, depending of the floating state of TAG.
881 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
883 Defines a rule which will be applied to all new clients. Its
884 behaviour is described in the RULES section.
885 unrule LABEL|--all|-F
887 Removes all rules named LABEL. If --all or -F is passed, then all
888 rules are removed.
889 apply_rules WINID|--all
891 Apply the rules to the specified window WINID. If --all is passed,
892 then the rules are applied to all clients.
893 apply_tmp_rule WINID|--all [RULEDESCRIPTION...]
895 Apply the rule RULEDESCRIPTION to one particular client WINID or
896 all clients (--all) without adding the rule to the rule list. The
897 RULEDESCRIPTION specifies a rule consisting of conditions and
898 consequences as one would pass it to the rule command as described
899 in the RULES section. This allows testing rules before adding them.
900 Running apply_tmp_rule only applies the particular rule given in
901 the arguments and ignores the existing rules.
902 fullscreen [on|off|toggle]
904 Sets or toggles the fullscreen state of the focused client. If no
905 argument is given, fullscreen mode is toggled.
906 pseudotile [on|off|toggle]
908 Sets or toggles the pseudotile state of the focused client. If a
909 client is pseudotiled, then in tiling mode the client is only moved
910 but not resized - the client size will stay the floating size. The
911 only reason to resize the client is to ensure that it fits into its
912 tile. If no argument is given, pseudotile mode is toggled.
913 object_tree [PATH]
915 Prints the tree of objects. If the object path PATH is given, only
916 the subtree starting at PATH is printed. See the OBJECTS section
917 for more details.
918 attr [PATH [NEWVALUE]
920 Prints the children and attributes of the given object addressed by
921 PATH. If PATH is an attribute, then print the attribute value. If
922 NEWVALUE is given, assign NEWVALUE to the attribute given by PATH.
923 See the OBJECTS section for more details.
924 get_attr ATTRIBUTE
926 Print the value of the specified ATTRIBUTE as described in the
927 OBJECTS section.
928 set_attr ATTRIBUTE NEWVALUE
930 Assign NEWVALUE to the specified ATTRIBUTE as described in the
931 OBJECTS section.
932 attr_type ATTRIBUTE
934 Print the type of the specified ATTRIBUTE.
935 new_attr bool|color|int|string|uint PATH [VALUE]
937 Creates a new attribute with the name and in the object specified
938 by PATH. Its type is specified by the first argument. The attribute
939 name has to begin with my_. If VALUE is supplied, then it is
940 written to the attribute (if this fails the attribute still
941 remains).
942 watch PATH
944 Watch the value of the given attribute PATH. Whenever the value
945 changes from OLDVALUE to NEWVALUE, a hook is emitted:
946 attribute_changed PATH OLDVALUE NEWVALUE
948 remove_attr PATH
950 Removes the user defined attribute PATH.
951 substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
953 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
954 ARGS by the value of the ATTRIBUTE. Note that the COMMAND also is
955 replaced by the attribute value if it equals IDENTIFIER. The
956 replaced command with its arguments then is executed. Example:
957 • substitute MYTITLE clients.focus.title echo MYTITLE
959 Prints the title of the currently focused window.
961 sprintf IDENTIFIER FORMAT [FORMATARG ...] COMMAND [CMDARGS ...]
963 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
964 CMDARGS by the string specified by FORMAT. The FORMAT string may
965 contain several placeholders, similar to the printf(1) command:
966 • %s inserts an attribute value whose path is given by the string
968 value of the next FORMATARG
969 • %c ("constant") inserts the next FORMATARG without
971 modification.
972 • %% stands for a plain %
974 The replaced command with its arguments then is executed. Examples:
976 • sprintf STR title=%s clients.focus.title echo STR
978 Prints the title of the currently focused window prepended by
980 title=.
981 • sprintf X "%c %s tags" "there are" tags.count echo X
983 Prints there are N tags with N replaced by the number of tags.
985 • sprintf X tag=%s tags.focus.name rule once X
987 Moves the next client that appears to the tag that is currently
989 focused.
990 • sprintf X %s/%s tags.focus.index tags.count echo X
992 Tells which tag is focused and how many tags there are
994 • sprintf l somelongstring echo l l l
996 Prints somelongstring three times, separated by spaces.
998 • substitute X tags.count sprintf Y "number=%c" X echo Y
1000 has the same output as
1002 sprintf Y "number=%s" tags.count echo Y
1004 (Note how the %c changes to %s)
1006 foreach IDENTIFIER OBJECT [--recursive] [--unique]
1008 [--filter-name=REGEX] COMMAND [ARGS ...]
1009 For each child of the given OBJECT the COMMAND is called with its
1010 ARGS, where the IDENTIFIER is replaced by the path of the child.
1011 The options are:
1012 • --filter-name=REGEX consider children whose name match the
1014 specified REGEX.
1015 • --unique do not print duplicates (some objects can be reached
1017 via multiple paths, such as clients.focus)
1018 • --recursive print OBJECT and all its children of arbitrary
1020 depth in breadth-first search order. This implicitly activates
1021 --unique.
1022 The exit code is the exit code of the command executed last.
1024 Examples:
1025 • foreach T tags.by-name. echo T
1027 Prints:
1029 tags.by-name.1
1031 tags.by-name.2
1032 tags.by-name.3
1033 [...]
1034 • Note that foreach only iterates over children, but not over
1036 attributes, so foreach S settings echo S prints nothing, since
1037 the settings object has only attributes but no child objects.
1038 • foreach C clients. echo C prints the object paths of all
1040 clients, but the focused client twice, because it is mentioned
1041 in clients. twice: by window id and as clients.focus.
1042 • foreach F tags.focus.tiling.root. --recursive echo F prints the
1044 object paths of all frames on the focused tag.
1045 mktemp [bool|int|string|uint] IDENTIFIER COMMAND [ARGS ...]
1047 Creates a temporary attribute with the given type and replaces all
1048 occurrences of IDENTIFIER in COMMAND and ARGS by the path of the
1049 temporary attribute. The replaced command with its arguments is
1050 executed then. The exit status of COMMAND is returned.
1051 compare ATTRIBUTE OPERATOR VALUE
1053 Compares the value of ATTRIBUTE with VALUE using the comparison
1054 method OPERATOR. If the comparison succeeds, it returns 0, else 1.
1055 The operators are:
1056 • =: ATTRIBUTE's value equals VALUE
1058 • !=: ATTRIBUTE's value does not equal VALUE
1060 • le: ATTRIBUTE's value <= VALUE
1062 • lt: ATTRIBUTE's value < VALUE
1064 • ge: ATTRIBUTE's value >= VALUE
1066 • gt: ATTRIBUTE's value > VALUE
1068 The OPERATORs le,lt,ge,gt can only be used if ATTRIBUTE is of the
1070 type integer or unsigned integer. Note that the first parameter
1071 must always be an attribute and the second a constant value. If you
1072 want to compare two attributes, use the substitute command:
1073 substitute FC tags.focus.frame_count \
1075 compare tags.focus.client_count gt FC
1076 It returns success if there are more clients on the focused tag
1078 than frames.
1079 getenv NAME
1081 Gets the value of the environment variable NAME.
1082 setenv NAME VALUE
1084 Set the value of the environment variable NAME to VALUE. See the
1085 export command for a convenience wrapper.
1086 unsetenv NAME
1088 Unsets the environment variable NAME.
1089 export NAME=VALUE
1091 Set the value of the environment variable NAME to VALUE. The syntax
1092 is the same as for export in unix shells (notice that there is a
1093 =). Intuitively, if you forgot to run export FOO=BAR before
1094 starting herbstluftwm, you can run herbstclient export FOO=BAR from
1095 within your herbstluftwm session for the same effect. The export
1096 command is the same as the setenv command with different syntax.
1097
1099 Rules are used to change default properties for certain clients when
1100 they appear or when the apply_rules command is called. Each rule
1101 matches against a certain subset of all clients and defines a set of
1102 properties for them (called CONSEQUENCEs). A rule can be defined with
1103 this command:
1104 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
1106 Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
1108 optionally, a LABEL. (each of them can be optionally prefixed with two
1109 dashes (--) to provide a more iptables(8)-like feeling).
1110 Each rule can be given a custom label by specifying the LABEL property:
1112 • [--]label=VALUE
1114 If multiple labels are specified, the last one in the list will be
1116 applied. If no label is given, then the rule will be given an integer
1117 name that represents the index of the rule since the last unrule -F
1118 command (which is triggered in the default autostart).
1119 Tip
1121 Rule labels default to an incremental index. These default labels
1122 are unique, unless you assign a different rule a custom integer
1123 LABEL. Default labels can be captured with the printlabel flag.
1124 If a new client appears, herbstluftwm tries to apply each rule to this
1126 new client as follows: If each CONDITION of this rule matches against
1127 this client, then every CONSEQUENCE is executed. (If there are no
1128 conditions given, then this rule is executed for each client)
1129 Each CONDITION consists of a property name, an operator and a value.
1131 Valid operators are:
1132 • ~ matches if client’s property is matched by the regex value.
1134 • = matches if client’s property string is equal to value.
1136 Valid properties are:
1138 instance
1140 the first entry in client’s WM_CLASS.
1141 class
1143 the second entry in client’s WM_CLASS.
1144 title
1146 client’s window title.
1147 pid
1149 the client’s process id (Warning: the pid is not available for
1150 every client. This only matches if the client sets _NET_WM_PID to
1151 the pid itself).
1152 pgid
1154 this client’s process group id. Since the pgid of a window is
1155 derived from its pid the same restrictions apply as above.
1156 maxage
1158 matches if the age of the rule measured in seconds does not exceed
1159 value. This condition only can be used with the = operator. If
1160 maxage already is exceeded (and never will match again), then this
1161 rule is removed. (With this you can build rules that only live for
1162 a certain time.)
1163 windowtype
1165 matches the _NET_WM_WINDOW_TYPE property of a window. If
1166 _NET_WM_WINDOW_TYPE has multiple entries, then only the first entry
1167 is used here.
1168 windowrole
1170 matches the WM_WINDOW_ROLE property of a window if it is set by the
1171 window.
1172 fixedsize (no parameter)
1174 matches if the window does not allow being resized (i.e. if the
1175 minimum size matches the maximum size). This condition does not
1176 take a parameter. Example:
1177 hc rule fixedsize floating=on
1180 Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:
1182 tag
1184 moves the client to tag VALUE.
1185 monitor
1187 moves the client to the tag on monitor VALUE. If the tag
1188 consequence was also specified, and switchtag is set for the
1189 client, move the client to that tag, then display that tag on
1190 monitor VALUE. If the tag consequence was specified, but switchtag
1191 was not, ignore this consequence.
1192 focus
1194 decides whether the client gets the input focus in its tag. The
1195 default is off. VALUE is a boolean (on or off).
1196 switchtag
1198 if focus is activated and the client is put to a not focused tag,
1199 then switchtag tells whether the client’s tag will be shown or not.
1200 If the tag is shown on any monitor but is not focused, the client’s
1201 tag only is brought to the current monitor if
1202 swap_monitors_to_get_tag is activated. VALUE is a boolean (on or
1203 off).
1204 manage
1206 decides whether the client will be managed or not. The default is
1207 on. VALUE is a boolean (on or off).
1208 index
1210 moves the window to a specified index in the tree. VALUE is a
1211 frame index.
1212 floating
1214 sets the floating state of the client. VALUE is a boolean.
1215 pseudotile
1217 sets the pseudotile state of the client. VALUE is a boolean.
1218 ewmhrequests
1220 sets whether the window state (the fullscreen state and the demands
1221 attention flag) can be changed by the application via ewmh itself.
1222 This does not affect the initial fullscreen state requested by the
1223 window. VALUE is a boolean; it defaults to on.
1224 ewmhnotify
1226 sets whether hlwm should let the client know about EMWH changes
1227 (currently only the fullscreen state). If this is set, applications
1228 do not change to their fullscreen-mode while still being
1229 fullscreen. VALUE is a boolean, it defaults to on.
1230 fullscreen
1232 sets the fullscreen flag of the client. VALUE is a boolean.
1233 hook
1235 emits the custom hook rule VALUE WINID when this rule is triggered
1236 by a new window with the id WINID. This consequence can be used
1237 multiple times, which will cause a hook to be emitted for each
1238 occurrence of a hook consequence.
1239 keymask
1241 sets the keymask for a client (see the keymask attribute
1242 documentation).
1243 keys_inactive
1245 sets a regex that determines which key bindings are inactive for a
1246 client (see the keys_inactive attribute documentation).
1247 floatplacement
1249 changes the floating position of a window. The VALUE can be one of
1250 the following:
1251 • none does not change the placement at all
1253 • center centers the window on the monitor
1255 • smart tries to place it with as little overlap to other
1257 floating windows as possible. If there are multiple options
1258 with the least overlap, then the position with the least
1259 overlap to tiling windows is chosen.
1260 floating_geometry
1262 Sets the client’s floating_geometry attribute. The VALUE is a
1263 rectangle, interpreted relatively to the monitor. If floatplacement
1264 is also specified for the client (possibly by another rule), then
1265 only the size of the floating_geometry is used. In order to force
1266 the position from the geometry, it is necessary to add
1267 floatplacement=none.
1268 A rule’s behaviour can be configured by some special FLAGS:
1270 • not: negates the next CONDITION.
1272 • !: same as not.
1274 • once: only apply this rule once (and delete it afterwards).
1276 • printlabel: prints the label of the newly created rule to stdout.
1278 • prepend: prepend the rule to the list of rules instead of appending
1280 it. So its consequences may be overwritten by already existing
1281 rules.
1282 Examples:
1284 • rule --class=Netscape --tag=6 --focus=off
1286 Moves all Netscape instances to tag 6, but doesn’t give focus to
1288 them.
1289 • rule not class~.*[Tt]erm tag=2
1291 Moves all clients to tag 2, if their class does not end with term
1293 or Term.
1294 • rule class=Thunderbird index=/0
1296 Insert all Thunderbird instances in the tree that has no focus and
1298 there in the first child.
1299 • rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
1301 Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE
1303 correctly.
1304
1306 Several commands accept a window as reference, e.g. close. The syntax
1307 is as follows:
1308 • an empty string — or missing argument — references the currently
1310 focused window.
1311 • urgent references some window that is urgent.
1313 • 0xHEXID — where HEXID is some hexadecimal number — references the
1315 window with hexadecimal X11 window id HEXID.
1316 • longest-minimized references the minimized window on the focused
1318 tag that has been minimized for the longest time.
1319 • latest-minimized references the minimized window on the focused tag
1321 that has been minimized most recently.
1322 • DECID — where DECID is some decimal number — references the window
1324 with the decimal X11 window id DECID.
1325
1327 The object tree is a collection of objects with attributes similar to
1328 /sys known from the Linux kernel. Many entities (like tags, monitors,
1329 clients, ...) have objects to access their attributes directly. The
1330 tree is printed by the object_tree command and looks more or less as
1331 follows:
1332 $ herbstclient object_tree
1334 ╾─┐
1335 ├─┐ tags
1336 │ ├─┐ by-name
1337 │ │ ├─╼ 1
1338 │ │ ...
1339 │ │ └─╼ 9
1340 │ └─╼ focus
1341 ├─┐ clients
1342 │ ├─╼ 0x1400022
1343 │ └─╼ focus
1344 └─┐ monitors
1345 ├─╼ by-name
1346 └─╼ focus
1347 To print a subtree starting at a certain object, pass the PATH of the
1349 object to object_tree. The object PATH is the path using the separator
1350 . (dot), e.g. tags.by-name:
1351 $ herbstclient object_tree tags.by-name.
1353 ╾─┐ tags.by-name.
1354 ├─╼ 1
1355 ├─╼ 2
1356 ...
1357 └─╼ 9
1358 To query all attributes and children of a object, pass its PATH to
1360 attr:
1361 $ herbstclient attr tags.
1363 2 children:
1364 by-name.
1365 focus.
1366 1 attributes:
1368 .---- type
1369 | .-- writable
1370 V V
1371 u - count = 9
1372 $ herbstclient attr tags.focus.
1374 0 children.
1375 6 attributes:
1376 .---- type
1377 | .-- writable
1378 V V
1379 s w name = "1"
1380 b w floating = false
1381 i - frame_count = 2
1382 i - client_count = 1
1383 i - curframe_windex = 0
1384 i - curframe_wcount = 1
1385 This already gives an intuition of the output: attr first lists the
1387 names of the child objects and then all attributes, telling for each
1388 attribute:
1389 • its type
1391 • b for boolean
1393 • c for color
1395 • i for integer
1397 • r for regex
1399 • s for string
1401 • u for unsigned integer
1403 • if it is writable by the user: w if yes, - else.
1405 • the name of the attribute
1407 • its current value (only quoted for strings)
1409 To get the unquoted value of a certain attribute, address the attribute
1411 using the same syntax as for object paths and pass it to attr or
1412 get_attr:
1413 $ herbstclient attr clients.focus.title
1415 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1416 $ herbstclient get_attr clients.focus.title
1417 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1418 To change a writable attribute value pass the new value to attr or to
1420 set_attr:
1421 $ herbstclient attr tags.focus.floating
1423 false
1424 $ herbstclient attr tags.focus.floating true
1425 $ herbstclient attr tags.focus.floating
1426 true
1427 $ herbstclient set_attr tags.focus.floating false
1428 $ herbstclient attr tags.focus.floating
1429 false
1430 More information on an attribute or object is given by the help
1432 command:
1433 $ herbstclient help clients.focus
1435 Just look around to get a feeling what is there. The entry point is a
1437 root object that has the following child objects:
1438 autostart:
1440 • string global_path = globalAutostart: Path of the system-wide
1441 autostart, used as a fallback.
1442 • int last_status = 0: the exit status of the last autostart run. if
1444 the autostart is still running, then this status corresponds to the
1445 exit status of the previous autostart invocation.
1446 • string path = autostartFromCmdLine: Custom path to the user’s
1448 autostart path. If it is empty, then the autostart in
1449 $XDG_CONFIG_HOME or $HOME is used.
1450 • uint pid = 0: the process id of the last autostart invocation. Even
1452 if the autostart is not running anymore, its pid is still present
1453 here.
1454 • bool running = false: whether the autostart process (with pid) is
1456 still running.
1457 clients:
1459 The managed windows. For every (managed) window id there is an entry
1460 here.
1461 • dragged: the object of a client which is currently dragged by the
1463 mouse, if any. See the documentation of the mousebind command for
1464 examples. For attributes and children, see clients.focus
1465 • focus: the focused client (only exists if a client is focused). a
1467 managed window
1468 • string class: the class of it (second entry in WM_CLASS)
1470 • Rectangle content_geometry: the geometry of the application
1472 content, that is, not taking the decoration into account. Also,
1473 this is the last window geometry that was reported to the
1474 client application.
1475 • bool decorated = true: whether window border and title are
1477 drawn
1478 • Rectangle decoration_geometry: the geometry of the client,
1480 taking the window decoration into account. The position is the
1481 global window position, that is, relative to the top left
1482 corner of the entire screen
1483 • bool ewmhnotify = true: if the client is told about its state
1485 via ewmh
1486 • bool ewmhrequests = true: if ewmh requests are permitted for
1488 this client
1489 • bool floating = false: whether this client is set as a
1491 (single-window) floating client. If set, the client is floated
1492 above the tiled clients.
1493 • bool floating_effectively = false: whether this client is in
1495 the floating state currently. This is the case if the client’s
1496 tag is set to floating mode or if the client itself is set as
1497 floating. Its value is also indicated via the X11 properties
1498 HLWM_FLOATING_WINDOW and HLWM_TILING_WINDOW.
1499 • Rectangle floating_geometry = 0: the geometry of the client
1501 content if the client is in floating mode. The position is
1502 relative to the monitor and does not take the window decoration
1503 into account.
1504 • bool fullscreen = false: whether this client covers all other
1506 windows and panels on its monitor.
1507 • string instance: the instance of it (first entry in WM_CLASS)
1509 • regex keymask = "": A regular expression that is matched
1511 against the string representation of all key bindings (as they
1512 are printed by list_keybinds). While this client is focused,
1513 only bindings that match the expression will be active. Any
1514 other bindings will be disabled. The default keymask is an
1515 empty string (), which does not disable any keybinding.
1516 • regex keys_inactive = "": A regular expression that describes
1518 which keybindings are inactive while the client is focused. If
1519 a key combination is pressed and its string representation (as
1520 given by list_keybinds) matches the regex, then the key press
1521 is propagated to the client.
1522 • bool minimized = false: whether this client is minimized (also
1524 called iconified).
1525 • int pgid = -1
1527 • int pid = -1: the process id of it (-1 if unset).
1529 • bool pseudotile = false: if activated, the client always has
1531 its floating window size, even if it is in tiling mode.
1532 • bool sizehints_floating = true: if sizehints for this client
1534 should be respected in floating mode
1535 • bool sizehints_tiling = false: if sizehints for this client
1537 should be respected in tiling mode
1538 • string tag: the name of the tag it’s currently on.
1540 • string title = "": its window title
1542 • bool urgent = false: the urgency state (also known as: demands
1544 attention). The focused client can not be urgent.
1545 • bool visible = visible_already: whether this client is rendered
1547 currently
1548 • string winid = "": its window id (as a hexadecimal number with
1550 0x prefix)
1551 • parent_frame: the frame contaning this client if the client is
1553 tiled. For attributes and children, see tags.focus.tiling.root
1554 monitors:
1556 Every monitor is a rectangular part of the screen on which a tag is
1557 shown. These monitors may or may not match the actual outputs. This has
1558 an entry INDEX for each monitor with index INDEX.
1559 • uint count
1561 • by-name: This has an entry name for every object with the given
1563 name. If an object has an empty name then it is not listed here.
1564 • focus: the focused monitor. The monitor is a rectangular part on
1566 the screen that holds precisely one tag at a time. The pad
1567 attributes reserve space on the monitor’s edge for panels, so this
1568 space (given in number of pixels) is never occupied by tiled
1569 clients.
1570 • Rectangle geometry = rect_: the outer geometry of the monitor
1572 • uint index = 0: the monitor’s index (starts at index 0)
1574 • bool lock_tag = false: if activated, then it it is not possible
1576 to switch this monitor to a different tag.
1577 • string name = "": the monitor’s name (can be empty)
1579 • int pad_down = 0: space for panels at the monitor’s lower edge
1581 • int pad_left = 0: space for panels at the monitor’s left edge
1583 • int pad_right = 0: space for panels at the monitor’s right edge
1585 • int pad_up = 0: space for panels at the monitor’s upper edge
1587 • string tag: the name of the tag viewed here
1589 panels:
1591 For every panel window, there is an entry with the panel’s window id
1592 here.
1593 • uint count
1595 • 0xWindowID: a panel is an unmanaged window that reserves space at
1597 the edge of the monitor it is on. The space depends on the
1598 _NET_WM_STRUT defined by the panel. If it is however not defined
1599 explicitly, then the amount of reserved space is inferred from the
1600 window geometry.
1601 • string class: the window class (second entry of WM_CLASS)
1603 • Rectangle geometry: the size and position of the window
1605 • string instance: the window instance (first entry of WM_CLASS)
1607 • WindowID winid = winid: the ID of the panel window
1609 settings:
1611 Settings configure the general behaviour of herbstluftwm and can be
1612 controlled via the set, get and toggle commands. The settings. object
1613 has an attribute for each setting. Many settings are wrappers around
1614 attributes and only remain for compatibility.
1615 • bool always_show_frame = false: If set, all frames are displayed.
1617 If unset, only frames with focus or with windows in them are
1618 displayed.
1619 • bool auto_detect_monitors = false: If set, detect_monitors is
1621 automatically executed every time a monitor is connected,
1622 disconnected or resized.
1623 • bool auto_detect_panels = true: If set, EWMH panels are
1625 automatically detected and reserve space at the side of the
1626 monitors they are on (via pad attributes of each monitor). This
1627 setting is activated per default.
1628 • bool default_direction_external_only = false: This setting controls
1630 the behaviour of focus and shift if no -e or -i argument is given.
1631 If set, then focus and shift changes the focused frame even if
1632 there are other clients in this frame in the specified DIRECTION.
1633 Else, a client within current frame is selected if it is in the
1634 specified DIRECTION.
1635 • LayoutAlgorithm default_frame_layout = vertical: Name of the layout
1637 algorithm, which is used if a new frame is created (on a new tag or
1638 by a non-trivial split). See above for the list of layout
1639 algorithms.
1640 • string ellipsis = ...: string to append when window or tab titles
1642 are shortened to fit in the available space.
1643 • bool focus_crosses_monitor_boundaries = true: If set, commands
1645 focus and shift cross monitor boundaries. If there is no client in
1646 the direction given to focus, then the monitor in the specified
1647 direction is focused. Similarly, if shift cannot move a window
1648 within a tag, the window is moved to the neighbour monitor in the
1649 desired direction.
1650 • bool focus_follows_mouse = false: If set and a window is focused by
1652 mouse cursor, this window is focused (this feature is also known as
1653 sloppy focus). If unset, you need to click to change the window
1654 focus by mouse.
1655 If another window is hidden by the focus change (e.g. when having
1658 pseudotiled windows in the max layout) then an extra click is
1659 required to change the focus.
1660 • bool focus_stealing_prevention = true: If set, only pagers and
1662 taskbars are allowed to change the focus. If unset, all
1663 applications can request a focus change.
1664 • int frame_active_opacity = 100: Focused frame opacity in percent.
1666 Requires a running compositing manager to take actual effect.
1667 • color frame_bg_active_color = black: The fill color of a focused
1669 frame.
1670 • color frame_bg_normal_color = black: The fill color of an unfocused
1672 frame (It is only visible if always_show_frame is set).
1673 • bool frame_bg_transparent = false: If set, the background of frames
1675 are transparent. That means a rectangle is cut out from the inner
1676 such that only the frame border and a stripe of width
1677 frame_transparent_width can be seen. Use frame_active_opacity and
1678 frame_normal_opacity for real transparency.
1679 • color frame_border_active_color = red: The border color of a
1681 focused frame.
1682 • color frame_border_inner_color = black: The color of the inner
1684 border of a frame.
1685 • int frame_border_inner_width = 0: The width of the inner border of
1687 a frame. Must be less than frame_border_width, since it does not
1688 add to the frame border width but is a part of it.
1689 • color frame_border_normal_color = blue: The border color of an
1691 unfocused frame.
1692 • int frame_border_width = 2: Border width of a frame.
1694 • int frame_gap = 5: The gap between frames in the tiling mode.
1696 • int frame_normal_opacity = 100: Unfocused frame opacity in percent.
1698 Requires a running compositing manager to take actual effect.
1699 • int frame_padding = 0: The padding within a frame in the tiling
1701 mode, i.e. the space between the border of a frame and the windows
1702 within it.
1703 • int frame_transparent_width = 0: Specifies the width of the
1705 remaining frame colored with frame_bg_active_color if
1706 frame_bg_transparent is set.
1707 • bool gapless_grid = true: This setting affects the size of the last
1709 client in a frame that is arranged by grid layout. If set, then the
1710 last client always fills the gap within this frame. If unset, then
1711 the last client has the same size as all other clients in this
1712 frame.
1713 • bool hide_covered_windows = false: If activated, windows are
1715 explicitly hidden when they are covered by another window in a
1716 frame with max layout. This only has a visible effect if a
1717 compositor is used. If activated, shadows do not stack up and
1718 transparent windows show the wallpaper behind them instead of the
1719 other clients in the max layout.
1720 • uint monitors_locked = 0: If greater than 0, then the clients on
1722 all monitors aren’t moved or resized anymore. If it is set to 0,
1723 then the arranging of monitors is enabled again, and all monitors
1724 are rearranged if their content has changed in the meantime. You
1725 should not change this setting manually due to concurrency issues;
1726 use the commands lock and unlock instead.
1727 • int mouse_recenter_gap = 0: Specifies the gap around a monitor. If
1729 the monitor is selected and the mouse position would be restored
1730 into this gap, it is set to the center of the monitor. This is
1731 useful, when the monitor was left via mouse movement, but is
1732 reselected by keyboard. If the gap is 0 (default), the mouse is
1733 never recentered.
1734 • int pseudotile_center_threshold = 10: If greater than 0, it
1736 specifies the least distance between a centered pseudotile window
1737 and the border of the frame or tile it is assigned to. If this
1738 distance is lower than pseudotile_center_threshold, it is aligned
1739 to the top left of the client’s tile.
1740 • bool raise_on_click = true: If set, a window is raised if it is
1742 clicked. The value of this setting is only noticed in floating
1743 mode.
1744 • bool raise_on_focus = false: If set, a window is raised if it is
1746 focused. The value of this setting is only used in floating mode.
1747 • bool raise_on_focus_temporarily = false: If set, a window is raised
1749 temporarily if it is focused on its tag. Temporarily in this case
1750 means that the window will return to its previous stacking position
1751 if another window is focused.
1752 • bool smart_frame_surroundings = false: If set, frame borders and
1754 gaps will be removed when there’s no ambiguity regarding the
1755 focused frame.
1756 • bool smart_window_surroundings = false: If set, window borders and
1758 gaps will be removed and minimal when there’s no ambiguity
1759 regarding the focused window. This minimal window decoration can be
1760 configured by the theme.minimal object.
1761 • int snap_distance = 10: If a client is dragged in floating mode,
1763 then it snaps to neighbour clients if the distance between them is
1764 smaller than snap_distance.
1765 • int snap_gap = 5: Specifies the remaining gap if a dragged client
1767 snaps to an edge in floating mode. If snap_gap is set to 0, no gap
1768 will remain.
1769 • bool swap_monitors_to_get_tag = true: If set: If you want to view a
1771 tag, that already is viewed on another monitor, then the monitor
1772 contents will be swapped and you see the wanted tag on the focused
1773 monitor. If not set, the other monitor is focused if it shows the
1774 desired tag.
1775 • bool tabbed_max = true: if activated, multiple windows in a frame
1777 with the max layout algorithm are drawn as tabs.
1778 • string tree_style = "*| +`--.": It contains the chars that are used
1780 to print a nice ascii tree. It must contain at least 8 characters.
1781 e.g. X|:#+*-. produces a tree like:
1782 X-.
1784 #-. child 0
1785 | #-* child 00
1786 | +-* child 01
1787 +-. child 1
1788 : #-* child 10
1789 : +-* child 11
1790 Useful values for tree_style are: ╾│ ├└╼─┐ or -| |'--. or ╾│
1792 ├╰╼─╮.
1793 • bool update_dragged_clients = false: If set, a client's window
1795 content is resized immediately during resizing it with the mouse.
1796 If unset, the client's content is resized after the mouse button is
1797 released.
1798 • bool verbose = false: If set, verbose output is logged to
1800 herbstluftwm’s stderr. The default value is controlled by the
1801 --verbose command line flag.
1802 • color window_border_active_color: Border color of a focused window.
1804 Warning: This only exists for compatibility reasons; it is only an
1807 alias for the attribute theme.active.color.
1808 • color window_border_inner_color: Color of the inner border of a
1810 window. Warning: This only exists for compatibility reasons; it is
1811 only an alias for the attribute theme.inner_color.
1812 • int window_border_inner_width: The width of the inner border of a
1814 window. Must be less than window_border_width, since it does not
1815 add to the window border width but is a part of it.
1816 Warning: This only exists for compatibility reasons; it is only an
1819 alias for the attribute theme.inner_width.
1820 • color window_border_normal_color: Border color of an unfocused
1822 window.
1823 Warning: This only exists for compatibility reasons; it is only an
1826 alias for the attribute theme.normal.color.
1827 • color window_border_urgent_color: Border color of an unfocused but
1829 urgent window.
1830 Warning: This only exists for compatibility reasons; it is only an
1833 alias for the attribute theme.urgent.color.
1834 • int window_border_width: Border width of a window.
1836 Warning: This only exists for compatibility reasons; it is only an
1839 alias for the attribute theme.border_width.
1840 • int window_gap = 0: The gap between windows within one frame in the
1842 tiling mode.
1843 • string wmname = herbstluftwm: It controls the value of the
1845 _NET_WM_NAME property on the root window, which specifies the name
1846 of the running window manager. The value of this setting is not
1847 updated if the actual _NET_WM_NAME property on the root window is
1848 changed externally. Example usage:
1849 • cycle_value wmname herbstluftwm LG3D
1853 tags:
1855 The tags (or virtual desktops or workspaces). This contains an entry
1856 index for each tag with the given index.
1857 • uint count
1859 • by-name: For attributes and children, see monitors.by-name
1861 • focus: the object of the focused tag, equivalently, the tag on the
1863 focused monitor.
1864 • int client_count: the number of clients on this tag
1867 • int curframe_wcount: number of clients in the selected frame
1869 • int curframe_windex: index of the focused client in the
1871 selected frame
1872 • bool floating = false: if the entire tag is set to floating
1874 mode
1875 • bool floating_focused = false: if the floating layer is focused
1877 (otherwise the tiling layer is)
1878 • int frame_count: the number of frames on this tag
1880 • uint index = 0: index of this tag (the first index is 0)
1882 • string name = name_: name of the tag (must be non-empty)
1884 • int urgent_count: the number of urgent clients on this tag
1886 • bool visible = false: if this tag is shown on some monitor
1888 • focused_client: For attributes and children, see clients.focus
1890 • tiling:
1892 • focused_frame: The focused frame (leaf) in this frame tree.
1895 For attributes and children, see tags.focus.tiling.root
1896 • root can be a frame leaf.
1898 • LayoutAlgorithm algorithm
1901 • int client_count
1903 • string index
1905 • int selection
1907 • root can be a frame split.
1909 • decimal fraction
1912 • string index
1914 • int selection
1916 • SplitAlign split_type
1918 • 0 can be a frame leaf. For attributes and children, see
1920 tags.focus.tiling.root
1921 • 0 can be a frame split. For attributes and children,
1923 see tags.focus.tiling.root
1924 • 1 can be a frame leaf. For attributes and children, see
1926 tags.focus.tiling.root
1927 • 1 can be a frame split. For attributes and children,
1929 see tags.focus.tiling.root
1930 theme:
1932 inner_color/inner_width
1933 ╻ outer_color/outer_width
1934 │ ╻
1935 │ │
1936 ┌────╴│╶─────────────────┷─────┐ ⎫ border_width
1937 │ │ color │ ⎬ + title_height + title_depth
1938 │ ┌──┷─────────────────────┐ │ ⎭ + padding_top
1939 │ │====================....│ │
1940 │ │== window content ==....│ │
1941 │ │====================..╾──────── background_color
1942 │ │........................│ │
1943 │ └────────────────────────┘ │ ⎱ border_width +
1944 └──────────────────────────────┘ ⎰ padding_bottom
1945 Setting an attribute of the theme object just propagates the value to
1947 the respective attribute of the tiling and the floating object. If the
1948 title area is divided into tabs, then the not selected tabs can be
1949 styled using the tab_... attributes. If these attributes are empty,
1950 then the colors are taken from the theme of the client to which the tab
1951 refers to.
1952 • color background_color = black: color behind window contents
1954 visible on resize
1955 • uint border_width = 0: the base width of the border
1957 • color color = black: the basic background color of the border
1959 • color inner_color = black: color of the inner border
1961 • uint inner_width = 0: width of the border around the clients
1963 content
1964 • color outer_color = black: color of the outer border
1966 • uint outer_width = 0: width of an border close to the edge
1968 • uint padding_bottom = 0: additional border width on the bottom
1970 • uint padding_left = 0: additional border width on the left
1972 • uint padding_right = 0: additional border width on the right
1974 • uint padding_top = 0: additional border width on the top
1976 • string reset: writing this resets all attributes to a default value
1978 • MaybeColor tab_color = Inherit: if non-empty, the color of
1980 non-urgent and unfocused tabs
1981 • MaybeColor tab_outer_color = Inherit: if non-empty, the outer
1983 border color of non-urgent and unfocused tabs; if empty, the colors
1984 are taken from the tab’sclient decoration settings.
1985 • MaybeULong tab_outer_width = Inherit: if non-empty, the outer
1987 border width of non-urgent and unfocused tabs
1988 • MaybeColor tab_title_color = Inherit: if non-empty, the title color
1990 of non-urgent and unfocused tabs
1991 • bool tight_decoration = false: specifies whether the size hints
1993 also affect the window decoration or only the window contents of
1994 tiled clients (requires enabled sizehints_tiling)
1995 • TextAlign title_align = left: the horizontal alignment of the title
1997 within the tab or title bar. The value is one of: left, center,
1998 right
1999 • color title_color = black
2001 • int title_depth = 0: the space below the baseline of the window
2003 title
2004 • font title_font = fixed
2006 • uint title_height = 0
2008 • TitleWhen title_when = always: when to show the window title:
2010 always, never, if the the client is in a tabbed scenario like a max
2011 frame (one_tab), if there are multiple_tabs to be shown.
2012 • active: configures the decoration of the focused client.
2014 • color background_color = black: color behind window contents
2017 visible on resize
2018 • uint border_width = 0: the base width of the border
2020 • color color = black: the basic background color of the border
2022 • color inner_color = black: color of the inner border
2024 • uint inner_width = 0: width of the border around the clients
2026 content
2027 • color outer_color = black: color of the outer border
2029 • uint outer_width = 0: width of an border close to the edge
2031 • uint padding_bottom = 0: additional border width on the bottom
2033 • uint padding_left = 0: additional border width on the left
2035 • uint padding_right = 0: additional border width on the right
2037 • uint padding_top = 0: additional border width on the top
2039 • string reset: writing this resets all attributes to a default
2041 value
2042 • MaybeColor tab_color = Inherit: if non-empty, the color of
2044 non-urgent and unfocused tabs
2045 • MaybeColor tab_outer_color = Inherit: if non-empty, the outer
2047 border color of non-urgent and unfocused tabs; if empty, the
2048 colors are taken from the tab’sclient decoration settings.
2049 • MaybeULong tab_outer_width = Inherit: if non-empty, the outer
2051 border width of non-urgent and unfocused tabs
2052 • MaybeColor tab_title_color = Inherit: if non-empty, the title
2054 color of non-urgent and unfocused tabs
2055 • bool tight_decoration = false: specifies whether the size hints
2057 also affect the window decoration or only the window contents
2058 of tiled clients (requires enabled sizehints_tiling)
2059 • TextAlign title_align = left: the horizontal alignment of the
2061 title within the tab or title bar. The value is one of: left,
2062 center, right
2063 • color title_color = black
2065 • int title_depth = 0: the space below the baseline of the window
2067 title
2068 • font title_font = fixed
2070 • uint title_height = 0
2072 • TitleWhen title_when = always: when to show the window title:
2074 always, never, if the the client is in a tabbed scenario like a
2075 max frame (one_tab), if there are multiple_tabs to be shown.
2076 • floating: behaves analogously to tiling.
2078 • color background_color = black: color behind window contents
2081 visible on resize
2082 • uint border_width = 0: the base width of the border
2084 • color color = black: the basic background color of the border
2086 • color inner_color = black: color of the inner border
2088 • uint inner_width = 0: width of the border around the clients
2090 content
2091 • color outer_color = black: color of the outer border
2093 • uint outer_width = 0: width of an border close to the edge
2095 • uint padding_bottom = 0: additional border width on the bottom
2097 • uint padding_left = 0: additional border width on the left
2099 • uint padding_right = 0: additional border width on the right
2101 • uint padding_top = 0: additional border width on the top
2103 • string reset: writing this resets all attributes to a default
2105 value
2106 • MaybeColor tab_color = Inherit: if non-empty, the color of
2108 non-urgent and unfocused tabs
2109 • MaybeColor tab_outer_color = Inherit: if non-empty, the outer
2111 border color of non-urgent and unfocused tabs; if empty, the
2112 colors are taken from the tab’sclient decoration settings.
2113 • MaybeULong tab_outer_width = Inherit: if non-empty, the outer
2115 border width of non-urgent and unfocused tabs
2116 • MaybeColor tab_title_color = Inherit: if non-empty, the title
2118 color of non-urgent and unfocused tabs
2119 • bool tight_decoration = false: specifies whether the size hints
2121 also affect the window decoration or only the window contents
2122 of tiled clients (requires enabled sizehints_tiling)
2123 • TextAlign title_align = left: the horizontal alignment of the
2125 title within the tab or title bar. The value is one of: left,
2126 center, right
2127 • color title_color = black
2129 • int title_depth = 0: the space below the baseline of the window
2131 title
2132 • font title_font = fixed
2134 • uint title_height = 0
2136 • TitleWhen title_when = always: when to show the window title:
2138 always, never, if the the client is in a tabbed scenario like a
2139 max frame (one_tab), if there are multiple_tabs to be shown.
2140 • active: configures the decoration of the focused client. For
2142 attributes and children, see theme.active
2143 • normal: the default decoration scheme for clients. For
2145 attributes and children, see theme.active
2146 • urgent: configures the decoration of urgent clients. For
2148 attributes and children, see theme.active
2149 • fullscreen: configures clients in fullscreen state. For attributes
2151 and children, see theme.floating
2152 • minimal: configures clients with minimal decorations triggered by
2154 smart_window_surroundings. For attributes and children, see
2155 theme.floating
2156 • normal: the default decoration scheme for clients. For attributes
2158 and children, see theme.active
2159 • tiling: configures the decoration of tiled clients, setting one of
2161 its attributes propagates the respective attribute of the active,
2162 normal and urgent child objects. For attributes and children, see
2163 theme.floating
2164 • urgent: configures the decoration of urgent clients. For attributes
2166 and children, see theme.active
2167 types:
2169 This lists the types that are used for attributes and command
2170 arguments.
2171 • bool: Type representing boolean values, i.e. an on or off state,
2173 with aliases true and false. When writing to a boolean value, one
2174 can also specify toggle in order to alter its value.
2175 • string fullname: the full and unique name of this type
2178 • string shortname: A short (one-character long) name of this
2180 type which is used in the output of the attr command
2181 • color: Type representing colors. A color can be defined in one of
2183 the following formats:
2184 1. #RRGGBB where R, G, B are hexidecimal digits (0-9, A-F), and
2186 RR, GG, BB represent the values for red, green, blue.
2187 2. #RRGGBBAA represents a color with alpha-value AA. The alpha
2189 value 00 is fully transparent and FF is fully
2190 opaque/intransparent.
2191 3. a common color name like red, blue, orange, etc. For attributes
2193 and children, see types.bool
2194 • decimal: Fixed precision decimal numbers, e.g. 0.34. For attributes
2196 and children, see types.bool
2197 • font: A font specification (font family with modifiers regarding
2199 size, weight, etc.) in one of the following formats:
2200 • Fontconfig description. This supports antialiased fonts, for
2204 example:
2205 • Dejavu Sans:pixelsize=12
2207 • Bitstream Vera Sans:size=12:bold
2209 • X logical font description (XLFD), as provided by the xfontsel
2211 tool. No antialiasing is supported here, but this is usually
2212 superior for bitmap fonts. For example:
2213 • -*-fixed-medium-r-*-*-13-*-*-*-*-*-*-* for a standard
2215 bitmap font available on most systems. For attributes and
2216 children, see types.bool
2217 • int: Type representing signed integers. When overwriting an
2219 integer, you can increase or decrease its value relatively by
2220 writing +=N or -=N where N is an integer. So for example, writing
2221 +=3 to an attribute increases its value by 3. For attributes and
2222 children, see types.bool
2223 • names: A fixed set of names, depending on the context, e.g. names
2225 of layout algorithms or the split type of a non-leaf frame (which
2226 is only horizontal or vertical). For attributes and children, see
2227 types.bool
2228 • rectangle: A rectangle on the screen consisting of a size and the
2230 position on the screen. The format is WxH+X+Y where W is the width,
2231 H is the height, and X and Y are the coordinates of the top left
2232 corner of the rectangle: X is the number of pixels to the left
2233 screen edge and Y is the number of pixels to the top screen edge.
2234 (if X or Y is negative, then the + turns into -). For example:
2235 800x600+800+0 or 400x200-10+30. For attributes and children, see
2236 types.bool
2237 • regex: A POSIX extended regular expression. Note that when passing
2239 a regex on the command line, additional quoting can be necessary.
2240 For explanations and examples, see section 9.4.6 of the
2241 documentation:
2242 https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04_06.
2243 For attributes and children, see types.bool
2244 • string: Type representing normal text. For attributes and children,
2246 see types.bool
2247 • uint: Type representing unsigned (i.e. non-negative) integers. When
2249 overwriting an integer, you can increase or decrease its value
2250 relatively by writing +=N or -=N where N is an integer. For
2251 attributes and children, see types.bool
2252 • windowid: The window id is the number of a window. This can be a
2254 managed window (i.e. client) or an unmanaged window (e.g. a panel,
2255 a menu, or a desktop window). The default format is 0xHEX where HEX
2256 is a hexadecimal number (digits 0-9 and a-f) but it can also be
2257 specified in the decimal system (base 10), or as an octal number
2258 (with prefix 0 and base 8). When a window id is printed, it is
2259 always printed in the 0xHEX format and without any leading zeroes.
2260 For attributes and children, see types.bool
2261 watchers:
2263 • uint count: the number of attributes that are watched
2264
2266 There is no configuration file but an autostart file, which is executed
2267 on startup. It is also executed on command reload. If not specified by
2268 the --autostart argument, autostart file is located at
2269 $XDG_CONFIG_HOME/herbstluftwm/autostart or at
2270 ~/.config/herbstluftwm/autostart. Normally it consists of a few
2271 herbstclient calls. If executing the autostart file in a user’s home
2272 fails the global autostart file (mostly placed at
2273 /etc/xdg/herbstluftwm/autostart) is executed as a fallback.
2274 For a quick install, copy the default autostart file to
2276 ~/.config/herbstluftwm/.
2277
2279 On special events, herbstluftwm emits some hooks (with parameters). You
2280 can receive or wait for them with herbstclient(1). Also custom hooks
2281 can be emitted with the emit_hook command. The following hooks are
2282 emitted by herbstluftwm itself:
2283 attribute_changed PATH OLDVALUE NEWVALUE
2285 The attribute PATH was changed from OLDVALUE to NEWVALUE. Requires
2286 that the attribute PATH has been passed to the watch command
2287 before.
2288 fullscreen [on|off] WINID
2290 The fullscreen state of window WINID was changed to [on|off].
2291 tag_changed TAG MONITOR
2293 The tag TAG was selected on MONITOR.
2294 focus_changed WINID TITLE
2296 The window WINID was focused. Its window title is TITLE.
2297 window_title_changed WINID TITLE
2299 The title of the focused window was changed. Its window id is WINID
2300 and its new title is TITLE.
2301 tag_flags
2303 The flags (i.e. urgent or filled state) have been changed.
2304 tag_added TAG
2306 A tag named TAG was added.
2307 tag_removed TAG
2309 The tag named TAG was removed.
2310 tag_renamed OLD NEW
2312 The tag name changed from OLD to NEW.
2313 urgent [on|off] WINID
2315 The urgent state of client with given WINID has been changed to
2316 [on|off].
2317 rule NAME WINID
2319 A window with the id WINID appeared which triggered a rule with the
2320 consequence hook=NAME.
2321 There are also other useful hooks, which never will be emitted by
2323 herbstluftwm itself, but which can be emitted with the emit_hook
2324 command:
2325 quit_panel
2327 Tells a panel to quit. The default panel.sh quits on this hook.
2328 Many scripts are using this hook.
2329 reload
2331 Tells all daemons that the autostart file is reloaded — and tells
2332 them to quit. This hook should be emitted in the first line of
2333 every autostart file.
2334
2336 Every tag has its own stack of clients that are on this tag. Similar to
2337 the EWMH specification each tag stack contains several layers, which
2338 are from top to bottom:
2339 • the focused client (if raise_on_focus_temporarily is enabled)
2341 • clients in fullscreen
2343 • normal clients
2345 • frame decorations
2347 All monitors are managed in one large stack which only consists of the
2349 stacks of the visible tags put above each other. The stacking order of
2350 these monitors is independent from their indices and can be modified
2351 using the raise_monitor command. The current stack is illustrated by
2352 the stack command.
2353
2355 As far as possible, herbstluftwm tries to be EWMH compliant. That
2356 includes:
2357 • Information about tag names and client lists is provided.
2359 • Desktop windows from desktop environments are not managed and kept
2361 below the other windows.
2362 • Client requests like getting focused are only processed if the
2364 setting focus_stealing_prevention is disabled.
2365 Moreover, herbstluftwm sets the X11 properties HLWM_FLOATING_WINDOW and
2367 HLWM_TILING_WINDOW to indicate whether a window is in floating or
2368 tiling mode, that is, the value of the client’s floating_effectively
2369 attribute.
2370
2372 DISPLAY
2373 Specifies the DISPLAY to use.
2374
2376 The following files are used by herbstluftwm:
2377 • autostart, see section AUTOSTART FILE.
2379
2381 Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
2382 wmexec fails.
2383
2385 See the herbstluftwm Github issues:
2386 https://github.com/herbstluftwm/herbstluftwm/issues
2387
2389 Feel free to join the IRC channel #herbstluftwm on irc.libera.chat.
2390
2392 herbstluftwm was written by Thorsten Wißmann. All contributors are
2393 listed in the herbstluftwm distribution AUTHORS file.
2394
2396 Homepage: http://herbstluftwm.org
2397 Github page: http://github.com/herbstluftwm/herbstluftwm
2399 Patch submission and bug reporting:
2401 hlwm@lists.herbstluftwm.org
2403
2405 Copyright 2011-2020 Thorsten Wißmann. All rights reserved.
2406 This software is licensed under the "Simplified BSD License". See
2408 LICENSE for details.
2409 herbstluftwm 0.9.4 2022-03-16 HERBSTLUFTWM(1)