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 -c, --autostart PATH
19 use PATH as autostart file instead of the one in $XDG_CONFIG_HOME
20 -v, --version
22 print version and exit
23 -l, --locked
25 Initially set the monitors_locked setting to 1
26 --verbose
28 print verbose information to stderr
29 This manual documents the scripting and configuration interface. For a
31 more verbose introduction see herbstluftwm-tutorial(7).
32
34 The basic tiling concept is that the layout is represented by a binary
35 tree. On startup you see one big frame across the entire screen. A
36 frame fulfills exactly one of the following conditions:
37 1. Frame contains windows:
39 It shows some clients and arranges them. The current layout
41 algorithms are:
42 · 0: vertical - clients are placed below each other
44 · 1: horizontal - clients are placed next to each other
46 · 2: max - all clients are maximized in this frame
48 · 3: grid - clients are arranged in an almost quadratic grid
50 2. Frame is split into subframes:
52 It is split into exactly two subframes in a configurable fraction
54 either in a vertical or horizontal way. So it produces two frames
55 which fulfill the same conditions (new frames always are about to
56 contain windows). If you split a frame that already contains
57 windows, the windows are inherited by the first new child frame.
58 If a new window appears, it is put in the currently focused frame. Only
60 the leaves of the frame tree can be focused.
61 A frame can be removed, it is then merged with its neighbour frame. Due
63 to the layout structure of a binary tree, each frame (i.e. node in
64 binary tree) has exactly one neighbour.
65 The analogy to a binary tree is explained the best way with a small
67 example: On startup you have a simple binary tree, with one frame that
68 can contain clients:
69 C
71 When splitting it (e.g. with the command split vertical 0.5) you will
73 get this:
74 V
76 / \
77 C C
78 You also can split the left frame horizontally and you will get:
80 V
82 / \
83 H C
84 / \
85 C C
86 If you change the focus to the client on the right and remove this
88 frame, it will be merged with the left subtree and you will get:
89 H
91 / \
92 C C
93 The layout command prints the current layout of all tags as a tree.
95
97 The exact position of a frame in the layout tree may be described by
98 its index which is just a string of characters. The lookup algorithm
99 starts at the root frame and selects one of its two subtrees according
100 to the each character in the index.
101 The characters are interpreted as follows:
103 · 0: select the first subtree
105 · 1: select the second subtree
107 · .: select the subtree having the focus
109 · /: select the subtree not having the focus
111 Thus an empty string refers to the root frame, and "00" refers to the
113 first subtree of the first subtree of the root frame.
114 As a special case, the string "@" always refers to the currently
116 focused frame.
117
119 Tags are very similar to workspaces, virtual desktops or window groups.
120 Each tag has one layout. There is a list of tags. You can add or remove
121 tags dynamically.
122
124 Monitors in herbstluftwm are totally independent of the actual physical
125 screens. This means you can for example split your screen in two
126 virtual monitors to view two tags at once on a big screen.
127 Each monitor displays exactly one tag on a specified rectangle on the
129 screen.
130 Each monitor may have a name, which can be set via add_monitor and
132 rename_monitor. It can be unset with the rename_monitor command. A
133 monitor name is an arbitrary non-empty string which must not start with
134 +, - or any digit.
135 A monitor can be referenced in different ways:
137 · by its absolute index as listed in the list_monitors command.
139 · by its relative index: a + or - followed by a delta, e.g.: +3
141 · by its relative position to the focused monitor. -l denotes the
143 monitor left of the focused monitor, -r right of, -u above of, and
144 -d below of, respectively.
145 · by "" (an empty string) which represents the current monitor.
147 · by its name.
149
151 herbstluftwm is controlled by internal commands, which can be executed
152 via herbstclient(1) or via keybindings.
153 quit
155 Quits herbstluftwm.
156 reload
158 Executes the autostart file.
159 version
161 Prints the version of the running herbstluftwm instance.
162 echo [ARGS ...]
164 Prints all given ARGS separated by a single space and a newline
165 afterwards.
166 true
168 Ignores all arguments and always returns success, i.e. 0.
169 false
171 Ignores all arguments and always returns failure, i.e. 1.
172 list_commands
174 Lists all available commands.
175 list_monitors
177 List currently configured monitors with their index, area (as
178 rectangle), name (if named) and currently viewed tag.
179 list_rules
181 Lists all active rules. Each line consists of all the parameters
182 the rule was called with, plus its label, separated by tabs.
183 list_keybinds
185 Lists all bound keys with their associated command. Each line
186 consists of one key combination and the command with its parameters
187 separated by tabs.
188 Warning
190 Tabs within command parameters are not escaped!
191 lock
193 Increases the monitors_locked setting. Use this if you want to do
194 multiple window actions at once (i.e. without repainting between
195 the single steps). See also: unlock
196 unlock
198 Decreases the monitors_locked setting. If monitors_locked is
199 changed to 0, then all monitors are repainted again. See also: lock
200 keybind KEY COMMAND [ARGS ...]
202 Adds a key binding. When KEY is pressed, the internal COMMAND (with
203 its ARGS) is executed. A key binding is a (possibly empty) list of
204 modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl,
205 Shift) and one key (see keysymdef.h for a list of keys). Modifiers
206 and the key are concatenated with - or + as separator. If there is
207 already a binding for this KEY, it will be overwritten. Examples:
208 · keybind Mod4+Ctrl+q quit
210 · keybind Mod1-i toggle always_show_frame
212 · keybind Mod1-Shift-space cycle_layout -1
214 keyunbind KEY|-F|--all
216 Removes the key binding for KEY. The syntax for KEY is defined in
217 keybind. If -F or --all is given, then all key bindings will be
218 removed.
219 mousebind BUTTON ACTION [COMMAND ...]
221 Adds a mouse binding for the floating mode. When BUTTON is pressed,
222 the specified ACTION will be performed. BUTTON has a similar
223 syntax to the KEY argument of keybind: It consists of a list of
224 modifiers (separated by - or +, valid modifiers are listed in the
225 description of keybind) and exactly one button name:
226 · B1 or Button1
228 · B2 or Button2
230 · B3 or Button3
232 · B4 or Button4
234 · B5 or Button5
236 ACTION must be one of the following actions:
238 · move: Moves the window by dragging the cursor.
240 · resize: Resizes the window by dragging a corner.
242 · zoom: Resizes the window into all four directions while keeping
244 the center of the window constant.
245 · call: Only calls the specified COMMAND while client.dragged
247 links to the client on which the BUTTON has been performed.
248 While an ACTION is performed, client.dragged is the client which is
250 dragged. E.g.:
251 · mousebind Mod1-Button3 zoom
253 · mousebind Mod1-B4 call substitute WID clients.dragged.winid
255 spawn transset-df --inc -i WID 0.05
256 · mousebind Mod1-B5 call substitute WID clients.dragged.winid
258 spawn transset-df --dec -i WID -m 0.2 0.05
259 mouseunbind
261 Removes all mouse bindings.
262 spawn EXECUTABLE [ARGS ...]
264 Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp.
265 Example:
266 · spawn xterm -e man 3 execvp
268 wmexec [WINDOWMANAGER [ARGS ...]]
270 Executes the WINDOWMANAGER with its ARGS. This is useful to switch
271 the window manager in the running session without restarting the
272 session. If no or an invalid WINDOWMANAGER is given, then
273 herbstluftwm is restarted. For details see man 3 execvp. Example:
274 · wmexec openbox
276 chain SEPARATOR [COMMANDS ...]
278 chain expects a SEPARATOR and a list of COMMANDS with arguments.
279 The commands have to be separated by the specified SEPARATOR. The
280 SEPARATOR can by any word and only is recognized as the separator
281 between commands if it exactly matches SEPARATOR. "chain" outputs
282 the appended outputs of all commands and returns the exit code of
283 the last executed command. Examples are:
284 · Create a tag called "foo" and directly use it:
286 chain , add foo , use foo
288 · Rotate the layout clockwise:
290 chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
292 Counterexamples are:
294 · This will only create a tag called "foo,":
296 chain , add foo, use foo
298 · Separator "." defined, but "," is used:
300 chain . add foo , use foo
302 and SEPARATOR [COMMANDS ...]
304 "and" behaves like the chain command but only executes the
305 specified COMMANDS while the commands return the exit code 0.
306 or SEPARATOR [COMMANDS ...]
308 "or" behaves like the chain command but only executes the specified
309 COMMANDS until one command returns the exit code 0.
310 ! COMMAND
312 "!" executes the provided command, but inverts its return value. If
313 the provided command returns a nonzero, "!" returns a 0, if the
314 command returns a zero, "!" returns a 1.
315 try COMMAND
317 "try" executes the provided command, prints its output, but always
318 returns success, i.e. 0.
319 silent COMMAND
321 "silent" executes the provided command, but discards its output and
322 only returns its exit code.
323 focus_nth INDEX
325 Focuses the nth window in a frame. The first window has INDEX 0. If
326 INDEX is negative or greater than the last window index, then the
327 last window is focused.
328 cycle [DELTA]
330 Cycles the selection within the current frame by DELTA. If DELTA is
331 omitted, DELTA = 1 will be used. DELTA can be negative; DELTA = -1
332 means: cycle in the opposite direction by 1.
333 cycle_all [--skip-invisible] [DIRECTION]
335 Cycles through all windows and frames on the current tag.
336 DIRECTION = 1 means forward, DIRECTION = -1 means backward,
337 DIRECTION = 0 has no effect. DIRECTION defaults to 1. If there are
338 multiple windows within on frame, then it acts similar to the cycle
339 command. (The cycle_all command focuses the next/previous leave in
340 the layout tree.). If --skip-invisible is given, then this only
341 cycles through all visible windows and skips invisible windows in
342 the max layout. The focused window is raised.
343 cycle_frame [DIRECTION]
345 Cycles through all frames on the current tag. DIRECTION = 1 means
346 forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
347 effect. DIRECTION defaults to 1.
348 cycle_layout [DELTA [LAYOUTS ...]]
350 Cycles the layout algorithm in the current frame by DELTA. DELTA
351 defaults to 1. You can find a list of layout algorithms above. If a
352 list of LAYOUTS is given, cycle_layout will cycle through those
353 instead of the default layout algorithm list. Each layout name
354 should occur at most once. Example:
355 · cycle_layout -1
357 · cycle_layout 1 vertical grid
359 set_layout LAYOUT
361 Sets the layout algorithm in the current frame to LAYOUT. For the
362 list of layouts, check the list of layout algorithms above.
363 close WINID
365 Closes the specified window gracefully or the focused window if
366 none is given explicitly. See the section on WINDOW IDS how to
367 reference a certain window.
368 close_or_remove
370 Closes the focused window or removes the current frame if no window
371 is focused.
372 split ALIGN [FRACTION]
374 Splits the focused frame into two subframes with a specified
375 FRACTION between 0 and 1 which defaults to 0.5. ALIGN is one of
376 · top
379 · bottom (= vertical)
381 · left,
383 · right (= horizontal)
385 · explode
387 · auto (split along longest side)
389 It specifies which of the two halves will be empty after the
391 split. The other half will be occupied by the currently focused
392 frame. After splitting, the originally focuse frame will stay
393 focused. One special ALIGN mode is explode, which splits the
394 frame in such a way that the window sizes and positions are
395 kept as much as possible. If no FRACTION is given to explode
396 mode an optimal fraction is picked automatically. Example:
397 · split explode
399 · split bottom 0.5
401 · split horiz 0.3
403 · split vertical 0.5
405 · split h
407 focus [-i|-e] DIRECTION
409 Moves the focus from current frame to the next frame or client in
410 DIRECTION which is in:
411 · l[eft]
414 · r[ight]
416 · u[p]
418 · d[own]
420 If -i (internal) is given or default_direction_external_only is
422 unset, then the next client in DIRECTION can also be within the
423 same frame. If there is no client within this frame or -e
424 (external) is given, then the next frame in specified DIRECTION
425 will be focused.
426 The direction between frames is defined as follows: The focus is in
428 a leaf of the binary tree. Each inner node in the tree remembers
429 the last focus direction (child 0 or child 1). The algorithm uses
430 the shortest possible way from the leaf (the currently focused
431 frame) to the root until it is possible to change focus in the
432 specified DIRECTION. From there the focus goes back to the leaf.
433 Example: The focus is at frame A. After executing focus right focus
435 will be at frame C.
436 Tree: V,0 Screen: .-----..-----. (before)
438 / \ | B || C |
439 / \ '-----''-----'
440 H,1 H,0 .-----..-----.
441 / \ / \ | A* || D |
442 A* B C D '-----''-----'
443 Tree: V,0 Screen: .-----..-----. (after focus right)
445 / \ | B || C* |
446 / \ '-----''-----'
447 H,1 H,0 .-----..-----.
448 / \ / \ | A || D |
449 A B C* D '-----''-----'
450 If the currently focused client is floated, then the next floating
452 window in the specified direction is focused and raised.
453 If focus_crosses_monitor_boundaries is set and no client or frame
455 is found in the specified DIRECTION, then the next monitor in that
456 DIRECTION is focused.
457 focus_edge [-i|-e] DIRECTION
459 Focuses the window on the edge of the tag in the specified
460 DIRECTION. The DIRECTIONS and -e behave as specified at the focus
461 command.
462 If -i (internal) is given or default_direction_external_only is
464 unset, then the window on the edge of the tag will be focused.
465 Else, only the frame on the edge of the tag will be focused, and
466 the window that was last focused in that frame will be focused.
467 raise WINID
469 Raises the specified window. See the section on WINDOW IDS on how
470 to reference a certain window. Its result is only visible in
471 floating mode.
472 Tip
474 The WINID also can specify an unmanaged window, although the
475 completion for the raise command does not list the IDs of unmanaged
476 windows.
477 jumpto WINID
479 Puts the focus to the specified window. See the section on WINDOW
480 IDS on how to reference a certain window.
481 bring WINID
483 Moves the specified window to the current frame and focuses it. See
484 the section on WINDOW IDS on how to reference a certain window.
485 resize DIRECTION FRACTIONDELTA
487 Changes the next fraction in specified DIRECTION by FRACTIONDELTA.
488 DIRECTION behaves as specified at the focus command. You should not
489 omit the sign - or +, because in future versions, the behaviour may
490 change if the sign is omitted. Example:
491 · resize right +0.05
493 · resize down -0.1
495 shift_edge [-i|-e] DIRECTION
497 Shifts the focused window to the the edge of a tag in the specified
498 DIRECTION. The DIRECTIONS behave as specified at the focus command
499 and -i and -e behave as specified at the focus_edge command.
500 shift [-i|-e] DIRECTION
502 Shifts the focused window to the next frame in the specified
503 DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
504 focus command. If the focused client is floated instead of being
505 tiled, then client is shifted to the next window or screen edge.
506 shift_to_monitor MONITOR
508 Moves the focused window to the tag on the specified MONITOR.
509 remove
511 Removes focused frame and merges its windows to its neighbour
512 frame.
513 rotate
515 Rotates the layout on the focused tag counterclockwise by 90
516 degrees. This only manipulates the alignment of frames, not the
517 content of them.
518 set NAME VALUE
520 Sets the specified setting NAME to VALUE. All SETTINGS are listed
521 in the section below.
522 get NAME
524 Prints the value of setting NAME. All SETTINGS are listed in the
525 section below.
526 toggle NAME
528 Toggles the setting NAME if it’s an integer setting: If its value
529 is unequal to 0, it becomes 0; else its previous value (which was
530 unequal to 0) is restored.
531 cycle_value NAME VALUES ...
533 Cycles value of the setting NAME through VALUES: I.e. it searches
534 the first occurrence of the current value in VALUES and changes the
535 value to the next in the list or to the first one if the end is
536 reached or current value wasn’t found. Example:
537 · cycle_value frame_gap 0 5 10 15
539 · cycle_value frame_bg_normal_color red green blue
541 cycle_monitor [DELTA]
543 Cycles monitor focused by DELTA. DELTA defaults to 1.
544 focus_monitor MONITOR
546 Puts focus to the specified monitor.
547 add TAG
549 Creates a new empty tag named TAG.
550 use TAG
552 Switches the focused monitor to specified TAG.
553 use_index INDEX [--skip-visible]
555 Switches the focused monitor to the TAG with the specified INDEX.
556 If INDEX starts with + or -, then INDEX is treated relative to the
557 current TAG. If --skip-visible is passed and INDEX is relative,
558 then tags that are already visible on a monitor are skipped. E.g.
559 this cycles backwards through the tags:
560 · use_index -1 --skip-visible
562 use_previous
564 Switches the focused monitor to the previously viewed tag.
565 merge_tag TAG [TARGET]
567 Removes tag named TAG and moves all its windows to tag TARGET. If
568 TARGET is omitted, the focused tag will be used.
569 rename OLDTAG NEWTAG
571 Renames tag named OLDTAG to NEWTAG.
572 move TAG
574 Moves the focused window to the tag named TAG.
575 move_index INDEX [--skip-visible]
577 Moves the focused window to the tag specified by INDEX. Analogical
578 to the argument for use_index: If INDEX starts with + or -, then it
579 is treated relative. If --skip-visible is passed with a relative
580 index, then already visible tags are skipped.
581 lock_tag [MONITOR]
583 Lock the tag switching on the specified monitor. If no argument is
584 given, the currently focused monitor is used. When the tag
585 switching is disabled for a monitor, the commands use and use_index
586 have no effect when executed there. When swap_monitors_to_get_tag
587 is enabled, switching to a tag which is located on a locked
588 monitor, switches to that monitor instead of stealing it from
589 there. The lock state of a monitor is indicated by "[LOCKED]" in
590 the list_monitors output.
591 unlock_tag [MONITOR]
593 Re-enables the tag switching on the specified monitor. If no
594 argument is given, the currently focused monitor is used. This is
595 the reverse operation to lock_tag and has no further side effects
596 but removing this lock.
597 disjoin_rects RECTS ...
599 Takes a list of rectangles and splits them into smaller pieces
600 until all rectangles are disjoint, the result rectangles are
601 printed line by line. This command does not modify the current list
602 of monitors! So this can be useful in combination with the
603 set_monitors command.
604 · E.g. disjoin_rects 600x400+0+0 600x400+300+250 prints this:
606 300x150+300+250
608 600x250+0+0
609 300x150+0+250
610 300x150+600+250
611 600x250+300+400
612 · In the above example two monitors are split into 5 monitors,
614 which graphically means:
615 11111111 11111111
617 1 222222222 333222224444
618 1 2 1 2 disjoin 3 32 24 4
619 11121111 2 --------> 333222224444
620 2 2 555555555
621 222222222 555555555
622 set_monitors RECTS ...
624 Sets the list of monitors exactly to the list of given rectangles:
625 · The i’th existing monitor is moved to the i’th given RECT
627 · New monitors are created if there are more RECTS then monitors
629 · Existing monitors are deleted if there are more monitors then
631 RECTS
632 detect_monitors -l|--list|--no-disjoin
634 Sets the list of monitors to the available Xinerama monitors. If
635 the Xinerama extension is missing, it will fall back to one monitor
636 across the entire screen. If the detected monitors overlap, the
637 will be split into more monitors that are disjoint but cover the
638 same area using disjoin_rects.
639 If -l or --list is passed, the list of rectangles of detected
641 pyhsical monitors is printed. So hc detect_monitors is equivalent
642 to the bash command hc set_monitors $(hc disjoin_rects $(hc
643 detect_monitors -l)).
644 add_monitor RECT [TAG [NAME]]
646 Adds a monitor on the specified rectangle RECT and displays TAG on
647 it. TAG currently must not be displayed on any other monitor.
648 RECT is a string of the form WxH±X±Y. If no or an empty TAG is
649 given, then any free tag will be chosen. If a NAME is given, you
650 can reference to this monitor by its name instead of using an
651 index. Example:
652 · add_monitor 1024x768-20+0 mynewtag main
654 remove_monitor MONITOR
656 Removes the specified monitor.
657 move_monitor MONITOR RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
659 Moves the specified monitor to rectangle RECT. RECT is defined as
660 in add_monitor. If no or an empty pad is given, it is not changed.
661 raise_monitor [MONITOR]
663 Raises the specified monitor or the current one if MONITOR is
664 omitted.
665 rename_monitor MONITOR NAME
667 (Re)names an already existing monitor. If NAME is empty, it removes
668 the monitor’s name.
669 stack
671 Prints the stack of monitors with the visible tags and their layers
672 as a tree. The order of the printed stack is top to bottom. The
673 style is configured by the tree_style setting.
674 monitor_rect [[-p] MONITOR]
676 Prints the rectangle of the specified monitor in the format: X Y W
677 H If no MONITOR or cur is given, then the current monitor is used.
678 If -p is supplied, then the remaining rect without the pad around
679 this monitor is printed.
680 pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
682 Sets the pad of specified monitor to the specified padding. If no
683 or an empty padding is given, it is not changed.
684 list_padding [MONITOR]
686 Lists the padding of the specified monitor, or the currently
687 focused monitor if no monitor is given.
688 layout [TAG [INDEX]]
690 Prints the layout of frame with INDEX on TAG, in a nice tree style.
691 Its style is defined by the tree_style setting. If no TAG is given,
692 the current tag is used. If no INDEX is given, the root frame is
693 used. To specify INDEX without specifying TAG (i.e. use current
694 tag), pass an empty string as TAG.
695 An example output is:
697 ╾─┐ horizontal 50% selection=1
699 ├─╼ vertical: 0xe00009
700 └─┐ vertical 50% selection=0
701 ├─╼ vertical: 0xa00009 [FOCUS]
702 └─╼ vertical: 0x1000009
703 dump [TAG [INDEX]]
705 Prints the same information as the layout command but in a machine
706 readable format. Its output can be read back with the load command.
707 An example output (formatted afterwards) is:
709 (split horizontal:0.500000:1
711 (clients vertical:0 0xe00009)
712 (split vertical:0.500000:1
713 (clients vertical:0 0xa00009)
714 (clients vertical:0 0x1000009)))
715 load [TAG] LAYOUT
717 Loads a given LAYOUT description to specified TAG or current tag if
718 no TAG is given.
719 Caution
721 LAYOUT is exactly one parameter. If you are calling it manually
722 from your shell or from a script, quote it properly!
723 complete POSITION [COMMAND ARGS ...]
725 Prints the result of tab completion for the partial COMMAND with
726 optional ARGS. You usually do not need this, because there is
727 already tab completion for bash. Example:
728 · complete 0 m
730 prints all commands beginning with m
732 · complete 1 toggle fra
734 prints all settings beginning with fra that can be toggled
736 complete_shell POSITION [COMMAND ARGS ...]
738 Behaves like complete with the following extras, useful for
739 completion on posix shells:
740 · Escape sequences are removed in COMMAND and ARGS.
742 · A space is appended to each full completion result.
744 · Special characters will be escaped in the output.
746 emit_hook ARGS ...
748 Emits a custom hook to all idling herbstclients.
749 tag_status [MONITOR]
751 Print a tab separated list of all tags for the specified MONITOR
752 index. If no MONITOR index is given, the focused monitor is used.
753 Each tag name is prefixed with one char, which indicates its state:
754 · . the tag is empty
756 · : the tag is not empty
758 · + the tag is viewed on the specified MONITOR, but this monitor
760 is not focused.
761 · # the tag is viewed on the specified MONITOR and it is focused.
763 · - the tag is viewed on a different MONITOR, but this monitor is
765 not focused.
766 · % the tag is viewed on a different MONITOR and it is focused.
768 · ! the tag contains an urgent window
770 Warning
772 If you use a tab in one of the tag names, then tag_status is
773 probably quite useless for you.
774 floating [[TAG] on|off|toggle|status]
776 Changes the current tag to floating/tiling mode on specified TAG or
777 prints it current status. If no TAG is given, the current tag is
778 used. If no argument is given, floating mode is toggled. If status
779 is given, then on or off is printed, depending of the floating
780 state of TAG.
781 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
783 Defines a rule which will be applied to all new clients. Its
784 behaviour is described in the RULES section.
785 unrule LABEL|--all|-F
787 Removes all rules named LABEL. If --all or -F is passed, then all
788 rules are removed.
789 fullscreen [on|off|toggle]
791 Sets or toggles the fullscreen state of the focused client. If no
792 argument is given, fullscreen mode is toggled.
793 pseudotile [on|off|toggle]
795 Sets or toggles the pseudotile state of the focused client. If a
796 client is pseudotiled, then in tiling mode the client is only moved
797 but not resized - the client size will stay the floating size. The
798 only reason to resize the client is to ensure that it fits into its
799 tile. If no argument is given, pseudotile mode is toggled.
800 object_tree [PATH]
802 Prints the tree of objects. If the object path PATH is given, only
803 the subtree starting at PATH is printed. See the OBJECTS section
804 for more details.
805 attr [PATH [NEWVALUE]
807 Prints the children and attributes of the given object addressed by
808 PATH. If PATH is an attribute, then print the attribute value. If
809 NEWVALUE is given, assign NEWVALUE to the attribute given by PATH.
810 See the OBJECTS section for more details.
811 get_attr ATTRIBUTE
813 Print the value of the specified ATTRIBUTE as described in the
814 OBJECTS section.
815 set_attr ATTRIBUTE NEWVALUE
817 Assign NEWVALUE to the specified ATTRIBUTE as described in the
818 OBJECTS section.
819 new_attr [bool|color|int|string|uint] PATH
821 Creates a new attribute with the name and in the object specified
822 by PATH. Its type is specified by the first argument. The attribute
823 name has to begin with my_.
824 remove_attr PATH
826 Removes the user defined attribute PATH.
827 substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
829 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
830 ARGS by the value of the ATTRIBUTE. Note that the COMMAND also is
831 replaced by the attribute value if it equals IDENTIFIER. The
832 replaced command with its arguments then is executed. Example:
833 · substitute MYTITLE clients.focus.title echo MYTITLE Prints the
835 title of the currently focused window.
836 sprintf IDENTIFIER FORMAT [ATTRIBUTES ...] COMMAND [ARGS ...]
838 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
839 ARGS by the string specified by FORMAT. Each %s in FORMAT stands
840 for the value of the next attribute in ATTRIBUTES, similar to the
841 printf(1) command. The replaced command with its arguments then is
842 executed. Examples:
843 · sprintf STR title=%s clients.focus.title echo STR Prints the
845 title of the currently focused window prepended by title=.
846 · sprintf X tag=%s tags.focus.name rule once X Moves the next
848 client that appears to the tag that is currently focused.
849 · sprintf X %s/%s tags.focus.index tags.count echo X Tells which
851 tag is focused and how many tags there are
852 · sprintf l somelongstring echo l l l Prints somelongstring three
854 times, separated by spaces.
855 mktemp [bool|int|string|uint] IDENTIFIER COMMAND [ARGS ...]
857 Creates a temporary attribute with the given type and replaces all
858 occurrences of IDENTIFIER in COMMAND and ARGS by by the path of the
859 temporary attribute. The replaced command with its arguments is
860 executed then. The exit status of COMMAND is returned.
861 compare ATTRIBUTE OPERATOR VALUE
863 Compares the value of ATTRIBUTE with VALUE using the comparation
864 method OPERATOR. If the comparation succeeds, it returns 0, else 1.
865 The operators are:
866 · =: ATTRIBUTE's value equals VALUE
868 · !=: ATTRIBUTE's value does not equal VALUE
870 · le: ATTRIBUTE's value <= VALUE
872 · lt: ATTRIBUTE's value < VALUE
874 · ge: ATTRIBUTE's value >= VALUE
876 · gt: ATTRIBUTE's value > VALUE
878 The OPERATORsle,lt,ge,gt can only be used if ATTRIBUTE is of the
880 type integer or unsigned integer. Note that the first parameter
881 must always be an attribute and the second a constant value. If you
882 want to compare two attributes, use the substitute command:
883 substitute FC tags.focus.frame_count \
885 compare tags.focus.client_count gt FC
886 It returns success if there are more clients on the focused tag
888 than frames.
889 getenv NAME
891 Gets the value of the environment variable NAME.
892 setenv NAME VALUE
894 Set the value of the environment variable NAME to VALUE.
895 unsetenv NAME
897 Unsets the environment variable NAME.
898
900 Settings configure the behaviour of herbstluftwm and can be controlled
901 via the set, get and toggle commands. There are two types of settings:
902 Strings and integer values. An integer value is set, if its value is 1
903 or another value unequal to 0. An integer value is unset, if its value
904 is 0.
905 frame_gap (Integer)
907 The gap between frames in the tiling mode.
908 frame_padding (Integer)
910 The padding within a frame in the tiling mode, i.e. the space
911 between the border of a frame and the windows within it.
912 window_gap (Integer)
914 The gap between windows within one frame in the tiling mode.
915 snap_distance (Integer)
917 If a client is dragged in floating mode, then it snaps to neighbour
918 clients if the distance between them is smaller then snap_distance.
919 snap_gap (Integer)
921 Specifies the remaining gap if a dragged client snaps to an edge in
922 floating mode. If snap_gap is set to 0, no gap will remain.
923 mouse_recenter_gap (Integer)
925 Specifies the gap around a monitor. If the monitor is selected and
926 the mouse position would be restored into this gap, it is set to
927 the center of the monitor. This is useful, when the monitor was
928 left via mouse movement, but is reselected by keyboard. If the gap
929 is 0 (default), the mouse is never recentered.
930 frame_border_active_color (String/Color)
932 The border color of a focused frame.
933 frame_border_normal_color (String/Color)
935 The border color of an unfocused frame.
936 frame_border_inner_color (String/Color)
938 The color of the inner border of a frame.
939 frame_bg_active_color (String/Color)
941 The fill color of a focused frame.
942 frame_bg_normal_color (String/Color)
944 The fill color of an unfocused frame (It is only visible if
945 always_show_frame is set).
946 frame_bg_transparent (Integer)
948 If set, the background of frames are transparent. That means a
949 rectangle is cut out frome the inner such that only the frame
950 border and a stripe of width frame_transparent_width can be seen.
951 Use frame_active_opacity and frame_normal_opacity for real
952 transparency.
953 frame_transparent_width (Integer)
955 Specifies the width of the remaining frame colored with
956 frame_bg_active_color if frame_bg_transparent is set.
957 frame_border_width (Integer)
959 Border width of a frame.
960 frame_border_inner_width (Integer)
962 The width of the inner border of a frame. Must be less than
963 frame_border_width, since it does not add to the frame border width
964 but is a part of it.
965 focus_crosses_monitor_boundaries (Integer)
967 If set, the focus command crosses monitor boundaries. If there is
968 no client in the direction given to focus, then the monitor in the
969 specified direction is focused.
970 raise_on_focus (Integer)
972 If set, a window is raised if it is focused. The value of this
973 setting is only used in floating mode.
974 raise_on_focus_temporarily (Integer)
976 If set, a window is raised temporarily if it is focused on its tag.
977 Temporarily in this case means that the window will return to its
978 previous stacking position if another window is focused.
979 raise_on_click (Integer)
981 If set, a window is raised if it is clicked. The value of this
982 setting is only noticed in floating mode.
983 window_border_width (Integer)
985 Border width of a window.
986 window_border_inner_width (Integer)
988 The width of the inner border of a window. Must be less than
989 window_border_width, since it does not add to the window border
990 width but is a part of it.
991 window_border_active_color (String/Color)
993 Border color of a focused window.
994 window_border_normal_color (String/Color)
996 Border color of an unfocused window.
997 window_border_urgent_color (String/Color)
999 Border color of an unfocused but urgent window.
1000 window_border_inner_color (String/Color)
1002 Color of the inner border of a window.
1003 always_show_frame (Integer)
1005 If set, all frames are displayed. If unset, only frames with focus
1006 or with windows in it are displayed.
1007 frame_active_opacity (Integer)
1009 Focused frame opacity in percent. Requires a running compositing
1010 manager to take actual effect.
1011 frame_normal_opacity (Integer)
1013 Unfocused frame opacity in percent. Requires a running compositing
1014 manager to take actual effect.
1015 default_frame_layout (Integer)
1017 Index of the frame layout, which is used if a new frame is created
1018 (by split or on a new tag). For a list of valid indices and their
1019 meanings, check the list of layout algorithms above.
1020 default_direction_external_only (Integer)
1022 This setting controls the behaviour of focus and shift if no -e or
1023 -i argument is given. if set, then focus and shift changes the
1024 focused frame even if there are other clients in this frame in the
1025 specified DIRECTION. Else, a client within current frame is
1026 selected if it is in the specified DIRECTION.
1027 gapless_grid (Integer)
1029 This setting affects the size of the last client in a frame that is
1030 arranged by grid layout. If set, then the last client always fills
1031 the gap within this frame. If unset, then the last client has the
1032 same size as all other clients in this frame.
1033 smart_frame_surroundings (Integer)
1035 If set, frame borders and gaps will be removed when there’s no
1036 ambiguity regarding the focused frame.
1037 smart_window_surroundings (Integer)
1039 If set, window borders and gaps will be removed and minimal when
1040 there’s no ambiguity regarding the focused window. This minimal
1041 window decoration can be configured by the theme.minimal object.
1042 focus_follows_mouse (Integer)
1044 If set and a window is focused by mouse cursor, this window is
1045 focused (this feature is also known as sloppy focus). If unset, you
1046 need to click to change the window focus by mouse.
1047 If another window is hidden by the focus change (e.g. when having
1049 pseudotiled windows in the max layout) then an extra click is
1050 required to change the focus.
1051 focus_stealing_prevention (Integer)
1053 If set, only pagers and taskbars are allowed to change the focus.
1054 If unset, all applications can request a focus change.
1055 monitors_locked (Integer)
1057 If greater than 0, then the clients on all monitors aren’t moved or
1058 resized anymore. If it is set to 0, then the arranging of monitors
1059 is enabled again, and all monitors are rearranged if their content
1060 has changed in the meantime. You should not change this setting
1061 manually due to concurrency issues; use the commands lock and
1062 unlock instead.
1063 swap_monitors_to_get_tag (Integer)
1065 If set: If you want to view a tag, that already is viewed on
1066 another monitor, then the monitor contents will be swapped and you
1067 see the wanted tag on the focused monitor. If not set, the other
1068 monitor is focused if it shows the desired tag.
1069 auto_detect_monitors (Integer)
1071 If set, detect_monitors is automatically executed every time a
1072 monitor is connected, disconnected or resized.
1073 tree_style (String)
1075 It contains the chars that are used to print a nice ascii tree. It
1076 must contain at least 8 characters. e.g. X|:#+*-. produces a tree
1077 like:
1078 X-.root
1080 #-. child 0
1081 | #-* child 01
1082 | +-* child 02
1083 +-. child 1
1084 : #-* child 10
1085 : +-* child 01
1086 Useful values for tree_style are: ╾│ ├└╼─┐ or -| |'--. or ╾│
1088 ├╰╼─╮.
1089 wmname (String)
1091 It controls the value of the _NET_WM_NAME property on the root
1092 window, which specifies the name of the running window manager. The
1093 value of this setting is not updated if the actual _NET_WM_NAME
1094 property on the root window is changed externally. Example usage:
1095 · cycle_value wmname herbstluftwm LG3D
1097 pseudotile_center_threshold (Int)
1099 If greater than 0, it specifies the least distance between a
1100 centered pseudotile window and the border of the frame or tile it
1101 is assigned to. If this distance is lower than
1102 pseudotile_center_threshold, it is aligned to the top left of the
1103 client’s tile.
1104 update_dragged_clients (Int)
1106 If set, a client’s window content is resized immediately during
1107 resizing it with the mouse. If unset, the client’s content is
1108 resized after the mouse button are released.
1109
1111 Rules are used to change default properties for certain clients when
1112 they appear. Each rule matches against a certain subset of all clients
1113 and defines a set of properties for them (called CONSEQUENCEs). A rule
1114 can be defined with this command:
1115 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
1117 Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
1119 optionally, a LABEL. (each of them can be optionally prefixed with two
1120 dashes (--) to provide a more iptables(8)-like feeling).
1121 Each rule can be given a custom label by specifying the LABEL property:
1123 · [--]label=VALUE
1125 If multiple labels are specified, the last one in the list will be
1127 applied. If no label is given, then the rule will be given an integer
1128 name that represents the index of the rule since the last unrule -F
1129 command (which is triggered in the default autostart).
1130 Tip
1132 Rule labels default to an incremental index. These default labels
1133 are unique, unless you assign a different rule a custom integer
1134 LABEL. Default labels can be captured with the printlabel flag.
1135 If a new client appears, herbstluftwm tries to apply each rule to this
1137 new client as follows: If each CONDITION of this rule matches against
1138 this client, then every CONSEQUENCE is executed. (If there are no
1139 conditions given, then this rule is executed for each client)
1140 Each CONDITION consists of a property name, an operator and a value.
1142 Valid operators are:
1143 · ~ matches if client’s property is matched by the regex value.
1145 · = matches if client’s properly string is equal to value.
1147 Valid properties are:
1149 instance
1151 the first entry in client’s WM_CLASS.
1152 class
1154 the second entry in client’s WM_CLASS.
1155 title
1157 client’s window title.
1158 pid
1160 the client’s process id (Warning: the pid is not available for
1161 every client. This only matches if the client sets _NET_WM_PID to
1162 the pid itself).
1163 maxage
1165 matches if the age of the rule measured in seconds does not exceed
1166 value. This condition only can be used with the = operator. If
1167 maxage already is exceeded (and never will match again), then this
1168 rule is removed. (With this you can build rules that only live for
1169 a certain time.)
1170 windowtype
1172 matches the _NET_WM_WINDOW_TYPE property of a window.
1173 windowrole
1175 matches the WM_WINDOW_ROLE property of a window if it is set by the
1176 window.
1177 Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:
1179 tag
1181 moves the client to tag VALUE.
1182 monitor
1184 moves the client to the tag on monitor VALUE. If the tag
1185 consequence was also specified, and switchtag is set for the
1186 client, move the client to that tag, then display that tag on
1187 monitor VALUE. If the tag consequence was specified, but switchtag
1188 was not, ignore this consequence.
1189 focus
1191 decides whether the client gets the input focus on his tag. The
1192 default is off. VALUE can be on, off or toggle.
1193 switchtag
1195 if focus is activated and the client is put to a not focused tag,
1196 then switchtag tells whether the client’s tag will be shown or not.
1197 If the tag is shown on any monitor but is not focused, the client’s
1198 tag only is brought to the current monitor if
1199 swap_monitors_to_get_tag is activated. VALUE can be on, off or
1200 toggle.
1201 manage
1203 decides whether the client will be managed or not. The default is
1204 on. VALUE can be on, off or toggle.
1205 index
1207 moves the window to a specified index in the tree. VALUE is a
1208 frame index.
1209 pseudotile
1211 sets the pseudotile state of the client. VALUE can be on, off or
1212 toggle.
1213 ewmhrequests
1215 sets whether the window state (the fullscreen state and the demands
1216 attention flag) can be changed by the application via ewmh itself.
1217 This does not affect the initial fullscreen state requested by the
1218 window. VALUE can be on, off or toggle, it defaults to on.
1219 ewmhnotify
1221 sets whether hlwm should let the client know about EMWH changes
1222 (currently only the fullscreen state). If this is set, applications
1223 do not change to their fullscreen-mode while still being
1224 fullscreen. VALUE can be on, off or toggle, it defaults to on.
1225 fullscreen
1227 sets the fullscreen flag of the client. VALUE can be on, off or
1228 toggle.
1229 hook
1231 emits the custom hook ruleVALUEWINID when this rule is triggered by
1232 a new window with the id WINID. This consequence can be used
1233 multiple times, which will cause a hook to be emitted for each
1234 occurrence of a hook consequence.
1235 keymask
1237 Sets the keymask for an client. A keymask is an regular expression
1238 that is matched against the string represenation (see
1239 list_keybinds). If it matches the keybinding is active when this
1240 client is focused, otherwise it is disabled. The default keymask is
1241 an empty string (""), which does not disable any keybinding.
1242 A rule’s behaviour can be configured by some special FLAGS:
1244 · not: negates the next CONDITION.
1246 · !: same as not.
1248 · once: only apply this rule once (and delete it afterwards).
1250 · printlabel: prints the label of the newly created rule to stdout.
1252 · prepend: prepend the rule to the list of rules instead of appending
1254 it. So its consequences may be overwritten by already existing
1255 rules.
1256 Examples:
1258 · rule --class=Netscape --tag=6 --focus=off Moves all Netscape
1260 instances to tag 6, but doesn’t give focus to them.
1261 · rule not class~.*[Tt]erm tag=2 Moves all clients to tag 2, if their
1263 class does not end with term or Term.
1264 · rule class=Thunderbird index=/0 Insert all Thunderbird instances in
1266 the tree that has no focus and there in the first child.
1267 · rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on Sets focus
1269 to new dialogs which set their _NET_WM_WINDOW_TYPE correctly.
1270
1272 Several commands accept a window as reference, e.g. close. The syntax
1273 is as follows:
1274 · an empty string — or missing argument — references the currently
1276 focused window.
1277 · urgent references some window that is urgent.
1279 · 0xHEXID — where HEXID is some hexadecimal number — references the
1281 window with hexadecimal X11 window id is HEXID.
1282 · DECID — where DECID is some decimal number — references the window
1284 with the decimal X11 window id DECID.
1285
1287 Warning
1288 The object tree is not stable yet, i.e. its interface may change
1289 until the next stable release. So check this documentation again
1290 after upgrading the next time.
1291 The object tree is a collection of objects with attributes similar to
1293 /sys known from the Linux kernel. Many entities (like tags, monitors,
1294 clients, ...) have objects to access their attributes directly. The
1295 tree is printed by the object_tree command and looks more or less as
1296 follows:
1297 $ herbstclient object_tree
1299 ╾─┐
1300 ├─┐ tags
1301 │ ├─┐ by-name
1302 │ │ ├─╼ 1
1303 │ │ ...
1304 │ │ └─╼ 9
1305 │ └─╼ focus
1306 ├─┐ clients
1307 │ ├─╼ 0x1400022
1308 │ └─╼ focus
1309 └─┐ monitors
1310 ├─╼ by-name
1311 └─╼ focus
1312 To print a subtree starting at a certain object, pass the PATH of the
1314 object to object_tree. The object PATH is the path using the separator
1315 . (dot), e.g. tags.by-name:
1316 $ herbstclient object_tree tags.by-name.
1318 ╾─┐ tags.by-name.
1319 ├─╼ 1
1320 ├─╼ 2
1321 ...
1322 └─╼ 9
1323 To query all attributes and children of a object, pass its PATH to
1325 attr:
1326 $ herbstclient attr tags.
1328 2 children:
1329 by-name.
1330 focus.
1331 1 attributes:
1333 .---- type
1334 | .-- writeable
1335 V V
1336 u - count = 9
1337 $ herbstclient attr tags.focus.
1339 0 children.
1340 6 attributes:
1341 .---- type
1342 | .-- writeable
1343 V V
1344 s w name = "1"
1345 b w floating = false
1346 i - frame_count = 2
1347 i - client_count = 1
1348 i - curframe_windex = 0
1349 i - curframe_wcount = 1
1350 This already gives an intuition of the output: attr first lists the
1352 names of the child objects and then all attributes, telling for each
1353 attribute:
1354 · its type
1356 · s for string
1358 · i for integer
1360 · b for boolean
1362 · u for unsigned integer
1364 · if it is writeable by the user: w if yes, - else.
1366 · the name of the attribute
1368 · its current value (only quoted for strings)
1370 To get the unquoted value of a certain attribute, address the attribute
1372 using the same syntax as for object paths and pass it to attr or
1373 get_attr:
1374 $ herbstclient attr clients.focus.title
1376 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1377 $ herbstclient get_attr clients.focus.title
1378 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1379 To change a writeable attribute value pass the new value to attr or to
1381 set_attr:
1382 $ herbstclient attr tags.focus.floating
1384 false
1385 $ herbstclient attr tags.focus.floating true
1386 $ herbstclient attr tags.focus.floating
1387 true
1388 $ herbstclient set_attr tags.focus.floating false
1389 $ herbstclient attr tags.focus.floating
1390 false
1391 Just look around to get a feeling what is there. The detailed tree
1393 content is listed as follows:
1394 · tags: subtree for tags.
1396 ┌──────────┬────────────────┐
1398 │u - count │ number of tags │
1399 └──────────┴────────────────┘
1400 · by-name
1402 · TAG: a object for each tag with the name TAG
1404 ┌────────────────────┬────────────────────────────┐
1406 │s w name │ name of the tag │
1407 ├────────────────────┼────────────────────────────┤
1408 │b w floating │ if it is in floating mode │
1409 ├────────────────────┼────────────────────────────┤
1410 │i - index │ index of this tag │
1411 ├────────────────────┼────────────────────────────┤
1412 │i - frame_count │ number of frames │
1413 ├────────────────────┼────────────────────────────┤
1414 │i - client_count │ number of clients on this │
1415 │ │ tag │
1416 ├────────────────────┼────────────────────────────┤
1417 │i - curframe_windex │ index of the focused │
1418 │ │ client in the select frame │
1419 ├────────────────────┼────────────────────────────┤
1420 │i - curframe_wcount │ number of clients in the │
1421 │ │ selected frame │
1422 └────────────────────┴────────────────────────────┘
1423 · focus: the object of the focused tag
1425 · clients
1427 · WINID: a object for each client with its WINID
1429 ┌───────────────────────┬────────────────────────────┐
1431 │s - winid │ its window id │
1432 ├───────────────────────┼────────────────────────────┤
1433 │s - title │ its window title │
1434 ├───────────────────────┼────────────────────────────┤
1435 │s - tag │ the tag it’s currently on │
1436 ├───────────────────────┼────────────────────────────┤
1437 │i - pid │ the process id of it (-1 │
1438 │ │ if unset) │
1439 ├───────────────────────┼────────────────────────────┤
1440 │s - class │ the class of it (second │
1441 │ │ entry in WM_CLASS) │
1442 ├───────────────────────┼────────────────────────────┤
1443 │s - instance │ the instance of it (first │
1444 │ │ entry in WM_CLASS) │
1445 ├───────────────────────┼────────────────────────────┤
1446 │b w fullscreen │ │
1447 ├───────────────────────┼────────────────────────────┤
1448 │b w pseudotile │ │
1449 ├───────────────────────┼────────────────────────────┤
1450 │b w ewmhrequests │ if ewmh requests are │
1451 │ │ permitted for this client │
1452 ├───────────────────────┼────────────────────────────┤
1453 │b w ewmhnotify │ if the client is told │
1454 │ │ about its state via ewmh │
1455 ├───────────────────────┼────────────────────────────┤
1456 │b w urgent │ its urgent state │
1457 ├───────────────────────┼────────────────────────────┤
1458 │b w sizehints_tiling │ if sizehints for this │
1459 │ │ client should be respected │
1460 │ │ in tiling mode │
1461 ├───────────────────────┼────────────────────────────┤
1462 │b w sizehints_flaoting │ if sizehints for this │
1463 │ │ client should be respected │
1464 │ │ in floating mode │
1465 └───────────────────────┴────────────────────────────┘
1466 · focus: the object of the focused client, if any
1468 · dragged: the object of a client which is dragged by the mouse,
1470 if any. See the documentation of the mousebind command for
1471 examples.
1472 · monitors
1474 ┌──────────┬────────────────────┐
1476 │u - count │ number of monitors │
1477 └──────────┴────────────────────┘
1478 · INDEX: a object for each monitor with its INDEX
1480 · by-name
1482 · NAME: a object for each named monitor
1484 ┌─────────────┬──────────────────────────┐
1486 │s - name │ its name │
1487 ├─────────────┼──────────────────────────┤
1488 │i - index │ its index │
1489 ├─────────────┼──────────────────────────┤
1490 │s - tag │ the tag currently viewed │
1491 │ │ on it │
1492 ├─────────────┼──────────────────────────┤
1493 │b - lock_tag │ │
1494 └─────────────┴──────────────────────────┘
1495 · focus: the object of the focused monitor
1497 · settings has an attribute for each setting. See SETTINGS for a
1499 list.
1500 · theme has attributes to configure the window decorations. theme
1502 and many of its child objects have the following attributes
1503 ┌─────────────────────┬────────────────────────────┐
1505 │i w border_width │ the base width of the │
1506 │ │ border │
1507 ├─────────────────────┼────────────────────────────┤
1508 │i w padding_top │ additional border width on │
1509 │ │ the top │
1510 ├─────────────────────┼────────────────────────────┤
1511 │i w padding_right │ on the right │
1512 ├─────────────────────┼────────────────────────────┤
1513 │i w padding_bottom │ on the bottom │
1514 ├─────────────────────┼────────────────────────────┤
1515 │i w padding_left │ and on the left of the │
1516 │ │ border │
1517 ├─────────────────────┼────────────────────────────┤
1518 │c w color │ the basic background color │
1519 │ │ of the border │
1520 ├─────────────────────┼────────────────────────────┤
1521 │i w inner_width │ width of the border around │
1522 │ │ the clients content │
1523 ├─────────────────────┼────────────────────────────┤
1524 │c w inner_color │ its color │
1525 ├─────────────────────┼────────────────────────────┤
1526 │i w outer_width │ width of an additional │
1527 │ │ border close to the edge │
1528 ├─────────────────────┼────────────────────────────┤
1529 │c w outer_color │ its color │
1530 ├─────────────────────┼────────────────────────────┤
1531 │c w background_color │ color behind window │
1532 │ │ contents visible on resize │
1533 ├─────────────────────┼────────────────────────────┤
1534 │s w reset │ Writing this resets all │
1535 │ │ attributes to a default │
1536 │ │ value │
1537 └─────────────────────┴────────────────────────────┘
1538 inner_color/inner_width
1540 ╻ outer_color/outer_width
1541 │ ╻
1542 │ │
1543 ┌────╴│╶─────────────────┷─────┐ ╮ border_width
1544 │ │ color │ ┝ +
1545 │ ┌──┷─────────────────────┐ │ ╯ padding_top
1546 │ │====================....│ │
1547 │ │== window content ==....│ │
1548 │ │====================..╾──────── background_color
1549 │ │........................│ │
1550 │ └────────────────────────┘ │ ⎱ border_width +
1551 └──────────────────────────────┘ ⎰ padding_bottom
1552 Setting an attribute of the theme object just propagates the value
1554 to the respective attribute of the tiling and the floating object.
1555 · tiling configures the decoration of tiled clients, setting one
1557 of its attributes propagates the respective attribute of the
1558 active, normal and urgent child objects.
1559 · active configures the decoration of focused and tiled
1561 clients
1562 · normal configures the decoration of unfocused and tiled
1564 clients
1565 · urgent configures the decoration of urgent and tiled
1567 clients
1568 · floating behaves analogously to tiling
1570 · minimal behaves analogously to tiling and configures those
1572 minimal decorations triggered by smart_window_surroundings.
1573 · active propagates the attribute values to tiling.active and
1575 floating.active
1576 · normal propagates the attribute values to tiling.normal and
1578 floating.normal
1579 · urgent propagates the attribute values to tiling.urgent and
1581 floating.urgent
1582
1584 There is no configuration file but an autostart file, which is executed
1585 on startup. It is also executed on command reload. If not specified by
1586 the --autostart argument, autostart file is located at
1587 $XDG_CONFIG_HOME/herbstluftwm/autostart or at
1588 ~/.config/herbstluftwm/autostart. Normally it consists of a few
1589 herbstclient calls. If executing the autostart file in a user’s home
1590 fails the global autostart file (mostly placed at
1591 /etc/xdg/herbstluftwm/autostart) is executed as a fallback.
1592 For a quick install, copy the default autostart file to
1594 ~/.config/herbstluftwm/.
1595
1597 On special events, herbstluftwm emits some hooks (with parameters). You
1598 can receive or wait for them with herbstclient(1). Also custom hooks
1599 can be emitted with the emit_hook command. The following hooks are
1600 emitted by herbstluftwm itself:
1601 fullscreen [on|off] WINID STATE
1603 The fullscreen state of window WINID was changed to [on|off].
1604 tag_changed TAG MONITOR
1606 The tag TAG was selected on MONITOR.
1607 focus_changed WINID TITLE
1609 The window WINID was focused. Its window title is TITLE.
1610 window_title_changed WINID TITLE
1612 The title of the focused window was changed. Its window id is WINID
1613 and its new title is TITLE.
1614 tag_flags
1616 The flags (i.e. urgent or filled state) have been changed.
1617 tag_added TAG
1619 A tag named TAG was added.
1620 tag_removed TAG
1622 The tag named TAG was removed.
1623 urgent [on|off] WINID
1625 The urgent state of client with given WINID has been changed to
1626 [on|off].
1627 rule NAME WINID
1629 A window with the id WINID appeared which triggerd a rule with the
1630 consequence hook=NAME.
1631 There are also other useful hooks, which never will be emitted by
1633 herbstluftwm itself, but which can be emitted with the emit_hook
1634 command:
1635 quit_panel
1637 Tells a panel to quit. The default panel.sh quits on this hook.
1638 Many scripts are using this hook.
1639 reload
1641 Tells all daemons that the autostart file is reloaded — and tells
1642 them to quit. This hook should be emitted in the first line of
1643 every autostart file.
1644
1646 Every tag has its own stack of clients that are on this tag. Similar to
1647 the EWMH specification each tag stack contains several layers, which
1648 are from top to bottom:
1649 · the focused client (if raise_on_focus_temporarily is enabled)
1651 · clients in fullscreen
1653 · normal clients
1655 · frame decorations
1657 All monitors are managed in one large stack which only consists of the
1659 stacks of the visible tags put above each other. The stacking order of
1660 these monitors is independent from their indices and can be modified
1661 using the raise_monitor command. The current stack is illustrated by
1662 the stack command.
1663
1665 DISPLAY
1666 Specifies the DISPLAY to use.
1667
1669 Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
1670 wmexec fails.
1671
1673 See the herbstluftwm distribution BUGS file.
1674
1676 Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.
1677
1679 herbstluftwm was written by Thorsten Wißmann. All contributors are
1680 listed in the herbstluftwm distribution AUTHORS file.
1681
1683 Homepage: http://herbstluftwm.org
1684 Gitweb: http://git.cs.fau.de/?p=re06huxa/herbstluftwm
1686 Patch submission and bug reporting:
1688 hlwm@lists.herbstluftwm.org
1690
1692 Copyright 2011-2014 Thorsten Wißmann. All rights reserved.
1693 This software is licensed under the "Simplified BSD License". See
1695 LICENSE for details.
1696 herbstluftwm 0.6.2\ 2014-03-27 HERBSTLUFTWM(1)