This option determines in which mode new containers on workspace level will
start.
-///////////////////////////////
-See also <<stack-limit>>.
-//////////////////////////////
*Syntax*:
---------------------------------------------
workspace_layout default|stacking|tabbed
---------------------------------------------
-/////////////////////////////////////////////
-new_container stack-limit <cols|rows> <value>
-/////////////////////////////////////////////
*Example*:
---------------------
=== 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 <px>
-new_float normal|1pixel|none|pixel
+new_float normal|none|pixel
new_float normal|pixel <px>
---------------------------------------------
*Example*:
---------------------
-new_window 1pixel
+new_window pixel
---------------------
The "normal" and "pixel" border styles support an optional border width in
=== 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.
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
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
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*:
------------------------
-------------------------------------------------
bar {
status_command i3status --config ~/.i3status.conf
+
+ # For dash(1) users who want signal handling to work:
+ status_command exec ~/.bin/my_status_command
}
-------------------------------------------------
=== 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<n>+, 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 <command>
-wheel_down_cmd <command>
----------------------
+----------------------------
+bindsym button<n> <command>
+----------------------------
*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
you can turn off the functionality entirely.
*Syntax*:
--------------------------------
-tray_output none|primary|output
--------------------------------
+---------------------------------
+tray_output none|primary|<output>
+---------------------------------
*Example*:
-------------------------
}
# show tray icons on the primary monitor
-tray_output primary
+bar {
+ tray_output primary
+}
# show tray icons on the big monitor
bar {
xrandr --output <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> [px]
+-------------------------
+
+*Example*:
+-------------------------
+# Obey Fitts's law
+tray_padding 0
+-------------------------
+
=== Font
Specifies the font to be used in the bar. See <<fonts>>.
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*:
----------------------------------------
active_workspace #333333 #5f676a #ffffff
inactive_workspace #333333 #222222 #888888
urgent_workspace #2f343a #900000 #ffffff
+ binding_mode #2f343a #900000 #ffffff
}
}
--------------------------------------
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 <<vim_like_marks>>.
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]]
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 <<for_window>> directive, you can set the title format for any window
+based on <<command_criteria>>.
+
+*Syntax*:
+---------------------
+title_format <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 "<b>%title</b>"
-[[stack-limit]]
+# print window titles of firefox windows red
+for_window [class="(?i)firefox"] title_format "<span foreground='red'>%title</span>"
+-------------------------------------------------------------------------------------
-///////////////////////////////////////////////////////////////////////////////
-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 <value>
------------------------------
-
-*Examples*:
--------------------
-# I always want to have two window titles in one line
-stack-limit cols 2
+-----------------------------------------------
+border normal|pixel [<n>]
+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]]