You can also use <<binding_modes>> to define a mode for resizing via the
keyboard. To see an example for this, look at the
-https://github.com/i3/i3/blob/next/i3.config.keycodes[default config] provided
+https://github.com/i3/i3/blob/next/etc/config.keycodes[default config] provided
by i3.
=== Restarting i3 inplace
floating windows using the mouse is to right-click on the titlebar and drag.
For resizing floating windows with your keyboard, see the resizing binding mode
-provided by the i3 https://github.com/i3/i3/blob/next/i3.config.keycodes[default config].
+provided by the i3 https://github.com/i3/i3/blob/next/etc/config.keycodes[default config].
Floating windows are always on top of tiling windows.
Please note that you must not have +~/.i3/config+, otherwise the wizard will
exit.
+Since i3 4.0, a new configuration format is used. i3 will try to automatically
+detect the format version of a config file based on a few different keywords,
+but if you want to make sure that your config is read with the new format,
+include the following line in your config file:
+
+---------------------
+# i3 config file (v4)
+---------------------
+
=== Comments
It is possible and recommended to use comments in your configuration file to
can configure mouse bindings in a similar way to key bindings.
*Syntax*:
--------------------------------------------------------------------------------
-bindsym [--release] [--border] [--whole-window] [<Modifiers>+]button<n> command
--------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+bindsym [--release] [--border] [--whole-window] [--exclude-titlebar] [<Modifiers>+]button<n> command
+----------------------------------------------------------------------------------------------------
By default, the binding will only run when you click on the titlebar of the
window. If the +--release+ flag is given, it will run when the mouse button
of the window is clicked, with the exception of the border. To have a bind run
when the border is clicked, specify the +--border+ flag.
+If the +--exclude-titlebar+ flag is given, the titlebar will not be considered
+for the keybinding.
+
*Examples*:
--------------------------------
# The middle button over a titlebar kills the window
*Example*:
------------------------------------------------------------------------
-# Press $mod+o followed by either f, t, Esc or Return to launch firefox,
+# Press $mod+o followed by either f, t, Escape or Return to launch firefox,
# thunderbird or return to the default mode, respectively.
set $mode_launcher Launch: [f]irefox [t]hunderbird
bindsym $mod+o mode "$mode_launcher"
bindsym f exec firefox
bindsym t exec thunderbird
- bindsym Esc mode "default"
+ bindsym Escape mode "default"
bindsym Return mode "default"
}
------------------------------------------------------------------------
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*:
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 <<xresources>> to learn how to create variables based on resources
+loaded from the X resource database.
+
+[[xresources]]
+=== X resources
+
+<<variables>> 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 $<name> <resource_name> <fallback>
+----------------------------------------------------
+
+*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
=== Focus follows mouse
-By default, window focus follows your mouse movements. However, if you have a
-setup where your mouse usually is in your way (like a touchpad on your laptop
-which you do not want to disable completely), you might want to disable 'focus
-follows mouse' and control focus only by using your keyboard. The mouse will
-still be useful inside the currently active window (for example to click on
-links in your browser window).
+By default, window focus follows your mouse movements as the mouse crosses
+window borders. However, if you have a setup where your mouse usually is in your
+way (like a touchpad on your laptop which you do not want to disable
+completely), you might want to disable 'focus follows mouse' and control focus
+only by using your keyboard. The mouse will still be useful inside the
+currently active window (for example to click on links in your browser window).
*Syntax*:
--------------------------
[[show_marks]]
=== Drawing marks on window decoration
-If activated, marks on windows are drawn in their window decoration. However,
-any mark starting with an underscore in its name (+_+) will not be drawn even if
-this option is activated.
+If activated, marks (see <<vim_like_marks>>) on windows are drawn in their window
+decoration. However, any mark starting with an underscore in its name (+_+) will
+not be drawn even if this option is activated.
The default for this option is +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
*Syntax*:
---------------
-output <output>
+output primary|<output>
---------------
*Example*:
statusline #ffffff
}
}
+
+# show bar on the primary monitor and on HDMI2
+bar {
+ output primary
+ output HDMI2
+ status_command i3status
+}
+
-------------------------------
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
=== Tray output
You can configure on which output (monitor) the icons should be displayed or
you can turn off the functionality entirely.
-You can use mutliple +tray_output+ directives in your config to specify a list
+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.
# enable floating mode and move container to workspace 4
for_window [class="^evil-app$"] floating enable, move container to workspace 4
+
+# move all floating windows to the scratchpad
+bindsym $mod+x [floating] move scratchpad
------------------------------------
The criteria which are currently implemented are:
Compares the i3-internal container ID, which you can get via the IPC
interface. Handy for scripting. Use the special value +\_\_focused__+
to match only the currently focused window.
+floating::
+ Only matches floating windows. This criterion requires no value.
+tiling::
+ Only matches tiling windows. This criterion requires no value.
The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are
actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for
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.
+splitv to splith or vice-versa. You can also define a custom sequence of layouts
+to cycle through with +layout toggle+, see <<manipulating_layout>>.
*Syntax*:
--------------------------------
or +layout splith+ to change the current container layout to splith/splitv,
stacking, tabbed layout, splitv or splith, respectively.
+Specify up to four layouts after +layout toggle+ to cycle through them. Every
+time the command is executed, the layout specified after the currently active
+one will be applied. If the currently active layout is not in the list, the
+first layout in the list will be activated.
+
To make the current window (!) fullscreen, use +fullscreen enable+ (or
+fullscreen enable global+ for the global mode), to leave either fullscreen
mode use +fullscreen disable+, and to toggle between these two states use
--------------------------------------------
layout default|tabbed|stacking|splitv|splith
layout toggle [split|all]
+layout toggle [split|tabbed|stacking|splitv|splith] [split|tabbed|stacking|splitv|splith]…
--------------------------------------------
*Examples*:
# Toggle between stacking/tabbed/splith/splitv:
bindsym $mod+x layout toggle all
+# Toggle between stacking/tabbed/splith:
+bindsym $mod+x layout toggle stacking tabbed splith
+
+# Toggle between splitv/tabbed
+bindsym $mod+x layout toggle splitv tabbed
+
+# Toggle between last split layout/tabbed/stacking
+bindsym $mod+x layout toggle split tabbed stacking
+
# Toggle fullscreen
bindsym $mod+f fullscreen toggle
----------------------------------------------
focus left|right|down|up
focus parent|child|floating|tiling|mode_toggle
-focus output left|right|up|down|<output>
+focus output left|right|up|down|primary|<output>
----------------------------------------------
*Examples*:
# Focus the big output
bindsym $mod+x focus output HDMI-2
+
+# Focus the primary output
+bindsym $mod+x focus output primary
-------------------------------------------------
+-------------------------------
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
+
=== Moving containers
Use the +move+ command to move a container.
# Moves the container either to a specific location
# or to the center of the screen. If 'absolute' is
# used, it is moved to the center of all outputs.
-move [absolute] position [[<px> px] [<px> px]|center]
+move [absolute] position <pos_x> [px] <pos_y> [px]
+move [absolute] position center
# Moves the container to the current position of the
# mouse cursor. Only affects floating containers.
bindsym $mod+m move position mouse
-------------------------------------------------------
+=== Swapping containers
+
+Two containers can be swapped (i.e., move to each other's position) by using
+the +swap+ command. They will assume the position and geometry of the container
+they are swapped with.
+
+The first container to participate in the swapping can be selected through the
+normal command criteria process with the focused window being the usual
+fallback if no criteria are specified. The second container can be selected
+using one of the following methods:
+
++id+:: The X11 window ID of a client window.
++con_id+:: The i3 container ID of a container.
++mark+:: A container with the specified mark, see <<vim_like_marks>>.
+
+Note that swapping does not work with all containers. Most notably, swapping
+floating containers or containers that have a parent-child relationship to one
+another does not work.
+
+*Syntax*:
+----------------------------------------
+swap container with id|con_id|mark <arg>
+----------------------------------------
+
+*Examples*:
+-----------------------------------------------------------------
+# Swaps the focused container with the container marked »swapee«.
+swap container with mark swapee
+
+# Swaps container marked »A« and »B«
+[con_mark="^A$"] swap container with mark B
+-----------------------------------------------------------------
+
=== Sticky floating windows
If you want a window to stick to the glass, i.e., have it stay on screen even
bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: '
--------------------------------------------------------------------------
+If you want to rename workspaces on demand while keeping the navigation stable,
+you can use a setup like this:
+
+*Example*:
+-------------------------
+bindsym $mod+1 workspace number "1: www"
+bindsym $mod+2 workspace number "2: mail"
+...
+-------------------------
+
+If a workspace does not exist, the command +workspace number "1: mail"+ will
+create workspace "1: mail".
+
+If a workspace with number 1 does already exist, the command will switch to this
+workspace and ignore the text part. So even when the workspace has been renamed
+to "1: web", the above command will still switch to it.
+
=== Moving workspaces to a different screen
See <<move_to_outputs>> for how to move a container/workspace to a different
RandR output.
[[move_to_outputs]]
+[[_moving_containers_workspaces_to_randr_outputs]]
=== Moving containers/workspaces to RandR outputs
To move a container to another RandR output (addressed by names like +LVDS1+ or
+right+, +up+ or +down+), there are two commands:
*Syntax*:
-----------------------------------------------------
-move container to output left|right|down|up|<output>
-move workspace to output left|right|down|up|<output>
-----------------------------------------------------
+------------------------------------------------------------
+move container to output left|right|down|up|current|primary|<output>
+move workspace to output left|right|down|up|current|primary|<output>
+------------------------------------------------------------
*Examples*:
--------------------------------------------------------
# Put this window on the presentation output.
bindsym $mod+x move container to output VGA1
+
+# Put this window on the primary output.
+bindsym $mod+x move container to output primary
--------------------------------------------------------
+-------------------------------
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
+
=== Moving containers/windows to marks
To move a container to another container with a specific mark (see <<vim_like_marks>>),
It is recommended to define bindings for resizing in a dedicated binding mode.
See <<binding_modes>> and the example in the i3
-https://github.com/i3/i3/blob/next/i3.config.keycodes[default config] for more
+https://github.com/i3/i3/blob/next/etc/config.keycodes[default config] for more
context.
*Example*:
---------------------------------------
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]]
track of which window you put where. Thus, you can use vim-like marks to
quickly switch between windows. See <<vim_like_marks>>.
4. For information on how to move existing workspaces between monitors,
- see <<_moving_containers_workspaces_to_randr_outputs>>.
+ see <<move_to_outputs>>.
== i3 and the rest of your software world
projects / i3 / i3.github.io / blobdiff