Hacking i3: How To
==================
Michael Stapelberg <michael+i3@stapelberg.de>
-February 2010
+July 2011
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 why things are like they are. If it does not mention something
you find necessary, please do not hesitate to contact me.
-PLEASE BEWARE THAT THIS DOCUMENT IS ONLY PARTIALLY UPDATED FOR -tree YET!
-
== Window Managers
A window manager is not necessarily needed to run X, but it is usually used in
=== The layout table
+*********************************************************************************
+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* :).
+*********************************************************************************
+
+/////////////////////////////////////////////////////////////////////////////////
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
|========
Furthermore, you can freely resize table cells.
+/////////////////////////////////////////////////////////////////////////////////
== Files
== Data structures
+*********************************************************************************
+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* :).
+*********************************************************************************
+
+/////////////////////////////////////////////////////////////////////////////////
+
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:
+. *X11 root window*, the root container
. *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)
+. *Content container* (there are also containers for dock windows)
+. *Workspaces* (Workspace 1 in this example, with horizontal orientation)
+. *Split container* (vertically split)
+. *X11 window containers*
+
+The data type is +Con+, in all cases.
=== Virtual screens
=== 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
=== The layout table
+*********************************************************************************
+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* :).
+*********************************************************************************
+
+/////////////////////////////////////////////////////////////////////////////////
+
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
+*********************************************************************************
+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* :).
+*********************************************************************************
+
+/////////////////////////////////////////////////////////////////////////////////
+
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.
+/////////////////////////////////////////////////////////////////////////////////
+
=== Client
A client is x11-speak for a window.
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,
+The lists used are +SLIST+ (single linked lists), +CIRCLEQ+ (circular
+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
+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
selected window to the window above/below.
== Naming conventions
* ``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+
+ * ``con'' names a container
+ * ``current'' is a loop variable when using +TAILQ_FOREACH+ etc.
== Startup (src/mainx.c, main())
* Establish the xcb connection
- * Check for XKB extension on the separate X connection
- * Check for RandR screens
+ * Check for XKB extension on the separate X connection, load Xcursor
+ * Check for RandR screens (with a fall-back to Xinerama)
* Grab the keycodes for which bindings exist
* Manage all existing windows
* Enter the event loop
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+.
-== Manage windows (src/mainx.c, manage_window() and reparent_window())
+== 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:
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
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)
== Rendering (src/layout.c, render_layout() and render_container())
+*********************************************************************************
+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* :).
+*********************************************************************************
+
+/////////////////////////////////////////////////////////////////////////////////
+
+
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
* The new width_factor for each involved column (respectively row) will be
calculated.
-== User commands / commandmode (src/commands.c)
+/////////////////////////////////////////////////////////////////////////////////
+
+== 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* :).
+*********************************************************************************
+
+/////////////////////////////////////////////////////////////////////////////////
+
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
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.
+/////////////////////////////////////////////////////////////////////////////////
+
== Moving containers
The movement code is pretty delicate. You need to consider all cases before
projects / i3 / i3 / blobdiff