3 Michael Stapelberg <michael+i3@stapelberg.de>
6 This document is intended to be the first thing you read before looking and/or touching
7 i3’s source code. It should contain all important information to help you understand
8 why things are like they are. If it does not mention something you find necessary, please
9 do not hesitate to contact me.
13 A window manager is not necessarily needed to run X, but it is usually used in combination
14 to facilitate some things. The window manager's job is to take care of the placement of
15 windows, to provide the user some mechanisms to change the position/size of windows and
16 to communicate with clients to a certain extent (for example handle fullscreen requests
17 of clients such as MPlayer).
19 There are no different contexts in which X11 clients run, so a window manager is just another
20 client, like all other X11 applications. However, it handles some events which normal clients
23 In the case of i3, the tasks (and order of them) are the following:
25 . Grab the key bindings (events will be sent upon keypress/keyrelease)
26 . Iterate through all existing windows (if the window manager is not started as the first
27 client of X) and manage them (= reparent them, create window decorations)
28 . When new windows are created, manage them
29 . Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN`
30 . Handle the client’s `WM_NAME` property
31 . Handle the client’s size hints to display them proportionally
32 . Handle enter notifications (focus follows mouse)
33 . Handle button (as in mouse buttons) presses for focus/raise on click
34 . Handle expose events to re-draw own windows such as decorations
35 . React to the user’s commands: Change focus, Move windows, Switch workspaces,
36 Change the layout mode of a container (default/stacking), Start a new application,
37 Restart the window manager
39 In the following chapters, each of these tasks and their implementation details will be discussed.
41 === Tiling window managers
43 Traditionally, there are two approaches to managing windows: The most common one nowadays is
44 floating, which means the user can freely move/resize the windows. The other approach is called
45 tiling, which means that your window manager distributing windows to use as much space as
46 possible while not overlapping.
48 The idea behind tiling is that you should not need to waste your time moving/resizing windows
49 while you usually want to get some work done. After all, most users sooner or later tend to
50 lay out their windows in a way which corresponds to tiling or stacking mode in i3. Therefore,
51 why not let i3 do this for you? Certainly, it’s faster than you could ever do it.
53 The problem with most tiling window managers is that they are too unflexible. In my opinion, a
54 window manager is just another tool, and similar to vim which can edit all kinds of text files
55 (like source code, HTML, …) and is not limited to a specific file type, a window manager should
56 not limit itself to a certain layout (like dwm, awesome, …) but provide mechanisms for you to
57 easily create the layout you need at the moment.
61 To accomplish flexible layouts, we decided to simply use a table. The table grows and shrinks
62 as you need it. Each cell holds a container which then holds windows (see picture below). You
63 can use different layouts for each container (default layout and stacking layout).
65 So, when you open a terminal and immediately open another one, they reside in the same container,
66 in default layout. The layout table has exactly one column, one row and therefore one cell.
67 When you move one of the terminals to the right, the table needs to grow. It will be expanded
68 to two columns and one row. This enables you to have different layouts for each container.
69 The table then looks like this:
71 [width="15%",cols="^,^"]
76 When moving terminal 2 to the bottom, the table will be expanded again.
78 [width="15%",cols="^,^"]
84 You can really think of the layout table like a traditional HTML table, if you’ve ever
85 designed one. Especially col- and rowspan work equally. Below you see an example of
86 colspan=2 for the first container (which has T1 as window).
88 [width="15%",cols="^asciidoc"]
92 [cols="^,^",frame="none"]
98 Furthermore, you can freely resize table cells.
103 Contains data definitions used by nearly all files. You really need to read this first.
106 Contains forward definitions for all public functions, aswell as doxygen-compatible
107 comments (so if you want to get a bit more of the big picture, either browse all
108 header files or use doxygen if you prefer that).
111 Contains all functions which are specific to a certain client (make it
112 fullscreen, see if its class/name matches a pattern, kill it, …).
115 Parsing commands and actually execute them (focussing, moving, …).
118 Parses the configuration file.
121 Contains debugging functions to print unhandled X events.
124 Contains functions for floating mode (mostly resizing/dragging).
127 Contains all handlers for all kind of X events (new window title, new hints,
128 unmapping, key presses, button presses, …).
131 Renders your layout (screens, workspaces, containers).
134 Initializes the window manager.
137 Looks at existing or new windows and decides whether to manage them. If so, it
138 reparents the window and inserts it into our data structures.
141 Contains the functions to resize columns/rows in the table.
144 Contains the functions to resize columns/rows in the table.
147 Manages the most important internal data structure, the design table.
150 Contains useful functions which are not really dependant on anything.
153 Contains wrappers to use xcb more easily.
156 (Re-)initializes the available screens and converts them to virtual screens (see below).
160 See include/data.h for documented data structures. The most important ones are explained
163 image:bigpicture.png[The Big Picture]
165 So, the hierarchy is:
167 . *Virtual screens* (Screen 0 in this example)
168 . *Workspaces* (Workspace 1 in this example)
169 . *Table* (There can only be one table per Workspace)
170 . *Container* (left and right in this example)
171 . *Client* (The two clients in the left container)
175 A virtual screen (type `i3Screen`) is generated from the connected screens obtained
176 through Xinerama. The difference to the raw Xinerama monitors as seen when using +xrandr(1)+
177 is that it falls back to the lowest common resolution of the logical screens.
179 For example, if your notebook has 1280x800 and you connect a video projector with
180 1024x768, set up in clone mode (+xrandr \--output VGA \--mode 1024x768 \--same-as LVDS+),
181 i3 will have one virtual screen.
183 However, if you configure it using +xrandr \--output VGA \--mode 1024x768 \--right-of LVDS+,
184 i3 will generate two virtual screens. For each virtual screen, a new workspace will be
185 assigned. New workspaces are created on the screen you are currently on.
189 A workspace is identified by its number. Basically, you could think of workspaces
190 as different desks in your bureau, if you like the desktop methaphor. They just contain
191 different sets of windows and are completely separate of each other. Other window
192 managers also call this ``Virtual desktops''.
196 Each workspace has a table, which is just a two-dimensional dynamic array containing
197 Containers (see below). This table grows and shrinks as you need it (by moving windows
198 to the right you can create a new column in the table, by moving them to the bottom
199 you create a new row).
203 A container is the content of a table’s cell. It holds an arbitrary amount of windows
204 and has a specific layout (default layout or stack layout). Containers can consume
205 multiple table cells by modifying their colspan/rowspan attribute.
209 A client is x11-speak for a window.
213 i3 makes heavy use of the list macros defined in BSD operating systems. To ensure
214 that the operating system on which i3 is compiled has all the awaited features,
215 i3 comes with `include/queue.h`. On BSD systems, you can use man `queue(3)`. On Linux,
216 you have to use google.
218 The lists used are `SLIST` (single linked lists) and `CIRCLEQ` (circular queues).
219 Usually, only forward traversal is necessary, so an `SLIST` works fine. However,
220 for the windows inside a container, a `CIRCLEQ` is necessary to go from the currently
221 selected window to the window above/below.
223 == Naming conventions
225 There is a row of standard variables used in many events. The following names should be
228 * ``conn'' is the xcb_connection_t
229 * ``event'' is the event of the particular type
230 * ``container'' names a container
231 * ``client'' names a client, for example when using a +CIRCLEQ_FOREACH+
233 == Startup (src/mainx.c, main())
235 * Establish the xcb connection
236 * Check for XKB extension on the separate X connection
237 * Check for Xinerama screens
238 * Grab the keycodes for which bindings exist
239 * Manage all existing windows
240 * Enter the event loop
244 === Grabbing the bindings
246 Grabbing the bindings is quite straight-forward. You pass X your combination of modifiers and
247 the keycode you want to grab and whether you want to grab them actively or passively. Most
248 bindings (everything except for bindings using Mode_switch) are grabbed passively, that is,
249 just the window manager gets the event and cannot replay it.
251 We need to grab bindings that use Mode_switch actively because of a bug in X. When the window
252 manager receives the keypress/keyrelease event for an actively grabbed keycode, it has to decide
253 what to do with this event: It can either replay it so that other applications get it or it
254 can prevent other applications from receiving it.
256 So, why do we need to grab keycodes actively? Because X does not set the state-property of
257 keypress/keyrelease events properly. The Mode_switch bit is not set and we need to get it
258 using XkbGetState. This means we cannot pass X our combination of modifiers containing Mode_switch
259 when grabbing the key and therefore need to grab the keycode itself without any modiffiers.
260 This means, if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
261 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it will handle
262 the event, if not, it will replay the event.
264 === Handling a keypress
266 As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets the correct state.
268 Then, it looks through all bindings and gets the one which matches the received event.
270 The bound command is parsed directly in command mode.
272 == Manage windows (src/mainx.c, manage_window() and reparent_window())
274 `manage_window()` does some checks to decide whether the window should be managed at all:
276 * Windows have to be mapped, that is, visible on screen
277 * The override_redirect must not be set. Windows with override_redirect shall not be
278 managed by a window manager
280 Afterwards, i3 gets the intial geometry and reparents the window if it wasn’t already
283 Reparenting means that for each window which is reparented, a new window, slightly larger
284 than the original one, is created. The original window is then reparented to the bigger one
287 After reparenting, the window type (`_NET_WM_WINDOW_TYPE`) is checked to see whether this
288 window is a dock (`_NET_WM_WINDOW_TYPE_DOCK`), like dzen2 for example. Docks are handled
289 differently, they don’t have decorations and are not assigned to a specific container.
290 Instead, they are positioned at the bottom of the screen. To get the height which needsd
291 to be reserved for the window, the `_NET_WM_STRUT_PARTIAL` property is used.
293 == What happens when an application is started?
295 i3 does not care for applications. All it notices is when new windows are mapped (see
296 `src/handlers.c`, `handle_map_notify_event()`). The window is then reparented (see section
299 After reparenting the window, `render_layout()` is called which renders the internal
300 layout table. The window was placed in the currently focused container and
301 therefore the new window and the old windows (if any) need te be moved/resized
302 so that the currently active layout (default mode/stacking mode) is rendered
303 correctly. To move/resize windows, a window is ``configured'' in X11-speak.
305 Some applications, such as MPlayer obivously assume the window manager is stupid
306 and therefore configure their windows by themselves. This generates an event called
307 configurenotify. i3 handles these events and pushes the window back to its position/size.
311 Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls ``toggle_fullscreen()'' for the
312 specific client which just configures the client to use the whole screen on which it
313 currently is. Also, it is set as fullscreen_client for the i3Screen.
317 When the WM_NAME property of a window changes, its decoration (containing the title)
322 Size hints specify the minimum/maximum size for a given window aswell as its aspect ratio.
323 At the moment, as i3 does not have a floating mode yet, only the aspect ratio is parsed.
324 This is important for clients like mplayer, who only set the aspect ratio and resize their
325 window to be as small as possible (but only with some video outputs, for example in Xv,
326 while when using x11, mplayer does the necessary centering for itself).
328 So, when an aspect ratio was specified, i3 adjusts the height of the window until the
329 size maintains the correct aspect ratio. For the code to do this, see src/layout.c,
330 function resize_client().
332 == Rendering (src/layout.c, render_layout() and render_container())
334 There are two entry points to rendering: render_layout() and render_container(). The
335 former one renders all virtual screens, the currently active workspace of each virtual
336 screen and all containers (inside the table cells) of these workspaces using
337 render_container(). Therefore, if you need to render only a single container, for
338 example because a window was removed, added or changed its title, you should directly
339 call render_container().
341 Rendering consists of two steps: In the first one, in render_layout(), each container
342 gets its position (screen offset + offset in the table) and size (container's width
343 times colspan/rowspan). Then, render_container() is called:
345 render_container() then takes different approaches, depending on the mode the container
350 On the frame (the window which was created around the client’s window for the decorations),
351 a black rectangle is drawn as a background for windows like MPlayer, which don’t completely
356 Each clients gets the container’s width and an equal amount of height.
360 In stack mode, a window containing the decorations of all windows inside the container
361 is placed at the top. The currently focused window is then given the whole remaining
364 === Window decorations
366 The window decorations consist of a rectangle in the appropriate color (depends on whether
367 this window is the currently focused one or the last focused one in a not focused container
368 or not focused at all) forming the background. Afterwards, two lighter lines are drawn
369 and the last step is drawing the window’s title (see WM_NAME) onto it.
371 === Fullscreen windows
373 For fullscreen windows, the `rect` (x, y, width, height) is not changed to allow the client
374 to easily go back to its previous position. Instead, fullscreen windows are skipped
377 === Resizing containers
379 By clicking and dragging the border of a container, you can resize the whole column
380 (respectively row) which this container is in. This is necessary to keep the table
381 layout working and consistent.
383 Currently, only vertical resizing is implemented.
385 The resizing works similarly to the resizing of floating windows or movement of floating
388 * A new, invisible window with the size of the root window is created (+grabwin+)
389 * Another window, 2px width and as high as your screen (or vice versa for horizontal
390 resizing) is created. Its background color is the border color and it is only
391 there to signalize the user how big the container will be (it creates the impression
392 of dragging the border out of the container).
393 * The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer and
394 enter an own event loop which will pass all events (expose events) but motion notify
395 events. This function then calls the specified callback (+resize_callback+) which
396 does some boundary checking and moves the helper window. As soon as the mouse
397 button is released, this loop will be terminated.
398 * The new width_factor for each involved column (respectively row) will be calculated.
400 == User commands / commandmode (src/commands.c)
402 Like in vim, you can control i3 using commands. They are intended to be a powerful
403 alternative to lots of shortcuts, because they can be combined. There are a few special
404 commands, which are the following:
407 Starts the given command by passing it to `/bin/sh`.
410 Restarts i3 by executing `argv[0]` (the path with which you started i3) without forking.
413 "With". This is used to select a bunch of windows. Currently, only selecting the whole
414 container in which the window is in, is supported by specifying "w".
417 Toggle fullscreen, stacking, default mode for the current window/container.
419 The other commands are to be combined with a direction. The directions are h, j, k and l,
420 like in vim (h = left, j = down, k = up, l = right). When you just specify the direction
421 keys, i3 will move the focus in that direction. You can provide "m" or "s" before the
422 direction to move a window respectively or snap.
426 * Forgetting to call `xcb_flush(conn);` after sending a request. This usually leads to
427 code which looks like it works fine but which does not work under certain conditions.
429 == Using git / sending patches
431 For a short introduction into using git, see http://www.spheredev.org/wiki/Git_for_the_lazy
432 or, for more documentation, see http://git-scm.com/documentation
434 When you want to send a patch because you fixed a bug or implemented a cool feature (please
435 talk to us before working on features to see whether they are maybe already implemented, not
436 possible because of some reason or don’t fit into the concept), please use git to create
439 First of all, update your working copy to the latest version of the master branch:
445 Afterwards, make the necessary changes for your bugfix/feature. Then, review the changes
446 using +git diff+ (you might want to enable colors in the diff using +git config diff.color auto+).
447 When you are definitely done, use +git commit -a+ to commit all changes you’ve made.
449 Then, use the following command to generate a patchfile which we can directly apply to
450 the branch, preserving your commit message and name:
452 -----------------------
453 git format-patch origin
454 -----------------------
456 Just send us the generated file via mail.