From: Michael Stapelberg Date: Sun, 28 Aug 2011 13:04:23 +0000 (+0200) Subject: make the 4.0 docs the default X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=d065d5315144e44aab9288d458a57cf0a2ca8de5;p=i3%2Fi3.github.io make the 4.0 docs the default --- diff --git a/docs/3.e/i3status.html b/docs/3.e/i3status.html deleted file mode 100644 index 0860168..0000000 --- a/docs/3.e/i3status.html +++ /dev/null @@ -1,372 +0,0 @@ - - - - - - -i3: i3status(1) - - - - - - - -

i3 - improved tiling WM

-
-

- -

1. NAME

i3status - Generates a status line for dzen2 or xmobar

2. SYNOPSIS

i3status [-c configfile] [-h] [-v]

3. OPTIONS

--c -

-Specifies an alternate configuration file path. By default, i3status looks for -configuration files in the following order: -

-
-~/.i3status.conf -
-
-
-~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set) -
-
-
-/etc/i3status.conf -
-
-
-/etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set) -
-

4. DESCRIPTION

i3status is a small program (about 1500 SLOC) for generating a status bar for -i3bar, dzen2, xmobar or similar programs. It is designed to be very -efficient by issuing a very small number of system calls, as one generally -wants to update such a status line every second. This ensures that even under -high load, your status bar is updated correctly. Also, it saves a bit of energy -by not hogging your CPU as much as spawning the corresponding amount of shell -commands would.

5. CONFIGURATION

Since version 2, the configuration file for i3status will be parsed using -libconfuse. This makes configuration easier in the programmerâs point of -view and more flexible for the user at the same time.

The basic idea of i3status is that you can specify which "modules" should -be used (the order directive). You can then configure each module with its -own section. For every module, you can specify the output format. See below -for a complete reference.

Sample configuration

general {
-        output_format = "dzen2"
-        colors = true
-        interval = 5
-}
-
-order  = "ipv6"
-order += "disk /"
-order += "run_watch DHCP"
-order += "run_watch VPN"
-order += "wireless wlan0"
-order += "ethernet eth0"
-order += "battery 0"
-order += "cpu_temperature 0"
-order += "load"
-order += "time"
-
-wireless wlan0 {
-        format_up = "W: (%quality at %essid, %bitrate) %ip"
-        format_down = "W: down"
-}
-
-ethernet eth0 {
-        # if you use %speed, i3status requires the cap_net_admin capability
-        format_up = "E: %ip (%speed)"
-        format_down = "E: down"
-}
-
-battery 0 {
-        format = "%status %percentage %remaining"
-}
-
-run_watch DHCP {
-        pidfile = "/var/run/dhclient*.pid"
-}
-
-run_watch VPN {
-        pidfile = "/var/run/vpnc/pid"
-}
-
-time {
-        format = "%Y-%m-%d %H:%M:%S"
-}
-
-load {
-        format = "%5min"
-}
-
-cpu_temperature 0 {
-        format = "T: %degrees Â°C"
-        path = "/sys/devices/platform/coretemp.0/temp1_input"
-}
-
-disk "/" {
-        format = "%free"
-}

5.1. General

The colors directive will disable all colors if you set it to false. You can -also specify the colors that will be used to display "good", "degraded" or "bad" -values using the color_good, color_degraded or color_bad directives, -respectively. Those directives are only used if color support is not disabled by -the colors directive. The input format for color values is the canonical RGB -hexadecimal triplet (with no separators between the colors), prefixed by a hash -character ("#").

Example configuration:

color_good = "#00FF00"

Likewise, you can use the color_separator directive to specify the color that -will be used to paint the separator bar. The separator is always output in -color, even when colors are disabled by the colors directive.

The interval directive specifies the time in seconds for which i3status will -sleep before printing the next status line.

Using output_format you can chose which format strings i3status should -use in its output. Currently available are:

-dzen2 -: -
-Dzen is a general purpose messaging, notification and menuing program for X11. -It was designed to be scriptable in any language and integrate well with window -managers like dwm, wmii and xmonad though it will work with any windowmanger -
-
-xmobar -: -
-xmobar is a minimalistic, text based, status bar. It was designed to work -with the xmonad Window Manager. -
-
-none -: -
-Does not use any color codes. Separates values by the pipe symbol. This should -be used with i3bar and can be used for custom scripts. -
-

5.2. IPv6

This module gets the IPv6 address used for outgoing connections (that is, the -best available public IPv6 address on your computer).

Example format_up: %ip

Example format_down no IPv6

5.3. Disk

Gets used, free, available and total amount of bytes on the given mounted filesystem.

Example order: disk /mnt/usbstick

Example format: %free (%avail)/ %total

5.4. Run-watch

Expands the given path to a pidfile and checks if the process ID found inside -is valid (that is, if the process is running). You can use this to check if -a specific application, such as a VPN client or your DHCP client is running.

Example order: run_watch DHCP

5.5. Wireless

Gets the link quality and ESSID of the given wireless network interface. You -can specify different format strings for the network being connected or not -connected.

Example order: wireless wlan0

Example format: W: (%quality at %essid, %bitrate) %ip

5.6. Ethernet

Gets the IP address and (if possible) the link speed of the given ethernet -interface. Getting the link speed requires the cap_net_admin capability. Set -it using setcap cap_net_admin=ep $(which i3status).

Example order: ethernet eth0

Example format: E: %ip (%speed)

5.7. Battery

Gets the status (charging, discharging, running), percentage and remaining -time of the given battery. If you want to use the last full capacity instead -of the design capacity (when using the design capacity, it may happen that -your battery is at 23% when fully charged because itâs old. In general, I -want to see it this way, because it tells me how worn off my battery is.), -just specify last_full_capacity = true.

Example order: battery 0

Example format: %status %remaining

5.8. CPU-Temperature

Gets the temperature of the given thermal zone.

Example order: cpu_temperature 0

Example format: T: %degrees Â°C

5.9. CPU Usage

Gets the percentual CPU usage from /proc/stat.

Example order: cpu_usage

Example format: %usage

5.10. Load

Gets the system load (number of processes waiting for CPU time in the last -5, 10 and 15 minutes).

Example order: load

Example format: %5min %10min %15min

5.11. Time

Formats the current system time. See strftime(3) for the format.

Example order: time

Example format: %Y-%m-%d %H:%M:%S

5.12. DDate

Outputs the current discordian date in user-specified format. See ddate(1) for -details on the format string. -Note: Neither %. nor %X are implemented yet.

Example order: ddate

Example format: %{%a, %b %d%}, %Y%N - %H

5.13. Volume

Outputs the volume of the specified mixer on the specified device. Works only -on Linux because it uses ALSA.

Example order: volume master

Example format: âª: %volume

Example configuration:

volume master {
-        format = "âª: %volume"
-        device = "default"
-        mixer = "Master"
-        mixer_idx = 0
-}

6. Using i3status with dzen2

After installing dzen2, you can directly use it with i3status. Just ensure that -output_format is set to dzen2.

Example for usage of i3status with dzen2:

i3status | dzen2 -fg white -ta r -w 1280 \
--fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"

7. Using i3status with xmobar

To get xmobar to start, you might need to copy the default configuration -file to ~/.xmobarrc. Also, ensure that the output_format option for i3status -is set to xmobar.

Example for usage of i3status with xmobar:

i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"

8. SEE ALSO

strftime(3), date(1), glob(3), dzen2(1), xmobar(1)

9. AUTHORS

Michael Stapelberg and contributors

Thorsten Toepper

Baptiste Daroussin

Axel Wagner

Fernando TarlÃ¡ Cardoso Lemos

- - - diff --git a/docs/3.e/index.html.mako b/docs/3.e/index.html.mako new file mode 100644 index 0000000..59be338 --- /dev/null +++ b/docs/3.e/index.html.mako @@ -0,0 +1,75 @@ +<%! + section = "docs" +%> +<%inherit file="_templates/i3.mako" /> +

Documentation

+ +

+One of i3âs goals is good documentation. The documents which you will find +below will hopefully answer all your questions. If you have any corrections or +suggestions please let us know! +

+ +

+These documents are for i3 version 3.Îµ. Version 4 was released and we strongly recommend you to upgrade! +

+ +

For users

+ +

+Userâs Guide
+Introduction and reference. Read this one. +

+ +

+Multi-monitor
+Interesting for users of the nVidia driver. +

+ +

+Debugging i3
+Explains you how to enable the i3 logfile. +

+ +

+External workspace bars
+About bar programs such as i3bar or dzen2. +

+ +

+i3 reference card (PDF)
+Might be useful to memorize i3âs shortcuts. +

+ +

For developers

+ +

+Downloads â Development version
+Tells you how to check out our git repository. +

+ +

+Hacking Howto
+Helps you if you want to get into i3âs source code. +

+ +

+Debugging i3
+Explains you how to enable core dumps. +

+ +

+IPC documentation
+Explains how i3âs Inter Process Communication interface works. Read this if you +want to talk to i3 within your own scripts or programs. +

+ +

+ +
+ +

diff --git a/docs/4.0/i3status.html b/docs/4.0/i3status.html deleted file mode 100644 index 0860168..0000000 --- a/docs/4.0/i3status.html +++ /dev/null @@ -1,372 +0,0 @@ - - - - - - -i3: i3status(1) - - - - - - - -

i3 - improved tiling WM

-
-

- -

1. NAME

i3status - Generates a status line for dzen2 or xmobar

2. SYNOPSIS

i3status [-c configfile] [-h] [-v]

3. OPTIONS

--c -

-Specifies an alternate configuration file path. By default, i3status looks for -configuration files in the following order: -

-
-~/.i3status.conf -
-
-
-~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set) -
-
-
-/etc/i3status.conf -
-
-
-/etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set) -
-

4. DESCRIPTION

5. CONFIGURATION

Sample configuration

general {
-        output_format = "dzen2"
-        colors = true
-        interval = 5
-}
-
-order  = "ipv6"
-order += "disk /"
-order += "run_watch DHCP"
-order += "run_watch VPN"
-order += "wireless wlan0"
-order += "ethernet eth0"
-order += "battery 0"
-order += "cpu_temperature 0"
-order += "load"
-order += "time"
-
-wireless wlan0 {
-        format_up = "W: (%quality at %essid, %bitrate) %ip"
-        format_down = "W: down"
-}
-
-ethernet eth0 {
-        # if you use %speed, i3status requires the cap_net_admin capability
-        format_up = "E: %ip (%speed)"
-        format_down = "E: down"
-}
-
-battery 0 {
-        format = "%status %percentage %remaining"
-}
-
-run_watch DHCP {
-        pidfile = "/var/run/dhclient*.pid"
-}
-
-run_watch VPN {
-        pidfile = "/var/run/vpnc/pid"
-}
-
-time {
-        format = "%Y-%m-%d %H:%M:%S"
-}
-
-load {
-        format = "%5min"
-}
-
-cpu_temperature 0 {
-        format = "T: %degrees Â°C"
-        path = "/sys/devices/platform/coretemp.0/temp1_input"
-}
-
-disk "/" {
-        format = "%free"
-}

5.1. General

Example configuration:

color_good = "#00FF00"

The interval directive specifies the time in seconds for which i3status will -sleep before printing the next status line.

Using output_format you can chose which format strings i3status should -use in its output. Currently available are:

-dzen2 -: -
-Dzen is a general purpose messaging, notification and menuing program for X11. -It was designed to be scriptable in any language and integrate well with window -managers like dwm, wmii and xmonad though it will work with any windowmanger -
-
-xmobar -: -
-xmobar is a minimalistic, text based, status bar. It was designed to work -with the xmonad Window Manager. -
-
-none -: -
-Does not use any color codes. Separates values by the pipe symbol. This should -be used with i3bar and can be used for custom scripts. -
-

