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.
11 PLEASE BEWARE THAT THIS DOCUMENT IS ONLY PARTIALLY UPDATED FOR -tree YET!
15 A window manager is not necessarily needed to run X, but it is usually used in
16 combination with X to facilitate some things. The window manager's job is to
17 take care of the placement of windows, to provide the user with some mechanisms
18 to change the position/size of windows and to communicate with clients to a
19 certain extent (for example handle fullscreen requests of clients such as
22 There are no different contexts in which X11 clients run, so a window manager
23 is just another client, like all other X11 applications. However, it handles
24 some events which normal clients usually don’t handle.
26 In the case of i3, the tasks (and order of them) are the following:
28 . Grab the key bindings (events will be sent upon keypress/keyrelease)
29 . Iterate through all existing windows (if the window manager is not started as
30 the first client of X) and manage them (reparent them, create window
32 . When new windows are created, manage them
33 . Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN`
34 . Handle the client’s `WM_NAME` property
35 . Handle the client’s size hints to display them proportionally
36 . Handle the client’s urgency hint
37 . Handle enter notifications (focus follows mouse)
38 . Handle button (as in mouse buttons) presses for focus/raise on click
39 . Handle expose events to re-draw own windows such as decorations
40 . React to the user’s commands: Change focus, Move windows, Switch workspaces,
41 Change the layout mode of a container (default/stacking/tabbed), start a new
42 application, restart the window manager
44 In the following chapters, each of these tasks and their implementation details
47 === Tiling window managers
49 Traditionally, there are two approaches to managing windows: The most common
50 one nowadays is floating, which means the user can freely move/resize the
51 windows. The other approach is called tiling, which means that your window
52 manager distributes windows to use as much space as possible while not
53 overlapping each other.
55 The idea behind tiling is that you should not need to waste your time
56 moving/resizing windows while you usually want to get some work done. After
57 all, most users sooner or later tend to lay out their windows in a way which
58 corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this
59 for you? Certainly, it’s faster than you could ever do it.
61 The problem with most tiling window managers is that they are too unflexible.
62 In my opinion, a window manager is just another tool, and similar to vim which
63 can edit all kinds of text files (like source code, HTML, …) and is not limited
64 to a specific file type, a window manager should not limit itself to a certain
65 layout (like dwm, awesome, …) but provide mechanisms for you to easily create
66 the layout you need at the moment.
70 To accomplish flexible layouts, we decided to simply use a table. The table
71 grows and shrinks as you need it. Each cell holds a container which then holds
72 windows (see picture below). You can use different layouts for each container
73 (default layout and stacking layout).
75 So, when you open a terminal and immediately open another one, they reside in
76 the same container, in default layout. The layout table has exactly one column,
77 one row and therefore one cell. When you move one of the terminals to the
78 right, the table needs to grow. It will be expanded to two columns and one row.
79 This enables you to have different layouts for each container. The table then
82 [width="15%",cols="^,^"]
87 When moving terminal 2 to the bottom, the table will be expanded again.
89 [width="15%",cols="^,^"]
95 You can really think of the layout table like a traditional HTML table, if
96 you’ve ever designed one. Especially col- and rowspan work similarly. Below,
97 you see an example of colspan=2 for the first container (which has T1 as
100 [width="15%",cols="^asciidoc"]
104 [cols="^,^",frame="none"]
110 Furthermore, you can freely resize table cells.
114 include/atoms.xmacro::
115 A file containing all X11 atoms which i3 uses. This file will be included
116 various times (for defining, requesting and receiving the atoms), each time
117 with a different definition of xmacro().
120 Contains data definitions used by nearly all files. You really need to read
124 Contains forward definitions for all public functions, as well as
125 doxygen-compatible comments (so if you want to get a bit more of the big
126 picture, either browse all header files or use doxygen if you prefer that).
129 Contains the lexer for i3’s configuration file, written for +flex(1)+.
132 Contains the parser for i3’s configuration file, written for +bison(1)+.
135 Contains all functions which handle mouse button clicks (right mouse button
136 clicks initiate resizing and thus are relatively complex).
139 Contains the lexer for i3 commands, written for +flex(1)+.
142 Contains the parser for i3 commands, written for +bison(1)+.
145 Contains all functions which deal with containers directly (creating
146 containers, searching containers, getting specific properties from containers,
150 Contains all functions handling the configuration file (calling the parser
151 (src/cfgparse.y) with the correct path, switching key bindings mode).
154 Contains debugging functions to print unhandled X events.
157 iFunctions to get/set certain EWMH properties easily.
160 Contains functions for floating mode (mostly resizing/dragging).
163 Contains all handlers for all kinds of X events (new window title, new hints,
164 unmapping, key presses, button presses, …).
167 Contains code for the IPC interface.
170 Contains code for loading layouts from JSON files.
173 Handles the setting of loglevels, contains the logging functions.
176 Initializes the window manager.
179 Looks at existing or new windows and decides whether to manage them. If so, it
180 reparents the window and inserts it into our data structures.
183 A "match" is a data structure which acts like a mask or expression to match
184 certain windows or not. For example, when using commands, you can specify a
185 command like this: [title="*Firefox*"] kill. The title member of the match
186 data structure will then be filled and i3 will check each window using
187 match_matches_window() to find the windows affected by this command.
190 Contains code to move a container in a specific direction.
193 Functions to handle CT_OUTPUT cons.
196 The RandR API is used to get (and re-query) the configured outputs (monitors,
200 Renders the tree data structure by assigning coordinates to every node. These
201 values will later be pushed to X11 in +src/x.c+.
204 Contains the functions to resize containers.
207 Handles +SIGSEGV+, +SIGABRT+ and +SIGFPE+ by showing a dialog that i3 crashed.
208 You can chose to let it dump core, to restart it in-place or to restart it
209 in-place but forget about the layout.
212 Contains functions which open or close containers in the tree, change focus or
213 cleanup ("flatten") the tree. See also +src/move.c+ for another similar
214 function, which was moved into its own file because it is so long.
217 Contains useful functions which are not really dependant on anything.
220 Handlers to update X11 window properties like +WM_CLASS+, +_NET_WM_NAME+,
221 +CLIENT_LEADER+, etc.
224 Contains all functions related to workspaces (displaying, hiding, renaming…)
227 Transfers our in-memory tree (see +src/render.c+) to X11.
230 Contains wrappers to use xcb more easily.
233 XCursor functions (for cursor themes).
236 Legacy support for Xinerama. See +src/randr.c+ for the preferred API.
240 See include/data.h for documented data structures. The most important ones are
241 explained right here.
243 image:bigpicture.png[The Big Picture]
245 So, the hierarchy is:
247 . *X11 root window*, the root container
248 . *Virtual screens* (Screen 0 in this example)
249 . *Content container* (there are also containers for dock windows)
250 . *Workspaces* (Workspace 1 in this example, with horizontal orientation)
251 . *Split container* (vertically split)
252 . *X11 window containers*
254 The data type is +Con+, in all cases.
258 A virtual screen (type `i3Screen`) is generated from the connected outputs
259 obtained through RandR. The difference to the raw RandR outputs as seen
260 when using +xrandr(1)+ is that it falls back to the lowest common resolution of
261 the actual enabled outputs.
263 For example, if your notebook has a screen resolution of 1280x800 px and you
264 connect a video projector with a resolution of 1024x768 px, set it up in clone
265 mode (+xrandr \--output VGA1 \--mode 1024x768 \--same-as LVDS1+), i3 will have
268 However, if you configure it using +xrandr \--output VGA1 \--mode 1024x768
269 \--right-of LVDS1+, i3 will generate two virtual screens. For each virtual
270 screen, a new workspace will be assigned. New workspaces are created on the
271 screen you are currently on.
275 A workspace is identified by its name. Basically, you could think of
276 workspaces as different desks in your office, if you like the desktop
277 methaphor. They just contain different sets of windows and are completely
278 separate of each other. Other window managers also call this ``Virtual
283 Each workspace has a table, which is just a two-dimensional dynamic array
284 containing Containers (see below). This table grows and shrinks as you need it
285 (by moving windows to the right you can create a new column in the table, by
286 moving them to the bottom you create a new row).
290 A container is the content of a table’s cell. It holds an arbitrary amount of
291 windows and has a specific layout (default layout, stack layout or tabbed
292 layout). Containers can consume multiple table cells by modifying their
293 colspan/rowspan attribute.
297 A client is x11-speak for a window.
301 i3 makes heavy use of the list macros defined in BSD operating systems. To
302 ensure that the operating system on which i3 is compiled has all the expected
303 features, i3 comes with `include/queue.h`. On BSD systems, you can use man
304 `queue(3)`. On Linux, you have to use google (or read the source).
306 The lists used are +SLIST+ (single linked lists), +CIRCLEQ+ (circular
307 queues) and +TAILQ+ (tail queues). Usually, only forward traversal is necessary,
308 so an `SLIST` works fine. If inserting elements at arbitrary positions or at
309 the end of a list is necessary, a +TAILQ+ is used instead. However, for the
310 windows inside a container, a +CIRCLEQ+ is necessary to go from the currently
311 selected window to the window above/below.
313 == Naming conventions
315 There is a row of standard variables used in many events. The following names
316 should be chosen for those:
318 * ``conn'' is the xcb_connection_t
319 * ``event'' is the event of the particular type
320 * ``con'' names a container
321 * ``current'' is a loop variable when using +TAILQ_FOREACH+ etc.
323 == Startup (src/mainx.c, main())
325 * Establish the xcb connection
326 * Check for XKB extension on the separate X connection, load Xcursor
327 * Check for RandR screens (with a fall-back to Xinerama)
328 * Grab the keycodes for which bindings exist
329 * Manage all existing windows
330 * Enter the event loop
334 === Grabbing the bindings
336 Grabbing the bindings is quite straight-forward. You pass X your combination of
337 modifiers and the keycode you want to grab and whether you want to grab them
338 actively or passively. Most bindings (everything except for bindings using
339 Mode_switch) are grabbed passively, that is, just the window manager gets the
340 event and cannot replay it.
342 We need to grab bindings that use Mode_switch actively because of a bug in X.
343 When the window manager receives the keypress/keyrelease event for an actively
344 grabbed keycode, it has to decide what to do with this event: It can either
345 replay it so that other applications get it or it can prevent other
346 applications from receiving it.
348 So, why do we need to grab keycodes actively? Because X does not set the
349 state-property of keypress/keyrelease events properly. The Mode_switch bit is
350 not set and we need to get it using XkbGetState. This means we cannot pass X
351 our combination of modifiers containing Mode_switch when grabbing the key and
352 therefore need to grab the keycode itself without any modifiers. This means,
353 if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
354 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
355 will handle the event, if not, it will replay the event.
357 === Handling a keypress
359 As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
362 Then, it looks through all bindings and gets the one which matches the received
365 The bound command is parsed by the cmdparse lexer/parser, see +parse_cmd+ in
368 == Manage windows (src/main.c, manage_window() and reparent_window())
370 `manage_window()` does some checks to decide whether the window should be
373 * Windows have to be mapped, that is, visible on screen
374 * The override_redirect must not be set. Windows with override_redirect shall
375 not be managed by a window manager
377 Afterwards, i3 gets the intial geometry and reparents the window (see
378 `reparent_window()`) if it wasn’t already managed.
380 Reparenting means that for each window which is reparented, a new window,
381 slightly larger than the original one, is created. The original window is then
382 reparented to the bigger one (called "frame").
384 After reparenting, the window type (`_NET_WM_WINDOW_TYPE`) is checked to see
385 whether this window is a dock (`_NET_WM_WINDOW_TYPE_DOCK`), like dzen2 for
386 example. Docks are handled differently, they don’t have decorations and are not
387 assigned to a specific container. Instead, they are positioned at the bottom
388 of the screen. To get the height which needs to be reserved for the window,
389 the `_NET_WM_STRUT_PARTIAL` property is used.
391 Furthermore, the list of assignments (to other workspaces, which may be on
392 other screens) is checked. If the window matches one of the user’s criteria,
393 it may either be put in floating mode or moved to a different workspace. If the
394 target workspace is not visible, the window will not be mapped.
396 == What happens when an application is started?
398 i3 does not care for applications. All it notices is when new windows are
399 mapped (see `src/handlers.c`, `handle_map_request()`). The window is then
400 reparented (see section "Manage windows").
402 After reparenting the window, `render_layout()` is called which renders the
403 internal layout table. The new window has been placed in the currently focused
404 container and therefore the new window and the old windows (if any) need to be
405 moved/resized so that the currently active layout (default/stacking/tabbed mode)
406 is rendered correctly. To move/resize windows, a window is ``configured'' in
409 Some applications, such as MPlayer obviously assume the window manager is
410 stupid and try to configure their windows by themselves. This generates an
411 event called configurerequest. i3 handles these events and tells the window the
412 size it had before the configurerequest (with the exception of not yet mapped
413 windows, which get configured like they want to, and floating windows, which
414 can reconfigure themselves).
418 Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls
419 ``toggle_fullscreen()'' for the specific client which just configures the
420 client to use the whole screen on which it currently is. Also, it is set as
421 fullscreen_client for the i3Screen.
425 When the WM_NAME property of a window changes, its decoration (containing the
426 title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
427 totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
432 Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
433 is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
434 to X. Using an appropriate font (ISO-10646), you can see most special
435 characters (every special character contained in your font).
439 Size hints specify the minimum/maximum size for a given window as well as its
440 aspect ratio. This is important for clients like mplayer, who only set the
441 aspect ratio and resize their window to be as small as possible (but only with
442 some video outputs, for example in Xv, while when using x11, mplayer does the
443 necessary centering for itself).
445 So, when an aspect ratio was specified, i3 adjusts the height of the window
446 until the size maintains the correct aspect ratio. For the code to do this, see
447 src/layout.c, function resize_client().
449 == Rendering (src/layout.c, render_layout() and render_container())
451 There are several entry points to rendering: `render_layout()`,
452 `render_workspace()` and `render_container()`. The former one calls
453 `render_workspace()` for every screen, which in turn will call
454 `render_container()` for every container inside its layout table. Therefore, if
455 you need to render only a single container, for example because a window was
456 removed, added or changed its title, you should directly call
459 Rendering consists of two steps: In the first one, in `render_workspace()`, each
460 container gets its position (screen offset + offset in the table) and size
461 (container's width times colspan/rowspan). Then, `render_container()` is called,
462 which takes different approaches, depending on the mode the container is in:
466 On the frame (the window which was created around the client’s window for the
467 decorations), a black rectangle is drawn as a background for windows like
468 MPlayer, which do not completely fit into the frame.
472 Each clients gets the container’s width and an equal amount of height.
476 In stack mode, a window containing the decorations of all windows inside the
477 container is placed at the top. The currently focused window is then given the
478 whole remaining space.
482 Tabbed mode is like stack mode, except that the window decorations are drawn
483 in one single line at the top of the container.
485 === Window decorations
487 The window decorations consist of a rectangle in the appropriate color (depends
488 on whether this window is the currently focused one, the last focused one in a
489 not focused container or not focused at all) forming the background.
490 Afterwards, two lighter lines are drawn and the last step is drawing the
491 window’s title (see WM_NAME) onto it.
493 === Fullscreen windows
495 For fullscreen windows, the `rect` (x, y, width, height) is not changed to
496 allow the client to easily go back to its previous position. Instead,
497 fullscreen windows are skipped when rendering.
499 === Resizing containers
501 By clicking and dragging the border of a container, you can resize the whole
502 column (respectively row) which this container is in. This is necessary to keep
503 the table layout working and consistent.
505 The resizing works similarly to the resizing of floating windows or movement of
508 * A new, invisible window with the size of the root window is created
510 * Another window, 2px width and as high as your screen (or vice versa for
511 horizontal resizing) is created. Its background color is the border color and
512 it is only there to inform the user how big the container will be (it
513 creates the impression of dragging the border out of the container).
514 * The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer
515 and enter its own event loop which will pass all events (expose events) but
516 motion notify events. This function then calls the specified callback
517 (+resize_callback+) which does some boundary checking and moves the helper
518 window. As soon as the mouse button is released, this loop will be
520 * The new width_factor for each involved column (respectively row) will be
523 == User commands / commandmode (src/commands.c)
525 Like in vim, you can control i3 using commands. They are intended to be a
526 powerful alternative to lots of shortcuts, because they can be combined. There
527 are a few special commands, which are the following:
530 Starts the given command by passing it to `/bin/sh`.
533 Restarts i3 by executing `argv[0]` (the path with which you started i3) without
537 "With". This is used to select a bunch of windows. Currently, only selecting
538 the whole container in which the window is in, is supported by specifying "w".
541 Toggle fullscreen, stacking, default mode for the current window/container.
543 The other commands are to be combined with a direction. The directions are h,
544 j, k and l, like in vim (h = left, j = down, k = up, l = right). When you just
545 specify the direction keys, i3 will move the focus in that direction. You can
546 provide "m" or "s" before the direction to move a window respectively or snap.
550 The movement code is pretty delicate. You need to consider all cases before
551 making any changes or before being able to fully understand how it works.
553 === Case 1: Moving inside the same container
555 The reference layout for this case is a single workspace in horizontal
556 orientation with two containers on it. Focus is on the left container (1).
559 [width="15%",cols="^,^"]
564 When moving the left window to the right (command +move right+), tree_move will
565 look for a container with horizontal orientation and finds the parent of the
566 left container, that is, the workspace. Afterwards, it runs the code branch
567 commented with "the easy case": it calls TAILQ_NEXT to get the container right
568 of the current one and swaps both containers.
570 === Case 2: Move a container into a split container
572 The reference layout for this case is a horizontal workspace with two
573 containers. The right container is a v-split with two containers. Focus is on
574 the left container (1).
576 [width="15%",cols="^,^"]
582 When moving to the right (command +move right+), i3 will work like in case 1
583 ("the easy case"). However, as the right container is not a leaf container, but
584 a v-split, the left container (1) will be inserted at the right position (below
585 2, assuming that 2 is focused inside the v-split) by calling +insert_con_into+.
587 +insert_con_into+ detaches the container from its parent and inserts it
588 before/after the given target container. Afterwards, the on_remove_child
589 callback is called on the old parent container which will then be closed, if
592 Afterwards, +con_focus+ will be called to fix the focus stack and the tree will
595 === Case 3: Moving to non-existant top/bottom
597 Like in case 1, the reference layout for this case is a single workspace in
598 horizontal orientation with two containers on it. Focus is on the left
601 [width="15%",cols="^,^"]
606 This time however, the command is +move up+ or +move down+. tree_move will look
607 for a container with vertical orientation. As it will not find any,
608 +same_orientation+ is NULL and therefore i3 will perform a forced orientation
609 change on the workspace by creating a new h-split container, moving the
610 workspace contents into it and then changing the workspace orientation to
611 vertical. Now it will again search for parent containers with vertical
612 orientation and it will find the workspace.
614 This time, the easy case code path will not be run as we are not moving inside
615 the same container. Instead, +insert_con_into+ will be called with the focused
616 container and the container above/below the current one (on the level of
619 Now, +con_focus+ will be called to fix the focus stack and the tree will be
622 === Case 4: Moving to existant top/bottom
624 The reference layout for this case is a vertical workspace with two containers.
625 The bottom one is a h-split containing two containers (1 and 2). Focus is on
626 the bottom left container (1).
628 [width="15%",cols="^,^"]
634 This case is very much like case 3, only this time the forced workspace
635 orientation change does not need to be performed because the workspace already
636 is in vertical orientation.
638 === Case 5: Moving in one-child h-split
640 The reference layout for this case is a horizontal workspace with two
641 containers having a v-split on the left side with a one-child h-split on the
642 bottom. Focus is on the bottom left container (2(h)):
644 [width="15%",cols="^,^"]
650 In this case, +same_orientation+ will be set to the h-split container around
651 the focused container. However, when trying the easy case, the next/previous
652 container +swap+ will be NULL. Therefore, i3 will search again for a
653 +same_orientation+ container, this time starting from the parent of the h-split
656 After determining a new +same_orientation+ container (if it is NULL, the
657 orientation will be force-changed), this case is equivalent to case 2 or case
661 === Case 6: Floating containers
663 The reference layout for this case is a horizontal workspace with two
664 containers plus one floating h-split container. Focus is on the floating
667 TODO: nice illustration. table not possible?
669 When moving up/down, the container needs to leave the floating container and it
670 needs to be placed on the workspace (at workspace level). This is accomplished
671 by calling the function +attach_to_workspace+.
675 Without much ado, here is the list of cases which need to be considered:
677 * click to focus (tiling + floating) and raise (floating)
678 * click to focus/raise when in stacked/tabbed mode
679 * floating_modifier + left mouse button to drag a floating con
680 * floating_modifier + right mouse button to resize a floating con
681 * click on decoration in a floating con to either initiate a resize (if there
682 is more than one child in the floating con) or to drag the
683 floating con (if it’s the one at the top).
684 * click on border in a floating con to resize the floating con
685 * floating_modifier + right mouse button to resize a tiling con
686 * click on border/decoration to resize a tiling con
690 * Forgetting to call `xcb_flush(conn);` after sending a request. This usually
691 leads to code which looks like it works fine but which does not work under
694 == Using git / sending patches
696 For a short introduction into using git, see
697 http://www.spheredev.org/wiki/Git_for_the_lazy or, for more documentation, see
698 http://git-scm.com/documentation
700 When you want to send a patch because you fixed a bug or implemented a cool
701 feature (please talk to us before working on features to see whether they are
702 maybe already implemented, not possible for some some reason, or don’t fit
703 into the concept), please use git to create a patchfile.
705 First of all, update your working copy to the latest version of the master
712 Afterwards, make the necessary changes for your bugfix/feature. Then, review
713 the changes using +git diff+ (you might want to enable colors in the diff using
714 +git config diff.color auto+). When you are definitely done, use +git commit
715 -a+ to commit all changes you’ve made.
717 Then, use the following command to generate a patchfile which we can directly
718 apply to the branch, preserving your commit message and name:
720 -----------------------
721 git format-patch origin
722 -----------------------
724 Just send us the generated file via email.