X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fuserguide;h=9abdd5b0cea8a631dfd45e89dc8f5306803073e0;hb=4bec3b9d24fe0bd7bab4792497bbd02bffaa6620;hp=0d63269f861401b11f8d8d86932eda5755f8f353;hpb=60158d31a29d9f70f8e950015f6c8105ac2f1fda;p=i3%2Fi3 diff --git a/docs/userguide b/docs/userguide index 0d63269f..9abdd5b0 100644 --- a/docs/userguide +++ b/docs/userguide @@ -4,8 +4,9 @@ Michael Stapelberg March 2013 This document contains all the information you need to configure and use the i3 -window manager. If it does not, please check http://faq.i3wm.org/ first, then -contact us on IRC (preferred) or post your question(s) on the mailing list. +window manager. If it does not, please check https://www.reddit.com/r/i3wm/ +first, then contact us on IRC (preferred) or post your question(s) on the +mailing list. == Default keybindings @@ -604,15 +605,18 @@ new_window pixel 3 --------------------- -=== Hiding vertical borders +[[_hiding_vertical_borders]] +=== Hiding borders adjacent to the screen edges -You can hide vertical borders adjacent to the screen edges using +You can hide container borders adjacent to the screen edges using +hide_edge_borders+. This is useful if you are using scrollbars, or do not want -to waste even two pixels in displayspace. Default is none. +to waste even two pixels in displayspace. The "smart" setting hides borders on +workspaces with only one window visible, but keeps them on workspaces with +multiple windows visible. Default is none. *Syntax*: ----------------------------------------------- -hide_edge_borders none|vertical|horizontal|both +hide_edge_borders none|vertical|horizontal|both|smart ----------------------------------------------- *Example*: @@ -698,6 +702,38 @@ absolutely no plans to change this. If you need a more dynamic configuration you should create a little script which generates a configuration file and run it before starting i3 (for example in your +~/.xsession+ file). +Also see <> to learn how to create variables based on resources +loaded from the X resource database. + +[[xresources]] +=== X resources + +<> can also be created using a value configured in the X resource +database. This is useful, for example, to avoid configuring color values within +the i3 configuration. Instead, the values can be configured, once, in the X +resource database to achieve an easily maintainable, consistent color theme +across many X applications. + +Defining a resource will load this resource from the resource database and +assign its value to the specified variable. A fallback must be specified in +case the resource cannot be loaded from the database. + +*Syntax*: +---------------------------------------------------- +set_from_resource $ +---------------------------------------------------- + +*Example*: +---------------------------------------------------------------------------- +# The ~/.Xresources should contain a line such as +# *color0: #121212 +# and must be loaded properly, e.g., by using +# xrdb ~/.Xresources +# This value is picked up on by other applications (e.g., the URxvt terminal +# emulator) and can be used in i3 like this: +set_from_resource $black i3wm.color0 #000000 +---------------------------------------------------------------------------- + [[assign_workspace]] === Automatically putting clients on specific workspaces @@ -784,7 +820,7 @@ keyword. These commands will be run in order. See <> for details on the special meaning of +;+ (semicolon) and +,+ (comma): they chain commands together in i3, so you need to use quoted -strings if they appear in your command. +strings (as shown in <>) if they appear in your command. *Syntax*: --------------------------------------- @@ -835,9 +871,9 @@ workspace "2: vim" output VGA1 You can change all colors which i3 uses to draw the window decorations. *Syntax*: ------------------------------------------------------- - ------------------------------------------------------- +-------------------------------------------------------------------- + +-------------------------------------------------------------------- Where colorclass can be one of: @@ -862,20 +898,20 @@ client.background:: Colors are in HTML hex format (#rrggbb), see the following example: *Examples (default colors)*: ---------------------------------------------------------- -# class border backgr. text indicator -client.focused #4c7899 #285577 #ffffff #2e9ef4 -client.focused_inactive #333333 #5f676a #ffffff #484e50 -client.unfocused #333333 #222222 #888888 #292d2e -client.urgent #2f343a #900000 #ffffff #900000 -client.placeholder #000000 #0c0c0c #ffffff #000000 +---------------------------------------------------------------------- +# class border backgr. text indicator child_border +client.focused #4c7899 #285577 #ffffff #2e9ef4 #285577 +client.focused_inactive #333333 #5f676a #ffffff #484e50 #5f676a +client.unfocused #333333 #222222 #888888 #292d2e #222222 +client.urgent #2f343a #900000 #ffffff #900000 #900000 +client.placeholder #000000 #0c0c0c #ffffff #000000 #0c0c0c client.background #ffffff ---------------------------------------------------------- +---------------------------------------------------------------------- Note that for the window decorations, the color around the child window is the -background color, and the border color is only the two thin lines at the top of -the window. +"child_border", and "border" color is only the two thin lines around the +titlebar. The indicator color is used for indicating where a new window will be opened. For horizontal split containers, the right border will be painted in indicator @@ -1113,11 +1149,15 @@ show_marks yes Config files support line continuation, meaning when you end a line in a backslash character (`\`), the line-break will be ignored by the parser. This feature can be used to create more readable configuration files. +Commented lines are not continued. *Examples*: ------------------- bindsym Mod1+f \ fullscreen toggle + +# this line is not continued \ +bindsym Mod1+F fullscreen toggle ------------------- == Configuring i3bar @@ -1236,7 +1276,7 @@ the windows key). The default value for the hidden_state is hide. ------------------------- mode dock|hide|invisible hidden_state hide|show -modifier +modifier |none ------------------------ *Example*: @@ -1248,7 +1288,8 @@ bar { } ---------------- -Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). +Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). You can +also use "none" if you don't want any modifier to trigger this behavior. === Mouse button commands @@ -1369,6 +1410,11 @@ NetworkManager, VLC, Pidgin, etc. can place little icons. You can configure on which output (monitor) the icons should be displayed or you can turn off the functionality entirely. +You can use multiple +tray_output+ directives in your config to specify a list +of outputs on which you want the tray to appear. The first available output in +that list as defined by the order of the directives will be used for the tray +output. + *Syntax*: --------------------------------- tray_output none|primary| @@ -1529,6 +1575,15 @@ statusline:: Text color to be used for the statusline. separator:: Text color to be used for the separator. +focused_background:: + Background color of the bar on the currently focused monitor output. If + not used, the color will be taken from +background+. +focused_statusline:: + Text color to be used for the statusline on the currently focused + monitor output. If not used, the color will be taken from +statusline+. +focused_separator:: + Text color to be used for the separator on the currently focused + monitor output. If not used, the color will be taken from +separator+. focused_workspace:: Border, background and text color for a workspace button when the workspace has focus. @@ -1643,7 +1698,7 @@ window_role:: window_type:: Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are +normal+, +dialog+, +utility+, +toolbar+, +splash+, +menu+, +dropdown_menu+, - +popup_menu+ and +tooltip+. + +popup_menu+, +tooltip+ and +notification+. id:: Compares the X11 window ID, which you can get via +xwininfo+ for example. title:: @@ -1681,7 +1736,7 @@ searched in your +$PATH+. See <> for details on the special meaning of +;+ (semicolon) and +,+ (comma): they chain commands together in i3, so you need to use quoted -strings if they appear in your command. +strings (as shown in <>) if they appear in your command. *Syntax*: -------------------------------- @@ -1705,6 +1760,27 @@ launching. So, if an application is not startup-notification aware (most GTK and Qt using applications seem to be, though), you will end up with a watch cursor for 60 seconds. +[[exec_quoting]] +If the command to be executed contains a +;+ (semicolon) and/or a +,+ (comma), +the entire command must be quoted. For example, to have a keybinding for the +shell command +notify-send Hello, i3+, you would add an entry to your +configuration file like this: + +*Example*: +------------------------------ +# Execute a command with a comma in it +bindsym $mod+p exec "notify-send Hello, i3" +------------------------------ + +If however a command with a comma and/or semicolon itself requires quotes, you +must escape the internal quotation marks with double backslashes, like this: + +*Example*: +------------------------------ +# Execute a command with a comma, semicolon and internal quotes +bindsym $mod+p exec "notify-send \\"Hello, i3; from $USER\\"" +------------------------------ + === Splitting containers The split command makes the current window a split container. Split containers @@ -1714,20 +1790,24 @@ get placed below the current one (splitv). If you apply this command to a split container with the same orientation, nothing will happen. If you use a different orientation, the split container’s -orientation will be changed (if it does not have more than one window). Use -+layout toggle split+ to change the layout of any split container from splitv -to splith or vice-versa. +orientation will be changed (if it does not have more than one window). +The +toggle+ option will toggle the orientation of the split container if it +contains a single window. Otherwise it makes the current window a split +container with opposite orientation compared to the parent container. +Use +layout toggle split+ to change the layout of any split container from +splitv to splith or vice-versa. *Syntax*: -------------------------- -split vertical|horizontal -------------------------- +-------------------------------- +split vertical|horizontal|toggle +-------------------------------- *Example*: ------------------------------- +------------------------------- bindsym $mod+v split vertical bindsym $mod+h split horizontal ------------------------------- +bindsym $mod+t split toggle +------------------------------- === Manipulating layout @@ -1884,8 +1964,11 @@ for_window [instance=notepad] sticky enable === Changing (named) workspaces/moving to workspaces To change to a specific workspace, use the +workspace+ command, followed by the -number or name of the workspace. To move containers to specific workspaces, use -+move container to workspace+. +number or name of the workspace. Pass the optional flag ++--no-auto-back-and-forth+ to disable <> for this specific call +only. + +To move containers to specific workspaces, use +move container to workspace+. You can also switch to the next and previous workspace with the commands +workspace next+ and +workspace prev+, which is handy, for example, if you have @@ -1913,16 +1996,16 @@ back_and_forth+; likewise, you can move containers to the previously focused workspace using +move container to workspace back_and_forth+. *Syntax*: ------------------------------------ +-------------------------------------------------------------------------------- workspace next|prev|next_on_output|prev_on_output workspace back_and_forth -workspace -workspace number +workspace [--no-auto-back-and-forth] +workspace [--no-auto-back-and-forth] number -move [window|container] [to] workspace -move [window|container] [to] workspace number +move [--no-auto-back-and-forth] [window|container] [to] workspace +move [--no-auto-back-and-forth] [window|container] [to] workspace number move [window|container] [to] workspace prev|next|current ------------------------------------ +-------------------------------------------------------------------------------- *Examples*: ------------------------- @@ -2159,7 +2242,7 @@ bindsym $mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: ' --------------------------------------- Alternatively, if you do not want to mess with +i3-input+, you could create -seperate bindings for a specific set of labels and then only use those labels. +separate bindings for a specific set of labels and then only use those labels. /////////////////////////////////////////////////////////////////// [[pango_markup]] @@ -2172,7 +2255,10 @@ https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup] and the following placeholders which will be replaced: +%title+:: - The X11 window title (_NET_WM_NAME or WM_NAME as fallback). + For normal windows, this is the X11 window title (_NET_WM_NAME or WM_NAME + as fallback). When used on containers without a window (e.g., a split + container inside a tabbed/stacked layout), this will be the tree + representation of the container (e.g., "H[xterm xterm]"). +%class+:: The X11 window class (second part of WM_CLASS). This corresponds to the +class+ criterion, see <>. @@ -2208,6 +2294,10 @@ and +border none+ to make the client borderless. There is also +border toggle+ which will toggle the different border styles. +Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel +may be represented by multiple physical pixels, so +pixel 1+ might not +necessarily translate into a single pixel row wide border. + *Syntax*: ----------------------------------------------- border normal|pixel []