5.2. IPv6

This module gets the IPv6 address used for outgoing connections (that is, the -best available public IPv6 address on your computer).

Example format_up: %ip

Example format_down no IPv6

5.3. Disk

Gets used, free, available and total amount of bytes on the given mounted filesystem.

Example order: disk /mnt/usbstick

Example format: %free (%avail)/ %total

5.4. Run-watch

Example order: run_watch DHCP

5.5. Wireless

Gets the link quality and ESSID of the given wireless network interface. You -can specify different format strings for the network being connected or not -connected.

Example order: wireless wlan0

Example format: W: (%quality at %essid, %bitrate) %ip

5.6. Ethernet

Example order: ethernet eth0

Example format: E: %ip (%speed)

5.7. Battery

Example order: battery 0

Example format: %status %remaining

5.8. CPU-Temperature

Gets the temperature of the given thermal zone.

Example order: cpu_temperature 0

Example format: T: %degrees Â°C

5.9. CPU Usage

Gets the percentual CPU usage from /proc/stat.

Example order: cpu_usage

Example format: %usage

5.10. Load

Gets the system load (number of processes waiting for CPU time in the last -5, 10 and 15 minutes).

Example order: load

Example format: %5min %10min %15min

5.11. Time

Formats the current system time. See strftime(3) for the format.

Example order: time

Example format: %Y-%m-%d %H:%M:%S

5.12. DDate

Outputs the current discordian date in user-specified format. See ddate(1) for -details on the format string. -Note: Neither %. nor %X are implemented yet.

Example order: ddate

Example format: %{%a, %b %d%}, %Y%N - %H

5.13. Volume

Outputs the volume of the specified mixer on the specified device. Works only -on Linux because it uses ALSA.

Example order: volume master

Example format: âª: %volume

Example configuration:

volume master {
-        format = "âª: %volume"
-        device = "default"
-        mixer = "Master"
-        mixer_idx = 0
-}

6. Using i3status with dzen2

After installing dzen2, you can directly use it with i3status. Just ensure that -output_format is set to dzen2.

Example for usage of i3status with dzen2:

i3status | dzen2 -fg white -ta r -w 1280 \
--fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"

7. Using i3status with xmobar

To get xmobar to start, you might need to copy the default configuration -file to ~/.xmobarrc. Also, ensure that the output_format option for i3status -is set to xmobar.

Example for usage of i3status with xmobar:

i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"

8. SEE ALSO

strftime(3), date(1), glob(3), dzen2(1), xmobar(1)

9. AUTHORS

Michael Stapelberg and contributors

Thorsten Toepper

Baptiste Daroussin

Axel Wagner

Fernando TarlÃ¡ Cardoso Lemos

- - - diff --git a/docs/debugging.html b/docs/debugging.html index 9ff561e..4101fc0 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -31,7 +31,7 @@ window.onload = function(){asciidoc.footnotes();}

Debugging i3: How To

Michael Stapelberg
<michael+i3@stapelberg.de>
-March 2010 +July 2011

@@ -45,14 +45,20 @@ debugging and/or need further help, do not hesitate to contact us!

1. Enabling logging

i3 spits out much information onto stdout, if told so. To have a clearly -defined place where log files will be saved, you should redirect stdout and -stderr in xsession. While youâre at it, putting each run of i3 in a separate -log file with date/time in it is a good idea to not get confused about the -different log files later on.

i3 logs useful information to stdout. To have a clearly defined place where log +files will be saved, you should redirect stdout and stderr in your +~/.xsession. While youâre at it, putting each run of i3 in a separate log +file with date/time in its filename is a good idea to not get confused about +the different log files later on.

exec /usr/bin/i3 -V -d all >/home/michael/i3/i3log-$(date +'%F-%k-%M-%S') 2>&1

exec /usr/bin/i3 >~/i3log-$(date +'%F-%k-%M-%S') 2>&1

To enable verbose output and all levels of debug output (required when +attaching logfiles to bugreports), add the parameters -V -d all, like this:

exec /usr/bin/i3 -V -d all >~/i3log-$(date +'%F-%k-%M-%S') 2>&1

@@ -64,7 +70,7 @@ of the memory of the i3 process which can be loaded into a debugger). To get a core dump, you have to make sure that the user limit for core dump files is set high enough. Many systems ship with a default value which even forbids core dumps completely. To disable the limit completely and thus enable core dumps, -use the following command (in your .xsession, before starting i3):

+use the following command (in your ~/.xsession, before starting i3):

ulimit -c unlimited

@@ -85,9 +91,9 @@ process id (%p) in it. You can save this setting across reboots using

3. Compiling with debug symbols

To actually get useful core dumps, you should make sure that your version of i3 -is compiled with debug symbols, that is, that they are not stripped during the -build process. You can check whether your executable contains symbols by -issuing the following command:

+is compiled with debug symbols, that is, that the symbols are not stripped +during the build process. You can check whether your executable contains +symbols by issuing the following command:

file $(which i3)

diff --git a/docs/hacking-howto.html b/docs/hacking-howto.html index 90029de..382b5c3 100644 --- a/docs/hacking-howto.html +++ b/docs/hacking-howto.html @@ -31,7 +31,7 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}

Hacking i3: How To

Michael Stapelberg
<michael+i3@stapelberg.de>
-December 2009 +July 2011

Table of Contents

@@ -142,89 +142,12 @@ the layout you need at the moment.

1.2. The layout table

To accomplish flexible layouts, we decided to simply use a table. The table -grows and shrinks as you need it. Each cell holds a container which then holds -windows (see picture below). You can use different layouts for each container -(default layout and stacking layout).

So, when you open a terminal and immediately open another one, they reside in -the same container, in default layout. The layout table has exactly one column, -one row and therefore one cell. When you move one of the terminals to the -right, the table needs to grow. It will be expanded to two columns and one row. -This enables you to have different layouts for each container. The table then -looks like this:

- --- - - - - - -

When moving terminal 2 to the bottom, the table will be expanded again.

- --- - - - - - - - - - -

T1
	T2

You can really think of the layout table like a traditional HTML table, if -youâve ever designed one. Especially col- and rowspan work similarly. Below, -you see an example of colspan=2 for the first container (which has T1 as -window).

- -- - - - - - - - -

T1

- --- - - - - - -

Furthermore, you can freely resize table cells.

This section has not been updated for v4.0 yet, sorry! We wanted to release on +time, but we will update this soon. Please talk to us on IRC if you need to +know stuff NOW :).

@@ -233,6 +156,16 @@ cellspacing="0" cellpadding="4">

+include/atoms.xmacro +: +
+A file containing all X11 atoms which i3 uses. This file will be included +various times (for defining, requesting and receiving the atoms), each time +with a different definition of xmacro(). +
+
include/data.h: @@ -277,20 +210,29 @@ clicks initiate resizing and thus are relatively complex).
-src/client.c +src/cmdparse.l: -Contains all functions which are specific to a certain client (make it -fullscreen, see if its class/name matches a pattern, kill it, â¦). +Contains the lexer for i3 commands, written for flex(1).
-src/commands.c +src/cmdparse.y: -Parsing commands and actually executing them (focusing, moving, â¦). +Contains the parser for i3 commands, written for bison(1). +
+
+src/con.c +: +
+Contains all functions which deal with containers directly (creating +containers, searching containers, getting specific properties from containers, +â¦).
@@ -298,7 +240,8 @@ src/config.c: -Parses the configuration file. +Contains all functions handling the configuration file (calling the parser +(src/cfgparse.y) with the correct path, switching key bindings mode).
@@ -310,6 +253,14 @@ Contains debugging functions to print unhandled X events.
+src/ewmh.c +: +
+iFunctions to get/set certain EWMH properties easily. +
+
src/floating.c: @@ -335,15 +286,23 @@ Contains code for the IPC interface.
-src/layout.c +src/load_layout.c: -Renders your layout (screens, workspaces, containers). +Contains code for loading layouts from JSON files.
-src/mainx.c +src/log.c +: +
+Handles the setting of loglevels, contains the logging functions. +
+
+src/main.c: @@ -360,19 +319,77 @@ reparents the window and inserts it into our data structures.
+src/match.c +: +
+A "match" is a data structure which acts like a mask or expression to match +certain windows or not. For example, when using commands, you can specify a +command like this: [title="Firefox"] kill. The title member of the match +data structure will then be filled and i3 will check each window using +match_matches_window() to find the windows affected by this command. +
+
+src/move.c +: +
+Contains code to move a container in a specific direction. +
+
+src/output.c +: +
+Functions to handle CT_OUTPUT cons. +
+
+src/randr.c +: +
+The RandR API is used to get (and re-query) the configured outputs (monitors, +â¦). +
+
+src/render.c +: +
+Renders the tree data structure by assigning coordinates to every node. These +values will later be pushed to X11 in src/x.c. +
+
src/resize.c: -Contains the functions to resize columns/rows in the table. +Contains the functions to resize containers. +
+
+src/sighandler.c +: +
+Handles SIGSEGV, SIGABRT and SIGFPE by showing a dialog that i3 crashed. +You can chose to let it dump core, to restart it in-place or to restart it +in-place but forget about the layout.
-src/table.c +src/tree.c: -Manages the most important internal data structure, the design table. +Contains functions which open or close containers in the tree, change focus or +cleanup ("flatten") the tree. See also src/move.c for another similar +function, which was moved into its own file because it is so long.
@@ -384,6 +401,15 @@ Contains useful functions which are not really dependant on anything.
+src/window.c +: +
+Handlers to update X11 window properties like WM_CLASS, _NET_WM_NAME, +CLIENT_LEADER, etc. +
+
src/workspace.c: @@ -392,6 +418,14 @@ Contains all functions related to workspaces (displaying, hiding, renamingâ¦)
+src/x.c +: +
+Transfers our in-memory tree (see src/render.c) to X11. +
+
src/xcb.c: @@ -400,12 +434,19 @@ Contains wrappers to use xcb more easily.
+src/xcursor.c +: +
+XCursor functions (for cursor themes). +
+
src/xinerama.c: -(Re-)initializes the available screens and converts them to virtual screens -(see below). +Legacy support for Xinerama. See src/randr.c for the preferred API.

@@ -414,56 +455,64 @@ src/xinerama.c

3. Data structures

See include/data.h for documented data structures. The most important ones are -explained right here.

- The Big Picture -

This section has not been updated for v4.0 yet, sorry! We wanted to release on +time, but we will update this soon. Please talk to us on IRC if you need to +know stuff NOW :).

So, the hierarchy is:

+X11 root window, the root container +
+
+
Virtual screens (Screen 0 in this example)
-Workspaces (Workspace 1 in this example) +Content container (there are also containers for dock windows)
-Table (There can only be one table per Workspace) +Workspaces (Workspace 1 in this example, with horizontal orientation)
-Container (left and right in this example) +Split container (vertically split)
-Client (The two clients in the left container) +X11 window containers

The data type is Con, in all cases.

3.1. Virtual screens

A virtual screen (type i3Screen) is generated from the connected screens -obtained through Xinerama. The difference to the raw Xinerama monitors as seen +

A virtual screen (type i3Screen) is generated from the connected outputs +obtained through RandR. The difference to the raw RandR outputs as seen when using xrandr(1) is that it falls back to the lowest common resolution of -the logical screens.

For example, if your notebook has 1280x800 and you connect a video projector -with 1024x768, set up in clone mode (xrandr --output VGA --mode 1024x768 ---same-as LVDS), i3 will have one virtual screen.

However, if you configure it using xrandr --output VGA --mode 1024x768 ---right-of LVDS, i3 will generate two virtual screens. For each virtual +the actual enabled outputs.

