X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fuserguide;h=7145442d2d2659610574ea3a6013abde681ab482;hb=cea6f7ad96c5e28274dd49c4c394db7f80884bde;hp=d97ef6aeea5da1a286cef96c3435d4bab5884f4c;hpb=18c2ef33d3312e1d72cc2d2ab49d3e1ea6632cdf;p=i3%2Fi3 diff --git a/docs/userguide b/docs/userguide index d97ef6ae..7145442d 100644 --- a/docs/userguide +++ b/docs/userguide @@ -174,7 +174,7 @@ Floating windows are always on top of tiling windows. i3 stores all information about the X11 outputs, workspaces and layout of the windows on them in a tree. The root node is the X11 root window, followed by the X11 outputs, then dock areas and a content container, then workspaces and -finally the windows themselve. In previous versions of i3 we had multiple lists +finally the windows themselves. In previous versions of i3 we had multiple lists (of outputs, workspaces) and a table for each workspace. That approach turned out to be complicated to use (snapping), understand and implement. @@ -323,7 +323,7 @@ bindcode [Modifiers+]keycode command *Examples*: -------------------------------- # Fullscreen -bindsym mod+f f +bindsym mod+f fullscreen # Restart bindsym mod+Shift+r restart @@ -357,7 +357,8 @@ it to the position you want. When holding the floating modifier, you can resize a floating window by pressing the right mouse button on it and moving around while holding it. If -you hold the shift button as well, the resize will be proportional. +you hold the shift button as well, the resize will be proportional (the aspect +ratio will be preserved). *Syntax*: -------------------------------- @@ -518,7 +519,7 @@ use it, it has to be a UTF-8 encoded arrow, not `->` or something like that. To get the class and instance, you can use +xprop+. After clicking on the window, you will see the following output: -*xwininfo*: +*xprop*: ----------------------------------- WM_CLASS(STRING) = "irssi", "URxvt" ----------------------------------- @@ -568,17 +569,20 @@ the second screen and so on). *Syntax*: ---------------------------------- -workspace output +workspace output ---------------------------------- The 'output' is the name of the RandR output you attach your screen to. On a laptop, you might have VGA1 and LVDS1 as output names. You can see the available outputs by running +xrandr --current+. +If you use named workspaces, they must be quoted: + *Examples*: --------------------------- workspace 1 output LVDS1 workspace 5 output VGA1 +workspace "2: vim" output VGA1 --------------------------- === Changing colors @@ -615,7 +619,7 @@ Only clients that do not cover the whole area of this window expose the color used to paint it. If you use a color other than black for your terminals, you most likely want to set the client background color to the same color as your terminal program's background color to avoid black gaps between the rendered -area of the termianal and the i3 border. +area of the terminal and the i3 border. Colors are in HTML hex format (#rrggbb), see the following example: @@ -639,16 +643,19 @@ programs to get information from i3, such as the current workspaces (to display a workspace bar), and to control i3. The IPC socket is enabled by default and will be created in -+/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the PID -of i3. ++/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is +the PID of i3 and XXXXXX is a string of random characters from the portable +filename character set (see mkdtemp(3)). You can override the default path through the environment-variable +I3SOCK+ or by specifying the +ipc-socket+ directive. This is discouraged, though, since i3 -does the right thing by default. +does the right thing by default. If you decide to change it, it is strongly +recommended to set this to a location in your home directory so that no other +user can create that directory. *Examples*: ---------------------------- -ipc-socket /tmp/i3-ipc.sock +ipc-socket ~/.i3/i3-ipc.sock ---------------------------- You can then use the +i3-msg+ application to perform any command listed in @@ -792,6 +799,28 @@ bar { } --------------------------- +=== i3bar command + +By default i3 will just pass +i3bar+ and let your shell handle the execution, +searching your +$PATH+ for a correct version. +If you have a different +i3bar+ somewhere or the binary is not in your +$PATH+ you can +tell i3 what to execute. + +The specified command will be passed to +sh -c+, so you can use globbing and +have to have correct quoting etc. + +*Syntax*: +---------------------- +i3bar_command command +---------------------- + +*Example*: +------------------------------------------------- +bar { + i3bar_command /home/user/bin/i3bar +} +------------------------------------------------- + === Statusline command i3bar can run a program and display every line of its +stdout+ output on the @@ -808,7 +837,9 @@ status_command command *Example*: ------------------------------------------------- -status_command i3status --config ~/.i3status.conf +bar { + status_command i3status --config ~/.i3status.conf +} ------------------------------------------------- === Display mode @@ -830,7 +861,9 @@ mode *Example*: ---------------- -mode hide +bar { + mode hide +} ---------------- === Position @@ -846,7 +879,9 @@ position *Example*: --------------------- -position top +bar { + position top +} --------------------- === Output(s) @@ -855,6 +890,9 @@ You can restrict i3bar to one or more outputs (monitors). The default is to handle all outputs. Restricting the outputs is useful for using different options for different outputs by using multiple 'bar' blocks. +To make a particular i3bar instance handle multiple outputs, specify the output +directive multiple times. + *Syntax*: --------------- output @@ -864,18 +902,20 @@ output ------------------------------- # big monitor: everything bar { - output HDMI2 - status_command i3status + # The display is connected either via HDMI or via DisplayPort + output HDMI2 + output DP2 + status_command i3status } # laptop monitor: bright colors and i3status with less modules. bar { - output LVDS1 - status_command i3status --config ~/.i3status-small.conf - colors { - background #000000 - statusline #ffffff - } + output LVDS1 + status_command i3status --config ~/.i3status-small.conf + colors { + background #000000 + statusline #ffffff + } } ------------------------------- @@ -895,10 +935,14 @@ tray_output *Example*: ------------------------- # disable system tray -tray_output none +bar { + tray_output none +} # show tray icons on the big monitor -tray_output HDMI2 +bar { + tray_output HDMI2 +} ------------------------- === Font @@ -913,7 +957,9 @@ font *Example*: -------------------------------------------------------------- -font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1 +bar { + font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1 +} -------------------------------------------------------------- === Workspace buttons @@ -930,7 +976,9 @@ workspace_buttons *Example*: -------------------- -workspace_buttons no +bar { + workspace_buttons no +} -------------------- === Colors @@ -970,14 +1018,16 @@ colors { *Example*: -------------------------------------- -colors { - background #000000 - statusline #ffffff - - focused_workspace #ffffff #285577 - active_workspace #888888 #222222 - inactive_workspace #888888 #222222 - urgent_workspace #ffffff #900000 +bar { + colors { + background #000000 + statusline #ffffff + + focused_workspace #ffffff #285577 + active_workspace #ffffff #333333 + inactive_workspace #888888 #222222 + urgent_workspace #ffffff #900000 + } } -------------------------------------- @@ -1059,7 +1109,7 @@ exec [--no-startup-id] command bindsym mod+g exec gimp # Start the terminal emulator urxvt which is not yet startup-notification-aware -bindsym mod+enter exec --no-startup-id urxvt +bindsym mod+Return exec --no-startup-id urxvt ------------------------------ The +--no-startup-id+ parameter disables startup-notification support for this @@ -1178,7 +1228,7 @@ number or name of the workspace. To move containers to specific workspaces, use 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 workspace 1, 3, 4 and 9 and you want to cycle through them with a single key -combination. Similarily, you can use +move workspace next+ and +move workspace +combination. Similarly, you can use +move workspace next+ and +move workspace prev+ to move a container to the next/previous workspace. [[back_and_forth]] @@ -1188,7 +1238,7 @@ back_and_forth+. To move a container to another xrandr output such as +LVDS1+ or +VGA1+, you can use the +move output+ command followed by the name of the target output. You may also use +left+, +right+, +up+, +down+ instead of the xrandr output name to -move to the the next output in the specified direction. +move to the next output in the specified direction. *Examples*: ------------------------- @@ -1244,9 +1294,9 @@ resize [ px] [or ppt] Direction can be one of +up+, +down+, +left+ or +right+. The optional pixel argument specifies by how many pixels a *floating container* should be grown or -shrinked (the default is 10 pixels). The ppt argument means percentage points +shrunk (the default is 10 pixels). The ppt argument means percentage points and specifies by how many percentage points a *tiling container* should be -grown or shrinked (the default is 10 percentage points). +grown or shrunk (the default is 10 percentage points). I recommend using the resize command inside a so called +mode+: @@ -1406,6 +1456,40 @@ bindsym mod+Shift+w reload bindsym mod+Shift+e exit ---------------------------- +=== Scratchpad + +There are two commands to use any existing window as scratchpad window. +move +scratchpad+ will move a window to the scratchpad workspace. This will make it +invisible until you show it again. There is no way to open that workspace. +Instead, when using +scratchpad show+, the window will be shown again, as a +floating window, centered on your current workspace (using +scratchpad show+ on +a visible scratchpad window will make it hidden again, so you can have a +keybinding to toggle). + +As the name indicates, this is useful for having a window with your favorite +editor always at hand. However, you can also use this for other permanently +running applications which you don’t want to see all the time: Your music +player, alsamixer, maybe even your mail client…? + +*Syntax*: +--------------- +move scratchpad + +scratchpad show +--------------- + +*Examples*: +------------------------------------------------ +# Make the currently focused window a scratchpad +bindsym mod+Shift+minus move scratchpad + +# Show the first scratchpad window +bindsym mod+minus scratchpad show + +# Show the sup-mail scratchpad window, if any. +bindsym mod4+s [title="^Sup ::"] scratchpad show +------------------------------------------------ + [[multi_monitor]] == Multiple monitors