Hacking i3: How To
==================
Michael Stapelberg <michael+i3@stapelberg.de>
-March 2009
+May 2009
This document is intended to be the first thing you read before looking and/or touching
i3’s source code. It should contain all important information to help you understand
. Iterate through all existing windows (if the window manager is not started as the first
client of X) and manage them (= reparent them, create window decorations)
. When new windows are created, manage them
-. Handle the client’s _WM_STATE property, but only the _WM_STATE_FULLSCREEN
-. Handle the client’s WM_NAME property
+. Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN`
+. Handle the client’s `WM_NAME` property
. Handle the client’s size hints to display them proportionally
. Handle enter notifications (focus follows mouse)
. Handle button (as in mouse buttons) presses for focus/raise on click
In the following chapters, each of these tasks and their implementation details will be discussed.
+=== Tiling window managers
+
+Traditionally, there are two approaches to managing windows: The most common one nowadays is
+floating, which means the user can freely move/resize the windows. The other approach is called
+tiling, which means that your window manager distributing windows to use as much space as
+possible while not overlapping.
+
+The idea behind tiling is that you should not need to waste your time moving/resizing windows
+while you usually want to get some work done. After all, most users sooner or later tend to
+lay out their windows in a way which corresponds to tiling or stacking mode in i3. Therefore,
+why not let i3 do this for you? Certainly, it’s faster than you could ever do it.
+
+The problem with most tiling window managers is that they are too unflexible. In my opinion, a
+window manager is just another tool, and similar to vim which can edit all kinds of text files
+(like source code, HTML, …) and is not limited to a specific file type, a window manager should
+not limit itself to a certain layout (like dwm, awesome, …) but provide mechanisms for you to
+easily create the layout you need at the moment.
+
+=== 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:
+
+[width="15%",cols="^,^"]
+|========
+| T1 | T2
+|========
+
+When moving terminal 2 to the bottom, the table will be expanded again.
+
+[width="15%",cols="^,^"]
+|========
+| 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 equally. Below you see an example of
+colspan=2 for the first container (which has T1 as window).
+
+[width="15%",cols="^asciidoc"]
+|========
+| T1
+|
+[cols="^,^",frame="none"]
+!========
+! T2 ! T3
+!========
+|========
+
+Furthermore, you can freely resize table cells.
+
== Files
include/data.h::
Contains data definitions used by nearly all files. You really need to read this first.
include/*.h::
-Contains forward definitions for all public functions.
+Contains forward definitions for all public functions, aswell as doxygen-compatible
+comments (so if you want to get a bit more of the big picture, either browse all
+header files or use doxygen if you prefer that).
+
+src/client.c::
+Contains all functions which are specific to a certain client (make it
+fullscreen, see if its class/name matches a pattern, kill it, …).
src/commands.c::
-Parsing commands
+Parsing commands and actually execute them (focussing, moving, …).
src/config.c::
-Parses the configuration file
+Parses the configuration file.
src/debug.c::
-Contains debugging functions to print unhandled X events
+Contains debugging functions to print unhandled X events.
+
+src/floating.c::
+Contains functions for floating mode (mostly resizing/dragging).
src/handlers.c::
-Contains all handlers for all kind of X events
+Contains all handlers for all kind of X events (new window title, new hints,
+unmapping, key presses, button presses, …).
src/layout.c::
-Renders your layout (screens, workspaces, containers)
+Renders your layout (screens, workspaces, containers).
src/mainx.c::
-Initializes the window manager
+Initializes the window manager.
+
+src/manage.c::
+Looks at existing or new windows and decides whether to manage them. If so, it
+reparents the window and inserts it into our data structures.
+
+src/resize.c::
+Contains the functions to resize columns/rows in the table.
+
+src/resize.c::
+Contains the functions to resize columns/rows in the table.
src/table.c::
Manages the most important internal data structure, the design table.
== Data structures
-See include/data.h for documented data structures.
+See include/data.h for documented data structures. The most important ones are explained
+right here.
+
+image:bigpicture.png[The Big Picture]
+
+So, the hierarchy is:
+
+. *Virtual screens* (Screen 0 in this example)
+. *Workspaces* (Workspace 1 in this example)
+. *Table* (There can only be one table per Workspace)
+. *Container* (left and right in this example)
+. *Client* (The two clients in the left container)
=== 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 when using xrandr(1)
+A virtual screen (type `i3Screen`) is generated from the connected screens obtained
+through Xinerama. The difference to the raw Xinerama monitors 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),
+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,
+However, if you configure it using +xrandr \--output VGA \--mode 1024x768 \--right-of LVDS+,
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.
+=== Workspace
+
+A workspace is identified by its number. Basically, you could think of workspaces
+as different desks in your bureau, 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 desktops''.
+
+=== 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).
+
+=== 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 or stack layout). Containers can consume
+multiple table cells by modifying their colspan/rowspan attribute.
+
+=== Client
+
+A client is x11-speak for a window.
+
== List/queue macros
i3 makes heavy use of the list macros defined in BSD operating systems. To ensure
that the operating system on which i3 is compiled has all the awaited features,
-i3 comes with include/queue.h. On BSD systems, you can use man queue(3). On Linux,
+i3 comes with `include/queue.h`. On BSD systems, you can use man `queue(3)`. On Linux,
you have to use google.
-The lists used are SLISTs (single linked lists) and CIRCLEQ (circular queues).
-Usually, only forward traversal is necessary, so an SLIST works fine. However,
-for the windows inside a container, a CIRCLEQ is necessary to go from the currently
+The lists used are `SLIST` (single linked lists) and `CIRCLEQ` (circular queues).
+Usually, only forward traversal is necessary, so an `SLIST` works fine. However,
+for the windows inside a container, a `CIRCLEQ` is necessary to go from the currently
selected window to the window above/below.
== Naming conventions
There is a row of standard variables used in many events. The following names should be
chosen for those:
- * "conn" is the xcb_connection_t
- * "event" is the event of the particular type
- * "container" names a container
- * "client" names a client, for example when using a CIRCLEQ_FOREACH
+ * ``conn'' is the xcb_connection_t
+ * ``event'' is the event of the particular type
+ * ``container'' names a container
+ * ``client'' names a client, for example when using a +CIRCLEQ_FOREACH+
-== Startup (src/mainx.c)
+== Startup (src/mainx.c, main())
* Establish the xcb connection
* Check for XKB extension on the separate X connection
== Manage windows (src/mainx.c, manage_window() and reparent_window())
-manage_window() does some checks to decide whether the window should be managed at all:
+`manage_window()` does some checks to decide whether the window should be managed at all:
* Windows have to be mapped, that is, visible on screen
* The override_redirect must not be set. Windows with override_redirect shall not be
than the original one, is created. The original window is then reparented to the bigger one
(called "frame").
-After reparenting, the window type (_NET_WM_WINDOW_TYPE) is checked to see whether this
-window is a dock (_NET_WM_WINDOW_TYPE_DOCK), like dzen2 for example. Docks are handled
+After reparenting, the window type (`_NET_WM_WINDOW_TYPE`) is checked to see 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, the _NET_WM_STRUT_PARTIAL property is used.
+to be reserved for the window, the `_NET_WM_STRUT_PARTIAL` property is used.
== What happens when an application is started?
i3 does not care for applications. All it notices is when new windows are mapped (see
-src/handlers.c, handle_map_notify_event()). The window is then reparented (see section
+`src/handlers.c`, `handle_map_notify_event()`). The window is then reparented (see section
"Manage windows").
-After reparenting the window, render_layout() is called which renders the internal
+After reparenting the window, `render_layout()` is called which renders the internal
layout table. The window was placed in the currently focused container and
therefore the new window and the old windows (if any) need te be moved/resized
so that the currently active layout (default mode/stacking mode) is rendered
-correctly. To move/resize windows, a window is "configured" in X11-speak.
+correctly. To move/resize windows, a window is ``configured'' in X11-speak.
Some applications, such as MPlayer obivously assume the window manager is stupid
and therefore configure their windows by themselves. This generates an event called
== _NET_WM_STATE
-Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls toggle_fullscreen() for the
+Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls ``toggle_fullscreen()'' for the
specific client which just configures the client to use the whole screen on which it
currently is. Also, it is set as fullscreen_client for the i3Screen.
== Size hints
-== Rendering
+Size hints specify the minimum/maximum size for a given window aswell as its aspect ratio.
+At the moment, as i3 does not have a floating mode yet, only the aspect ratio is parsed.
+This is important for clients like mplayer, who only set the aspect ratio and resize their
+window to be as small as possible (but only with some video outputs, for example in Xv,
+while when using x11, mplayer does the necessary centering for itself).
+
+So, when an aspect ratio was specified, i3 adjusts the height of the window until the
+size maintains the correct aspect ratio. For the code to do this, see src/layout.c,
+function resize_client().
+
+== Rendering (src/layout.c, render_layout() and render_container())
There are two entry points to rendering: render_layout() and render_container(). The
former one renders all virtual screens, the currently active workspace of each virtual
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.
+=== 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.
+
=== Resizing containers
-By clicking and dragging the border of a container, you can resize it freely.
+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.
+
+Currently, only vertical resizing is implemented.
-TODO
+The resizing works similarly to the resizing of floating windows or movement of floating
+windows:
+
+* A new, invisible window with the size of the root window is created (+grabwin+)
+* 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 signalize the user how big the container will be (it creates the impression
+ of dragging the border out of the container).
+* The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer and
+ enter an 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.
+* The new width_factor for each involved column (respectively row) will be calculated.
== User commands / commandmode (src/commands.c)
alternative to lots of shortcuts, because they can be combined. There are a few special
commands, which are the following:
-exec::
-Starts the given command by passing it to /bin/sh.
+exec <command>::
+Starts the given command by passing it to `/bin/sh`.
restart::
-Restarts i3 by executing argv[0] (the path with which you started i3) without forking.
+Restarts i3 by executing `argv[0]` (the path with which you started i3) without forking.
w::
"With". This is used to select a bunch of windows. Currently, only selecting the whole
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.
+
+== Gotchas
+
+* Forgetting to call `xcb_flush(conn);` after sending a request. This usually leads to
+ code which looks like it works fine but which does not work under certain conditions.
+
+== 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 http://git-scm.com/documentation
+
+When you want to send a patch because you fixed a bug or implemented a cool feature (please
+talk to us before working on features to see whether they are maybe already implemented, not
+possible because of some reason or don’t fit into the concept), please use git to create
+a patchfile.
+
+First of all, update your working copy to the latest version of the master branch:
+
+--------
+git pull
+--------
+
+Afterwards, make the necessary changes for your bugfix/feature. Then, review the changes
+using +git diff+ (you might want to enable colors in the diff using +git config diff.color auto+).
+When you are definitely done, use +git commit -a+ to commit all changes you’ve made.
+
+Then, use the following command to generate a patchfile which we can directly apply to
+the branch, preserving your commit message and name:
+
+-----------------------
+git format-patch origin
+-----------------------
+
+Just send us the generated file via mail.
projects / i3 / i3 / blobdiff