For example, if your notebook has a screen resolution of 1280x800 px and you +connect a video projector with a resolution of 1024x768 px, set it up in clone +mode (xrandr --output VGA1 --mode 1024x768 --same-as LVDS1), i3 will have +one virtual screen.

However, if you configure it using xrandr --output VGA1 --mode 1024x768 +--right-of LVDS1, i3 will generate two virtual screens. For each virtual screen, a new workspace will be assigned. New workspaces are created on the screen you are currently on.

3.2. Workspace

A workspace is identified by its number. Basically, you could think of +

A workspace is identified by its name. Basically, you could think of workspaces as different desks in your office, if you like the desktop methaphor. They just contain different sets of windows and are completely separate of each other. Other window managers also call this “Virtual @@ -471,17 +520,21 @@ desktops”.

3.3. The layout table

Each workspace has a table, which is just a two-dimensional dynamic array -containing Containers (see below). This table grows and shrinks as you need it -(by moving windows to the right you can create a new column in the table, by -moving them to the bottom you create a new row).

This section has not been updated for v4.0 yet, sorry! We wanted to release on +time, but we will update this soon. Please talk to us on IRC if you need to +know stuff NOW :).

3.4. Container

A container is the content of a tableâs cell. It holds an arbitrary amount of -windows and has a specific layout (default layout, stack layout or tabbed -layout). Containers can consume multiple table cells by modifying their -colspan/rowspan attribute.

This section has not been updated for v4.0 yet, sorry! We wanted to release on +time, but we will update this soon. Please talk to us on IRC if you need to +know stuff NOW :).

3.5. Client

@@ -497,7 +550,7 @@ ensure that the operating system on which i3 is compiled has all the expected features, i3 comes with include/queue.h. On BSD systems, you can use man queue(3). On Linux, you have to use google (or read the source).

The lists used are SLIST (single linked lists), CIRCLEQ (circular -queues) and TAILQ (tail queues). Usually, only forward traversal is necessary, +queues) and TAILQ (tail queues). Usually, only forward traversal is necessary, so an SLIST works fine. If inserting elements at arbitrary positions or at the end of a list is necessary, a TAILQ is used instead. However, for the windows inside a container, a CIRCLEQ is necessary to go from the currently @@ -522,12 +575,12 @@ should be chosen for those:

-“container” names a container +“con” names a container

-“client” names a client, for example when using a CIRCLEQ_FOREACH +“current” is a loop variable when using TAILQ_FOREACH etc.

@@ -544,12 +597,12 @@ Establish the xcb connection

-Check for XKB extension on the separate X connection +Check for XKB extension on the separate X connection, load Xcursor

-Check for Xinerama screens +Check for RandR screens (with a fall-back to Xinerama)

@@ -600,12 +653,13 @@ will handle the event, if not, it will replay the event.

the correct state.

Then, it looks through all bindings and gets the one which matches the received event.

The bound command is parsed directly in command mode.

The bound command is parsed by the cmdparse lexer/parser, see parse_cmd in +src/cmdparse.y.

8. Manage windows (src/mainx.c, manage_window() and reparent_window())

8. Manage windows (src/main.c, manage_window() and reparent_window())

manage_window() does some checks to decide whether the window should be managed at all:

@@ -631,7 +685,7 @@ reparented to the bigger one (called "frame").

whether this window is a dock (_NET_WM_WINDOW_TYPE_DOCK), like dzen2 for example. Docks are handled differently, they donât have decorations and are not assigned to a specific container. Instead, they are positioned at the bottom -of the screen. To get the height which needsd to be reserved for the window, +of the screen. To get the height which needs to be reserved for the window, the _NET_WM_STRUT_PARTIAL property is used.

Furthermore, the list of assignments (to other workspaces, which may be on other screens) is checked. If the window matches one of the userâs criteria, @@ -645,7 +699,7 @@ target workspace is not visible, the window will not be mapped.

i3 does not care for applications. All it notices is when new windows are mapped (see src/handlers.c, handle_map_request()). The window is then reparented (see section "Manage windows").

After reparenting the window, render_layout() is called which renders the +

After reparenting the window, render_tree() is called which renders the internal layout table. The new window has been placed in the currently focused container and therefore the new window and the old windows (if any) need to be moved/resized so that the currently active layout (default/stacking/tabbed mode) @@ -702,144 +756,246 @@ src/layout.c, function resize_client().

14. Rendering (src/layout.c, render_layout() and render_container())

There are several entry points to rendering: render_layout(), -render_workspace() and render_container(). The former one calls -render_workspace() for every screen, which in turn will call -render_container() for every container inside its layout table. Therefore, if -you need to render only a single container, for example because a window was -removed, added or changed its title, you should directly call -render_container().

Rendering consists of two steps: In the first one, in render_workspace(), each -container gets its position (screen offset + offset in the table) and size -(container’s width times colspan/rowspan). Then, render_container() is called, -which takes different approaches, depending on the mode the container is in:

14.1. Common parts

On the frame (the window which was created around the clientâs window for the -decorations), a black rectangle is drawn as a background for windows like -MPlayer, which do not completely fit into the frame.

This section has not been updated for v4.0 yet, sorry! We wanted to release on +time, but we will update this soon. Please talk to us on IRC if you need to +know stuff NOW :).

15. User commands / commandmode (src/cmdparse.{l,y})

This section has not been updated for v4.0 yet, sorry! We wanted to release on +time, but we will update this soon. Please talk to us on IRC if you need to +know stuff NOW :).

16. Moving containers

The movement code is pretty delicate. You need to consider all cases before +making any changes or before being able to fully understand how it works.

14.2. Default mode

Each clients gets the containerâs width and an equal amount of height.

16.1. Case 1: Moving inside the same container

The reference layout for this case is a single workspace in horizontal +orientation with two containers on it. Focus is on the left container (1).

+ +++ + + + + + +

When moving the left window to the right (command move right), tree_move will +look for a container with horizontal orientation and finds the parent of the +left container, that is, the workspace. Afterwards, it runs the code branch +commented with "the easy case": it calls TAILQ_NEXT to get the container right +of the current one and swaps both containers.

14.3. Stack mode

In stack mode, a window containing the decorations of all windows inside the -container is placed at the top. The currently focused window is then given the -whole remaining space.

16.2. Case 2: Move a container into a split container

The reference layout for this case is a horizontal workspace with two +containers. The right container is a v-split with two containers. Focus is on +the left container (1).

+ +++ + + + + + + + + +

1	2
	3

When moving to the right (command move right), i3 will work like in case 1 +("the easy case"). However, as the right container is not a leaf container, but +a v-split, the left container (1) will be inserted at the right position (below +2, assuming that 2 is focused inside the v-split) by calling insert_con_into.

insert_con_into detaches the container from its parent and inserts it +before/after the given target container. Afterwards, the on_remove_child +callback is called on the old parent container which will then be closed, if +empty.

Afterwards, con_focus will be called to fix the focus stack and the tree will +be flattened.

14.4. Tabbed mode

Tabbed mode is like stack mode, except that the window decorations are drawn -in one single line at the top of the container.

16.3. Case 3: Moving to non-existant top/bottom

Like in case 1, the reference layout for this case is a single workspace in +horizontal orientation with two containers on it. Focus is on the left +container:

+ +++ + + + + + +

This time however, the command is move up or move down. tree_move will look +for a container with vertical orientation. As it will not find any, +same_orientation is NULL and therefore i3 will perform a forced orientation +change on the workspace by creating a new h-split container, moving the +workspace contents into it and then changing the workspace orientation to +vertical. Now it will again search for parent containers with vertical +orientation and it will find the workspace.

This time, the easy case code path will not be run as we are not moving inside +the same container. Instead, insert_con_into will be called with the focused +container and the container above/below the current one (on the level of +same_orientation).

Now, con_focus will be called to fix the focus stack and the tree will be +flattened.

14.5. Window decorations

The window decorations consist of a rectangle in the appropriate color (depends -on whether this window is the currently focused one, the last focused one in a -not focused container or not focused at all) forming the background. -Afterwards, two lighter lines are drawn and the last step is drawing the -windowâs title (see WM_NAME) onto it.

16.4. Case 4: Moving to existant top/bottom

The reference layout for this case is a vertical workspace with two containers. +The bottom one is a h-split containing two containers (1 and 2). Focus is on +the bottom left container (1).

+ +++ + + + + + + + + +

3
1	2

This case is very much like case 3, only this time the forced workspace +orientation change does not need to be performed because the workspace already +is in vertical orientation.

14.6. Fullscreen windows

For fullscreen windows, the rect (x, y, width, height) is not changed to -allow the client to easily go back to its previous position. Instead, -fullscreen windows are skipped when rendering.

16.5. Case 5: Moving in one-child h-split

The reference layout for this case is a horizontal workspace with two +containers having a v-split on the left side with a one-child h-split on the +bottom. Focus is on the bottom left container (2(h)):

+ +++ + + + + + + + + +

1	3
2(h)

In this case, same_orientation will be set to the h-split container around +the focused container. However, when trying the easy case, the next/previous +container swap will be NULL. Therefore, i3 will search again for a +same_orientation container, this time starting from the parent of the h-split +container.

After determining a new same_orientation container (if it is NULL, the +orientation will be force-changed), this case is equivalent to case 2 or case +4.

14.7. Resizing containers

By clicking and dragging the border of a container, you can resize the whole -column (respectively row) which this container is in. This is necessary to keep -the table layout working and consistent.

The resizing works similarly to the resizing of floating windows or movement of -floating windows:

16.6. Case 6: Floating containers

The reference layout for this case is a horizontal workspace with two +containers plus one floating h-split container. Focus is on the floating +container.

TODO: nice illustration. table not possible?

When moving up/down, the container needs to leave the floating container and it +needs to be placed on the workspace (at workspace level). This is accomplished +by calling the function attach_to_workspace.

17. Click handling

Without much ado, here is the list of cases which need to be considered:

-A new, invisible window with the size of the root window is created - (grabwin) +click to focus (tiling + floating) and raise (floating)
-Another window, 2px width and as high as your screen (or vice versa for - horizontal resizing) is created. Its background color is the border color and - it is only there to inform the user how big the container will be (it - creates the impression of dragging the border out of the container). +click to focus/raise when in stacked/tabbed mode
-The drag_pointer function of src/floating.c is called to grab the pointer - and enter its own event loop which will pass all events (expose events) but - motion notify events. This function then calls the specified callback - (resize_callback) which does some boundary checking and moves the helper - window. As soon as the mouse button is released, this loop will be - terminated. +floating_modifier + left mouse button to drag a floating con
-The new width_factor for each involved column (respectively row) will be - calculated. +floating_modifier + right mouse button to resize a floating con

15. User commands / commandmode (src/commands.c)

Like in vim, you can control i3 using commands. They are intended to be a -powerful alternative to lots of shortcuts, because they can be combined. There -are a few special commands, which are the following:

-exec <command> -: +

-Starts the given command by passing it to /bin/sh. +click on decoration in a floating con to either initiate a resize (if there + is more than one child in the floating con) or to drag the + floating con (if itâs the one at the top).
-
-restart -: + +

-Restarts i3 by executing argv[0] (the path with which you started i3) without -forking. +click on border in a floating con to resize the floating con
-
-w -: + +

-"With". This is used to select a bunch of windows. Currently, only selecting -the whole container in which the window is in, is supported by specifying "w". +floating_modifier + right mouse button to resize a tiling con
-
-f, s, d -: + +

-Toggle fullscreen, stacking, default mode for the current window/container. +click on border/decoration to resize a tiling con
-

The other commands are to be combined with a direction. The directions are h, -j, k and l, like in vim (h = left, j = down, k = up, l = right). When you just -specify the direction keys, i3 will move the focus in that direction. You can -provide "m" or "s" before the direction to move a window respectively or snap.

