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. This can be switched at
29 run-time by the verbose setting.
30 This manual documents the scripting and configuration interface. For a
32 more verbose introduction see herbstluftwm-tutorial(7).
33
35 The basic tiling concept is that the layout is represented by a binary
36 tree. On startup you see one big frame across the entire screen. A
37 frame fulfills exactly one of the following conditions:
38 1. Frame contains windows:
40 It shows some clients and arranges them. The current layout
42 algorithms are:
43 · 0: vertical - clients are placed below each other
45 · 1: horizontal - clients are placed next to each other
47 · 2: max - all clients are maximized in this frame
49 · 3: grid - clients are arranged in an almost quadratic grid
51 2. Frame is split into subframes:
53 It is split into exactly two subframes in a configurable fraction
55 either in a vertical or horizontal way. So it produces two frames
56 which fulfill the same conditions (new frames always are about to
57 contain windows). If you split a frame that already contains
58 windows, the windows are inherited by the first new child frame.
59 If a new window appears, it is put in the currently focused frame. Only
61 the leaves of the frame tree can be focused.
62 A frame can be removed, it is then merged with its neighbour frame. Due
64 to the layout structure of a binary tree, each frame (i.e. node in
65 binary tree) has exactly one neighbour.
66 The analogy to a binary tree is explained the best way with a small
68 example: On startup you have a simple binary tree, with one frame that
69 can contain clients:
70 C
72 When splitting it (e.g. with the command split vertical 0.5) you will
74 get this:
75 V
77 / \
78 C C
79 You also can split the left frame horizontally and you will get:
81 V
83 / \
84 H C
85 / \
86 C C
87 If you change the focus to the client on the right and remove this
89 frame, it will be merged with the left subtree and you will get:
90 H
92 / \
93 C C
94 The layout command prints the current layout of all tags as a tree.
96
98 The exact position of a frame in the layout tree may be described by
99 its index which is just a string of characters. The lookup algorithm
100 starts at the root frame and selects one of its two subtrees according
101 to the each character in the index.
102 The characters are interpreted as follows:
104 · 0: select the first subtree
106 · 1: select the second subtree
108 · .: select the subtree having the focus
110 · /: select the subtree not having the focus
112 Thus an empty string refers to the root frame, and "00" refers to the
114 first subtree of the first subtree of the root frame.
115 As a special case, the string "@" always refers to the currently
117 focused frame.
118
120 Tags are very similar to workspaces, virtual desktops or window groups.
121 Each tag has one layout. There is a list of tags. You can add or remove
122 tags dynamically.
123
125 Monitors in herbstluftwm are totally independent of the actual physical
126 screens. This means you can for example split your screen in two
127 virtual monitors to view two tags at once on a big screen.
128 Each monitor displays exactly one tag on a specified rectangle on the
130 screen.
131 Each monitor may have a name, which can be set via add_monitor and
133 rename_monitor. It can be unset with the rename_monitor command. A
134 monitor name is an arbitrary non-empty string which must not start with
135 +, - or any digit.
136 A monitor can be referenced in different ways:
138 · by its absolute index as listed in the list_monitors command.
140 · by its relative index: a + or - followed by a delta, e.g.: +3
142 · by its relative position to the focused monitor. -l denotes the
144 monitor left of the focused monitor, -r right of, -u above of, and
145 -d below of, respectively.
146 · by "" (an empty string) which represents the current monitor.
148 · by its name.
150
152 herbstluftwm is controlled by internal commands, which can be executed
153 via herbstclient(1) or via keybindings.
154 quit
156 Quits herbstluftwm.
157 reload
159 Executes the autostart file.
160 version
162 Prints the version of the running herbstluftwm instance.
163 echo [ARGS ...]
165 Prints all given ARGS separated by a single space and a newline
166 afterwards.
167 true
169 Ignores all arguments and always returns success, i.e. 0.
170 false
172 Ignores all arguments and always returns failure, i.e. 1.
173 list_commands
175 Lists all available commands.
176 list_monitors
178 List currently configured monitors with their index, area (as
179 rectangle), name (if named) and currently viewed tag.
180 list_rules
182 Lists all active rules. Each line consists of all the parameters
183 the rule was called with, plus its label, separated by tabs.
184 list_keybinds
186 Lists all bound keys with their associated command. Each line
187 consists of one key combination and the command with its parameters
188 separated by tabs.
189 Warning
191 Tabs within command parameters are not escaped!
192 lock
194 Increases the monitors_locked setting. Use this if you want to do
195 multiple window actions at once (i.e. without repainting between
196 the single steps). See also: unlock
197 unlock
199 Decreases the monitors_locked setting. If monitors_locked is
200 changed to 0, then all monitors are repainted again. See also: lock
201 keybind KEY COMMAND [ARGS ...]
203 Adds a key binding. When KEY is pressed, the internal COMMAND (with
204 its ARGS) is executed. A key binding is a (possibly empty) list of
205 modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl,
206 Shift) and one key (see keysymdef.h for a list of keys). Modifiers
207 and the key are concatenated with - or + as separator. If there is
208 already a binding for this KEY, it will be overwritten. Examples:
209 · keybind Mod4+Ctrl+q quit
211 · keybind Mod1-i toggle always_show_frame
213 · keybind Mod1-Shift-space cycle_layout -1
215 keyunbind KEY|-F|--all
217 Removes the key binding for KEY. The syntax for KEY is defined in
218 keybind. If -F or --all is given, then all key bindings will be
219 removed.
220 mousebind BUTTON ACTION [COMMAND ...]
222 Adds a mouse binding for the floating mode. When BUTTON is pressed,
223 the specified ACTION will be performed. BUTTON has a similar
224 syntax to the KEY argument of keybind: It consists of a list of
225 modifiers (separated by - or +, valid modifiers are listed in the
226 description of keybind) and exactly one button name:
227 · B1 or Button1
229 · B2 or Button2
231 · B3 or Button3
233 · B4 or Button4
235 · B5 or Button5
237 ACTION must be one of the following actions:
239 · move: Moves the window by dragging the cursor.
241 · resize: Resizes the window by dragging a corner.
243 · zoom: Resizes the window into all four directions while keeping
245 the center of the window constant.
246 · call: Only calls the specified COMMAND while client.dragged
248 links to the client on which the BUTTON has been performed.
249 While an ACTION is performed, client.dragged is the client which is
251 dragged. E.g.:
252 · mousebind Mod1-Button3 zoom
254 · mousebind Mod1-B4 call substitute WID clients.dragged.winid
256 spawn transset-df --inc -i WID 0.05
257 · mousebind Mod1-B5 call substitute WID clients.dragged.winid
259 spawn transset-df --dec -i WID -m 0.2 0.05
260 mouseunbind
262 Removes all mouse bindings.
263 spawn EXECUTABLE [ARGS ...]
265 Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp.
266 Example:
267 · spawn xterm -e man 3 execvp
269 wmexec [WINDOWMANAGER [ARGS ...]]
271 Executes the WINDOWMANAGER with its ARGS. This is useful to switch
272 the window manager in the running session without restarting the
273 session. If no or an invalid WINDOWMANAGER is given, then
274 herbstluftwm is restarted. For details see man 3 execvp. Example:
275 · wmexec openbox
277 chain SEPARATOR [COMMANDS ...]
279 chain expects a SEPARATOR and a list of COMMANDS with arguments.
280 The commands have to be separated by the specified SEPARATOR. The
281 SEPARATOR can by any word and only is recognized as the separator
282 between commands if it exactly matches SEPARATOR. "chain" outputs
283 the appended outputs of all commands and returns the exit code of
284 the last executed command. Examples are:
285 · Create a tag called "foo" and directly use it:
287 chain , add foo , use foo
289 · Rotate the layout clockwise:
291 chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
293 Counterexamples are:
295 · This will only create a tag called "foo,":
297 chain , add foo, use foo
299 · Separator "." defined, but "," is used:
301 chain . add foo , use foo
303 and SEPARATOR [COMMANDS ...]
305 "and" behaves like the chain command but only executes the
306 specified COMMANDS while the commands return the exit code 0.
307 or SEPARATOR [COMMANDS ...]
309 "or" behaves like the chain command but only executes the specified
310 COMMANDS until one command returns the exit code 0.
311 ! COMMAND
313 "!" executes the provided command, but inverts its return value. If
314 the provided command returns a nonzero, "!" returns a 0, if the
315 command returns a zero, "!" returns a 1.
316 try COMMAND
318 "try" executes the provided command, prints its output, but always
319 returns success, i.e. 0.
320 silent COMMAND
322 "silent" executes the provided command, but discards its output and
323 only returns its exit code.
324 focus_nth INDEX
326 Focuses the nth window in a frame. The first window has INDEX 0. If
327 INDEX is negative or greater than the last window index, then the
328 last window is focused.
329 cycle [DELTA]
331 Cycles the selection within the current frame by DELTA. If DELTA is
332 omitted, DELTA = 1 will be used. DELTA can be negative; DELTA = -1
333 means: cycle in the opposite direction by 1.
334 cycle_all [--skip-invisible] [DIRECTION]
336 Cycles through all windows and frames on the current tag.
337 DIRECTION = 1 means forward, DIRECTION = -1 means backward,
338 DIRECTION = 0 has no effect. DIRECTION defaults to 1. If there are
339 multiple windows within on frame, then it acts similar to the cycle
340 command. (The cycle_all command focuses the next/previous leaf in
341 the layout tree.). If --skip-invisible is given, then this only
342 cycles through all visible windows and skips invisible windows in
343 the max layout. The focused window is raised.
344 cycle_frame [DIRECTION]
346 Cycles through all frames on the current tag. DIRECTION = 1 means
347 forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
348 effect. DIRECTION defaults to 1.
349 cycle_layout [DELTA [LAYOUTS ...]]
351 Cycles the layout algorithm in the current frame by DELTA. DELTA
352 defaults to 1. You can find a list of layout algorithms above. If a
353 list of LAYOUTS is given, cycle_layout will cycle through those
354 instead of the default layout algorithm list. This is done by
355 finding the first occurrence of the current layout in LAYOUTS and
356 picking the next layout according to DELTA. If the current layout
357 doesn’t occur in LAYOUTS, the first entry is picked. Example:
358 · cycle_layout -1
360 · cycle_layout 1 vertical grid
362 set_layout LAYOUT
364 Sets the layout algorithm in the current frame to LAYOUT. For the
365 list of layouts, check the list of layout algorithms above.
366 close WINID
368 Closes the specified window gracefully or the focused window if
369 none is given explicitly. See the section on WINDOW IDS how to
370 reference a certain window.
371 close_or_remove
373 Closes the focused window or removes the current frame if no window
374 is focused.
375 close_and_remove
377 Closes the focused window and removes the current frame if no other
378 window is present in that frame.
379 split ALIGN [FRACTION]
381 Splits the focused frame into two subframes with a specified
382 FRACTION between 0 and 1 which defaults to 0.5. ALIGN is one of
383 · top
386 · bottom (= vertical)
388 · left,
390 · right (= horizontal)
392 · explode
394 · auto (split along longest side)
396 It specifies which of the two halves will be empty after the
398 split. The other half will be occupied by the currently focused
399 frame. After splitting, the originally focuse frame will stay
400 focused. One special ALIGN mode is explode, which splits the
401 frame in such a way that the window sizes and positions are
402 kept as much as possible. If no FRACTION is given to explode
403 mode an optimal fraction is picked automatically. Example:
404 · split explode
406 · split bottom 0.5
408 · split horiz 0.3
410 · split vertical 0.5
412 · split h
414 focus [-i|-e] DIRECTION
416 Moves the focus from current frame to the next frame or client in
417 DIRECTION which is in:
418 · l[eft]
421 · r[ight]
423 · u[p]
425 · d[own]
427 If -i (internal) is given or default_direction_external_only is
429 unset, then the next client in DIRECTION can also be within the
430 same frame. If there is no client within this frame or -e
431 (external) is given, then the next frame in specified DIRECTION
432 will be focused.
433 The direction between frames is defined as follows: The focus is in
436 a leaf of the binary tree. Each inner node in the tree remembers
437 the last focus direction (child 0 or child 1). The algorithm uses
438 the shortest possible way from the leaf (the currently focused
439 frame) to the root until it is possible to change focus in the
440 specified DIRECTION. From there the focus goes back to the leaf.
441 Example: The focus is at frame A. After executing focus right focus
444 will be at frame C.
445 Tree: V,0 Screen: ┌─────┐┌─────┐ (before)
447 ╱ ╲ │ B ││ C │
448 ╱ ╲ └─────┘└─────┘
449 H,1 H,0 ┌─────┐┌─────┐
450 ╱ ╲ ╱ ╲ │ A* ││ D │
451 A* B C D └─────┘└─────┘
452 Tree: V,0 Screen: ┌─────┐┌─────┐ (after focus right)
454 ╱ ╲ │ B ││ C* │
455 ╱ ╲ └─────┘└─────┘
456 H,1 H,0 ┌─────┐┌─────┐
457 ╱ ╲ ╱ ╲ │ A ││ D │
458 A B C* D └─────┘└─────┘
459 If the currently focused client is floated, then the next floating
461 window in the specified direction is focused and raised.
462 If focus_crosses_monitor_boundaries is set and no client or frame
464 is found in the specified DIRECTION, then the next monitor in that
465 DIRECTION is focused.
466 focus_edge [-i|-e] DIRECTION
468 Focuses the window on the edge of the tag in the specified
469 DIRECTION. The DIRECTIONS and -e behave as specified at the focus
470 command.
471 If -i (internal) is given or default_direction_external_only is
474 unset, then the window on the edge of the tag will be focused.
475 Else, only the frame on the edge of the tag will be focused, and
476 the window that was last focused in that frame will be focused.
477 raise WINID
479 Raises the specified window. See the section on WINDOW IDS on how
480 to reference a certain window. Its result is only visible in
481 floating mode.
482 Tip
484 The WINID also can specify an unmanaged window, although the
485 completion for the raise command does not list the IDs of unmanaged
486 windows.
487 jumpto WINID
489 Puts the focus to the specified window. See the section on WINDOW
490 IDS on how to reference a certain window.
491 bring WINID
493 Moves the specified window to the current frame and focuses it. See
494 the section on WINDOW IDS on how to reference a certain window.
495 resize DIRECTION FRACTIONDELTA
497 Changes the next fraction in specified DIRECTION by FRACTIONDELTA.
498 DIRECTION behaves as specified at the focus command. You should not
499 omit the sign - or +, because in future versions, the behaviour may
500 change if the sign is omitted. Example:
501 · resize right +0.05
503 · resize down -0.1
505 shift_edge [-i|-e] DIRECTION
507 Shifts the focused window to the the edge of a tag in the specified
508 DIRECTION. The DIRECTIONS behave as specified at the focus command
509 and -i and -e behave as specified at the focus_edge command.
510 shift [-i|-e] DIRECTION
512 Shifts the focused window to the next frame in the specified
513 DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
514 focus command. If the focused client is floated instead of being
515 tiled, then client is shifted to the next window or screen edge.
516 shift_to_monitor MONITOR
518 Moves the focused window to the tag on the specified MONITOR. See
519 the MONITORS section, how to address a monitor.
520 remove
522 Removes focused frame and merges its windows to its neighbour
523 frame.
524 rotate
526 Rotates the layout on the focused tag counterclockwise by 90
527 degrees. This only manipulates the alignment of frames, not the
528 content of them.
529 set NAME VALUE
531 Sets the specified setting NAME to VALUE. All SETTINGS are listed
532 in the section below.
533 get NAME
535 Prints the value of setting NAME. All SETTINGS are listed in the
536 section below.
537 toggle NAME
539 Toggles the setting NAME if it’s an integer setting: If its value
540 is unequal to 0, it becomes 0; else its previous value (which was
541 unequal to 0) is restored.
542 cycle_value NAME VALUES ...
544 Cycles value of the setting NAME through VALUES: I.e. it searches
545 the first occurrence of the current value in VALUES and changes the
546 value to the next in the list or to the first one if the end is
547 reached or current value wasn’t found. Example:
548 · cycle_value frame_gap 0 5 10 15
550 · cycle_value frame_bg_normal_color red green blue
552 cycle_monitor [DELTA]
554 Cycles monitor focused by DELTA. DELTA defaults to 1.
555 focus_monitor MONITOR
557 Puts focus to the specified monitor. See the MONITORS section, how
558 to address a monitor.
559 add TAG
561 Creates a new empty tag named TAG.
562 use TAG
564 Switches the focused monitor to specified TAG.
565 use_index INDEX [--skip-visible]
567 Switches the focused monitor to the TAG with the specified INDEX.
568 If INDEX starts with + or -, then INDEX is treated relative to the
569 current TAG. If --skip-visible is passed and INDEX is relative,
570 then tags that are already visible on a monitor are skipped. E.g.
571 this cycles backwards through the tags:
572 · use_index -1 --skip-visible
574 use_previous
576 Switches the focused monitor to the previously viewed tag.
577 merge_tag TAG [TARGET]
579 Removes tag named TAG and moves all its windows to tag TARGET. If
580 TARGET is omitted, the focused tag will be used.
581 rename OLDTAG NEWTAG
583 Renames tag named OLDTAG to NEWTAG.
584 move TAG
586 Moves the focused window to the tag named TAG.
587 move_index INDEX [--skip-visible]
589 Moves the focused window to the tag specified by INDEX. Analogical
590 to the argument for use_index: If INDEX starts with + or -, then it
591 is treated relative. If --skip-visible is passed with a relative
592 index, then already visible tags are skipped.
593 lock_tag [MONITOR]
595 Lock the tag switching on the specified monitor. If no argument is
596 given, the currently focused monitor is used. When the tag
597 switching is disabled for a monitor, the commands use and use_index
598 have no effect when executed there. When swap_monitors_to_get_tag
599 is enabled, switching to a tag which is located on a locked
600 monitor, switches to that monitor instead of stealing it from
601 there. The lock state of a monitor is indicated by "[LOCKED]" in
602 the list_monitors output.
603 unlock_tag [MONITOR]
605 Re-enables the tag switching on the specified monitor. If no
606 argument is given, the currently focused monitor is used. This is
607 the reverse operation to lock_tag and has no further side effects
608 but removing this lock.
609 disjoin_rects RECTS ...
611 Takes a list of rectangles and splits them into smaller pieces
612 until all rectangles are disjoint, the result rectangles are
613 printed line by line. This command does not modify the current list
614 of monitors! So this can be useful in combination with the
615 set_monitors command.
616 · E.g. disjoin_rects 600x400+0+0 600x400+300+250 prints this:
618 300x150+300+250
620 600x250+0+0
621 300x150+0+250
622 300x150+600+250
623 600x250+300+400
624 · In the above example two monitors are split into 5 monitors,
626 which graphically means:
627 ┌──────┐ ┌──────┐
629 │ │ └──────┘
630 │ ┌───┼───┐ ┌─┐┌───┐┌──┐
631 │ │ │ │ disjoin │ ││ ││ │
632 └──┼───┘ │ ─────────> └─┘└───┘└──┘
633 │ │ ┌───────┐
634 └───────┘ └───────┘
635 set_monitors RECTS ...
637 Sets the list of monitors exactly to the list of given rectangles:
638 · The i’th existing monitor is moved to the i’th given RECT
640 · New monitors are created if there are more RECTS then monitors
642 · Existing monitors are deleted if there are more monitors then
644 RECTS
645 detect_monitors -l|--list|--no-disjoin
647 Sets the list of monitors to the available Xinerama monitors. If
648 the Xinerama extension is missing, it will fall back to one monitor
649 across the entire screen. If the detected monitors overlap, the
650 will be split into more monitors that are disjoint but cover the
651 same area using disjoin_rects.
652 If -l or --list is passed, the list of rectangles of detected
654 pyhsical monitors is printed. So hc detect_monitors is equivalent
655 to the bash command hc set_monitors $(hc disjoin_rects $(hc
656 detect_monitors -l)).
657 add_monitor RECT [TAG [NAME]]
659 Adds a monitor on the specified rectangle RECT and displays TAG on
660 it. TAG currently must not be displayed on any other monitor.
661 RECT is a string of the form WxH±X±Y. If no or an empty TAG is
662 given, then any free tag will be chosen. If a NAME is given, you
663 can reference to this monitor by its name instead of using an
664 index. Example:
665 · add_monitor 1024x768-20+0 mynewtag main
667 remove_monitor MONITOR
669 Removes the specified monitor.
670 move_monitor MONITOR RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
672 Moves the specified monitor to rectangle RECT. RECT is defined as
673 in add_monitor. If no or an empty pad is given, it is not changed.
674 raise_monitor [MONITOR]
676 Raises the specified monitor or the current one if MONITOR is
677 omitted.
678 rename_monitor MONITOR NAME
680 (Re)names an already existing monitor. If NAME is empty, it removes
681 the monitor’s name.
682 stack
684 Prints the stack of monitors with the visible tags and their layers
685 as a tree. The order of the printed stack is top to bottom. The
686 style is configured by the tree_style setting.
687 monitor_rect [[-p] MONITOR]
689 Prints the rectangle of the specified monitor in the format: X Y W
690 H If no MONITOR or cur is given, then the current monitor is used.
691 If -p is supplied, then the remaining rect without the pad around
692 this monitor is printed.
693 pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
695 Sets the pad of specified monitor to the specified padding. If no
696 or an empty padding is given, it is not changed.
697 list_padding [MONITOR]
699 Lists the padding of the specified monitor, or the currently
700 focused monitor if no monitor is given.
701 layout [TAG [INDEX]]
703 Prints the layout of frame with INDEX on TAG, in a nice tree style.
704 Its style is defined by the tree_style setting. If no TAG is given,
705 the current tag is used. If no INDEX is given, the root frame is
706 used. To specify INDEX without specifying TAG (i.e. use current
707 tag), pass an empty string as TAG.
708 An example output is:
710 ╾─┐ horizontal 50% selection=1
712 ├─╼ vertical: 0xe00009
713 └─┐ vertical 50% selection=0
714 ├─╼ vertical: 0xa00009 [FOCUS]
715 └─╼ vertical: 0x1000009
716 dump [TAG [INDEX]]
718 Prints the same information as the layout command but in a machine
719 readable format. Its output can be read back with the load command.
720 An example output (formatted afterwards) is:
722 (split horizontal:0.500000:1
724 (clients vertical:0 0xe00009)
725 (split vertical:0.500000:1
726 (clients vertical:0 0xa00009)
727 (clients vertical:0 0x1000009)))
728 load [TAG] LAYOUT
730 Loads a given LAYOUT description to specified TAG or current tag if
731 no TAG is given.
732 Caution
734 LAYOUT is exactly one parameter. If you are calling it manually
735 from your shell or from a script, quote it properly!
736 complete POSITION [COMMAND ARGS ...]
738 Prints the result of tab completion for the partial COMMAND with
739 optional ARGS. You usually do not need this, because there is
740 already tab completion for bash. Example:
741 · complete 0 m
743 prints all commands beginning with m
745 · complete 1 toggle fra
747 prints all settings beginning with fra that can be toggled
749 complete_shell POSITION [COMMAND ARGS ...]
751 Behaves like complete with the following extras, useful for
752 completion on posix shells:
753 · Escape sequences are removed in COMMAND and ARGS.
755 · A space is appended to each full completion result.
757 · Special characters will be escaped in the output.
759 emit_hook ARGS ...
761 Emits a custom hook to all idling herbstclients.
762 tag_status [MONITOR]
764 Print a tab separated list of all tags for the specified MONITOR
765 index. If no MONITOR index is given, the focused monitor is used.
766 Each tag name is prefixed with one char, which indicates its state:
767 · . the tag is empty
769 · : the tag is not empty
771 · + the tag is viewed on the specified MONITOR, but this monitor
773 is not focused.
774 · # the tag is viewed on the specified MONITOR and it is focused.
776 · - the tag is viewed on a different MONITOR, but this monitor is
778 not focused.
779 · % the tag is viewed on a different MONITOR and it is focused.
781 · ! the tag contains an urgent window
783 Warning
785 If you use a tab in one of the tag names, then tag_status is
786 probably quite useless for you.
787 floating [[TAG] on|off|toggle|status]
789 Changes the current tag to floating/tiling mode on specified TAG or
790 prints it current status. If no TAG is given, the current tag is
791 used. If no argument is given, floating mode is toggled. If status
792 is given, then on or off is printed, depending of the floating
793 state of TAG.
794 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
796 Defines a rule which will be applied to all new clients. Its
797 behaviour is described in the RULES section.
798 unrule LABEL|--all|-F
800 Removes all rules named LABEL. If --all or -F is passed, then all
801 rules are removed.
802 fullscreen [on|off|toggle]
804 Sets or toggles the fullscreen state of the focused client. If no
805 argument is given, fullscreen mode is toggled.
806 pseudotile [on|off|toggle]
808 Sets or toggles the pseudotile state of the focused client. If a
809 client is pseudotiled, then in tiling mode the client is only moved
810 but not resized - the client size will stay the floating size. The
811 only reason to resize the client is to ensure that it fits into its
812 tile. If no argument is given, pseudotile mode is toggled.
813 object_tree [PATH]
815 Prints the tree of objects. If the object path PATH is given, only
816 the subtree starting at PATH is printed. See the OBJECTS section
817 for more details.
818 attr [PATH [NEWVALUE]
820 Prints the children and attributes of the given object addressed by
821 PATH. If PATH is an attribute, then print the attribute value. If
822 NEWVALUE is given, assign NEWVALUE to the attribute given by PATH.
823 See the OBJECTS section for more details.
824 get_attr ATTRIBUTE
826 Print the value of the specified ATTRIBUTE as described in the
827 OBJECTS section.
828 set_attr ATTRIBUTE NEWVALUE
830 Assign NEWVALUE to the specified ATTRIBUTE as described in the
831 OBJECTS section.
832 new_attr [bool|color|int|string|uint] PATH
834 Creates a new attribute with the name and in the object specified
835 by PATH. Its type is specified by the first argument. The attribute
836 name has to begin with my_.
837 remove_attr PATH
839 Removes the user defined attribute PATH.
840 substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
842 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
843 ARGS by the value of the ATTRIBUTE. Note that the COMMAND also is
844 replaced by the attribute value if it equals IDENTIFIER. The
845 replaced command with its arguments then is executed. Example:
846 · substitute MYTITLE clients.focus.title echo MYTITLE
848 Prints the title of the currently focused window.
850 sprintf IDENTIFIER FORMAT [ATTRIBUTES ...] COMMAND [ARGS ...]
852 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
853 ARGS by the string specified by FORMAT. Each %s in FORMAT stands
854 for the value of the next attribute in ATTRIBUTES, similar to the
855 printf(1) command. The replaced command with its arguments then is
856 executed. Examples:
857 · sprintf STR title=%s clients.focus.title echo STR
859 Prints the title of the currently focused window prepended by
861 title=.
862 · sprintf X tag=%s tags.focus.name rule once X
864 Moves the next client that appears to the tag that is currently
866 focused.
867 · sprintf X %s/%s tags.focus.index tags.count echo X
869 Tells which tag is focused and how many tags there are
871 · sprintf l somelongstring echo l l l
873 Prints somelongstring three times, separated by spaces.
875 mktemp [bool|int|string|uint] IDENTIFIER COMMAND [ARGS ...]
877 Creates a temporary attribute with the given type and replaces all
878 occurrences of IDENTIFIER in COMMAND and ARGS by the path of the
879 temporary attribute. The replaced command with its arguments is
880 executed then. The exit status of COMMAND is returned.
881 compare ATTRIBUTE OPERATOR VALUE
883 Compares the value of ATTRIBUTE with VALUE using the comparison
884 method OPERATOR. If the comparison succeeds, it returns 0, else 1.
885 The operators are:
886 · =: ATTRIBUTE's value equals VALUE
888 · !=: ATTRIBUTE's value does not equal VALUE
890 · le: ATTRIBUTE's value <= VALUE
892 · lt: ATTRIBUTE's value < VALUE
894 · ge: ATTRIBUTE's value >= VALUE
896 · gt: ATTRIBUTE's value > VALUE
898 The OPERATORs le,lt,ge,gt can only be used if ATTRIBUTE is of the
900 type integer or unsigned integer. Note that the first parameter
901 must always be an attribute and the second a constant value. If you
902 want to compare two attributes, use the substitute command:
903 substitute FC tags.focus.frame_count \
905 compare tags.focus.client_count gt FC
906 It returns success if there are more clients on the focused tag
908 than frames.
909 getenv NAME
911 Gets the value of the environment variable NAME.
912 setenv NAME VALUE
914 Set the value of the environment variable NAME to VALUE.
915 unsetenv NAME
917 Unsets the environment variable NAME.
918
920 Settings configure the behaviour of herbstluftwm and can be controlled
921 via the set, get and toggle commands. There are two types of settings:
922 Strings and integer values. An integer value is set, if its value is 1
923 or another value unequal to 0. An integer value is unset, if its value
924 is 0.
925 frame_gap (Integer)
927 The gap between frames in the tiling mode.
928 frame_padding (Integer)
930 The padding within a frame in the tiling mode, i.e. the space
931 between the border of a frame and the windows within it.
932 window_gap (Integer)
934 The gap between windows within one frame in the tiling mode.
935 snap_distance (Integer)
937 If a client is dragged in floating mode, then it snaps to neighbour
938 clients if the distance between them is smaller then snap_distance.
939 snap_gap (Integer)
941 Specifies the remaining gap if a dragged client snaps to an edge in
942 floating mode. If snap_gap is set to 0, no gap will remain.
943 mouse_recenter_gap (Integer)
945 Specifies the gap around a monitor. If the monitor is selected and
946 the mouse position would be restored into this gap, it is set to
947 the center of the monitor. This is useful, when the monitor was
948 left via mouse movement, but is reselected by keyboard. If the gap
949 is 0 (default), the mouse is never recentered.
950 frame_border_active_color (String/Color)
952 The border color of a focused frame.
953 frame_border_normal_color (String/Color)
955 The border color of an unfocused frame.
956 frame_border_inner_color (String/Color)
958 The color of the inner border of a frame.
959 frame_bg_active_color (String/Color)
961 The fill color of a focused frame.
962 frame_bg_normal_color (String/Color)
964 The fill color of an unfocused frame (It is only visible if
965 always_show_frame is set).
966 frame_bg_transparent (Integer)
968 If set, the background of frames are transparent. That means a
969 rectangle is cut out frome the inner such that only the frame
970 border and a stripe of width frame_transparent_width can be seen.
971 Use frame_active_opacity and frame_normal_opacity for real
972 transparency.
973 frame_transparent_width (Integer)
975 Specifies the width of the remaining frame colored with
976 frame_bg_active_color if frame_bg_transparent is set.
977 frame_border_width (Integer)
979 Border width of a frame.
980 frame_border_inner_width (Integer)
982 The width of the inner border of a frame. Must be less than
983 frame_border_width, since it does not add to the frame border width
984 but is a part of it.
985 focus_crosses_monitor_boundaries (Integer)
987 If set, the focus command crosses monitor boundaries. If there is
988 no client in the direction given to focus, then the monitor in the
989 specified direction is focused.
990 raise_on_focus (Integer)
992 If set, a window is raised if it is focused. The value of this
993 setting is only used in floating mode.
994 raise_on_focus_temporarily (Integer)
996 If set, a window is raised temporarily if it is focused on its tag.
997 Temporarily in this case means that the window will return to its
998 previous stacking position if another window is focused.
999 raise_on_click (Integer)
1001 If set, a window is raised if it is clicked. The value of this
1002 setting is only noticed in floating mode.
1003 window_border_width (Integer)
1005 Border width of a window.
1006 window_border_inner_width (Integer)
1008 The width of the inner border of a window. Must be less than
1009 window_border_width, since it does not add to the window border
1010 width but is a part of it.
1011 window_border_active_color (String/Color)
1013 Border color of a focused window.
1014 window_border_normal_color (String/Color)
1016 Border color of an unfocused window.
1017 window_border_urgent_color (String/Color)
1019 Border color of an unfocused but urgent window.
1020 window_border_inner_color (String/Color)
1022 Color of the inner border of a window.
1023 always_show_frame (Integer)
1025 If set, all frames are displayed. If unset, only frames with focus
1026 or with windows in it are displayed.
1027 frame_active_opacity (Integer)
1029 Focused frame opacity in percent. Requires a running compositing
1030 manager to take actual effect.
1031 frame_normal_opacity (Integer)
1033 Unfocused frame opacity in percent. Requires a running compositing
1034 manager to take actual effect.
1035 default_frame_layout (Integer)
1037 Index of the frame layout, which is used if a new frame is created
1038 (by split or on a new tag). For a list of valid indices and their
1039 meanings, check the list of layout algorithms above.
1040 default_direction_external_only (Integer)
1042 This setting controls the behaviour of focus and shift if no -e or
1043 -i argument is given. if set, then focus and shift changes the
1044 focused frame even if there are other clients in this frame in the
1045 specified DIRECTION. Else, a client within current frame is
1046 selected if it is in the specified DIRECTION.
1047 gapless_grid (Integer)
1049 This setting affects the size of the last client in a frame that is
1050 arranged by grid layout. If set, then the last client always fills
1051 the gap within this frame. If unset, then the last client has the
1052 same size as all other clients in this frame.
1053 smart_frame_surroundings (Integer)
1055 If set, frame borders and gaps will be removed when there’s no
1056 ambiguity regarding the focused frame.
1057 smart_window_surroundings (Integer)
1059 If set, window borders and gaps will be removed and minimal when
1060 there’s no ambiguity regarding the focused window. This minimal
1061 window decoration can be configured by the theme.minimal object.
1062 focus_follows_mouse (Integer)
1064 If set and a window is focused by mouse cursor, this window is
1065 focused (this feature is also known as sloppy focus). If unset, you
1066 need to click to change the window focus by mouse.
1067 If another window is hidden by the focus change (e.g. when having
1070 pseudotiled windows in the max layout) then an extra click is
1071 required to change the focus.
1072 focus_stealing_prevention (Integer)
1074 If set, only pagers and taskbars are allowed to change the focus.
1075 If unset, all applications can request a focus change.
1076 monitors_locked (Integer)
1078 If greater than 0, then the clients on all monitors aren’t moved or
1079 resized anymore. If it is set to 0, then the arranging of monitors
1080 is enabled again, and all monitors are rearranged if their content
1081 has changed in the meantime. You should not change this setting
1082 manually due to concurrency issues; use the commands lock and
1083 unlock instead.
1084 swap_monitors_to_get_tag (Integer)
1086 If set: If you want to view a tag, that already is viewed on
1087 another monitor, then the monitor contents will be swapped and you
1088 see the wanted tag on the focused monitor. If not set, the other
1089 monitor is focused if it shows the desired tag.
1090 auto_detect_monitors (Integer)
1092 If set, detect_monitors is automatically executed every time a
1093 monitor is connected, disconnected or resized.
1094 tree_style (String)
1096 It contains the chars that are used to print a nice ascii tree. It
1097 must contain at least 8 characters. e.g. X|:#+*-. produces a tree
1098 like:
1099 X-.root
1101 #-. child 0
1102 | #-* child 01
1103 | +-* child 02
1104 +-. child 1
1105 : #-* child 10
1106 : +-* child 01
1107 Useful values for tree_style are: ╾│ ├└╼─┐ or -| |'--. or ╾│
1109 ├╰╼─╮.
1110 wmname (String)
1112 It controls the value of the _NET_WM_NAME property on the root
1113 window, which specifies the name of the running window manager. The
1114 value of this setting is not updated if the actual _NET_WM_NAME
1115 property on the root window is changed externally. Example usage:
1116 · cycle_value wmname herbstluftwm LG3D
1118 pseudotile_center_threshold (Int)
1120 If greater than 0, it specifies the least distance between a
1121 centered pseudotile window and the border of the frame or tile it
1122 is assigned to. If this distance is lower than
1123 pseudotile_center_threshold, it is aligned to the top left of the
1124 client’s tile.
1125 update_dragged_clients (Int)
1127 If set, a client’s window content is resized immediately during
1128 resizing it with the mouse. If unset, the client’s content is
1129 resized after the mouse button are released.
1130 verbose (Int)
1132 If set, verbose output is logged to herbstluftwm’s stderr. The
1133 default value is controlled by the --verbose command line flag.
1134
1136 Rules are used to change default properties for certain clients when
1137 they appear. Each rule matches against a certain subset of all clients
1138 and defines a set of properties for them (called CONSEQUENCEs). A rule
1139 can be defined with this command:
1140 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
1142 Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
1144 optionally, a LABEL. (each of them can be optionally prefixed with two
1145 dashes (--) to provide a more iptables(8)-like feeling).
1146 Each rule can be given a custom label by specifying the LABEL property:
1148 · [--]label=VALUE
1150 If multiple labels are specified, the last one in the list will be
1152 applied. If no label is given, then the rule will be given an integer
1153 name that represents the index of the rule since the last unrule -F
1154 command (which is triggered in the default autostart).
1155 Tip
1157 Rule labels default to an incremental index. These default labels
1158 are unique, unless you assign a different rule a custom integer
1159 LABEL. Default labels can be captured with the printlabel flag.
1160 If a new client appears, herbstluftwm tries to apply each rule to this
1162 new client as follows: If each CONDITION of this rule matches against
1163 this client, then every CONSEQUENCE is executed. (If there are no
1164 conditions given, then this rule is executed for each client)
1165 Each CONDITION consists of a property name, an operator and a value.
1167 Valid operators are:
1168 · ~ matches if client’s property is matched by the regex value.
1170 · = matches if client’s properly string is equal to value.
1172 Valid properties are:
1174 instance
1176 the first entry in client’s WM_CLASS.
1177 class
1179 the second entry in client’s WM_CLASS.
1180 title
1182 client’s window title.
1183 pid
1185 the client’s process id (Warning: the pid is not available for
1186 every client. This only matches if the client sets _NET_WM_PID to
1187 the pid itself).
1188 maxage
1190 matches if the age of the rule measured in seconds does not exceed
1191 value. This condition only can be used with the = operator. If
1192 maxage already is exceeded (and never will match again), then this
1193 rule is removed. (With this you can build rules that only live for
1194 a certain time.)
1195 windowtype
1197 matches the _NET_WM_WINDOW_TYPE property of a window.
1198 windowrole
1200 matches the WM_WINDOW_ROLE property of a window if it is set by the
1201 window.
1202 Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:
1204 tag
1206 moves the client to tag VALUE.
1207 monitor
1209 moves the client to the tag on monitor VALUE. If the tag
1210 consequence was also specified, and switchtag is set for the
1211 client, move the client to that tag, then display that tag on
1212 monitor VALUE. If the tag consequence was specified, but switchtag
1213 was not, ignore this consequence.
1214 focus
1216 decides whether the client gets the input focus on his tag. The
1217 default is off. VALUE can be on, off or toggle.
1218 switchtag
1220 if focus is activated and the client is put to a not focused tag,
1221 then switchtag tells whether the client’s tag will be shown or not.
1222 If the tag is shown on any monitor but is not focused, the client’s
1223 tag only is brought to the current monitor if
1224 swap_monitors_to_get_tag is activated. VALUE can be on, off or
1225 toggle.
1226 manage
1228 decides whether the client will be managed or not. The default is
1229 on. VALUE can be on, off or toggle.
1230 index
1232 moves the window to a specified index in the tree. VALUE is a
1233 frame index.
1234 pseudotile
1236 sets the pseudotile state of the client. VALUE can be on, off or
1237 toggle.
1238 ewmhrequests
1240 sets whether the window state (the fullscreen state and the demands
1241 attention flag) can be changed by the application via ewmh itself.
1242 This does not affect the initial fullscreen state requested by the
1243 window. VALUE can be on, off or toggle, it defaults to on.
1244 ewmhnotify
1246 sets whether hlwm should let the client know about EMWH changes
1247 (currently only the fullscreen state). If this is set, applications
1248 do not change to their fullscreen-mode while still being
1249 fullscreen. VALUE can be on, off or toggle, it defaults to on.
1250 fullscreen
1252 sets the fullscreen flag of the client. VALUE can be on, off or
1253 toggle.
1254 hook
1256 emits the custom hook rule VALUE WINID when this rule is triggered
1257 by a new window with the id WINID. This consequence can be used
1258 multiple times, which will cause a hook to be emitted for each
1259 occurrence of a hook consequence.
1260 keymask
1262 Sets the keymask for an client. A keymask is an regular expression
1263 that is matched against the string represenation (see
1264 list_keybinds). If it matches the keybinding is active when this
1265 client is focused, otherwise it is disabled. The default keymask is
1266 an empty string (""), which does not disable any keybinding.
1267 A rule’s behaviour can be configured by some special FLAGS:
1269 · not: negates the next CONDITION.
1271 · !: same as not.
1273 · once: only apply this rule once (and delete it afterwards).
1275 · printlabel: prints the label of the newly created rule to stdout.
1277 · prepend: prepend the rule to the list of rules instead of appending
1279 it. So its consequences may be overwritten by already existing
1280 rules.
1281 Examples:
1283 · rule --class=Netscape --tag=6 --focus=off
1285 Moves all Netscape instances to tag 6, but doesn’t give focus to
1287 them.
1288 · rule not class~.*[Tt]erm tag=2
1290 Moves all clients to tag 2, if their class does not end with term
1292 or Term.
1293 · rule class=Thunderbird index=/0
1295 Insert all Thunderbird instances in the tree that has no focus and
1297 there in the first child.
1298 · rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
1300 Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE
1302 correctly.
1303
1305 Several commands accept a window as reference, e.g. close. The syntax
1306 is as follows:
1307 · an empty string — or missing argument — references the currently
1309 focused window.
1310 · urgent references some window that is urgent.
1312 · 0xHEXID — where HEXID is some hexadecimal number — references the
1314 window with hexadecimal X11 window id is HEXID.
1315 · DECID — where DECID is some decimal number — references the window
1317 with the decimal X11 window id DECID.
1318
1320 Warning
1321 The object tree is not stable yet, i.e. its interface may change
1322 until the next stable release. So check this documentation again
1323 after upgrading the next time.
1324 The object tree is a collection of objects with attributes similar to
1326 /sys known from the Linux kernel. Many entities (like tags, monitors,
1327 clients, ...) have objects to access their attributes directly. The
1328 tree is printed by the object_tree command and looks more or less as
1329 follows:
1330 $ herbstclient object_tree
1332 ╾─┐
1333 ├─┐ tags
1334 │ ├─┐ by-name
1335 │ │ ├─╼ 1
1336 │ │ ...
1337 │ │ └─╼ 9
1338 │ └─╼ focus
1339 ├─┐ clients
1340 │ ├─╼ 0x1400022
1341 │ └─╼ focus
1342 └─┐ monitors
1343 ├─╼ by-name
1344 └─╼ focus
1345 To print a subtree starting at a certain object, pass the PATH of the
1347 object to object_tree. The object PATH is the path using the separator
1348 . (dot), e.g. tags.by-name:
1349 $ herbstclient object_tree tags.by-name.
1351 ╾─┐ tags.by-name.
1352 ├─╼ 1
1353 ├─╼ 2
1354 ...
1355 └─╼ 9
1356 To query all attributes and children of a object, pass its PATH to
1358 attr:
1359 $ herbstclient attr tags.
1361 2 children:
1362 by-name.
1363 focus.
1364 1 attributes:
1366 .---- type
1367 | .-- writeable
1368 V V
1369 u - count = 9
1370 $ herbstclient attr tags.focus.
1372 0 children.
1373 6 attributes:
1374 .---- type
1375 | .-- writeable
1376 V V
1377 s w name = "1"
1378 b w floating = false
1379 i - frame_count = 2
1380 i - client_count = 1
1381 i - curframe_windex = 0
1382 i - curframe_wcount = 1
1383 This already gives an intuition of the output: attr first lists the
1385 names of the child objects and then all attributes, telling for each
1386 attribute:
1387 · its type
1389 · s for string
1391 · i for integer
1393 · b for boolean
1395 · u for unsigned integer
1397 · if it is writeable by the user: w if yes, - else.
1399 · the name of the attribute
1401 · its current value (only quoted for strings)
1403 To get the unquoted value of a certain attribute, address the attribute
1405 using the same syntax as for object paths and pass it to attr or
1406 get_attr:
1407 $ herbstclient attr clients.focus.title
1409 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1410 $ herbstclient get_attr clients.focus.title
1411 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1412 To change a writeable attribute value pass the new value to attr or to
1414 set_attr:
1415 $ herbstclient attr tags.focus.floating
1417 false
1418 $ herbstclient attr tags.focus.floating true
1419 $ herbstclient attr tags.focus.floating
1420 true
1421 $ herbstclient set_attr tags.focus.floating false
1422 $ herbstclient attr tags.focus.floating
1423 false
1424 Just look around to get a feeling what is there. The detailed tree
1426 content is listed as follows:
1427 · tags: subtree for tags.
1429 ┌──────────┬────────────────┐
1431 │u - count │ number of tags │
1432 └──────────┴────────────────┘
1433 · index: the object of the tag with index index.
1435 · by-name
1437 · TAG: an object for each tag with the name TAG
1439 ┌────────────────────┬────────────────────────────┐
1441 │s w name │ name of the tag │
1442 ├────────────────────┼────────────────────────────┤
1443 │b w floating │ if it is in floating mode │
1444 ├────────────────────┼────────────────────────────┤
1445 │i - index │ index of this tag │
1446 ├────────────────────┼────────────────────────────┤
1447 │i - frame_count │ number of frames │
1448 ├────────────────────┼────────────────────────────┤
1449 │i - client_count │ number of clients on this │
1450 │ │ tag │
1451 ├────────────────────┼────────────────────────────┤
1452 │i - curframe_windex │ index of the focused │
1453 │ │ client in the select frame │
1454 ├────────────────────┼────────────────────────────┤
1455 │i - curframe_wcount │ number of clients in the │
1456 │ │ selected frame │
1457 └────────────────────┴────────────────────────────┘
1458 · focus: the object of the focused tag
1460 · clients
1462 · WINID: a object for each client with its WINID
1464 ┌───────────────────────┬────────────────────────────┐
1466 │s - winid │ its window id │
1467 ├───────────────────────┼────────────────────────────┤
1468 │s - title │ its window title │
1469 ├───────────────────────┼────────────────────────────┤
1470 │s - tag │ the tag it’s currently on │
1471 ├───────────────────────┼────────────────────────────┤
1472 │i - pid │ the process id of it (-1 │
1473 │ │ if unset) │
1474 ├───────────────────────┼────────────────────────────┤
1475 │s - class │ the class of it (second │
1476 │ │ entry in WM_CLASS) │
1477 ├───────────────────────┼────────────────────────────┤
1478 │s - instance │ the instance of it (first │
1479 │ │ entry in WM_CLASS) │
1480 ├───────────────────────┼────────────────────────────┤
1481 │b w fullscreen │ │
1482 ├───────────────────────┼────────────────────────────┤
1483 │b w pseudotile │ │
1484 ├───────────────────────┼────────────────────────────┤
1485 │b w ewmhrequests │ if ewmh requests are │
1486 │ │ permitted for this client │
1487 ├───────────────────────┼────────────────────────────┤
1488 │b w ewmhnotify │ if the client is told │
1489 │ │ about its state via ewmh │
1490 ├───────────────────────┼────────────────────────────┤
1491 │b w urgent │ its urgent state │
1492 ├───────────────────────┼────────────────────────────┤
1493 │b w sizehints_tiling │ if sizehints for this │
1494 │ │ client should be respected │
1495 │ │ in tiling mode │
1496 ├───────────────────────┼────────────────────────────┤
1497 │b w sizehints_flaoting │ if sizehints for this │
1498 │ │ client should be respected │
1499 │ │ in floating mode │
1500 └───────────────────────┴────────────────────────────┘
1501 · focus: the object of the focused client, if any
1503 · dragged: the object of a client which is dragged by the mouse,
1505 if any. See the documentation of the mousebind command for
1506 examples.
1507 · monitors
1509 ┌──────────┬────────────────────┐
1511 │u - count │ number of monitors │
1512 └──────────┴────────────────────┘
1513 · INDEX: a object for each monitor with its INDEX
1515 · by-name
1517 · NAME: a object for each named monitor
1519 ┌─────────────┬──────────────────────────┐
1521 │s - name │ its name │
1522 ├─────────────┼──────────────────────────┤
1523 │i - index │ its index │
1524 ├─────────────┼──────────────────────────┤
1525 │s - tag │ the tag currently viewed │
1526 │ │ on it │
1527 ├─────────────┼──────────────────────────┤
1528 │b - lock_tag │ │
1529 └─────────────┴──────────────────────────┘
1530 · focus: the object of the focused monitor
1532 · settings has an attribute for each setting. See SETTINGS for a
1534 list.
1535 · theme has attributes to configure the window decorations. theme
1537 and many of its child objects have the following attributes
1538 ┌─────────────────────┬────────────────────────────┐
1540 │i w border_width │ the base width of the │
1541 │ │ border │
1542 ├─────────────────────┼────────────────────────────┤
1543 │i w padding_top │ additional border width on │
1544 │ │ the top │
1545 ├─────────────────────┼────────────────────────────┤
1546 │i w padding_right │ on the right │
1547 ├─────────────────────┼────────────────────────────┤
1548 │i w padding_bottom │ on the bottom │
1549 ├─────────────────────┼────────────────────────────┤
1550 │i w padding_left │ and on the left of the │
1551 │ │ border │
1552 ├─────────────────────┼────────────────────────────┤
1553 │c w color │ the basic background color │
1554 │ │ of the border │
1555 ├─────────────────────┼────────────────────────────┤
1556 │i w inner_width │ width of the border around │
1557 │ │ the clients content │
1558 ├─────────────────────┼────────────────────────────┤
1559 │c w inner_color │ its color │
1560 ├─────────────────────┼────────────────────────────┤
1561 │i w outer_width │ width of an additional │
1562 │ │ border close to the edge │
1563 ├─────────────────────┼────────────────────────────┤
1564 │c w outer_color │ its color │
1565 ├─────────────────────┼────────────────────────────┤
1566 │c w background_color │ color behind window │
1567 │ │ contents visible on resize │
1568 ├─────────────────────┼────────────────────────────┤
1569 │s w reset │ Writing this resets all │
1570 │ │ attributes to a default │
1571 │ │ value │
1572 └─────────────────────┴────────────────────────────┘
1573 inner_color/inner_width
1575 ╻ outer_color/outer_width
1576 │ ╻
1577 │ │
1578 ┌────╴│╶─────────────────┷─────┐ ╮ border_width
1579 │ │ color │ ┝ +
1580 │ ┌──┷─────────────────────┐ │ ╯ padding_top
1581 │ │====================....│ │
1582 │ │== window content ==....│ │
1583 │ │====================..╾──────── background_color
1584 │ │........................│ │
1585 │ └────────────────────────┘ │ ⎱ border_width +
1586 └──────────────────────────────┘ ⎰ padding_bottom
1587 Setting an attribute of the theme object just propagates the value
1589 to the respective attribute of the tiling and the floating object.
1590 · tiling configures the decoration of tiled clients, setting one
1592 of its attributes propagates the respective attribute of the
1593 active, normal and urgent child objects.
1594 · active configures the decoration of focused and tiled
1596 clients
1597 · normal configures the decoration of unfocused and tiled
1599 clients
1600 · urgent configures the decoration of urgent and tiled
1602 clients
1603 · floating behaves analogously to tiling
1605 · minimal behaves analogously to tiling and configures those
1607 minimal decorations triggered by smart_window_surroundings.
1608 · active propagates the attribute values to tiling.active and
1610 floating.active
1611 · normal propagates the attribute values to tiling.normal and
1613 floating.normal
1614 · urgent propagates the attribute values to tiling.urgent and
1616 floating.urgent
1617
1619 There is no configuration file but an autostart file, which is executed
1620 on startup. It is also executed on command reload. If not specified by
1621 the --autostart argument, autostart file is located at
1622 $XDG_CONFIG_HOME/herbstluftwm/autostart or at
1623 ~/.config/herbstluftwm/autostart. Normally it consists of a few
1624 herbstclient calls. If executing the autostart file in a user’s home
1625 fails the global autostart file (mostly placed at
1626 /etc/xdg/herbstluftwm/autostart) is executed as a fallback.
1627 For a quick install, copy the default autostart file to
1629 ~/.config/herbstluftwm/.
1630
1632 On special events, herbstluftwm emits some hooks (with parameters). You
1633 can receive or wait for them with herbstclient(1). Also custom hooks
1634 can be emitted with the emit_hook command. The following hooks are
1635 emitted by herbstluftwm itself:
1636 fullscreen [on|off] WINID STATE
1638 The fullscreen state of window WINID was changed to [on|off].
1639 tag_changed TAG MONITOR
1641 The tag TAG was selected on MONITOR.
1642 focus_changed WINID TITLE
1644 The window WINID was focused. Its window title is TITLE.
1645 window_title_changed WINID TITLE
1647 The title of the focused window was changed. Its window id is WINID
1648 and its new title is TITLE.
1649 tag_flags
1651 The flags (i.e. urgent or filled state) have been changed.
1652 tag_added TAG
1654 A tag named TAG was added.
1655 tag_removed TAG
1657 The tag named TAG was removed.
1658 urgent [on|off] WINID
1660 The urgent state of client with given WINID has been changed to
1661 [on|off].
1662 rule NAME WINID
1664 A window with the id WINID appeared which triggered a rule with the
1665 consequence hook=NAME.
1666 There are also other useful hooks, which never will be emitted by
1668 herbstluftwm itself, but which can be emitted with the emit_hook
1669 command:
1670 quit_panel
1672 Tells a panel to quit. The default panel.sh quits on this hook.
1673 Many scripts are using this hook.
1674 reload
1676 Tells all daemons that the autostart file is reloaded — and tells
1677 them to quit. This hook should be emitted in the first line of
1678 every autostart file.
1679
1681 Every tag has its own stack of clients that are on this tag. Similar to
1682 the EWMH specification each tag stack contains several layers, which
1683 are from top to bottom:
1684 · the focused client (if raise_on_focus_temporarily is enabled)
1686 · clients in fullscreen
1688 · normal clients
1690 · frame decorations
1692 All monitors are managed in one large stack which only consists of the
1694 stacks of the visible tags put above each other. The stacking order of
1695 these monitors is independent from their indices and can be modified
1696 using the raise_monitor command. The current stack is illustrated by
1697 the stack command.
1698
1700 As far as possible, herbstluftwm tries to be EWMH compliant. That
1701 includes:
1702 · Information about tag names and client lists is provided.
1704 · Desktop windows from desktop environments are not managed and kept
1706 below the other windows.
1707 · Client requests like getting focused are only processed if the
1709 setting focus_stealing_prevention is disabled.
1710
1712 DISPLAY
1713 Specifies the DISPLAY to use.
1714
1716 The following files are used by herbstluftwm:
1717 · autostart, see section AUTOSTART FILE.
1719
1721 Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
1722 wmexec fails.
1723
1725 See the herbstluftwm distribution BUGS file.
1726
1728 Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.
1729
1731 herbstluftwm was written by Thorsten Wißmann. All contributors are
1732 listed in the herbstluftwm distribution AUTHORS file.
1733
1735 Homepage: http://herbstluftwm.org
1736 Github page: http://github.com/herbstluftwm/herbstluftwm
1738 Patch submission and bug reporting:
1740 hlwm@lists.herbstluftwm.org
1742
1744 Copyright 2011-2014 Thorsten Wißmann. All rights reserved.
1745 This software is licensed under the "Simplified BSD License". See
1747 LICENSE for details.
1748 herbstluftwm 0.7.2\ 2019-05-28 HERBSTLUFTWM(1)