X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fuserguide;h=e21553815601c5bebd60c5793c22595afd6863f5;hb=05fb9096362e788f032de6eccea2d7fea03317ab;hp=2ef17f38f823d01265a75f427cacda0b367014f6;hpb=651f3150d4d5137dd7999ff88516188eb7a7f2f2;p=i3%2Fi3 diff --git a/docs/userguide b/docs/userguide index 2ef17f38..e2155381 100644 --- a/docs/userguide +++ b/docs/userguide @@ -503,17 +503,11 @@ default_orientation vertical This option determines in which mode new containers on workspace level will start. -/////////////////////////////// -See also <>. -////////////////////////////// *Syntax*: --------------------------------------------- workspace_layout default|stacking|tabbed --------------------------------------------- -///////////////////////////////////////////// -new_container stack-limit -///////////////////////////////////////////// *Example*: --------------------- @@ -523,20 +517,20 @@ workspace_layout tabbed === Border style for new windows This option determines which border style new windows will have. The default is -"normal". Note that new_float applies only to windows which are starting out as -floating windows, e.g. dialog windows. ++normal+. Note that new_float applies only to windows which are starting out as +floating windows, e.g., dialog windows, but not windows that are floated later on. *Syntax*: --------------------------------------------- -new_window normal|1pixel|none|pixel +new_window normal|none|pixel new_window normal|pixel -new_float normal|1pixel|none|pixel +new_float normal|none|pixel new_float normal|pixel --------------------------------------------- *Example*: --------------------- -new_window 1pixel +new_window pixel --------------------- The "normal" and "pixel" border styles support an optional border width in @@ -570,6 +564,8 @@ hide_edge_borders vertical === Arbitrary commands for specific windows (for_window) +[[for_window]] + With the +for_window+ command, you can let i3 execute any command when it encounters a specific window. This can be used to set windows to floating or to change their border style, for example. @@ -585,7 +581,7 @@ for_window for_window [class="XTerm"] floating enable # Make all urxvts use a 1-pixel border: -for_window [class="urxvt"] border 1pixel +for_window [class="urxvt"] border pixel 1 # A less useful, but rather funny example: # makes the window floating as soon as I change @@ -1082,6 +1078,20 @@ show_marks yes|no show_marks yes -------------- +[[line_continuation]] + +=== Line continuation + +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. + +*Examples*: +------------------- +bindsym Mod1+f \ +fullscreen toggle +------------------- + == Configuring i3bar The bar at the bottom of your monitor is drawn by a separate process called @@ -1143,7 +1153,10 @@ right hand side of the bar. This is useful to display system information like your current IP address, battery status or date/time. The specified command will be passed to +sh -c+, so you can use globbing and -have to have correct quoting etc. +have to have correct quoting etc. Note that for signal handling, depending on +your shell (users of dash(1) are known to be affected), you have to use the +shell’s exec command so that signals are passed to your program, not to the +shell. *Syntax*: ------------------------ @@ -1154,6 +1167,9 @@ status_command ------------------------------------------------- bar { status_command i3status --config ~/.i3status.conf + + # For dash(1) users who want signal handling to work: + status_command exec ~/.bin/my_status_command } ------------------------------------------------- @@ -1209,23 +1225,41 @@ Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). === Mouse button commands Specifies a command to run when a button was pressed on i3bar to override the -default behavior. Currently only the mouse wheel buttons are supported. This is -useful for disabling the scroll wheel action or running scripts that implement -custom behavior for these buttons. +default behavior. This is useful, e.g., for disabling the scroll wheel action +or running scripts that implement custom behavior for these buttons. + +A button is always named +button+, where 1 to 5 are default buttons as follows and higher +numbers can be special buttons on devices offering more buttons: + +button1:: + Left mouse button. +button2:: + Middle mouse button. +button3:: + Right mouse button. +button4:: + Scroll wheel up. +button5:: + Scroll wheel down. + +Please note that the old +wheel_up_cmd+ and +wheel_down_cmd+ commands are deprecated +and will be removed in a future release. We strongly recommend using the more general ++bindsym+ with +button4+ and +button5+ instead. *Syntax*: ---------------------- -wheel_up_cmd -wheel_down_cmd ---------------------- +---------------------------- +bindsym button +---------------------------- *Example*: ---------------------- +--------------------------------------------------------- bar { - wheel_up_cmd nop - wheel_down_cmd exec ~/.i3/scripts/custom_wheel_down + # disable clicking on workspace buttons + bindsym button1 nop + # execute custom script when scrolling downwards + bindsym button5 exec ~/.i3/scripts/custom_wheel_down } ---------------------- +--------------------------------------------------------- === Bar ID @@ -1320,7 +1354,9 @@ bar { } # show tray icons on the primary monitor -tray_output primary +bar { + tray_output primary +} # show tray icons on the big monitor bar { @@ -1333,6 +1369,23 @@ Note that you might not have a primary output configured yet. To do so, run: xrandr --output --primary ------------------------- +=== Tray padding + +The tray is shown on the right-hand side of the bar. By default, a padding of 2 +pixels is used for the upper, lower and right-hand side of the tray area and +between the individual icons. + +*Syntax*: +------------------------- +tray_padding [px] +------------------------- + +*Example*: +------------------------- +# Obey Fitts's law +tray_padding 0 +------------------------- + === Font Specifies the font to be used in the bar. See <>. @@ -1457,7 +1510,10 @@ inactive_workspace:: will be the case for most workspaces. urgent_workspace:: Border, background and text color for a workspace button when the workspace - contains a window with the urgency hint set. Also applies to +mode+ indicators. + contains a window with the urgency hint set. +binding_mode:: + Border, background and text color for the binding mode indicator. If not used, + the colors will be taken from +urgent_workspace+. *Syntax*: ---------------------------------------- @@ -1482,6 +1538,7 @@ bar { active_workspace #333333 #5f676a #ffffff inactive_workspace #333333 #222222 #888888 urgent_workspace #2f343a #900000 #ffffff + binding_mode #2f343a #900000 #ffffff } } -------------------------------------- @@ -1556,14 +1613,16 @@ urgent:: Compares the urgent state of the window. Can be "latest" or "oldest". Matches the latest or oldest urgent window, respectively. (The following aliases are also available: newest, last, recent, first) +workspace:: + Compares the workspace name of the workspace the window belongs to. con_mark:: Compares the mark set for this container, see <>. con_id:: Compares the i3-internal container ID, which you can get via the IPC interface. Handy for scripting. -The criteria +class+, +instance+, +role+, +title+ and +mark+ are actually -regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for +The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are +actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for information on how to use them. [[exec]] @@ -2044,52 +2103,63 @@ 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. /////////////////////////////////////////////////////////////////// -=== Changing border style +=== Window title format -To change the border of the current client, you can use +border normal+ to use the normal -border (including window title), +border 1pixel+ to use a 1-pixel border (no window title) -and +border none+ to make the client borderless. +By default, i3 will simply print the X11 window title. Using +title_format+, +this can be customized by setting the format to the desired output. This +directive supports +https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup] +and the following placeholders which will be replaced: -There is also +border toggle+ which will toggle the different border styles. ++%title+:: + The X11 window title (_NET_WM_NAME or WM_NAME as fallback). + +Using the <> directive, you can set the title format for any window +based on <>. + +*Syntax*: +--------------------- +title_format +--------------------- *Examples*: ----------------------------- -bindsym $mod+t border normal -bindsym $mod+y border 1pixel -bindsym $mod+u border none ----------------------------- +------------------------------------------------------------------------------------- +# give the focused window a prefix +bindsym $mod+p title_format "Important | %title" + +# print all window titles bold +for_window [class=".*"] title_format "%title" -[[stack-limit]] +# print window titles of firefox windows red +for_window [class="(?i)firefox"] title_format "%title" +------------------------------------------------------------------------------------- -/////////////////////////////////////////////////////////////////////////////// -TODO: not yet implemented -=== Changing the stack-limit of a container +=== Changing border style -If you have a single container with a lot of windows inside it (say, more than -10), the default layout of a stacking container can get a little unhandy. -Depending on your screen’s size, you might end up with only half of the title -lines being actually used, wasting a lot of screen space. +To change the border of the current client, you can use +border normal+ to use the normal +border (including window title), +border pixel 1+ to use a 1-pixel border (no window title) +and +border none+ to make the client borderless. -Using the +stack-limit+ command, you can limit the number of rows or columns -in a stacking container. i3 will create columns or rows (depending on what -you limited) automatically as needed. +There is also +border toggle+ which will toggle the different border styles. *Syntax*: ------------------------------ -stack-limit cols|rows ------------------------------ - -*Examples*: -------------------- -# I always want to have two window titles in one line -stack-limit cols 2 +----------------------------------------------- +border normal|pixel [] +border none|toggle -# Not more than 5 rows in this stacking container -stack-limit rows 5 -------------------- +# legacy syntax, equivalent to "border pixel 1" +border 1pixel +----------------------------------------------- -image:stacklimit.png[Container limited to two columns] -/////////////////////////////////////////////////////////////////////////////// +*Examples*: +---------------------------------------------- +# use window title, but no border +bindsym $mod+t border normal 0 +# use no window title and a thick border +bindsym $mod+y border pixel 3 +# use neither window title nor border +bindsym $mod+u border none +---------------------------------------------- [[shmlog]]