+ +

16. Gotchas

18. Gotchas

@@ -853,7 +1009,7 @@ Forgetting to call xcb_flush(conn); after sending a request. This usual

17. Using git / sending patches

19. Using git / sending patches

For a short introduction into using git, see http://www.spheredev.org/wiki/Git_for_the_lazy or, for more documentation, see diff --git a/docs/i3-config-wizard.html b/docs/i3-config-wizard.html new file mode 100644 index 0000000..1389d2f --- /dev/null +++ b/docs/i3-config-wizard.html @@ -0,0 +1,96 @@ + + + + + + +i3: i3-config-wizard(1) + + + + + + + +

i3 - improved tiling WM

+
+

+ +

1. NAME

i3-config-wizard - creates a keysym based config based on your layout

2. SYNOPSIS

i3-config-wizard

3. FILES

3.1. /etc/i3/config.keycodes

This file contains the default configuration with keycodes. All the bindcode +lines will be transformed to bindsym and the user-specified modifier will be +used.

4. DESCRIPTION

i3-config-wizard is started by i3 in its default config, unless _{/.i3/config
+exists. i3-config-wizard creates a keysym based i3 config file (based on
+/etc/i3/config.keycodes) in}/.i3/config.

The advantage of using keysyms is that the config file is easy to read, +understand and modify. However, if we shipped with a keysym based default +config file, the key positions would not be consistent across different +keyboard layouts (take for example the homerow for movement). Therefore, we +ship with a keycode based default config and let the wizard transform it +according to your current keyboard layout.

5. SEE ALSO

i3(1)

6. AUTHOR

Michael Stapelberg and contributors

+ + + diff --git a/docs/i3-migrate-config-to-v4.html b/docs/i3-migrate-config-to-v4.html new file mode 100644 index 0000000..e2c31b2 --- /dev/null +++ b/docs/i3-migrate-config-to-v4.html @@ -0,0 +1,87 @@ + + + + + + +i3: i3-migrate-config-to-v4(1) + + + + + + + +

i3 - improved tiling WM

+
+

+ +

1. NAME

i3-migrate-config-to-v4 - migrates your i3 config file

2. SYNOPSIS

mv ~/.i3/config ~/.i3/old.config
+i3-migrate-config-to-v4 ~/.i3/old.config > ~/.i3/config

3. DESCRIPTION

i3-migrate-config-to-v4 is a Perl script which migrates your old (< version 4) +configuration files to a version 4 config file. The most significant changes +are the new commands (see the release notes).

This script will automatically be run by i3 when it detects an old config file. +Please migrate your config file as soon as possible. We plan to include this +script in all i3 release until 2012-08-01. Afterwards, old config files will no +longer be supported.

4. SEE ALSO

i3(1)

5. AUTHOR

Michael Stapelberg and contributors

+ + + diff --git a/docs/i3-msg.html b/docs/i3-msg.html new file mode 100644 index 0000000..2324fab --- /dev/null +++ b/docs/i3-msg.html @@ -0,0 +1,100 @@ + + + + + + +i3: i3-msg(1) + + + + + + + +

i3 - improved tiling WM

+
+

+ +

1. NAME

i3-msg - send messages to i3 window manager

2. SYNOPSIS

i3-msg "message"

3. DESCRIPTION

i3-msg is a sample implementation for a client using the unix socket IPC +interface to i3. At the moment, it can only be used for sending commands +(like in configuration file for key bindings), but this may change in the +future (staying backwards-compatible, of course).

4. EXAMPLE

i3-msg "bp" # Use 1-px border for current client

5. ENVIRONMENT

5.1. I3SOCK

If no ipc-socket is specified on the commandline, this variable is used +to determine the path, at wich the unix domain socket is expected, on which +to connect to i3.

6. SEE ALSO

i3(1)

7. AUTHOR

Michael Stapelberg and contributors

+ + + diff --git a/docs/i3-nagbar.html b/docs/i3-nagbar.html new file mode 100644 index 0000000..64ee27e --- /dev/null +++ b/docs/i3-nagbar.html @@ -0,0 +1,90 @@ + + + + + + +i3: i3-nagbar(1) + + + + + + + +

i3 - improved tiling WM

+
+

+ +

1. NAME

i3-nagbar - displays an error bar on top of your screen

2. SYNOPSIS

i3-nagbar -m message -b label action

3. DESCRIPTION

i3-nagbar is used by i3 to tell you about errors in your configuration file +(for example). While these errors are logged to the logfile (if any), the past +has proven that users are either not aware of their logfile or do not check it +after modifying the configuration file.

4. EXAMPLE

i3-nagbar -m 'You have an error in your i3 config file!' \
+-b 'edit config' 'xterm $EDITOR ~/.i3/config'

5. SEE ALSO

i3(1)

6. AUTHOR

Michael Stapelberg and contributors

+ + + diff --git a/docs/i3.html b/docs/i3.html new file mode 100644 index 0000000..1edda79 --- /dev/null +++ b/docs/i3.html @@ -0,0 +1,527 @@ + + + + + + +i3: i3(1) + + + + + + + +

i3 - improved tiling WM

+
+

+ +

1. NAME

i3 - an improved dynamic, tiling window manager

2. SYNOPSIS

i3 [-a] [-c configfile] [-C] [-d <loglevel>] [-v] [-V]

3. OPTIONS

+-a +: +
+Disables autostart. +
+
+-c +: +
+Specifies an alternate configuration file path. +
+
+-C +: +
+Check the configuration file for validity and exit. +
+
+-d +: +
+Specifies the debug loglevel. To see the most output, use -d all. +
+
+-v +: +
+Display version number (and date of the last commit). +
+
+-V +: +
+Be verbose. +
+

4. DESCRIPTION

4.1. INTRODUCTION

i3 was created because wmii, our favorite window manager at the time, didnât +provide some features we wanted (multi-monitor done right, for example), had +some bugs, didnât progress since quite some time and wasnât easy to hack at all +(source code comments/documentation completely lacking). Still, we think the +wmii developers and contributors did a great job. Thank you for inspiring us to +create i3.

Please be aware that i3 is primarily targeted at advanced users and developers.

4.2. IMPORTANT NOTE TO nVidia BINARY DRIVER USERS

If you are using the nVidia binary graphics driver (also known as blob) +you need to use the --force-xinerama flag (in your ~/.xsession) when starting +i3, like so:

exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1

See also docs/multi-monitor for the full explanation.

4.3. TERMINOLOGY

+Tree +: +
+i3 keeps your layout in a tree data structure. +
+
+Window +: +
+An X11 window, like the Firefox browser window or a terminal emulator. +
+
+Split container +: +
+A split container contains multiple other split containers or windows. +
+
Containers can be used in various layouts. The default mode is called "default" +and just resizes each client equally so that it fits.
+
+Workspace +: +
+A workspace is a set of containers. Other window managers call this "Virtual +Desktops". +
+
In i3, each workspace is assigned to a specific virtual screen. By default, +screen 1 has workspace 1, screen 2 has workspace 2 and so onâ¦ However, when you +create a new workspace (by simply switching to it), itâll be assigned the +screen you are currently on.
+
+Output +: +
+Using XRandR, you can have an X11 screen spanning multiple real monitors. +Furthermore, you can set them up in cloning mode or with positions (monitor 1 +is left of monitor 2). +
+
i3 uses the RandR API to query which outputs are available and which screens +are connected to these outputs.
+

5. KEYBINDINGS

Here is a short overview of the default keybindings:

+j/k/l/; +: +
+Direction keys (left, down, up, right). They are on your homerow (see the mark +on your "j" key). Alternatively, you can use the cursor keys. +
+
+Mod1+<direction> +: +
+Focus window in <direction>. +
+
+Mod1+Shift+<direction> +: +
+Move window to <direction>. +
+
+Mod1+<number> +: +
+Switch to workspace <number>. +
+
+Mod1+Shift+<number> +: +
+Move window to workspace <number>. +
+
+Mod1+f +: +
+Toggle fullscreen mode. +
+
+Mod1+s +: +
+Enable stacking layout for the current container. +
+
+Mod1+e +: +
+Enable default layout for the current container. +
+
+Mod1+w +: +
+Enable tabbed layout for the current container. +
+
+Mod1+Shift+Space +: +
+Toggle tiling/floating for the current container. +
+
+Mod1+Space +: +
+Select the first tiling container if the current container is floating and +vice-versa. +
+
+Mod1+Shift+q +: +
+Kills the current window. This is equivalent to "clicking on the close button", +meaning a polite request to the application to close this window. For example, +Firefox will save its session upon such a request. If the application does not +support that, the window will be killed and it depends on the application what +happens. +
+
+Mod1+Shift+r +: +
+Restarts i3 in place. Your layout will be preserved. +
+
+Mod1+Shift+e +: +
+Exits i3. +
+

6. FILES

6.1. ~/.i3/config (or ~/.config/i3/config)

When starting, i3 looks for configuration files in the following order:

+
+~/.config/i3/config (or $XDG_CONFIG_HOME/i3/config if set) +
+
+
+/etc/xdg/i3/config (or $XDG_CONFIG_DIRS/i3/config if set) +
+
+
+~/.i3/config +
+
+
+/etc/i3/config +
+

You can specify a custom path using the -c option.

Sample configuration

# i3 config file (v4)
+
+# font for window titles. ISO 10646 = Unicode
+font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+
+# use Mouse+Mod1 to drag floating windows to their wanted position
+floating_modifier Mod1
+
+# start a terminal
+bindsym Mod1+Return exec /usr/bin/urxvt
+
+# kill focused window
+bindsym Mod1+Shift+q kill
+
+# start dmenu (a program launcher)
+bindsym Mod1+d exec /usr/bin/dmenu_run
+
+# change focus
+bindsym Mod1+j focus left
+bindsym Mod1+k focus down
+bindsym Mod1+l focus up
+bindsym Mod1+semicolon focus right
+
+# alternatively, you can use the cursor keys:
+bindsym Mod1+Left focus left
+bindsym Mod1+Down focus down
+bindsym Mod1+Up focus up
+bindsym Mod1+Right focus right
+
+# move focused window
+bindsym Mod1+Shift+j move left
+bindsym Mod1+Shift+k move down
+bindsym Mod1+Shift+l move up
+bindsym Mod1+Shift+semicolon move right
+
+# alternatively, you can use the cursor keys:
+bindsym Mod1+Shift+Left move left
+bindsym Mod1+Shift+Down move down
+bindsym Mod1+Shift+Up move up
+bindsym Mod1+Shift+Right move right
+
+# split in horizontal orientation
+bindsym Mod1+h split h
+
+# split in vertical orientation
+bindsym Mod1+v split v
+
+# enter fullscreen mode for the focused container
+bindsym Mod1+f fullscreen
+
+# change container layout (stacked, tabbed, default)
+bindsym Mod1+s layout stacking
+bindsym Mod1+w layout tabbed
+bindsym Mod1+e layout default
+
+# toggle tiling / floating
+bindsym Mod1+Shift+space floating toggle
+
+# change focus between tiling / floating windows
+bindsym Mod1+space focus mode_toggle
+
+# focus the parent container
+bindsym Mod1+a focus parent
+
+# focus the child container
+#bindsym Mod1+d focus child
+
+# switch to workspace
+bindsym Mod1+1 workspace 1
+bindsym Mod1+2 workspace 2
+# ..
+
+# move focused container to workspace
+bindsym Mod1+Shift+1 move workspace 1
+bindsym Mod1+Shift+2 move workspace 2
+# ...
+
+# reload the configuration file
+bindsym Mod1+Shift+c reload
+# restart i3 inplace (preserves your layout/session, can be used to upgrade i3)
+bindsym Mod1+Shift+r restart
+# exit i3 (logs you out of your X session)
+bindsym Mod1+Shift+e exit
+
+# Start i3bar to display a workspace bar (plus the system information i3status
+# finds out, if available)
+exec i3status | i3bar -d

