'\" t .\" Title: herbstluftwm .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 2012-04-13 .\" Manual: \ \& .\" Source: \ \& herbstluftwm 0.3 .\" Language: English .\" .TH "HERBSTLUFTWM" "1" "2012\-04\-13" "\ \& herbstluftwm 0\&.3" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" herbstluftwm \- a manual tiling window manager for X .SH "SYNOPSIS" .sp \fBherbstluftwm\fR [\fIOPTION\fR \&...] .SH "DESCRIPTION" .sp Starts the \fBherbstluftwm\fR window manager on \fIDISPLAY\fR\&. It also listens for calls from \fBherbstclient\fR(1) and executes them\&. The list of available \fBCOMMANDS\fR is listed below\&. .sp \fIOPTION\fR can be: .PP \fB\-c\fR, \fB\-\-autostart\fR \fIPATH\fR .RS 4 use \fIPATH\fR as autostart file instead of the one in \fI$XDG_CONFIG_HOME\fR .RE .PP \fB\-v\fR, \fB\-\-version\fR .RS 4 print version and exit .RE .PP \fB\-l\fR, \fB\-\-locked\fR .RS 4 set the monitors_locked setting initially to 1 .RE .PP \fB\-\-verbose\fR .RS 4 print verbose information to stderr .RE .SH "TILING ALGORITHM" .sp The basic tiling concept is, that the layout is represented by a binary tree\&. On startup you see one big frame across the entire screen\&. A frame fulfills exactly one of the following conditions: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} Frame contains windows: It shows some clients and arranges them\&. The current layout algorithms are: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 0: \fIvertical\fR \- clients are placed below each other .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 1: \fIhorizontal\fR \- clients are placed next to each other .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 2: \fImax\fR \- all clients are maximized in this frame .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 3: \fIgrid\fR \- clients are arranged in an almost quadratic grid .RE .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} Frame is split into subframes: It is split into exactly two \fBsubframes\fR in a configurable \fIfraction\fR either in a vertical or horizontal way\&. So it produces two \fBframes\fR which fulfill the same conditions (new frames always are about to contain \fBwindows\fR)\&. If you split a frame that already contains windows, then the windows are inherited by the first new child frame\&. .RE .sp If a new window appears, it is put in the currently focused frame\&. Only the leaves of the frame tree can be focused\&. .sp A frame can be removed, so it is merged with its neighbour frame\&. Due to the layout structure of a binary tree, each frame (i\&.e\&. node in binary tree) has exactly one neighbour\&. .sp The analogy to a binary Tree is explained the best way with a small example: On startup you have a simple binary tree, with one frame that can contain clients: .sp .if n \{\ .RS 4 .\} .nf C .fi .if n \{\ .RE .\} .sp When splitting it (e\&.g\&. with command \fIsplit vertical 0\&.5\fR) you will get this: .sp .if n \{\ .RS 4 .\} .nf V / \e C C .fi .if n \{\ .RE .\} .sp You also can split the left frame horizontally and you will get: .sp .if n \{\ .RS 4 .\} .nf V / \e H C / \e C C .fi .if n \{\ .RE .\} .sp If you change the focus to the client on the right and remove this frame, it will be merged with the left subtree and you will get: .sp .if n \{\ .RS 4 .\} .nf H / \e C C .fi .if n \{\ .RE .\} .sp The \fIlayout\fR command prints the current layout of all tags as a tree\&. .SH "TAGS" .sp Tags are very similar to workspaces, virtual desktops or window groups\&. Each tag has one layout\&. There is a list of tags\&. You can add or remove tags dynamically\&. .sp There is also a list of monitors\&. Each monitor displays exactly one tag on a specified rectangle on the screen\&. .SH "COMMANDS" .sp \fBherbstluftwm\fR is controlled by internal commands, which can be executed via \fBherbstclient\fR(1) or via keybindings\&. .PP quit .RS 4 Quits herbstluftwm\&. .RE .PP reload .RS 4 Executes the autostart file\&. .RE .PP version .RS 4 Prints the version of the running herbstluftwm instance\&. .RE .PP list_commands .RS 4 Lists all available commands\&. .RE .PP list_monitors .RS 4 List currently configured monitors with their index, area (as rectangle) and currently viewed tag\&. .RE .PP list_keybinds .RS 4 Lists all bound keys with their associated command\&. Each line consists of one key combination and the command with its parameters separated by tabs\&. .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBWarning\fR .ps -1 .br .sp Tabs within command parameters are not escaped! .sp .5v .RE .PP lock .RS 4 Increases the \fImonitors_locked\fR setting\&. Use this if you want to do multiple window actions at once (i\&.e\&. without repainting between the single steps)\&. See also: \fBunlock\fR .RE .PP unlock .RS 4 Decreases the \fImonitors_locked\fR setting\&. If \fImonitors_locked\fR is changed to 0, then all monitors are repainted again\&. See also: \fBlock\fR .RE .PP keybind \fIKEY\fR \fICOMMAND\fR [\fIARGS \&...\fR] .RS 4 Adds a key binding\&. When \fIKEY\fR is pressed, the internal \fICOMMAND\fR (with its \fIARGS\fR) is executed\&. A key binding is a (possibly empty) list of modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl, Shift) and one key (see keysymdef\&.h for a list of keys)\&. Modifiers and the key are concatenated with \fI\-\fR or \fI+\fR as separator\&. If there is already a binding for this \fIKEY\fR, it will be overwritten\&. Examples: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} keybind Mod4+Ctrl+q quit .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} keybind Mod1\-i toggle always_show_frame .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} keybind Mod1\-Shift\-space cycle_layout \-1 .RE .RE .PP keyunbind \fIKEY\fR|\fB\-F\fR|\fB\-\-all\fR .RS 4 Removes the key binding for \fIKEY\fR\&. Syntax for \fIKEY\fR is defined in \fBkeybind\fR\&. If \fB\-F\fR or \fB\-\-all\fR is given, then all key bindings will be removed\&. .RE .PP mousebind \fIBUTTON\fR \fIACTION\fR .RS 4 Adds a mouse binding for the floating mode\&. When \fIBUTTON\fR is pressed, the specified \fIACTION\fR will be performed\&. \fIBUTTON\fR has a similar syntax to the \fIKEY\fR argument of keybind: It consists of a list of modifiers (separated by \fI\-\fR or \fI+\fR, valid modifiers are listed in the description of \fIkeybind\fR) and exactly one button name: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} B1 or Button1 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} B2 or Button2 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} B3 or Button3 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} B4 or Button4 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} B5 or Button5 .RE .RE .PP .RS 4 \fIACTION\fR must be one of the following actions: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} move: Moves the window by dragging the cursor .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} resize: Resizes the window by dragging the bottom right corner .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} zoom: Resizes the window into all four directions by keeping the center of the window constant\&. .RE .RE .PP .RS 4 E\&.g\&.: mousebind Mod1\-Button3 zoom .RE .PP mouseunbind .RS 4 Removes all mouse bindings\&. .RE .PP spawn \fIEXECUTABLE\fR [\fIARGS \&...\fR] .RS 4 Spawns an \fIEXECUTABLE\fR with its \fIARGS\fR\&. For details see \fIman 3 execvp\fR\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} spawn xterm \-e man 3 execvp .RE .RE .PP wmexec [\fIWINDOWMANAGER\fR [\fIARGS \&...\fR]] .RS 4 Executes the \fIWINDOWMANAGER\fR with its \fIARGS\fR\&. This is useful to switch the window manager in the running session without restarting the session\&. If no or an invalid \fIWINDOWMANAGER\fR is given, then herbstluftwm is restarted\&. For details see \fIman 3 execvp\fR\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} wmexec openbox .RE .RE .PP cycle [\fIDELTA\fR] .RS 4 Cycles the selection within the current frame by \fIDELTA\fR\&. If \fIDELTA\fR is omitted, \fIDELTA\fR = 1 will be used\&. \fIDELTA\fR can be negative; \fIDELTA\fR = \-1 means: cycle in the opposite direction by 1\&. .RE .PP cycle_all [\fIDIRECTION\fR] .RS 4 Cycles through all windows and frames on the current tag\&. \fIDIRECTION\fR = 1 means forward, \fIDIRECTION\fR = \-1 means backward, \fIDIRECTION\fR = 0 has no effect\&. \fIDIRECTION\fR defaults to 1\&. If there are multiple windows within on frame, then it acts similar to the \fIcycle\fR command\&. (The \fIcycle_all\fR command focuses the next/previous leave in the \fIlayout\fR tree\&.) .RE .PP cycle_layout [\fIDELTA\fR] .RS 4 Cycles the layout algorithm in the current frame by \fIDELTA\fR\&. \fIDELTA\fR defaults to 1\&. You can find a list of layout algorithms above\&. .RE .PP set_layout \fILAYOUT\fR .RS 4 Sets the layout algorithm in the current frame to \fILAYOUT\fR\&. For the list of layouts, check the list of layout algorithms above\&. .RE .PP close .RS 4 Closes the focused window\&. .RE .PP split \fIALIGN\fR \fIFRACTION\fR .RS 4 Splits the focused frame into two subframes with a specified \fIFRACTION\fR between 0 and 1\&. \fIALIGN\fR can be \fIhorizontal\fR or \fIvertical\fR (actually it only depends on the first letter of \fIALIGN\fR)\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} split horiz 0\&.3 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} split vertical 0\&.5 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} split h 0\&.8 .RE .RE .PP focus [\fI\-i\fR|\fI\-e\fR] \fIDIRECTION\fR .RS 4 Moves the focus from current frame to the next frame or client in \fIDIRECTION\fR which is in: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} l[eft] .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} r[ight] .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} u[p] .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} d[own] .RE .RE .PP .RS 4 If \fI\-i\fR (internal) is given or default_direction_external_only is unset, then the next client in \fIDIRECTION\fR can also be within the same frame\&. If there is no client within this frame or \fI\-e\fR (external) is given, then the next frame in specified \fIDIRECTION\fR will be focused\&. The direction between frames is defined as follows: The focus is in a leaf of the binary tree\&. Each inner node in the tree remembers the last focus direction (child 0 or child 1)\&. The algorithm is going as short as possible from the leaf (the currently focused frame) to the root until it is possible to change focus in the specified \fIDIRECTION\fR\&. From there the focus goes back to the leaf\&. Example: The focus is at frame A\&. After executing \fIfocus right\fR focus will be at frame C\&. .sp .if n \{\ .RS 4 .\} .nf Tree: V,0 Screen: \&.\-\-\-\-\-\&.\&.\-\-\-\-\-\&. (before) / \e | B || C | / \e \*(Aq\-\-\-\-\-\*(Aq\*(Aq\-\-\-\-\-\*(Aq H,1 H,0 \&.\-\-\-\-\-\&.\&.\-\-\-\-\-\&. / \e / \e | A* || D | A* B C D \*(Aq\-\-\-\-\-\*(Aq\*(Aq\-\-\-\-\-\*(Aq Tree: V,0 Screen: \&.\-\-\-\-\-\&.\&.\-\-\-\-\-\&. (after focus right) / \e | B || C* | / \e \*(Aq\-\-\-\-\-\*(Aq\*(Aq\-\-\-\-\-\*(Aq H,1 H,0 \&.\-\-\-\-\-\&.\&.\-\-\-\-\-\&. / \e / \e | A || D | A B C* D \*(Aq\-\-\-\-\-\*(Aq\*(Aq\-\-\-\-\-\*(Aq .fi .if n \{\ .RE .\} .RE .PP raise [\fI0xWINID\fR] .RS 4 Raises the specified window, which is specified by hexadecimal \fI0xWINID\fR\&. If no \fI0xWINID\fR is given, the focused window will be raised\&. Its result is only visible in floating mode\&. .RE .PP resize \fIDIRECTION\fR \fIFRACTIONDELTA\fR .RS 4 Changes the next fraction in specified \fIDIRECTION\fR by \fIFRACTIONDELTA\fR\&. \fIDIRECTION\fR is specified at the \fIfocus\fR command\&. You should not omit the sign \fI\-\fR or \fI+\fR, because in future versions, the behaviour may change if the sign is omitted\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} resize right +0\&.05 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} resize down \-0\&.1 .RE .RE .PP shift [\fI\-i\fR|\fI\-e\fR] \fIDIRECTION\fR .RS 4 Shifts the focused window to the next frame in the specified \fIDIRECTION\fR\&. The \fIDIRECTIONS\fR and \fI\-i\fR|\fI\-e\fR behave as specified at the \fIfocus\fR command\&. If \fIfocus_follows_shift\fR is set, then focus stays in the window; otherwise it stays in the frame\&. .RE .PP remove .RS 4 Removes focused frame and merges its windows to its neighbour frame\&. .RE .PP set \fINAME\fR \fIVALUE\fR .RS 4 Sets the specified setting \fINAME\fR to \fIVALUE\fR\&. All \fBSETTINGS\fR are listed in the section below\&. .RE .PP get \fINAME\fR .RS 4 Prints the value of setting \fINAME\fR\&. All \fBSETTINGS\fR are listed in the section below\&. .RE .PP toggle \fINAME\fR .RS 4 Toggles the setting \fINAME\fR if it\(cqs an integer setting: if its value is unequal to 0, it becomes 0; else its previous value (which was unequal to 0) is restored\&. .RE .PP cycle_value \fINAME\fR \fIVALUES\fR \&... .RS 4 Cycles value of the setting \fINAME\fR through \fIVALUES\fR: I\&.e\&. it searches the first occurence of the current value in \fIVALUES\fR and changes the value to the next in the list or to the first one if the end is reached or current value wasn\(cqt found\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} cycle_value window_gap 0 5 10 15 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} cycle_value frame_bg_normal_color red green blue .RE .RE .PP cycle_monitor [\fIDELTA\fR] .RS 4 Cycles monitor focused by \fIDELTA\fR\&. \fIDELTA\fR defaults to 1\&. .RE .PP focus_monitor \fIINDEX\fR .RS 4 Puts focus to monitor with specified \fIINDEX\fR (as specified by the list_monitors command) .RE .PP add \fITAG\fR .RS 4 Creates a new empty tag named \fITAG\fR\&. .RE .PP use \fITAG\fR .RS 4 Switches the focused monitor to specified \fITAG\fR\&. .RE .PP use_index \fIINDEX\fR .RS 4 Switches the focused monitor to the \fITAG\fR with the specified \fIINDEX\fR\&. If \fIINDEX\fR starts with + or \-, then \fIINDEX\fR is treated relative to the current \fITAG\fR\&. E\&.g\&. this cycles backwards through the tags: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} use_index \-1 .RE .RE .PP merge_tag \fITAG\fR [\fITARGET\fR] .RS 4 Removes tag named \fITAG\fR and moves all its windows to tag \fITARGET\fR\&. If \fITARGET\fR is omitted, the focused tag will be used\&. .RE .PP rename \fIOLDTAG\fR \fINEWTAG\fR .RS 4 Renames tag named \fIOLDTAG\fR to \fINEWTAG\fR\&. .RE .PP move \fITAG\fR .RS 4 Moves the focused window to tag named \fITAG\fR\&. .RE .PP move_index \fIINDEX\fR .RS 4 Moves the focused window to the tag specified by \fIINDEX\fR\&. Analogical to the argument for \fBuse_index\fR: If \fIINDEX\fR starts with + or \-, then it is treated relative\&. .RE .PP add_monitor \fIRECT\fR [\fITAG\fR [\fIPADUP\fR [\fIPADRIGHT\fR [\fIPADDOWN\fR [\fIPADLEFT\fR]]]]] .RS 4 Adds a monitor on the specified rectangle \fIRECT\fR and displays \fITAG\fR on it\&. \fITAG\fR currently must not be displayed on any other monitor\&. \fIRECT\fR is a string of the form \fIWxH\(+-X\(+-Y\fR\&. The padding specifies extra space around the monitor for some statusbars/panels\&. If no or an empty padding is given, it is set to 0\&. If no or an empty \fITAG\fR is given, then any free tag will be chosen\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} add_monitor 1024x768\-20+0 mynewtag 16 .RE .RE .PP remove_monitor \fIINDEX\fR .RS 4 Removes the monitor with specified \fIINDEX\fR\&. Its \fIINDEX\fR can be found out via the \fIlist_monitors\fR command\&. .RE .PP move_monitor \fIINDEX\fR \fIRECT\fR [\fIPADUP\fR [\fIPADRIGHT\fR [\fIPADDOWN\fR [\fIPADLEFT\fR]]]] .RS 4 Moves the monitor with specified \fIINDEX\fR to rectangle \fIRECT\fR\&. \fIINDEX\fR and \fIRECT\fR are defined as in \fIremove_monitor\fR and \fIadd_monitor\fR\&. If no or an empty pad is given, it is not changed\&. .RE .PP monitor_rect [[\-p] \fIINDEX\fR] .RS 4 Prints the rectangle of the specified \fIINDEX\fR in the format: \fBX Y W H\fR If no \fIINDEX\fR or \fIcur\fR is given, then the current Monitor is used\&. If \fI\-p\fR is supplied, then the remaining rect without the pad around this monitor is printed\&. .RE .PP pad \fIINDEX\fR [\fIPADUP\fR [\fIPADRIGHT\fR [\fIPADDOWN\fR [\fIPADLEFT\fR]]]] .RS 4 Sets the pad of indexed monitor to the specified padding\&. If no or an empty padding is given, it is not changed\&. .RE .PP layout [\fITAG\fR] .RS 4 Prints the layout of \fITAG\fR in a nice tree style\&. Its style is defined by the \fItree_style\fR setting\&. If no \fITAG\fR is given, current tag is used\&. An example output is: .sp .if n \{\ .RS 4 .\} .nf ╾─┐horizontal 50% selection=1 ├╼ vertical: 0xe00009 └─┐vertical 50% selection=0 ├╼ vertical: 0xa00009 [FOCUS] └╼ vertical: 0x1000009 .fi .if n \{\ .RE .\} .RE .PP dump [\fITAG\fR] .RS 4 Prints the same information as the \fIlayout\fR command but in a machine readable format\&. Its output can be read back with the \fIload\fR command\&. An example output (formatted afterwards) is: .sp .if n \{\ .RS 4 .\} .nf (split horizontal:0\&.500000:1 (clients vertical:0 0xe00009) (splitvertical:0\&.500000:1 (clients vertical:0 0xa00009) (clients vertical:0 0x1000009))) .fi .if n \{\ .RE .\} .RE .PP load [\fITAG\fR] \fILAYOUT\fR .RS 4 Loads a given \fILAYOUT\fR description to specified \fITAG\fR or current tag if no \fITAG\fR is given\&. .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBCaution\fR .ps -1 .br .sp \fILAYOUT\fR is exactly one parameter\&. If you are calling it manually from your shell or from a script, quote it properly! .sp .5v .RE .PP complete \fIPOSITION\fR [\fICOMMAND\fR \fIARGS \&...\fR] .RS 4 Prints the result of tab completion in partial written \fICOMMAND\fR with optional \fIARGS\fR\&. You usually do not need this, because there is already tab completion for bash\&. Example: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} complete 0 m prints all commands beginning with m .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} complete 1 toggle fra prints all settings beginning with fra that can be toggled .RE .RE .PP emit_hook \fIARGS \&...\fR .RS 4 Emits a custom hook to all idling herbstclients\&. .RE .PP tag_status [\fIMONITOR\fR] .RS 4 Print a tab separated list of all tags for specified \fIMONITOR\fR index\&. If no \fIMONITOR\fR index is given, the focused monitor is used\&. Each tag name is prefixed with one char, which indicates its state: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\&.\fR the tag is empty .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB:\fR the tag is not empty .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB+\fR the tag is viewed on the specified \fIMONITOR\fR, but this monitor is not focused\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB#\fR the tag is viewed on the specified \fIMONITOR\fR and it is focused\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB!\fR the tag contains an urgent window .RE .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBWarning\fR .ps -1 .br .sp If you use a tab in one of the tag names, then tag_status is probably quite useless for you\&. .sp .5v .RE .PP floating [[\fITAG\fR] on|off|toggle|status] .RS 4 Changes the current tag to floating/tiling mode on specified \fITAG\fR or prints it current status\&. If no \fITAG\fR is given, current tag is used\&. If no argument is given, floating mode is toggled\&. If status is given, then on or off is printed, depending of the floating state on \fITAG\fR\&. .RE .PP rule [[\-\-]\fIFLAG\fR|[\-\-]\fICONDITION\fR|[\-\-]\fICONSEQUENCE\fR \&...] .RS 4 Defines a rule which will be applied to all new clients\&. Its behaviour is described in the \fBRULES section\fR\&. .RE .PP unrule \fB\-\-all\fR|\fB\-F\fR .RS 4 If \-\-all or \-F is passed, then all rules are removed\&. (It is not possible yet to remove certain rules) .RE .PP fullscreen \fBon\fR|\fBoff\fR|\fBtoggle\fR .RS 4 Sets or toggles the fullscreen state of the focused client\&. .RE .PP pseudotile \fBon\fR|\fBoff\fR|\fBtoggle\fR .RS 4 Sets or toggles the pseudotile state of the focused client\&. If a client is pseudotiled, then in tiling mode the client is only moved but not resized \- the client size will stay the floating size\&. The only reason to resize the client is to ensure, that it fits into its tile\&. .RE .SH "SETTINGS" .sp Settings configure the behaviour of herbstluftwm and can be controlled via the \fIset\fR, \fIget\fR and \fItoggle\fR command\&. There are two types of settings: Strings and integer values\&. An integer value is set, if its value is 1 or another value unequal to 0\&. An integer value is unset, if its value is 0\&. .PP window_gap (Integer) .RS 4 The gap between frames in the tiling mode\&. .RE .PP snap_distance (Integer) .RS 4 If a client is dragged in floating mode, then it snaps to neighbour clients if the distance between them is smaller then snap_distance\&. .RE .PP snap_gap (Integer) .RS 4 Specifies the remaining gap if a dragged client snaps to an edge in floating mode\&. If snap_gap is set to 0, no gap will remain\&. .RE .PP frame_border_active_color (String/Color) .RS 4 The border color of a focused frame .RE .PP frame_border_normal_color (String/Color) .RS 4 The border color of an unfocused frame .RE .PP frame_bg_active_color (String/Color) .RS 4 The fill color of a focused frame .RE .PP frame_bg_normal_color (String/Color) .RS 4 The fill color of an unfocused frame (It is only visible if always_show_frame is set) .RE .PP frame_bg_transparent (Integer) .RS 4 If set, frames have transparent backgrounds\&. .RE .PP frame_border_width (Integer) .RS 4 Border width of a frame .RE .PP raise_on_focus (Integer) .RS 4 If set, a window is raised if it is focused\&. The value of this setting is only noticed in floating mode\&. .RE .PP raise_on_click (Integer) .RS 4 If set, a window is raised if it is clicked\&. The value of this setting is only noticed in floating mode\&. .RE .PP window_border_width (Integer) .RS 4 Border width of a window\&. .RE .PP window_border_active_color (String/Color) .RS 4 Border color of a focused window\&. .RE .PP window_border_normal_color (String/Color) .RS 4 Border color of an unfocused window\&. .RE .PP always_show_frame (Integer) .RS 4 If set, all frames are displayed\&. If unset, only frames with focus or with windows in it are displayed\&. .RE .PP default_frame_layout (Integer) .RS 4 Index of the frame layout, which is used if a new frame is created (by split or on a new tag)\&. For a list of valid indizes and their meanings, check the list of layout algorithms above\&. .RE .PP default_direction_external_only (Integer) .RS 4 This setting controls the behaviour of focus and shift if no \fI\-e\fR or \fI\-i\fR argument is given\&. if set, then focus and shift changes the focused frame even if there are other clients in this frame in the specified \fIDIRECTION\fR\&. Else, a client within current frame is selected if it is in the specified \fIDIRECTION\fR\&. .RE .PP gapless_grid (Integer) .RS 4 This setting affects the size of the last client in a frame that is arranged by grid layout\&. If set, then the last client always fills the gap within this frame\&. If unset, then the last client has the same size as all other clients in this frame\&. .RE .PP focus_follows_shift (Integer) .RS 4 If set, focus stays in the window, if window is shifted to another frame\&. If unset, focus stays in the frame\&. .RE .PP focus_follows_mouse (Integer) .RS 4 If set and a window is focused by mouse cursor, this window is focused (This feature is also known as sloppy focus)\&. If unset, you need to click to change the window focus by mouse\&. .RE .PP focus_stealing_prevention (Integer) .RS 4 If set, only pagers and taskbars are allowed to change the focus\&. If unset, all applications can request a focus change\&. .RE .PP monitors_locked (Integer) .RS 4 If greater than 0, then the clients on all monitors aren\(cqt moved or resized anymore\&. If it is set to 0, then the arranging of monitors is enabled again, and all monitors are rearranged if their content has changed in the meantime\&. You should not change this setting manually due to concurrency issues; use the commands \fBlock\fR and \fBunlock\fR instead\&. .RE .PP swap_monitors_to_get_tag (Integer) .RS 4 If set: If you want to view a tag, that already is viewed on another monitor, then the monitor contents will be swapped and you see the wanted tag on the focused monitor\&. If not set, nothing will be swapped\&. .RE .PP tree_style (String) .RS 4 It contains the chars that are used to print a nice ascii tree\&. It must contain at least 8 characters\&. e\&.g\&. X|:#+*\-\&. produces a tree like: .sp .if n \{\ .RS 4 .\} .nf X\-\&.root #\-\&.child 0 | #* child 01 | +* child 02 +\-\&.child 1 : #* child 10 : +* child 01 .fi .if n \{\ .RE .\} .sp Useful values for \fItree_style\fR are: ╾│ ├└╼─┐ or ╾│ ├╰╼─╮\&. .RE .SH "RULES" .sp Rules are used to change default properties for certain clients when they appear\&. Each rule matches against a certain subset of all clients and defines a set of properties for them (called \fICONSEQUENCES\fR)\&. A rule can be defined with this command: .sp rule [[\-\-]\fIFLAG\fR|[\-\-]\fICONDITION\fR|[\-\-]\fICONSEQUENCE\fR \&...] .sp Each rule consists of a list of \fIFLAGS\fR, \fICONDITIONS\fR and \fICONSEQUENCES\fR (each of them can be optionally prefixed with two dashes (\-\-) to provide a more \fBiptables\fR(8)\-like feeling)\&. .sp If a new client appears, herbstluftwm tries to apply each rule to this new client as follows: If each \fICONDITION\fR of this rule matches against this client, then every \fICONSEQUENCE\fR is executed\&. (If there are no conditions given, then this rule is executed for each client) .sp Each \fICONDITION\fR consists of a \fIproperty\fR name, an operator and a \fIvalue\fR\&. Valid operators are: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} ~ matches if client\(cqs \fIproperty\fR is matched by the regex \fIvalue\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} = matches if client\(cqs \fIproperly\fR string is equal to \fIvalue\fR\&. .RE .sp Valid \fIproperties\fR are: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} instance: the first entry in client\(cqs WM_CLASS\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} class: the second entry in client\(cqs WM_CLASS\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} title: client\(cqs window title\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} pid: the client\(cqs process id (Warning: the pid is not available for every client\&. This only matches if the client sets the pid to the _NET_WM_PID itself)\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} maxage: matches if the age of the rule measured in seconds does not exceed \fIvalue\fR\&. This condition only can be used with the = operator\&. If maxage already is exceeded (and never will match again), then this rule is removed\&. (With this you can build rules that only live for a certain time\&.) .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} windowtype: matches the _NET_WM_WINDOW_TYPE property of a window\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} windowrole: matches the WM_WINDOW_ROLE property of a window if it is set by the window\&. .RE .sp Each \fICONSEQUENCE\fR consists of a \fINAME\fR=\fIVALUE\fR pair\&. Valid \fINAMES\fR are: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} tag: moves the client to tag \fIVALUE\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} focus: decides whether the client gets the input focus on his tag\&. The default is \fBoff\fR\&. \fIVALUE\fR can be \fBon\fR, \fBoff\fR or \fBtoggle\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} manage: decides whether the client will be managed or not\&. The default is \fBon\fR\&. \fIVALUE\fR can be \fBon\fR, \fBoff\fR or \fBtoggle\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} index: moves the window to a specified index in the tree\&. \fIVALUE\fR contains of a list of characters; each of them decides in which subtree the window is inserted\&. .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 0: insert it in the first subtree .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 1: insert it in the second subtree .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \&.: insert it in the subtree that has the focus .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /: insert it in the subtree that has not the focus .RE .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} pseudotile: sets the pseudotile state of the client\&. \fIVALUE\fR can be \fBon\fR, \fBoff\fR or \fBtoggle\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} fullscreen: sets the fullscreen flag of the client\&. \fIVALUE\fR can be \fBon\fR, \fBoff\fR or \fBtoggle\fR\&. .RE .sp A rule\(cqs behaviour can be configured by some special \fIFLAGS\fR: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} not: negates the next \fICONDITION\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} !: same as not\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} once: only apply this rule once (and delete it afterwards)\&. .RE .sp Examples: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} rule \-\-class=Netscape \-\-tag=6 \-\-focus=off Moves all Netscape instances to tag 6, but doesn\(cqt give focus to them\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} rule not class~\&.*[Tt]erm tag=2 Moves all clients to tag 2, if their class does not end with term or Term\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} rule class=Thunderbird index=/0 Insert all Thunderbird instances in the tree that has no focus and there in the first child\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} rule \-\-windowtype=_NET_WM_WINDOW_TYPE_DIALOG \-\-focus=on Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE correctly\&. .RE .SH "AUTOSTART FILE" .sp There is no configuration file but an autostart file, which is executed on startup\&. It is also executed on command \fIreload\fR\&. If not specified by the \fB\-\-autostart\fR argument, autostart file is located at \fI$XDG_CONFIG_HOME/herbstluftwm/autostart\fR or at \fI~/\&.config/herbstluftwm/autostart\fR\&. Normally it consists of a few \fBherbstclient\fR calls\&. .sp For a quick install, copy the default autostart file to \fI~/\&.config/herbstluftwm/\fR\&. .SH "HOOKS" .sp On special events, herbstluftwm emits some hooks (with parameters)\&. You can receive or wait for them with \fBherbstclient\fR(1)\&. Also custom hooks can be emitted with the \fBemit_hook\fR command\&. The following hooks are emitted by herbstluftwm itself: .PP fullscreen [on|off] \fIWINID\fR \fISTATE\fR .RS 4 The fullscreen state of window \fIWINID\fR was changed to [on|off]\&. .RE .PP tag_changed \fITAG\fR \fIMONITOR\fR .RS 4 The tag \fITAG\fR was selected on \fIMONITOR\fR\&. .RE .PP focus_changed \fIWINID\fR \fITITLE\fR .RS 4 The window \fIWINID\fR was focused\&. Its window title is \fITITLE\fR\&. .RE .PP window_title_changed \fIWINID\fR \fITITLE\fR .RS 4 The title of the \fBfocused\fR window was changed\&. Its window id is \fIWINID\fR and its new title is \fITITLE\fR\&. .RE .PP tag_flags .RS 4 The flags (i\&.e\&. urgent or filled state) have been changed\&. .RE .PP tag_added \fITAG\fR .RS 4 A tag named \fITAG\fR was added\&. .RE .PP tag_removed \fITAG\fR .RS 4 The tag named \fITAG\fR was removed\&. .RE .PP urgent [on|off] \fIWINID\fR .RS 4 The urgent state of client with given \fIWINID\fR has been changed to [on|off]\&. .RE .sp There are also other useful hooks, which never will be emitted by herbstluftwm itself, but which can be emitted with the \fBemit_hook\fR command: .PP quit_panel .RS 4 Tells a panel to quit\&. The default panel\&.sh quits on this hook\&. Many scripts are using this hook\&. .RE .PP reload .RS 4 Tells all daemons that the \fIautostart\fR file is reloaded \(em and tells them to quit\&. This hook \fBshould\fR be emitted in the first line of every \fIautostart\fR file\&. .RE .SH "ENVIRONMENT VARIABLES" .PP DISPLAY .RS 4 Specifies the \fIDISPLAY\fR to use\&. .RE .SH "EXIT STATUS" .sp Returns \fB0\fR on success\&. Returns EXIT_FAILURE if it cannot startup or if \fIwmexec\fR fails\&. .SH "BUGS" .sp See the \fBherbstluftwm\fR distribution BUGS file\&. .SH "COMMUNITY" .sp Feel free to join the IRC channel \fI#herbstluftwm\fR on \fIirc\&.freenode\&.net\fR\&. .SH "AUTHOR" .sp \fBherbstluftwm\fR was written by Thorsten Wißmann\&. .SH "RESOURCES" .sp Gitweb: http://git\&.cs\&.fau\&.de/?p=re06huxa/herbstluftwm .SH "COPYING" .sp Copyright 2011\-2012 Thorsten Wißmann\&. All rights reserved\&. .sp This software is licensed under the "Simplified BSD License"\&. See LICENSE for details