3 Michael Stapelberg <michael+i3@stapelberg.de>
6 This document is intended to be the first thing you read before looking and/or
7 touching i3’s source code. It should contain all important information to help
8 you understand why things are like they are. If it does not mention something
9 you find necessary, please do not hesitate to contact me.
13 A window manager is not necessarily needed to run X, but it is usually used in
14 combination with X to facilitate some things. The window manager's job is to
15 take care of the placement of windows, to provide the user with some mechanisms
16 to change the position/size of windows and to communicate with clients to a
17 certain extent (for example handle fullscreen requests of clients such as
20 There are no different contexts in which X11 clients run, so a window manager
21 is just another client, like all other X11 applications. However, it handles
22 some events which normal clients usually don’t handle.
24 In the case of i3, the tasks (and order of them) are the following:
26 . Grab the key bindings (events will be sent upon keypress/keyrelease)
27 . Iterate through all existing windows (if the window manager is not started as the first
28 client of X) and manage them (= reparent them, create window decorations)
29 . When new windows are created, manage them
30 . Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN`
31 . Handle the client’s `WM_NAME` property
32 . Handle the client’s size hints to display them proportionally
33 . Handle the client’s urgency hint
34 . Handle enter notifications (focus follows mouse)
35 . Handle button (as in mouse buttons) presses for focus/raise on click
36 . Handle expose events to re-draw own windows such as decorations
37 . React to the user’s commands: Change focus, Move windows, Switch workspaces,
38 Change the layout mode of a container (default/stacking), Start a new application,
39 Restart the window manager
41 In the following chapters, each of these tasks and their implementation details
44 === Tiling window managers
46 Traditionally, there are two approaches to managing windows: The most common
47 one nowadays is floating, which means the user can freely move/resize the
48 windows. The other approach is called tiling, which means that your window
49 manager distributing windows to use as much space as possible while not
52 The idea behind tiling is that you should not need to waste your time
53 moving/resizing windows while you usually want to get some work done. After
54 all, most users sooner or later tend to lay out their windows in a way which
55 corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this
56 for you? Certainly, it’s faster than you could ever do it.
58 The problem with most tiling window managers is that they are too unflexible.
59 In my opinion, a window manager is just another tool, and similar to vim which
60 can edit all kinds of text files (like source code, HTML, …) and is not limited
61 to a specific file type, a window manager should not limit itself to a certain
62 layout (like dwm, awesome, …) but provide mechanisms for you to easily create
63 the layout you need at the moment.
67 To accomplish flexible layouts, we decided to simply use a table. The table
68 grows and shrinks as you need it. Each cell holds a container which then holds
69 windows (see picture below). You can use different layouts for each container
70 (default layout and stacking layout).
72 So, when you open a terminal and immediately open another one, they reside in
73 the same container, in default layout. The layout table has exactly one column,
74 one row and therefore one cell. When you move one of the terminals to the
75 right, the table needs to grow. It will be expanded to two columns and one row.
76 This enables you to have different layouts for each container. The table then
79 [width="15%",cols="^,^"]
84 When moving terminal 2 to the bottom, the table will be expanded again.
86 [width="15%",cols="^,^"]
92 You can really think of the layout table like a traditional HTML table, if
93 you’ve ever designed one. Especially col- and rowspan work equally. Below you
94 see an example of colspan=2 for the first container (which has T1 as window).
96 [width="15%",cols="^asciidoc"]
100 [cols="^,^",frame="none"]
106 Furthermore, you can freely resize table cells.
111 Contains data definitions used by nearly all files. You really need to read
115 Contains forward definitions for all public functions, aswell as
116 doxygen-compatible comments (so if you want to get a bit more of the big
117 picture, either browse all header files or use doxygen if you prefer that).
120 Contains the lexer for i3’s configuration file, written for +flex(1)+.
123 Contains the parser for i3’s configuration file, written for +bison(1)+.
126 Contains all functions which handle mouse button clicks (right mouse button
127 clicks initiate resizing and thus are relatively complex).
130 Contains all functions which are specific to a certain client (make it
131 fullscreen, see if its class/name matches a pattern, kill it, …).
134 Parsing commands and actually execute them (focussing, moving, …).
137 Parses the configuration file.
140 Contains debugging functions to print unhandled X events.
143 Contains functions for floating mode (mostly resizing/dragging).
146 Contains all handlers for all kind of X events (new window title, new hints,
147 unmapping, key presses, button presses, …).
150 Contains code for the IPC interface.
153 Renders your layout (screens, workspaces, containers).
156 Initializes the window manager.
159 Looks at existing or new windows and decides whether to manage them. If so, it
160 reparents the window and inserts it into our data structures.
163 Contains the functions to resize columns/rows in the table.
166 Contains the functions to resize columns/rows in the table.
169 Manages the most important internal data structure, the design table.
172 Contains useful functions which are not really dependant on anything.
175 Contains all functions related to workspaces (displaying, hiding, renaming…)
178 Contains wrappers to use xcb more easily.
181 (Re-)initializes the available screens and converts them to virtual screens
186 See include/data.h for documented data structures. The most important ones are
187 explained right here.
189 image:bigpicture.png[The Big Picture]
191 So, the hierarchy is:
193 . *Virtual screens* (Screen 0 in this example)
194 . *Workspaces* (Workspace 1 in this example)
195 . *Table* (There can only be one table per Workspace)
196 . *Container* (left and right in this example)
197 . *Client* (The two clients in the left container)
201 A virtual screen (type `i3Screen`) is generated from the connected screens
202 obtained through Xinerama. The difference to the raw Xinerama monitors as seen
203 when using +xrandr(1)+ is that it falls back to the lowest common resolution of
206 For example, if your notebook has 1280x800 and you connect a video projector
207 with 1024x768, set up in clone mode (+xrandr \--output VGA \--mode 1024x768
208 \--same-as LVDS+), i3 will have one virtual screen.
210 However, if you configure it using +xrandr \--output VGA \--mode 1024x768
211 \--right-of LVDS+, i3 will generate two virtual screens. For each virtual
212 screen, a new workspace will be assigned. New workspaces are created on the
213 screen you are currently on.
217 A workspace is identified by its number. Basically, you could think of
218 workspaces as different desks in your bureau, if you like the desktop
219 methaphor. They just contain different sets of windows and are completely
220 separate of each other. Other window managers also call this ``Virtual
225 Each workspace has a table, which is just a two-dimensional dynamic array
226 containing Containers (see below). This table grows and shrinks as you need it
227 (by moving windows to the right you can create a new column in the table, by
228 moving them to the bottom you create a new row).
232 A container is the content of a table’s cell. It holds an arbitrary amount of
233 windows and has a specific layout (default layout or stack layout). Containers
234 can consume multiple table cells by modifying their colspan/rowspan attribute.
238 A client is x11-speak for a window.
242 i3 makes heavy use of the list macros defined in BSD operating systems. To
243 ensure that the operating system on which i3 is compiled has all the expected
244 features, i3 comes with `include/queue.h`. On BSD systems, you can use man
245 `queue(3)`. On Linux, you have to use google (or read the source).
247 The lists used are `SLIST` (single linked lists), `CIRCLEQ` (circular
248 queues) and TAILQ (tail queues). Usually, only forward traversal is necessary,
249 so an `SLIST` works fine. If inserting elements at arbitrary positions or at
250 the end of a list is necessary, a `TAILQ` is used instead. However, for the
251 windows inside a container, a `CIRCLEQ` is necessary to go from the currently
252 selected window to the window above/below.
254 == Naming conventions
256 There is a row of standard variables used in many events. The following names
257 should be chosen for those:
259 * ``conn'' is the xcb_connection_t
260 * ``event'' is the event of the particular type
261 * ``container'' names a container
262 * ``client'' names a client, for example when using a +CIRCLEQ_FOREACH+
264 == Startup (src/mainx.c, main())
266 * Establish the xcb connection
267 * Check for XKB extension on the separate X connection
268 * Check for Xinerama screens
269 * Grab the keycodes for which bindings exist
270 * Manage all existing windows
271 * Enter the event loop
275 === Grabbing the bindings
277 Grabbing the bindings is quite straight-forward. You pass X your combination of
278 modifiers and the keycode you want to grab and whether you want to grab them
279 actively or passively. Most bindings (everything except for bindings using
280 Mode_switch) are grabbed passively, that is, just the window manager gets the
281 event and cannot replay it.
283 We need to grab bindings that use Mode_switch actively because of a bug in X.
284 When the window manager receives the keypress/keyrelease event for an actively
285 grabbed keycode, it has to decide what to do with this event: It can either
286 replay it so that other applications get it or it can prevent other
287 applications from receiving it.
289 So, why do we need to grab keycodes actively? Because X does not set the
290 state-property of keypress/keyrelease events properly. The Mode_switch bit is
291 not set and we need to get it using XkbGetState. This means we cannot pass X
292 our combination of modifiers containing Mode_switch when grabbing the key and
293 therefore need to grab the keycode itself without any modiffiers. This means,
294 if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
295 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
296 will handle the event, if not, it will replay the event.
298 === Handling a keypress
300 As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
303 Then, it looks through all bindings and gets the one which matches the received
306 The bound command is parsed directly in command mode.
308 == Manage windows (src/mainx.c, manage_window() and reparent_window())
310 `manage_window()` does some checks to decide whether the window should be
313 * Windows have to be mapped, that is, visible on screen
314 * The override_redirect must not be set. Windows with override_redirect shall
315 not be managed by a window manager
317 Afterwards, i3 gets the intial geometry and reparents the window (see
318 `reparent_window()`) if it wasn’t already managed.
320 Reparenting means that for each window which is reparented, a new window,
321 slightly larger than the original one, is created. The original window is then
322 reparented to the bigger one (called "frame").
324 After reparenting, the window type (`_NET_WM_WINDOW_TYPE`) is checked to see
325 whether this window is a dock (`_NET_WM_WINDOW_TYPE_DOCK`), like dzen2 for
326 example. Docks are handled differently, they don’t have decorations and are not
327 assigned to a specific container. Instead, they are positioned at the bottom
328 of the screen. To get the height which needsd to be reserved for the window,
329 the `_NET_WM_STRUT_PARTIAL` property is used.
331 Furthermore, the list of assignments (to other workspaces, which may be on
332 other screens) is checked. If the window matches one of the user’s criteria,
333 it may either be put in floating mode or moved to a different workspace. If the
334 target workspace is not visible, the window will not be mapped.
336 == What happens when an application is started?
338 i3 does not care for applications. All it notices is when new windows are
339 mapped (see `src/handlers.c`, `handle_map_request()`). The window is then
340 reparented (see section "Manage windows").
342 After reparenting the window, `render_layout()` is called which renders the
343 internal layout table. The new window has been placed in the currently focused
344 container and therefore the new window and the old windows (if any) need to be
345 moved/resized so that the currently active layout (default mode/stacking mode)
346 is rendered correctly. To move/resize windows, a window is ``configured'' in
349 Some applications, such as MPlayer obivously assume the window manager is
350 stupid and try to configure their windows by themselves. This generates an
351 event called configurerequest. i3 handles these events and tells the window the
352 size it had before the configurerequest (with the exception of not yet mapped
353 windows, which get configured like they want to, and floating windows, which
354 can reconfigure themselves).
358 Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls
359 ``toggle_fullscreen()'' for the specific client which just configures the
360 client to use the whole screen on which it currently is. Also, it is set as
361 fullscreen_client for the i3Screen.
365 When the WM_NAME property of a window changes, its decoration (containing the
366 title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
367 totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
372 Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
373 is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
374 to X. Using an appropriate font (ISO-10646), you can see most special
375 characters (every special character contained in your font).
379 Size hints specify the minimum/maximum size for a given window aswell as its
380 aspect ratio. This is important for clients like mplayer, who only set the
381 aspect ratio and resize their window to be as small as possible (but only with
382 some video outputs, for example in Xv, while when using x11, mplayer does the
383 necessary centering for itself).
385 So, when an aspect ratio was specified, i3 adjusts the height of the window
386 until the size maintains the correct aspect ratio. For the code to do this, see
387 src/layout.c, function resize_client().
389 == Rendering (src/layout.c, render_layout() and render_container())
391 There are several entry points to rendering: `render_layout()`,
392 `render_workspace()` and `render_container()`. The former one calls
393 `render_workspace()` for every screen, which in turn will call
394 `render_container()` for every container inside its layout table. Therefore, if
395 you need to render only a single container, for example because a window was
396 removed, added or changed its title, you should directly call
399 Rendering consists of two steps: In the first one, in `render_workspace()`, each
400 container gets its position (screen offset + offset in the table) and size
401 (container's width times colspan/rowspan). Then, `render_container()` is called,
402 which takes different approaches, depending on the mode the container is in:
406 On the frame (the window which was created around the client’s window for the
407 decorations), a black rectangle is drawn as a background for windows like
408 MPlayer, which do not completely fit into the frame.
412 Each clients gets the container’s width and an equal amount of height.
416 In stack mode, a window containing the decorations of all windows inside the
417 container is placed at the top. The currently focused window is then given the
418 whole remaining space.
422 Tabbed mode is like stack mode, except that the window decorations are drawn
423 in one single line at the top of the container.
425 === Window decorations
427 The window decorations consist of a rectangle in the appropriate color (depends
428 on whether this window is the currently focused one, the last focused one in a
429 not focused container or not focused at all) forming the background.
430 Afterwards, two lighter lines are drawn and the last step is drawing the
431 window’s title (see WM_NAME) onto it.
433 === Fullscreen windows
435 For fullscreen windows, the `rect` (x, y, width, height) is not changed to
436 allow the client to easily go back to its previous position. Instead,
437 fullscreen windows are skipped when rendering.
439 === Resizing containers
441 By clicking and dragging the border of a container, you can resize the whole
442 column (respectively row) which this container is in. This is necessary to keep
443 the table layout working and consistent.
445 The resizing works similarly to the resizing of floating windows or movement of
448 * A new, invisible window with the size of the root window is created
450 * Another window, 2px width and as high as your screen (or vice versa for
451 horizontal resizing) is created. Its background color is the border color and
452 it is only there to signalize the user how big the container will be (it
453 creates the impression of dragging the border out of the container).
454 * The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer
455 and enter an own event loop which will pass all events (expose events) but
456 motion notify events. This function then calls the specified callback
457 (+resize_callback+) which does some boundary checking and moves the helper
458 window. As soon as the mouse button is released, this loop will be
460 * The new width_factor for each involved column (respectively row) will be
463 == User commands / commandmode (src/commands.c)
465 Like in vim, you can control i3 using commands. They are intended to be a
466 powerful alternative to lots of shortcuts, because they can be combined. There
467 are a few special commands, which are the following:
470 Starts the given command by passing it to `/bin/sh`.
473 Restarts i3 by executing `argv[0]` (the path with which you started i3) without
477 "With". This is used to select a bunch of windows. Currently, only selecting
478 the whole container in which the window is in, is supported by specifying "w".
481 Toggle fullscreen, stacking, default mode for the current window/container.
483 The other commands are to be combined with a direction. The directions are h,
484 j, k and l, like in vim (h = left, j = down, k = up, l = right). When you just
485 specify the direction keys, i3 will move the focus in that direction. You can
486 provide "m" or "s" before the direction to move a window respectively or snap.
490 * Forgetting to call `xcb_flush(conn);` after sending a request. This usually
491 leads to code which looks like it works fine but which does not work under
494 == Using git / sending patches
496 For a short introduction into using git, see
497 http://www.spheredev.org/wiki/Git_for_the_lazy or, for more documentation, see
498 http://git-scm.com/documentation
500 When you want to send a patch because you fixed a bug or implemented a cool
501 feature (please talk to us before working on features to see whether they are
502 maybe already implemented, not possible because of some reason or don’t fit
503 into the concept), please use git to create a patchfile.
505 First of all, update your working copy to the latest version of the master
512 Afterwards, make the necessary changes for your bugfix/feature. Then, review
513 the changes using +git diff+ (you might want to enable colors in the diff using
514 +git config diff.color auto+). When you are definitely done, use +git commit
515 -a+ to commit all changes you’ve made.
517 Then, use the following command to generate a patchfile which we can directly
518 apply to the branch, preserving your commit message and name:
520 -----------------------
521 git format-patch origin
522 -----------------------
524 Just send us the generated file via mail.