6.2. ~/.xsession

This file is where you should configure your locales and start i3. It is run by +your login manager (xdm, slim, gdm, â¦) as soon as you login.

Sample xsession

# Disable DPMS turning off the screen
+xset -dpms
+xset s off
+
+# Disable bell
+xset -b
+
+# Enable zapping (C-A-<Bksp> kills X)
+setxkbmap -option terminate:ctrl_alt_bksp
+
+# Enforce correct locales from the beginning
+unset LC_COLLATE
+export LC_CTYPE=de_DE.UTF-8
+export LC_TIME=de_DE.UTF-8
+export LC_NUMERIC=de_DE.UTF-8
+export LC_MONETARY=de_DE.UTF-8
+export LC_MESSAGES=C
+export LC_PAPER=de_DE.UTF-8
+export LC_NAME=de_DE.UTF-8
+export LC_ADDRESS=de_DE.UTF-8
+export LC_TELEPHONE=de_DE.UTF-8
+export LC_MEASUREMENT=de_DE.UTF-8
+export LC_IDENTIFICATION=de_DE.UTF-8
+
+# Use XToolkit in java applications
+export AWT_TOOLKIT=XToolkit
+
+# Set background color
+xsetroot -solid "#333333"
+
+# Enable core dumps in case something goes wrong
+ulimit -c unlimited
+
+# Start i3 and log to ~/.i3/logfile
+echo "Starting at $(date)" >> ~/.i3/logfile
+exec /usr/bin/i3 -V -d all >> ~/.i3/logfile

7. ENVIRONMENT

7.1. I3SOCK

This variable overwrites the IPC socket path (placed in +/tmp/i3-%u/ipc-socket.%p by default, where %u is replaced with your UNIX +username and %p is replaced with i3âs PID). The IPC socket is used by external +programs like i3-msg(1) or i3bar(1).

8. TODO

There is still lot of work to do. Please check our bugtracker for up-to-date +information about tasks which are still not finished.

9. SEE ALSO

You should have a copy of the userguide (featuring nice screenshots/graphics +which is why this is not integrated into this manpage), the debugging guide, +and the "how to hack" guide. If you are building from source, run: + make -C docs

You can also access these documents online at http://i3.zekjur.net/

i3-input(1), i3-msg(1), i3-wsbar(1), i3-nagbar(1), i3-config-wizard(1), +i3-migrate-config-to-v4(1)

10. AUTHOR

Michael Stapelberg and contributors

+ + + diff --git a/docs/index.html.mako b/docs/index.html.mako index 1c890bc..c8fef65 100644 --- a/docs/index.html.mako +++ b/docs/index.html.mako @@ -12,46 +12,36 @@ suggestions please let us know!

-Because version 4.0 is quite new, we still have the old documentation for 3.Îµ -online for a few weeks. You can chose which version you want by clicking on the -boxes right next to the links. +These documents are for i3 version 4.0. If you are still using the old version +3.Îµ, you can find the old documentation +here, but we strongly recommend to update.

For users

-Userâs Guide -4.0 -3.Îµ
+Userâs Guide
Introduction and reference. Read this one.

-Multi-monitor -4.0 -3.Îµ
+Multi-monitor
Interesting for users of the nVidia driver.

-Debugging i3 -4.0 -3.Îµ
+Debugging i3
Explains you how to enable the i3 logfile.

-External workspace bars -4.0 -3.Îµ
+External workspace bars
About bar programs such as i3bar or dzen2.

-i3 reference card (PDF) -4.0 -3.Îµ
+i3 reference card (PDF)
Might be useful to memorize i3âs shortcuts.

@@ -65,23 +55,17 @@ Tells you how to check out our git repository.

-Hacking Howto -4.0 -3.Îµ
+Hacking Howto
Helps you if you want to get into i3âs source code.

-Debugging i3 -4.0 -3.Îµ
+Debugging i3
Explains you how to enable core dumps.

-IPC documentation -4.0 -3.Îµ
+IPC documentation
Explains how i3âs Inter Process Communication interface works. Read this if you want to talk to i3 within your own scripts or programs.

diff --git a/docs/ipc.html b/docs/ipc.html index 88b13b7..3a3cb87 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -45,9 +45,11 @@ to get various information like the current workspaces to implement an external workspace bar.

The method of choice for IPC in our case is a unix socket because it has very little overhead on both sides and is usually available without headaches in -most languages. In the default configuration file, no ipc-socket path is -specified and thus no socket is created. The standard path (which i3-msg and -i3-input use) is ~/.i3/ipc.sock.

+most languages. In the default configuration file, the ipc-socket gets created +in /tmp/i3-%u/ipc-socket.%p where %u is your UNIX username and %p is the +PID of i3.

All i3 utilities, like i3-msg and i3-input will read the I3_SOCKET_PATH +X11 property, stored on the X11 root window.

@@ -58,7 +60,7 @@ snippet illustrates this in Perl:

use IO::Socket::UNIX;
-my $sock = IO::Socket::UNIX->new(Peer => '~/.i3/ipc.sock');

+my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');

@@ -113,6 +115,16 @@ GET_OUTPUTS (3) (see the reply section).

+GET_TREE (4) +

+ Gets the layout tree. i3 uses a tree as data structure which includes + every container. The reply will be the JSON-encoded tree (see the reply + section). +

So, a typical message could look like this:

@@ -187,6 +199,14 @@ GET_OUTPUTS (3) Reply to the GET_OUTPUTS message.

+GET_TREE (4) +

+ Reply to the GET_TREE message. +

@@ -381,6 +401,301 @@ rect (map) ]

3.6. GET_TREE reply

The reply consists of a serialized tree. Each node in the tree (representing +one container) has at least the properties listed below. While the nodes might +have more properties, please do not use any properties which are not documented +here. They are not yet finalized and will probably change!

+id (integer) +: +
+ The internal ID (actually a C pointer value) of this container. Do not + make any assumptions about it. You can use it to (re-)identify and + address containers when talking to i3. +
+
+name (string) +: +
+ The internal name of this container. For all containers which are part + of the tree structure down to the workspace contents, this is set to a + nice human-readable name of the container. + For all other containers, the content is not defined (yet). +
+
+border (string) +: +
+ Can be either "normal", "none" or "1pixel", dependending on the + containerâs border style. +
+
+layout (string) +: +
+ Can be either "default", "stacked", "tabbed", "dockarea" or "output". + Other values might be possible in the future, should we add new + layouts. +
+
+orientation (string) +: +
+ Can be either "none" (for non-split containers), "horizontal" or + "vertical". +
+
+percent (float) +: +
+ The percentage which this container takes in its parent. A value of + null means that the percent property does not make sense for this + container, for example for the root container. +
+
+rect (map) +: +
+ The absolute display coordinates for this container. Display + coordinates means that when you have two 1600x1200 monitors on a single + X11 Display (the standard way), the coordinates of the first window on + the second monitor are { "x": 1600, "y": 0, "width": 1600, "height": + 1200 }. +
+
+window_rect (map) +: +
+ The coordinates of the actual client window inside its container. + These coordinates are relative to the container and do not include the + window decoration (which is actually rendered on the parent container). + So, when using the default layout, you will have a 2 pixel border on + each side, making the window_rect { "x": 2, "y": 0, "width": 632, + "height": 366 } (for example). +
+
+geometry (map) +: +
+ The original geometry the window specified when i3 mapped it. Used when + switching a window to floating mode, for example. +
+
+urgent (bool) +: +
+ Whether this container (window or workspace) has the urgency hint set. +
+
+focused (bool) +: +
+ Whether this container is currently focused. +
+

Please note that in the following example, I have left out some keys/values +which are not relevant for the type of the node. Otherwise, the example would +be by far too long (it already is quite long, despite showing only 1 window and +one dock window).

It is useful to have an overview of the structure before taking a look at the +JSON dump:

+
+root +
+
- +
  +LVDS1 +
  +
  - +
    +topdock +
    +
  - +
    +content +
    +
    +
    +
    +workspace 1 +
    +
    +
    +
    +window 1 +
    +
    +
    +
    +
    +
  - +
    +bottomdock +
    +
    +
    +
    +dock window 1 +
    +
    +
    +
  +
- +
  +VGA1 +
  +
+

Example:

{
+ "id": 6875648,
+ "name": "root",
+ "rect": {
+   "x": 0,
+   "y": 0,
+   "width": 1280,
+   "height": 800
+ },
+ "nodes": [
+
+   {
+    "id": 6878320,
+    "name": "LVDS1",
+    "layout": "output",
+    "rect": {
+      "x": 0,
+      "y": 0,
+      "width": 1280,
+      "height": 800
+    },
+    "nodes": [
+
+      {
+       "id": 6878784,
+       "name": "topdock",
+       "layout": "dockarea",
+       "orientation": "vertical",
+       "rect": {
+         "x": 0,
+         "y": 0,
+         "width": 1280,
+         "height": 0
+       },
+      },
+
+      {
+       "id": 6879344,
+       "name": "content",
+       "rect": {
+         "x": 0,
+         "y": 0,
+         "width": 1280,
+         "height": 782
+       },
+       "nodes": [
+
+         {
+          "id": 6880464,
+          "name": "1",
+          "orientation": "horizontal",
+          "rect": {
+            "x": 0,
+            "y": 0,
+            "width": 1280,
+            "height": 782
+          },
+          "floating_nodes": [],
+          "nodes": [
+
+            {
+             "id": 6929968,
+             "name": "#aa0000",
+             "border": "normal",
+             "percent": 1,
+             "rect": {
+               "x": 0,
+               "y": 18,
+               "width": 1280,
+               "height": 782
+             }
+            }
+
+          ]
+         }
+
+       ]
+      },
+
+      {
+       "id": 6880208,
+       "name": "bottomdock",
+       "layout": "dockarea",
+       "orientation": "vertical",
+       "rect": {
+         "x": 0,
+         "y": 782,
+         "width": 1280,
+         "height": 18
+       },
+       "nodes": [
+
+         {
+          "id": 6931312,
+          "name": "#00aa00",
+          "percent": 1,
+          "rect": {
+            "x": 0,
+            "y": 782,
+            "width": 1280,
+            "height": 18
+          }
+         }
+
+       ]
+      }
+    ]
+   }
+ ]
+}

diff --git a/docs/keyboard-layer1.png b/docs/keyboard-layer1.png index 88268f7..52ffae0 100644 Binary files a/docs/keyboard-layer1.png and b/docs/keyboard-layer1.png differ diff --git a/docs/keyboard-layer1.svg b/docs/keyboard-layer1.svg new file mode 100644 index 0000000..109c19a --- /dev/null +++ b/docs/keyboard-layer1.svg @@ -0,0 +1,969 @@ + + + + diff --git a/docs/keyboard-layer2.png b/docs/keyboard-layer2.png index 85a7d21..83616d9 100644 Binary files a/docs/keyboard-layer2.png and b/docs/keyboard-layer2.png differ diff --git a/docs/keyboard-layer2.svg b/docs/keyboard-layer2.svg new file mode 100644 index 0000000..70cc602 --- /dev/null +++ b/docs/keyboard-layer2.svg @@ -0,0 +1,896 @@ + + + + diff --git a/docs/refcard.pdf b/docs/refcard.pdf index f1bb36f..3ff733d 100644 Binary files a/docs/refcard.pdf and b/docs/refcard.pdf differ diff --git a/docs/userguide.html b/docs/userguide.html index bfb4d63..85e77eb 100644 --- a/docs/userguide.html +++ b/docs/userguide.html @@ -31,7 +31,7 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}

i3 Userâs Guide

Michael Stapelberg
<michael+i3@stapelberg.de>
-March 2010 +August 2011

Table of Contents

@@ -40,8 +40,8 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}

This document contains all the information you need to configure and use the i3 -window manager. If it does not, please contact me on IRC, Jabber or E-Mail and -Iâll help you out.

+window manager. If it does not, please contact us on IRC (preferred) or post your +question(s) on the mailing list.

@@ -49,21 +49,18 @@ Iâll help you out.

For the "too long; didnât read" people, here is an overview of the default keybindings (click to see the full size image):

Keys to use with Mod1 (alt):

Keys to use with mod (alt):

- +

Keys to use with Shift+Mod1:

Keys to use with Shift+mod:

- +

As i3 uses keycodes in the default configuration, it does not matter which -keyboard layout you actually use. The key positions are what matters (of course -you can also use keysymbols, see [keybindings]).

The red keys are the modifiers you need to press (by default), the blue keys are your homerow.

@@ -71,42 +68,44 @@ are your homerow.

2. Using i3

Throughout this guide, the keyword mod will be used to refer to the +configured modifier. This is the alt key (Mod1) by default, with windows (Mod4) +being a popular alternative.

2.1. Opening terminals and moving around

One very basic operation is opening a new terminal. By default, the keybinding -for this is Mod1+Enter, that is Alt+Enter in the default configuration. By -pressing Mod1+Enter, a new terminal will be opened. It will fill the whole +for this is mod+Enter, that is Alt+Enter in the default configuration. By +pressing mod+Enter, a new terminal will be opened. It will fill the whole space available on your screen.

Single terminal

It is important to keep in mind that i3 uses a table to manage your windows. At -the moment, you have exactly one column and one row which leaves you with one -cell. In this cell there is a container, which is where your new terminal is -opened.

If you now open another terminal, you still have only one cell. However, the -container in that cell holds both of your terminals. So, a container is just a -group of clients with a specific layout. Containers can be resized by adjusting -the size of the cell that holds them.

If you now open another terminal, i3 will place it next to the current one, +splitting the screen size in half. Depending on your monitor, i3 will put the +created window beside the existing window (on wide displays) or below the +existing window (rotated displays).

Two terminals

To move the focus between the two terminals, you use the direction keys which -you may know from the editor vi. However, in i3, your homerow is used for -these keys (in vi, the keys are shifted to the left by one for compatibility -with most keyboard layouts). Therefore, Mod1+J is left, Mod1+K is down, -Mod1+L is up and Mod1+; is right. So, to switch between the terminals, -use Mod1+K or Mod1+L.

To create a new row/column (and a new cell), you can simply move a terminal (or -any other window) in the direction you want to expand your table. So, letâs -expand the table to the right by pressing Mod1+Shift+;.

- Two columns -

To move the focus between the two terminals, you can use the direction keys +which you may know from the editor vi. However, in i3, your homerow is used +for these keys (in vi, the keys are shifted to the left by one for +compatibility with most keyboard layouts). Therefore, mod+J is left, mod+K +is down, mod+L is up and mod+; is right. So, to switch between the +terminals, use mod+K or mod+L. Of course, you can also use the arrow keys.

At the moment, your workspace is split (it contains two terminals) in a +specific direction (horizontal by default). Every window can be split +horizontally or vertically again, just like the workspace. The terminology is +"window" for a container that actually contains an X11 window (like a terminal +or browser) and "split container" for containers that consist of one or more +windows.

TODO: picture of the tree

To split a window vertically, press mod+v. To split it horizontally, press +mod+h.

2.2. Changing container modes

A container can have the following modes:

2.2. Changing the container layout

A split container can have one of the following layouts:

default @@ -136,34 +135,34 @@ a single line which is vertically split.

To switch modes, press Mod1+e for default, Mod1+h for stacking and -Mod1+w for tabbed.

To switch modes, press mod+e for default, mod+s for stacking and +mod+w for tabbed.

Container modes

2.3. Toggling fullscreen mode for a window

To display a window fullscreen or to go out of fullscreen mode again, press -Mod1+f.

There is also a global fullscreen mode in i3 in which the client will use all -available outputs. To use it, or to get out of it again, press Mod1+Shift+f.

To display a window in fullscreen mode or to go out of fullscreen mode again, +press mod+f.

There is also a global fullscreen mode in i3 in which the client will span all +available outputs.

2.4. Opening other applications

Aside from opening applications from a terminal, you can also use the handy -dmenu which is opened by pressing Mod1+v by default. Just type the name -(or a part of it) of the application which you want to open. The application -typed has to be in your $PATH for this to work.

+dmenu which is opened by pressing mod+d by default. Just type the name +(or a part of it) of the application which you want to open. The corresponding +application has to be in your $PATH for this to work.

Additionally, if you have applications you open very frequently, you can create a keybinding for starting the application directly. See the section -"Configuring i3" for details.

+[configuring] for details.

2.5. Closing windows

If an application does not provide a mechanism for closing (most applications provide a menu, the escape key or a shortcut like Control+W to close), you -can press Mod1+Shift+q to kill a window. For applications which support +can press mod+Shift+q to kill a window. For applications which support the WM_DELETE protocol, this will correctly close the application (saving any modifications or doing other cleanup). If the application doesnât support the WM_DELETE protocol your X server will kill the window and the behaviour @@ -173,7 +172,7 @@ depends on the application.

2.6. Using workspaces

Workspaces are an easy way to group a set of windows. By default, you are on the first workspace, as the bar on the bottom left indicates. To switch to -another workspace, press Mod1+num where num is the number of the workspace +another workspace, press mod+num where num is the number of the workspace you want to use. If the workspace does not exist yet, it will be created.

A common paradigm is to put the web browser on one workspace, communication applications (mutt, irssi, …) on another one, and the ones with which you @@ -185,52 +184,35 @@ focus to that screen.

2.7. Moving windows to workspaces

To move a window to another workspace, simply press Mod1+Shift+num where +

To move a window to another workspace, simply press mod+Shift+num where num is (like when switching workspaces) the number of the target workspace. Similarly to switching workspaces, the target workspace will be created if it does not yet exist.

2.8. Resizing columns/rows

To resize columns or rows, just grab the border between the two columns/rows -and move it to the wanted size. Please keep in mind that each cell of the table -holds a container and thus you cannot horizontally resize single windows. If -you need applications with different horizontal sizes, place them in seperate -cells one above the other.

2.8. Resizing

The easiest way to resize a container is by using the mouse: Grab the border +and move it to the wanted size.

See [resizingconfig] for how to configure i3 to be able to resize columns/rows with your keyboard.

2.9. Restarting i3 inplace

To restart i3 inplace (and thus get into a clean state if there is a bug, or -to upgrade to a newer version of i3) you can use Mod1+Shift+r. Be aware, -though, that this kills your current layout and all the windows you have opened -will be put in a default container in only one cell. Saving layouts will be -implemented in a later version.

+to upgrade to a newer version of i3) you can use mod+Shift+r.

2.10. Exiting i3

To cleanly exit i3 without killing your X server, you can use Mod1+Shift+e.

To cleanly exit i3 without killing your X server, you can use mod+Shift+e.

2.11. Snapping

Snapping is a mechanism to increase/decrease the colspan/rowspan of a container. -Colspan/rowspan is the number of columns/rows a specific cell of the table -consumes. This is easier explained by giving an example, so take the following -layout:

- Snapping example -

To use the full size of your screen, you can now snap container 3 downwards -by pressing Mod1+Control+k (or snap container 2 rightwards).

2.12. Floating

2.11. Floating

Floating mode is the opposite of tiling mode. The position and size of a window are not managed by i3, but by you. Using this mode violates the tiling paradigm but can be useful for some corner cases like "Save as" dialog -windows, or toolbar windows (GIMP or similar).

You can enable floating mode for a window by pressing Mod1+Shift+Space. By +windows, or toolbar windows (GIMP or similar). Those windows usually set the +appropriate hint and are opened in floating mode by default.

You can enable floating mode for a window by pressing mod+Shift+Space. By dragging the windowâs titlebar with your mouse you can move the window around. By grabbing the borders and moving them you can resize the window. You can also do that by using the [floating_modifier].

@@ -240,7 +222,93 @@ can also do that by using the [floating_modifier]

3. Configuring i3

3. Tree

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 +(of outputs, workspaces) and a table for each workspace. That approach turned +out to be complicated to use (snapping), understand and implement.

3.1. The tree consists of Containers

The building blocks of our tree are so called Containers. A Container can +host a window (meaning an X11 window, one that you can actually see and use, +like a browser). Alternatively, it could contain one or more Containers. A +simple example is the workspace: When you start i3 with a single monitor, a +single workspace and you open two terminal windows, you will end up with a tree +like this:

Figure 1. Two terminals on standard workspace

3.2. Orientation and Split Containers

It is only natural to use so-called Split Containers in order to build a +layout when using a tree as data structure. In i3, every Container has an +orientation (horizontal, vertical or unspecified). So, in our example with the +workspace, the default orientation of the workspace Container is horizontal +(most monitors are widescreen nowadays). If you change the orientation to +vertical (mod+v in the default config) and then open two terminals, i3 will +configure your windows like this:

Figure 2. Vertical Workspace Orientation

An interesting new feature of the tree branch is the ability to split anything: +Letâs assume you have two terminals on a workspace (with horizontal +orientation), focus is on the right terminal. Now you want to open another +terminal window below the current one. If you would just open a new terminal +window, it would show up to the right due to the horizontal workspace +orientation. Instead, press mod+v to create a Vertical Split Container (to +open a Horizontal Split Container, use mod+h). Now you can open a new +terminal and it will open below the current one:

Figure 3. Vertical Split Container

You probably guessed it already: There is no limit on how deep your hierarchy +of splits can be.

3.3. Focus parent

Letâs stay with our example from above. We have a terminal on the left and two +vertically split terminals on the right, focus is on the bottom right one. When +you open a new terminal, it will open below the current one.

So, how can you open a new terminal window to the right of the current one? +The solution is to use focus parent, which will focus the Parent Container of +the current Container. In this case, you would focus the Vertical Split +Container which is inside the horizontally oriented workspace. Thus, now new +windows will be opened to the right of the Vertical Split Container:

Figure 4. Focus parent, then open new terminal

4. Configuring i3

This is where the real fun begins ;-). Most things are very dependant on your ideal working environment so we canât make reasonable defaults for them.

@@ -254,8 +322,15 @@ can bind your keys to do useful things.

To change the configuration of i3, copy /etc/i3/config to ~/.i3/config (or ~/.config/i3/config if you like the XDG directory scheme) and edit it with a text editor.

On first start (and on all following starts, unless you have a configuration +file), i3 will offer you to create a configuration file. You can tell the +wizard to use either Alt (Mod1) or Windows (Mod4) as modifier in the config +file. Also, the created config file will use the key symbols of your current +keyboard layout. To start the wizard, use the command i3-config-wizard. +Please note that you must not have ~/.i3/config, otherwise the wizard will +exit.

3.1. Comments

4.1. Comments

It is possible and recommended to use comments in your configuration file to properly document your setup for later reference. Comments are started with a # and can only be used at the beginning of a line:

@@ -266,11 +341,12 @@ a # and can only be used at the beginning of a line:

3.2. Fonts

i3 uses X core fonts (not Xft) for rendering window titles and the internal -workspace bar. You can use xfontsel(1) to generate such a font description. -To see special characters (Unicode), you need to use a font which supports -the ISO-10646 encoding.

4.2. Fonts

i3 uses X core fonts (not Xft) for rendering window titles. You can use +xfontsel(1) to generate such a font description. To see special characters +(Unicode), you need to use a font which supports the ISO-10646 encoding.

If i3 cannot open the configured font, it will output an error in the logfile +and fall back to a working font.

Syntax:

@@ -283,7 +359,7 @@ the ISO-10646 encoding.

3.3. Keyboard bindings

4.3. Keyboard bindings

A keyboard binding makes i3 execute a command (see below) upon pressing a specific key. i3 allows you to bind either on keycodes or on keysyms (you can also mix your bindings, though i3 will not protect you from overlapping ones).

@@ -298,9 +374,9 @@ A keysym (key symbol) is a description for a specific symbol, like "a"

-Keycodes do not need to have a symbol assigned (handy for some hotkeys - on some notebooks) and they will not change their meaning as you switch to a - different keyboard layout (when using xmodmap). +Keycodes do not need to have a symbol assigned (handy for custom vendor + hotkeys on some notebooks) and they will not change their meaning as you + switch to a different keyboard layout (when using xmodmap).

@@ -312,19 +388,19 @@ keysyms.

bindsym [Modifiers+]keysym command
-bind [Modifiers+]keycode command

+bindcode [Modifiers+]keycode command

Examples:

# Fullscreen
-bindsym Mod1+f f
+bindsym mod+f f
 
 # Restart
-bindsym Mod1+Shift+r restart
+bindsym mod+Shift+r restart
 
 # Notebook-specific hotkeys
-bind 214 exec /home/michael/toggle_beamer.sh

+bindcode 214 exec /home/michael/toggle_beamer.sh

Available Modifiers:

@@ -351,7 +427,7 @@ workspaces is totally convenient. Try it :-).

3.4. The floating modifier

4.4. The floating modifier

To move floating windows with your mouse, you can either grab their titlebar or configure the so called floating modifier which you can then press and click anywhere in the window itself to move it. The most common setup is to @@ -366,44 +442,86 @@ you hold the shift button as well, the resize will be proportional.

floating_modifier <Modifiers>

Examples:

Example:

floating_modifier Mod1

3.5. Layout mode for new containers

This option determines in which mode new containers will start. See also -[stack-limit].

4.5. Orientation for new workspaces

New workspaces get a reasonable default orientation: Wide-screen monitors +(anything wider than high) get horizontal orientation, rotated monitors +(anything higher than wide) get vertical orientation.

With the default_orientation configuration directive, you can override that +behaviour.

Syntax:

new_container <default|stacking|tabbed>
-new_container stack-limit <cols|rows> <value>

default_orientation <horizontal|vertical|auto>

Examples:

Example:

new_container tabbed

default_orientation vertical

3.6. Border style for new windows

4.6. Layout mode for new containers

This option determines in which mode new containers on workspace level will +start.

Syntax:

workspace_layout <default|stacking|tabbed>

Example:

workspace_layout tabbed

4.7. Border style for new windows

This option determines which border style new windows will have.

Syntax:

new_window <bp|bn|bb>

new_window <normal|1pixel|borderless>

Example:

new_window 1pixel

4.8. Arbitrary commands for specific windows (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.

Syntax:

for_window [criteria] command

Examples:

new_window bp

# enable floating mode for all XTerm windows
+for_window [class="XTerm"] floating enable
+
+# Make all urxvts use a 1-pixel border:
+for_window [class="urxvt"] border 1pixel
+
+# A less useful, but rather funny example:
+# makes the window floating as soon as I change
+# directory to ~/work
+for_window [title="x200: ~/work"] floating enable

3.7. Variables

4.9. Variables

As you learned in the section about keyboard bindings, you will have to configure lots of bindings containing modifier keys. If you want to save yourself some typing and be able to change the modifier you use later, @@ -411,9 +529,9 @@ variables can be handy.

Syntax:

set name value

set $name value

Examples:

Example:

set $m Mod1
@@ -423,56 +541,61 @@ bindsym $m+Shift+r restart

handling and there are 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).

+~/.xsession file).

3.8. Automatically putting clients on specific workspaces

It is recommended that you match on window classes wherever possible because -some applications first create their window, and then worry about setting the -correct title. Firefox with Vimperator comes to mind. The window starts up -being named Firefox, and only when Vimperator is loaded does the title change. -As i3 will get the title as soon as the application maps the window (mapping -means actually displaying it on the screen), youâd need to have to match on -Firefox in this case.

4.10. Automatically putting clients on specific workspaces

Specific windows can be matched by window class and/or window title. It is +recommended that you match on window classes instead of window titles whenever +possible because some applications first create their window, and then worry +about setting the correct title. Firefox with Vimperator comes to mind. The +window starts up being named Firefox, and only when Vimperator is loaded does +the title change. As i3 will get the title as soon as the application maps the +window (mapping means actually displaying it on the screen), youâd need to have +to match on Firefox in this case.

You can prefix or suffix workspaces with a ~ to specify that matching clients should be put into floating mode. If you specify only a ~, the client will not be put onto any workspace, but will be set floating on the current one.

Syntax:

assign ["]window class[/window title]["] [â] [~ | workspace]

assign ["]window class[/window title]["] [â] [workspace]

Examples:

assign urxvt 2
 assign urxvt â 2
+assign urxvt â work
 assign "urxvt" â 2
 assign "urxvt/VIM" â 3
-assign "gecko" â ~4
-assign "xv/MPlayer" â ~

+assign "gecko" â 4

Note that the arrow is not required, it just looks good :-). If you decide to -use it, it has to be a UTF-8 encoded arrow, not "→" or something like that.

+use it, it has to be a UTF-8 encoded arrow, not -> or something like that.

3.9. Automatically starting applications on i3 startup

By using the exec keyword outside a keybinding, you can configure which -commands will be performed by i3 on initial startup (not when restarting i3 -in-place however). These commands will be run in order.

4.11. Automatically starting applications on i3 startup

By using the exec keyword outside a keybinding, you can configure +which commands will be performed by i3 on initial startup. exec +commands will not run when restarting i3, if you need a command to run +also when restarting i3 you should use the exec_always +keyword. These commands will be run in order.

Syntax:

exec command

exec command
+exec_always command

Examples:

exec sudo i3status | dzen2 -dock

exec i3status | i3bar -d
+exec_always ~/my_script.sh

3.10. Automatically putting workspaces on specific screens

4.12. Automatically putting workspaces on specific screens

If you assign clients to workspaces, it might be handy to put the workspaces on specific screens. Also, the assignment of workspaces to screens will determine which workspace i3 uses for a new screen when adding screens @@ -494,28 +617,8 @@ workspace 5 output VGA1

3.11. Named workspaces

If you always have a certain arrangement of workspaces, you might want to give -them names (of course UTF-8 is supported):

Syntax:

workspace <number> <name>
-workspace <number> output <output> name

For more details about the output part of this command, see above.

Examples:

workspace 1 www
-workspace 2 work
-workspace 3 i â¥ workspaces

3.12. Changing colors

You can change all colors which i3 uses to draw the window decorations and the -bottom bar.

4.13. Changing colors

You can change all colors which i3 uses to draw the window decorations.

Syntax:

@@ -556,30 +659,6 @@ client.urgent A client which has its urgency hint activated.

-bar.focused -

- The current workspace in the bottom bar. -

-bar.unfocused -

- All other workspaces in the bottom bar. -

-bar.urgent -

- A workspace which has at least one client with an activated urgency hint. -

You can also specify the color to be used to paint the background of the client windows. This color will be used to paint the window on top of which the client @@ -595,33 +674,40 @@ 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.

Colors are in HTML hex format (#rrggbb), see the following example:

Examples:

Examples (default colors):

# class        border  backgr. text
-client.focused #2F343A #900000 #FFFFFF

# class                 border  backgr. text
+client.focused          #4c7899 #285577 #ffffff
+client.focused_inactive #333333 #5f676a #ffffff
+client.unfocused        #333333 #222222 #888888
+client.urgent           #2f343a #900000 #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.

3.13. Interprocess communication

4.14. Interprocess communication

i3 uses unix sockets to provide an IPC interface. This allows third-party programs to get information from i3, such as the current workspaces (to display a workspace bar), and to control i3.

To enable it, you have to configure a path where the unix socket will be -stored. The default path is ~/.i3/ipc.sock.

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.

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.

Examples:

ipc-socket ~/.i3/ipc.sock

ipc-socket /tmp/i3-ipc.sock

You can then use the i3-msg application to perform any command listed in the next section.

3.14. Disable focus follows mouse

4.15. Focus follows mouse

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. @@ -632,119 +718,230 @@ to click on links in your browser window).

focus_follows_mouse <yes|no>

Examples:

Example:

focus_follows_mouse no

3.15. Internal workspace bar

The internal workspace bar (the thing at the bottom of your screen) is very -simple — it does not provide a way to display custom text and it does not -offer advanced customization features. This is intended because we do not -want to duplicate functionality of tools like dzen2, xmobar and so on -(they render bars, we manage windows). Instead, there is an option which will -turn off the internal bar completely, so that you can use a separate program to -display it (see i3-wsbar, a sample implementation of such a program):

4.16. Popups during fullscreen mode

When you are in fullscreen mode, some applications still open popup windows +(take Xpdf for example). This is because these applications may not be aware +that they are in fullscreen mode (they do not check the corresponding hint). +There are two things which are possible to do in this situation:

+
+Just ignore the popup (donât map it). This wonât interrupt you while you are + in fullscreen. However, some apps might react badly to this (deadlock until + you go out of fullscreen). +
+
+
+Leave fullscreen mode. This is the default. +
+

Syntax:

workspace_bar <yes|no>

popup_during_fullscreen <ignore|leave_fullscreen>

Examples:

Example:

workspace_bar no

popup_during_fullscreen ignore

4.17. Focus wrapping

When being in a tabbed or stacked container, the first container will be +focused when you use focus down on the last container — the focus wraps. If +however there is another stacked/tabbed container in that direction, focus will +be set on that container. This is the default behaviour so you can navigate to +all your windows without having to use focus parent.

If you want the focus to always wrap and you are aware of using focus +parent to switch to different containers, you can use the +force_focus_wrapping configuration directive. After enabling it, the focus +will always wrap.

Syntax:

force_focus_wrapping <yes|no>

Example:

force_focus_wrapping yes

4. List of commands

5. List of commands

4.1. Manipulating layout

To change the layout of the current container to stacking, use s, for default -use d and for tabbed, use T. To make the current client (!) fullscreen, -use f, to make it span all outputs, use fg, to make it floating (or -tiling again) use t:

5.1. Splitting containers

The split command makes the current window a split container. Split containers +can contain multiple windows. Every split container has an orientation, it is +either split horizontally (a new window gets placed to the right of the current +one) or vertically (a new window gets placed below the current one).

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).

Syntax:

split <vertical|horizontal>

Example:

bindsym mod+v split vertical
+bindsym mod+h split horizontal

5.2. Manipulating layout

Use layout default, layout stacking or layout tabbed to change the +current container layout to default, stacking or tabbed layout, respectively.

To make the current window (!) fullscreen, use fullscreen, to make +it floating (or tiling again) use floating enable respectively floating disable +(or floating toggle):

Examples:

bindsym Mod1+s s
-bindsym Mod1+l d
-bindsym Mod1+w T
+bindsym mod+s layout stacking
+bindsym mod+l layout default
+bindsym mod+w layout tabbed
 
 # Toggle fullscreen
-bindsym Mod1+f f
-
-# Toggle global fullscreen
-bindsym Mod1+Shift+f fg
+bindsym mod+f fullscreen
 
 # Toggle floating/tiling
-bindsym Mod1+t t
+bindsym mod+t floating toggle

4.2. Focusing/Moving/Snapping clients/containers/screens

To change the focus, use one of the h, j, k and l commands, meaning -left, down, up, right (respectively). To focus a container, prefix it with -wc. To focus a screen, prefix it with ws.

The same principle applies for moving and snapping: just prefix the command -with m when moving and with s when snapping:

5.3. Focusing/Moving containers

To change the focus, use the focus command: focus left, focus right, focus down and focus up.

There are a few special parameters you can use for the focus command:

+parent +: +
+ Sets focus to the Parent Container of the current Container. +
+
+child +: +
+ The opposite of focus parent, sets the focus to the last focused + child container. +
+
+floating +: +
+ Sets focus to the last focused floating container. +
+
+tiling +: +
+ Sets focus to the last focused tiling container. +
+
+mode_toggle +: +
+ Toggles between floating/tiling containers. +
+

For moving, use move left, move right, move down and move up.

Examples:

# Focus clients on the left, bottom, top, right:
-bindsym Mod1+j h
-bindsym Mod1+k j
-bindsym Mod1+j k
-bindsym Mod1+semicolon l
+bindsym mod+j focus left
+bindsym mod+k focus down
+bindsym mod+l focus up
+bindsym mod+semicolon focus right
 
-# Move client to the left, bottom, top, right:
-bindsym Mod1+j mh
-bindsym Mod1+k mj
-bindsym Mod1+j mk
-bindsym Mod1+semicolon ml
+# Focus parent container
+bindsym mod+u focus parent
 
-# Snap client to the left, bottom, top, right:
-bindsym Mod1+j sh
-bindsym Mod1+k sj
-bindsym Mod1+j sk
-bindsym Mod1+semicolon sl
+# Focus last floating/tiling container
+bindsym mod+g focus mode_toggle
 
-# Focus container on the left, bottom, top, right:
-bindsym Mod3+j wch
-â¦

+# Move client to the left, bottom, top, right: +bindsym mod+j move left +bindsym mod+k move down +bindsym mod+l move up +bindsym mod+semicolon move right

4.3. Changing workspaces/moving clients to workspaces

To change to a specific workspace, the command is just the number of the -workspace, e.g. 1 or 3. To move the current client to a specific workspace, -prefix the number with an m.

You can also switch to the next and previous workspace with the commands nw -and pw, 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.

5.4. 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 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 +workspace 1, 3, 4 and 9 and you want to cycle through them with a single key +combination.

Examples:

bindsym Mod1+1 1
-bindsym Mod1+2 2
+bindsym mod+1 workspace 1
+bindsym mod+2 workspace 2
 ...
 
-bindsym Mod1+Shift+1 m1
-bindsym Mod1+Shift+2 m2
-...
-
-bindsym Mod1+o nw
-bindsym Mod1+p pw
+bindsym mod+Shift+1 move workspace 1
+bindsym mod+Shift+2 move workspace 2
+...

5.4.1. Named workspaces

Workspaces are identified by their name. So, instead of using numbers in the +workspace command, you can use an arbitrary name:

Example:

bindsym mod+1 workspace mail
+...

If you want the workspace to have a number and a name, just prefix the +number, like this:

Example:

bindsym mod+1 workspace 1: mail
+bindsym mod+2 workspace 2: www
+...

Note that the workspace will really be named "1: mail". i3 treats workspace +names beginning with a number in a slightly special way. Normally, named +workspaces are ordered the way they appeared. When they start with a number, i3 +will order them numerically.

4.4. Resizing columns/rows

If you want to resize columns/rows using your keyboard, you can use the +

5.5. Resizing containers/windows

If you want to resize containers/windows using your keyboard, you can use the resize command, I recommend using it inside a so called mode:

Example: Configuration file, defining a mode for resizing

@@ -756,50 +953,48 @@ bindsym Mod1+p pw # when pressing left, the window is resized so that it has # more space on its left - bindsym n resize left -10 - bindsym Shift+n resize left +10 + bindsym j resize shrink left + bindsym Shift+j resize grow left - bindsym r resize bottom +10 - bindsym Shift+r resize bottom -10 + bindsym k resize grow down + bindsym Shift+k resize shrink down - bindsym t resize top -10 - bindsym Shift+t resize top +10 + bindsym l resize shrink up + bindsym Shift+l resize grow up - bindsym d resize right +10 - bindsym Shift+d resize right -10 + bindsym semicolon resize grow right + bindsym Shift+semicolon resize shrink right - bind 36 mode default + bindcode 36 mode default } # Enter resize mode -bindsym Mod1+r mode resize +bindsym mod+r mode "resize"

4.5. Jumping to specific windows

5.6. Jumping to specific windows

Often when in a multi-monitor environment, you want to quickly jump to a specific window. For example, while working on workspace 3 you may want to jump to your mail client to email your boss that youâve achieved some important goal. Instead of figuring out how to navigate to your mailclient, -it would be more convenient to have a shortcut.

+it would be more convenient to have a shortcut. You can use the focus command +with criteria for that.

Syntax:

jump ["]window class[/window title]["]
-jump workspace [ column row ]

[class="class"] focus
+[title="title"] focus

You can either use the same matching algorithm as in the assign command -(see above) or you can specify the position of the client if you always use -the same layout.

Examples:

# Get me to the next open VIM instance
-bindsym Mod1+a jump "urxvt/VIM"

+bindsym mod+a [class="urxvt" title="VIM"] focus

4.6. VIM-like marks (mark/goto)

5.7. VIM-like marks (mark/goto)

This feature is like the jump feature: It allows you to directly jump to a specific window (this means switching to the appropriate workspace and setting focus to the windows). However, you can directly mark a specific window with @@ -813,123 +1008,49 @@ can also prefix this command and display a custom prompt for the input dialog.

Syntax:

mark <identifier>
-goto <identifier>

Examples:

# Read 1 character and mark the current window with this character
-bindsym Mod1+m exec i3-input -p 'mark ' -l 1 -P 'Mark: '
-
-# Read 1 character and go to the window with the character
-bindsym Mod1+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.

4.7. Traveling the focus stack

This mechanism can be thought of as the opposite of the jump command. -It travels the focus stack and jumps to the window which had focus previously.

Syntax:

focus [number] | floating | tiling | ft

mark identifier
+[con_mark="identifier"] focus

Where number by default is 1 meaning that the next client in the focus stack -will be selected.

The special values have the following meaning:

-floating -: -
- The next floating window is selected. -
-
-tiling -: -
- The next tiling window is selected. -
-
-ft -: -
- If the current window is floating, the next tiling window will be - selected; and vice-versa. -
-

4.8. Changing border style

To change the border of the current client, you can use bn to use the normal -border (including window title), bp to use a 1-pixel border (no window title) -and bb to make the client borderless. There is also bt which will toggle -the different border styles.

Examples:

Example (in a terminal):

bindsym Mod1+t bn
-bindsym Mod1+y bp
-bindsym Mod1+u bb

$ i3-msg mark irssi
+$ i3-msg '[con_mark="irssi"] focus'

4.9. Changing the stack-limit of a container

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 seeing only half of the -titlebars for each window in the container.

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.

Syntax:

stack-limit <cols|rows> <value>

5.8. Changing border style

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.

There is also border toggle which will toggle the different border styles.

Examples:

# I always want to have two window titles in one line
-stack-limit cols 2
-
-# Not more than 5 rows in this stacking container
-stack-limit rows 5

bindsym mod+t border normal
+bindsym mod+y border 1pixel
+bindsym mod+u border none

- Container limited to two columns -

4.10. Reloading/Restarting/Exiting

5.9. Reloading/Restarting/Exiting

You can make i3 reload its configuration file with reload. You can also restart i3 inplace with the restart command to get it out of some weird state (if that should ever happen) or to perform an upgrade without having to restart -your X session. However, your layout is not preserved at the moment, meaning -that all open windows will end up in a single container in default layout -after the restart. To exit i3 properly, you can use the exit command, +your X session. To exit i3 properly, you can use the exit command, however you donât need to (simply killing your X session is fine as well).

Examples:

bindsym Mod1+Shift+r restart
-bindsym Mod1+Shift+w reload
-bindsym Mod1+Shift+e exit

bindsym mod+Shift+r restart
+bindsym mod+Shift+w reload
+bindsym mod+Shift+e exit

5. Multiple monitors

6. Multiple monitors

As you can see in the goal list on the website, i3 was specifically developed with support for multiple monitors in mind. This section will explain how to @@ -952,7 +1073,7 @@ create an unlimited number of workspaces in i3 and tie them to specific screens, you can have the "traditional" approach of having X workspaces per screen by changing your configuration (using modes, for example).

5.1. Configuring your monitors

6.1. Configuring your monitors

To help you get going if you have never used multiple monitors before, here is a short overview of the xrandr options which will probably be of interest to you. It is always useful to get an overview of the current screen configuration. @@ -1015,7 +1136,7 @@ only what you can see in xrandr.

See also [presentations] for more examples of multi-monitor setups.

5.2. Interesting configuration for multi-monitor environments

6.2. Interesting configuration for multi-monitor environments

There are several things to configure in i3 which may be interesting if you have more than one monitor:

@@ -1046,51 +1167,35 @@ If you have many workspaces on many monitors, it might get hard to keep

6. i3 and the rest of your software world

7. i3 and the rest of your software world

6.1. Displaying a status line

7.1. Displaying a status line

A very common thing amongst users of exotic window managers is a status line at some corner of the screen. It is an often superior replacement to the widget approach you have in the task bar of a traditional desktop environment.

If you donât already have your favorite way of generating such a status line (self-written scripts, conky, â¦), then i3status is the recommended tool for this task. It was written in C with the goal of using as few syscalls as -possible to reduce the time your CPU is woken up from sleep states.

Regardless of which application you use to generate the status line, you -want to make sure that the application does one of the following things:

-
-Register as a dock window using EWMH hints. This will make i3 position the - window above the workspace bar but below every other client. This is the - recommended way, but in case of dzen2, for example, you need to check out - the source of dzen2 from subversion, as the -dock option is not present - in the released versions. -
-
-
-Overlay the internal workspace bar. This method will not waste any space - on the workspace bar, however, it is rather hackish. Just configure - the output window to be over the workspace bar (say -x 200 and -y 780 if - your screen is 800 px height). -
-

The planned solution for this problem is to make the workspace bar optional -and switch to a third party application completely (dzen2 for example) -which will then contain the workspace bar.

+possible to reduce the time your CPU is woken up from sleep states. Because +i3status only spits out text, you need to combine it with some other tool, like +i3bar. Use a pipe to connect them: i3status | i3bar -d.

Regardless of which application you use to display the status line, you +want to make sure that it registers as a dock window using EWMH hints. i3 will +position the window either at the top or at the bottom of the screen, depending +on which hint the application sets. With i3bar, you can use -d or -dbottom +for positioning it at the bottom and -dtop to position it at the top of the +screen.

6.2. Giving presentations (multi-monitor)

7.2. Giving presentations (multi-monitor)

When giving a presentation, you typically want the audience to see what you see on your screen and then go through a series of slides (if the presentation is simple). For more complex presentations, you might want to have some notes which only you can see on your screen, while the audience can only see the slides.

6.2.1. Case 1: everybody gets the same output

7.2.1. Case 1: everybody gets the same output

This is the simple case. You connect your computer to the video projector, turn on both (computer and video projector) and configure your X server to clone the internal flat panel of your computer to the video output:

@@ -1103,7 +1208,7 @@ your screen will be left untouched (it will show the X background). So, in our example, this would be 1024x768 (my notebook has 1280x800).

6.2.2. Case 2: you can see more than your audience

7.2.2. Case 2: you can see more than your audience

This case is a bit harder. First of all, you should configure the VGA output somewhere near your internal flat panel, say right of it:

diff --git a/docs/wsbar.svg b/docs/wsbar.svg new file mode 100644 index 0000000..e0c8679 --- /dev/null +++ b/docs/wsbar.svg @@ -0,0 +1,274 @@ + +