]> git.sur5r.net Git - i3/i3/blob - docs/hacking-howto
Fix: killing unfocused window shouldn't produce focus event
[i3/i3] / docs / hacking-howto
1 Hacking i3: How To
2 ==================
3 Michael Stapelberg <michael@i3wm.org>
4 February 2013
5
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.
10
11 == Building i3
12
13 You can build i3 like you build any other software package which uses autotools.
14 Here’s a memory refresher:
15
16     $ autoreconf -fi
17     $ mkdir -p build && cd build
18     $ ../configure
19     $ make -j8
20
21 (The autoreconf -fi step is unnecessary if you are building from a release tarball,
22  but shouldn’t hurt either.)
23
24 === Build system features
25
26 * We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate
27   directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building
28   in a separate directory is common practice anyway. In case this causes any
29   trouble when packaging i3 for your distribution, please open an issue.
30
31 * “make check” runs the i3 testsuite. See docs/testsuite for details.
32
33 * “make distcheck” (runs testsuite on “make dist” result, tiny bit quicker
34   feedback cycle than waiting for the travis build to catch the issue).
35
36 * “make uninstall” (occasionally requested by users who compile from source)
37
38 * “make” will build manpages/docs by default if the tools are installed.
39   Conversely, manpages/docs are not tried to be built for users who don’t want
40   to install all these dependencies to get started hacking on i3.
41
42 * non-release builds will enable address sanitizer by default. Use the
43   --disable-sanitizers configure option to turn off all sanitizers, and see
44   --help for available sanitizers.
45
46 * Support for pre-compiled headers (PCH) has been dropped for now in the
47   interest of simplicity. If you need support for PCH, please open an issue.
48
49 * Coverage reports are now generated using “make check-code-coverage”, which
50   requires specifying --enable-code-coverage when calling configure.
51
52 == Using git / sending patches
53
54 For a short introduction into using git, see
55 https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy
56 or, for more documentation, see https://git-scm.com/documentation
57
58 Please talk to us before working on new features to see whether they will be
59 accepted. A good way for this is to open an issue and asking for opinions on it.
60 Even for accepted features, this can be a good way to refine an idea upfront. However,
61 we don't want to see certain features in i3, e.g., switching window focus in an
62 Alt+Tab like way.
63
64 When working on bugfixes, please make sure you mention that you are working on
65 it in the corresponding bug report at https://github.com/i3/i3/issues. In case
66 there is no bug report yet, please create one.
67
68 After you are done, please submit your work for review as a pull request at
69 https://github.com/i3/i3.
70
71 Do not send emails to the mailing list or any author directly, and don’t submit
72 them in the bugtracker, since all reviews should be done in public at
73 https://github.com/i3/i3. In order to make your review go as fast as possible, you
74 could have a look at previous reviews and see what the common mistakes are.
75
76 === Which branch to use?
77
78 Work on i3 generally happens in two branches: “master” and “next” (the latter
79 being the default branch, the one that people get when they check out the git
80 repository).
81
82 The contents of “master” are always stable. That is, it contains the source code
83 of the latest release, plus any bugfixes that were applied since that release.
84
85 New features are only found in the “next” branch. Therefore, if you are working
86 on a new feature, use the “next” branch. If you are working on a bugfix, use the
87 “next” branch, too, but make sure your code also works on “master”.
88
89 == Window Managers
90
91 A window manager is not necessarily needed to run X, but it is usually used in
92 combination with X to facilitate some things. The window manager's job is to
93 take care of the placement of windows, to provide the user with some mechanisms
94 to change the position/size of windows and to communicate with clients to a
95 certain extent (for example handle fullscreen requests of clients such as
96 MPlayer).
97
98 There are no different contexts in which X11 clients run, so a window manager
99 is just another client, like all other X11 applications. However, it handles
100 some events which normal clients usually don’t handle.
101
102 In the case of i3, the tasks (and order of them) are the following:
103
104 . Grab the key bindings (events will be sent upon keypress/keyrelease)
105 . Iterate through all existing windows (if the window manager is not started as
106   the first client of X) and manage them (reparent them, create window
107   decorations, etc.)
108 . When new windows are created, manage them
109 . Handle the client’s `_WM_STATE` property, but only `_WM_STATE_FULLSCREEN` and
110   `_NET_WM_STATE_DEMANDS_ATTENTION`
111 . Handle the client’s `WM_NAME` property
112 . Handle the client’s size hints to display them proportionally
113 . Handle the client’s urgency hint
114 . Handle enter notifications (focus follows mouse)
115 . Handle button (as in mouse buttons) presses for focus/raise on click
116 . Handle expose events to re-draw own windows such as decorations
117 . React to the user’s commands: Change focus, Move windows, Switch workspaces,
118   Change the layout mode of a container (default/stacking/tabbed), start a new
119   application, restart the window manager
120
121 In the following chapters, each of these tasks and their implementation details
122 will be discussed.
123
124 === Tiling window managers
125
126 Traditionally, there are two approaches to managing windows: The most common
127 one nowadays is floating, which means the user can freely move/resize the
128 windows. The other approach is called tiling, which means that your window
129 manager distributes windows to use as much space as possible while not
130 overlapping each other.
131
132 The idea behind tiling is that you should not need to waste your time
133 moving/resizing windows while you usually want to get some work done. After
134 all, most users sooner or later tend to lay out their windows in a way which
135 corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this
136 for you? Certainly, it’s faster than you could ever do it.
137
138 The problem with most tiling window managers is that they are too inflexible.
139 In my opinion, a window manager is just another tool, and similar to vim which
140 can edit all kinds of text files (like source code, HTML, …) and is not limited
141 to a specific file type, a window manager should not limit itself to a certain
142 layout (like dwm, awesome, …) but provide mechanisms for you to easily create
143 the layout you need at the moment.
144
145 === The layout tree
146
147 The data structure which i3 uses to keep track of your windows is a tree. Every
148 node in the tree is a container (type +Con+). Some containers represent actual
149 windows (every container with a +window != NULL+), some represent split
150 containers and a few have special purposes: they represent workspaces, outputs
151 (like VGA1, LVDS1, …) or the X11 root window.
152
153 So, when you open a terminal and immediately open another one, they reside in
154 the same split container, which uses the default layout. In case of an empty
155 workspace, the split container we are talking about is the workspace.
156
157 To get an impression of how different layouts are represented, just play around
158 and look at the data structures -- they are exposed as a JSON hash. See
159 https://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an
160 example.
161
162 == Files
163
164 include/atoms.xmacro::
165 A file containing all X11 atoms which i3 uses. This file will be included
166 various times (for defining, requesting and receiving the atoms), each time
167 with a different definition of xmacro().
168
169 include/data.h::
170 Contains data definitions used by nearly all files. You really need to read
171 this first.
172
173 include/*.h::
174 Contains forward definitions for all public functions, as well as
175 doxygen-compatible comments (so if you want to get a bit more of the big
176 picture, either browse all header files or use doxygen if you prefer that).
177
178 src/config_parser.c::
179 Contains a custom configuration parser. See src/command_parser.c for rationale
180  on why we use a custom parser.
181
182 src/click.c::
183 Contains all functions which handle mouse button clicks (right mouse button
184 clicks initiate resizing and thus are relatively complex).
185
186 src/command_parser.c::
187 Contains a hand-written parser to parse commands (commands are what
188 you bind on keys and what you can send to i3 using the IPC interface, like
189 'move left' or 'workspace 4').
190
191 src/con.c::
192 Contains all functions which deal with containers directly (creating
193 containers, searching containers, getting specific properties from containers,
194 …).
195
196 src/config.c::
197 Contains all functions handling the configuration file (calling the parser
198 src/config_parser.c) with the correct path, switching key bindings mode).
199
200 src/ewmh.c::
201 Functions to get/set certain EWMH properties easily.
202
203 src/floating.c::
204 Contains functions for floating mode (mostly resizing/dragging).
205
206 src/handlers.c::
207 Contains all handlers for all kinds of X events (new window title, new hints,
208 unmapping, key presses, button presses, …).
209
210 src/ipc.c::
211 Contains code for the IPC interface.
212
213 src/load_layout.c::
214 Contains code for loading layouts from JSON files.
215
216 src/log.c::
217 Contains the logging functions.
218
219 src/main.c::
220 Initializes the window manager.
221
222 src/manage.c::
223 Looks at existing or new windows and decides whether to manage them. If so, it
224 reparents the window and inserts it into our data structures.
225
226 src/match.c::
227 A "match" is a data structure which acts like a mask or expression to match
228 certain windows or not. For example, when using commands, you can specify a
229 command like this: [title="*Firefox*"] kill. The title member of the match
230 data structure will then be filled and i3 will check each window using
231 match_matches_window() to find the windows affected by this command.
232
233 src/move.c::
234 Contains code to move a container in a specific direction.
235
236 src/output.c::
237 Functions to handle CT_OUTPUT cons.
238
239 src/randr.c::
240 The RandR API is used to get (and re-query) the configured outputs (monitors,
241 …).
242
243 src/render.c::
244 Renders the tree data structure by assigning coordinates to every node. These
245 values will later be pushed to X11 in +src/x.c+.
246
247 src/resize.c::
248 Contains the functions to resize containers.
249
250 src/restore_layout.c::
251 Everything for restored containers that is not pure state parsing (which can be
252 found in load_layout.c).
253
254 src/sighandler.c::
255 Handles +SIGSEGV+, +SIGABRT+ and +SIGFPE+ by showing a dialog that i3 crashed.
256 You can chose to let it dump core, to restart it in-place or to restart it
257 in-place but forget about the layout.
258
259 src/tree.c::
260 Contains functions which open or close containers in the tree, change focus or
261 cleanup ("flatten") the tree. See also +src/move.c+ for another similar
262 function, which was moved into its own file because it is so long.
263
264 src/util.c::
265 Contains useful functions which are not really dependent on anything.
266
267 src/window.c::
268 Handlers to update X11 window properties like +WM_CLASS+, +_NET_WM_NAME+,
269 +CLIENT_LEADER+, etc.
270
271 src/workspace.c::
272 Contains all functions related to workspaces (displaying, hiding, renaming…)
273
274 src/x.c::
275 Transfers our in-memory tree (see +src/render.c+) to X11.
276
277 src/xcb.c::
278 Contains wrappers to use xcb more easily.
279
280 src/xcursor.c::
281 XCursor functions (for cursor themes).
282
283 src/xinerama.c::
284 Legacy support for Xinerama. See +src/randr.c+ for the preferred API.
285
286 == Data structures
287
288
289 See include/data.h for documented data structures. The most important ones are
290 explained right here.
291
292 /////////////////////////////////////////////////////////////////////////////////
293 // TODO: update image
294
295 image:bigpicture.png[The Big Picture]
296
297 /////////////////////////////////////////////////////////////////////////////////
298
299 So, the hierarchy is:
300
301 . *X11 root window*, the root container
302 . *Output container* (LVDS1 in this example)
303 . *Content container* (there are also containers for dock windows)
304 . *Workspaces* (Workspace 1 in this example, with horizontal orientation)
305 . *Split container* (vertically split)
306 . *X11 window containers*
307
308 The data type is +Con+, in all cases.
309
310 === X11 root window
311
312 The X11 root window is a single window per X11 display (a display is identified
313 by +:0+ or +:1+ etc.). The root window is what you draw your background image
314 on. It spans all the available outputs, e.g. +VGA1+ is a specific part of the
315 root window and +LVDS1+ is a specific part of the root window.
316
317 === Output container
318
319 Every active output obtained through RandR is represented by one output
320 container. Outputs are considered active when a mode is configured (meaning
321 something is actually displayed on the output) and the output is not a clone.
322
323 For example, if your notebook has a screen resolution of 1280x800 px and you
324 connect a video projector with a resolution of 1024x768 px, set it up in clone
325 mode (+xrandr \--output VGA1 \--mode 1024x768 \--same-as LVDS1+), i3 will
326 reduce the resolution to the lowest common resolution and disable one of the
327 cloned outputs afterwards.
328
329 However, if you configure it using +xrandr \--output VGA1 \--mode 1024x768
330 \--right-of LVDS1+, i3 will set both outputs active. For each output, a new
331 workspace will be assigned. New workspaces are created on the output you are
332 currently on.
333
334 === Content container
335
336 Each output has multiple children. Two of them are dock containers which hold
337 dock clients. The other one is the content container, which holds the actual
338 content (workspaces) of this output.
339
340 === Workspace
341
342 A workspace is identified by its name. Basically, you could think of
343 workspaces as different desks in your office, if you like the desktop
344 metaphor. They just contain different sets of windows and are completely
345 separate of each other. Other window managers also call this ``Virtual
346 desktops''.
347
348 === Split container
349
350 A split container is a container which holds an arbitrary amount of split
351 containers or X11 window containers. It has an orientation (horizontal or
352 vertical) and a layout.
353
354 Split containers (and X11 window containers, which are a subtype of split
355 containers) can have different border styles.
356
357 === X11 window container
358
359 An X11 window container holds exactly one X11 window. These are the leaf nodes
360 of the layout tree, they cannot have any children.
361
362 == List/queue macros
363
364 i3 makes heavy use of the list macros defined in BSD operating systems. To
365 ensure that the operating system on which i3 is compiled has all the expected
366 features, i3 comes with `include/queue.h`. On BSD systems, you can use man
367 `queue(3)`. On Linux, you have to use google (or read the source).
368
369 The lists used are +SLIST+ (single linked lists), +CIRCLEQ+ (circular
370 queues) and +TAILQ+ (tail queues). Usually, only forward traversal is necessary,
371 so an `SLIST` works fine. If inserting elements at arbitrary positions or at
372 the end of a list is necessary, a +TAILQ+ is used instead. However, for the
373 windows inside a container, a +CIRCLEQ+ is necessary to go from the currently
374 selected window to the window above/below.
375
376 == Naming conventions
377
378 There is a row of standard variables used in many events. The following names
379 should be chosen for those:
380
381  * ``conn'' is the xcb_connection_t
382  * ``event'' is the event of the particular type
383  * ``con'' names a container
384  * ``current'' is a loop variable when using +TAILQ_FOREACH+ etc.
385
386 == Startup (src/mainx.c, main())
387
388  * Establish the xcb connection
389  * Check for XKB extension on the separate X connection, load Xcursor
390  * Check for RandR screens (with a fall-back to Xinerama)
391  * Grab the keycodes for which bindings exist
392  * Manage all existing windows
393  * Enter the event loop
394
395 == Keybindings
396
397 === Grabbing the bindings
398
399 Grabbing the bindings is quite straight-forward. You pass X your combination of
400 modifiers and the keycode you want to grab and whether you want to grab them
401 actively or passively. Most bindings (everything except for bindings using
402 Mode_switch) are grabbed passively, that is, just the window manager gets the
403 event and cannot replay it.
404
405 We need to grab bindings that use Mode_switch actively because of a bug in X.
406 When the window manager receives the keypress/keyrelease event for an actively
407 grabbed keycode, it has to decide what to do with this event: It can either
408 replay it so that other applications get it or it can prevent other
409 applications from receiving it.
410
411 So, why do we need to grab keycodes actively? Because X does not set the
412 state-property of keypress/keyrelease events properly. The Mode_switch bit is
413 not set and we need to get it using XkbGetState. This means we cannot pass X
414 our combination of modifiers containing Mode_switch when grabbing the key and
415 therefore need to grab the keycode itself without any modifiers. This means,
416 if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
417 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
418 will handle the event, if not, it will replay the event.
419
420 === Handling a keypress
421
422 As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
423 the correct state.
424
425 Then, it looks through all bindings and gets the one which matches the received
426 event.
427
428 The bound command is parsed by the cmdparse lexer/parser, see +parse_cmd+ in
429 +src/cmdparse.y+.
430
431 == Manage windows (src/main.c, manage_window() and reparent_window())
432
433 `manage_window()` does some checks to decide whether the window should be
434 managed at all:
435
436  * Windows have to be mapped, that is, visible on screen
437  * The override_redirect must not be set. Windows with override_redirect shall
438    not be managed by a window manager
439
440 Afterwards, i3 gets the initial geometry and reparents the window (see
441 `reparent_window()`) if it wasn’t already managed.
442
443 Reparenting means that for each window which is reparented, a new window,
444 slightly larger than the original one, is created. The original window is then
445 reparented to the bigger one (called "frame").
446
447 After reparenting, the window type (`_NET_WM_WINDOW_TYPE`) is checked to see
448 whether this window is a dock (`_NET_WM_WINDOW_TYPE_DOCK`), like dzen2 for
449 example. Docks are handled differently, they don’t have decorations and are not
450 assigned to a specific container. Instead, they are positioned at the bottom
451 or top of the screen (in the appropriate dock area containers). To get the
452 height which needs to be reserved for the window, the `_NET_WM_STRUT_PARTIAL`
453 property is used.
454
455 Furthermore, the list of assignments (to other workspaces, which may be on
456 other screens) is checked. If the window matches one of the user’s criteria,
457 it may either be put in floating mode or moved to a different workspace. If the
458 target workspace is not visible, the window will not be mapped.
459
460 == What happens when an application is started?
461
462 i3 does not care about applications. All it notices is when new windows are
463 mapped (see `src/handlers.c`, `handle_map_request()`). The window is then
464 reparented (see section "Manage windows").
465
466 After reparenting the window, `render_tree()` is called which renders the
467 internal layout table. The new window has been placed in the currently focused
468 container and therefore the new window and the old windows (if any) need to be
469 moved/resized so that the currently active layout (default/stacking/tabbed mode)
470 is rendered correctly. To move/resize windows, a window is ``configured'' in
471 X11-speak.
472
473 Some applications, such as MPlayer obviously assume the window manager is
474 stupid and try to configure their windows by themselves. This generates an
475 event called configurerequest. i3 handles these events and tells the window the
476 size it had before the configurerequest (with the exception of not yet mapped
477 windows, which get configured like they want to, and floating windows, which
478 can reconfigure themselves).
479
480 == _NET_WM_STATE
481
482 Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms
483 are handled.
484
485 The former calls ``toggle_fullscreen()'' for the specific client which just
486 configures the client to use the whole screen on which it currently is.
487 Also, it is set as fullscreen_client for the i3Screen.
488
489 The latter is used to set, read and display urgency hints.
490
491 == WM_NAME
492
493 When the WM_NAME property of a window changes, its decoration (containing the
494 title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
495 totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
496 if present.
497
498 == _NET_WM_NAME
499
500 Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
501 is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
502 to X. Using an appropriate font (ISO-10646), you can see most special
503 characters (every special character contained in your font).
504
505 == Size hints
506
507 Size hints specify the minimum/maximum size for a given window as well as its
508 aspect ratio.  This is important for clients like mplayer, who only set the
509 aspect ratio and resize their window to be as small as possible (but only with
510 some video outputs, for example in Xv, while when using x11, mplayer does the
511 necessary centering for itself).
512
513 So, when an aspect ratio was specified, i3 adjusts the height of the window
514 until the size maintains the correct aspect ratio. For the code to do this, see
515 src/layout.c, function resize_client().
516
517 == Rendering (src/layout.c, render_layout() and render_container())
518
519 Rendering in i3 version 4 is the step which assigns the correct sizes for
520 borders, decoration windows, child windows and the stacking order of all
521 windows. In a separate step (+x_push_changes()+), these changes are pushed to
522 X11.
523
524 Keep in mind that all these properties (+rect+, +window_rect+ and +deco_rect+)
525 are temporary, meaning they will be overwritten by calling +render_con+.
526 Persistent position/size information is kept in +geometry+.
527
528 The entry point for every rendering operation (except for the case of moving
529 floating windows around) currently is +tree_render()+ which will re-render
530 everything that’s necessary (for every output, only the currently displayed
531 workspace is rendered). This behavior is expected to change in the future,
532 since for a lot of updates, re-rendering everything is not actually necessary.
533 Focus was on getting it working correct, not getting it work very fast.
534
535 What +tree_render()+ actually does is calling +render_con()+ on the root
536 container and then pushing the changes to X11. The following sections talk
537 about the different rendering steps, in the order of "top of the tree" (root
538 container) to the bottom.
539
540 === Rendering the root container
541
542 The i3 root container (`con->type == CT_ROOT`) represents the X11 root window.
543 It contains one child container for every output (like LVDS1, VGA1, …), which
544 is available on your computer.
545
546 Rendering the root will first render all tiling windows and then all floating
547 windows. This is necessary because a floating window can be positioned in such
548 a way that it is visible on two different outputs. Therefore, by first
549 rendering all the tiling windows (of all outputs), we make sure that floating
550 windows can never be obscured by tiling windows.
551
552 Essentially, though, this code path will just call +render_con()+ for every
553 output and +x_raise_con(); render_con()+ for every floating window.
554
555 In the special case of having a "global fullscreen" window (fullscreen mode
556 spanning all outputs), a shortcut is taken and +x_raise_con(); render_con()+ is
557 only called for the global fullscreen window.
558
559 === Rendering an output
560
561 Output containers (`con->layout == L_OUTPUT`) represent a hardware output like
562 LVDS1, VGA1, etc. An output container has three children (at the moment): One
563 content container (having workspaces as children) and the top/bottom dock area
564 containers.
565
566 The rendering happens in the function +render_l_output()+ in the following
567 steps:
568
569 1. Find the content container (`con->type == CT_CON`)
570 2. Get the currently visible workspace (+con_get_fullscreen_con(content,
571    CF_OUTPUT)+).
572 3. If there is a fullscreened window on that workspace, directly render it and
573    return, thus ignoring the dock areas.
574 4. Sum up the space used by all the dock windows (they have a variable height
575    only).
576 5. Set the workspace rects (x/y/width/height) based on the position of the
577    output (stored in `con->rect`) and the usable space
578    (`con->rect.{width,height}` without the space used for dock windows).
579 6. Recursively raise and render the output’s child containers (meaning dock
580    area containers and the content container).
581
582 === Rendering a workspace or split container
583
584 From here on, there really is no difference anymore. All containers are of
585 `con->type == CT_CON` (whether workspace or split container) and some of them
586 have a `con->window`, meaning they represent an actual window instead of a
587 split container.
588
589 ==== Default layout
590
591 In default layout, containers are placed horizontally or vertically next to
592 each other (depending on the `con->orientation`). If a child is a leaf node (as
593 opposed to a split container) and has border style "normal", appropriate space
594 will be reserved for its window decoration.
595
596 ==== Stacked layout
597
598 In stacked layout, only the focused window is actually shown (this is achieved
599 by calling +x_raise_con()+ in reverse focus order at the end of +render_con()+).
600
601 The available space for the focused window is the size of the container minus
602 the height of the window decoration for all windows inside this stacked
603 container.
604
605 If border style is "1pixel" or "none", no window decoration height will be
606 reserved (or displayed later on), unless there is more than one window inside
607 the stacked container.
608
609 ==== Tabbed layout
610
611 Tabbed layout works precisely like stacked layout, but the window decoration
612 position/size is different: They are placed next to each other on a single line
613 (fixed height).
614
615 ==== Dock area layout
616
617 This is a special case. Users cannot choose the dock area layout, but it will be
618 set for the dock area containers. In the dockarea layout (at the moment!),
619 windows will be placed above each other.
620
621 === Rendering a window
622
623 A window’s size and position will be determined in the following way:
624
625 1. Subtract the border if border style is not "none" (but "normal" or "1pixel").
626 2. Subtract the X11 border, if the window has an X11 border > 0.
627 3. Obey the aspect ratio of the window (think MPlayer).
628 4. Obey the height- and width-increments of the window (think terminal emulator
629    which can only be resized in one-line or one-character steps).
630
631 == Pushing updates to X11 / Drawing
632
633 A big problem with i3 before version 4 was that we just sent requests to X11
634 anywhere in the source code. This was bad because nobody could understand the
635 entirety of our interaction with X11, it lead to subtle bugs and a lot of edge
636 cases which we had to consider all over again.
637
638 Therefore, since version 4, we have a single file, +src/x.c+, which is
639 responsible for repeatedly transferring parts of our tree datastructure to X11.
640
641 +src/x.c+ consists of multiple parts:
642
643 1. The state pushing: +x_push_changes()+, which calls +x_push_node()+.
644 2. State modification functions: +x_con_init+, +x_reinit+,
645    +x_reparent_child+, +x_move_win+, +x_con_kill+, +x_raise_con+, +x_set_name+
646    and +x_set_warp_to+.
647 3. Expose event handling (drawing decorations): +x_deco_recurse()+ and
648    +x_draw_decoration()+.
649
650 === Pushing state to X11
651
652 In general, the function +x_push_changes+ should be called to push state
653 changes. Only when the scope of the state change is clearly defined (for
654 example only the title of a window) and its impact is known beforehand, one can
655 optimize this and call +x_push_node+ on the appropriate con directly.
656
657 +x_push_changes+ works in the following steps:
658
659 1. Clear the eventmask for all mapped windows. This leads to not getting
660    useless ConfigureNotify or EnterNotify events which are caused by our
661    requests. In general, we only want to handle user input.
662 2. Stack windows above each other, in reverse stack order (starting with the
663    most obscured/bottom window). This is relevant for floating windows which
664    can overlap each other, but also for tiling windows in stacked or tabbed
665    containers. We also update the +_NET_CLIENT_LIST_STACKING+ hint which is
666    necessary for tab drag and drop in Chromium.
667 3. +x_push_node+ will be called for the root container, recursively calling
668    itself for the container’s children. This function actually pushes the
669    state, see the next paragraph.
670 4. If the pointer needs to be warped to a different position (for example when
671    changing focus to a different output), it will be warped now.
672 5. The eventmask is restored for all mapped windows.
673 6. Window decorations will be rendered by calling +x_deco_recurse+ on the root
674    container, which then recursively calls itself for the children.
675 7. If the input focus needs to be changed (because the user focused a different
676    window), it will be updated now.
677 8. +x_push_node_unmaps+ will be called for the root container. This function
678    only pushes UnmapWindow requests. Separating the state pushing is necessary
679    to handle fullscreen windows (and workspace switches) in a smooth fashion:
680    The newly visible windows should be visible before the old windows are
681    unmapped.
682
683 +x_push_node+ works in the following steps:
684
685 1. Update the window’s +WM_NAME+, if changed (the +WM_NAME+ is set on i3
686    containers mainly for debugging purposes).
687 2. Reparents a child window into the i3 container if the container was created
688    for a specific managed window.
689 3. If the size/position of the i3 container changed (due to opening a new
690    window or switching layouts for example), the window will be reconfigured.
691    Also, the pixmap which is used to draw the window decoration/border on is
692    reconfigured (pixmaps are size-dependent).
693 4. Size/position for the child window is adjusted.
694 5. The i3 container is mapped if it should be visible and was not yet mapped.
695    When mapping, +WM_STATE+ is set to +WM_STATE_NORMAL+. Also, the eventmask of
696    the child window is updated and the i3 container’s contents are copied from
697    the pixmap.
698 6. +x_push_node+ is called recursively for all children of the current
699    container.
700
701 +x_push_node_unmaps+ handles the remaining case of an i3 container being
702 unmapped if it should not be visible anymore. +WM_STATE+ will be set to
703 +WM_STATE_WITHDRAWN+.
704
705
706 === Drawing window decorations/borders/backgrounds
707
708 +x_draw_decoration+ draws window decorations. It is run for every leaf
709 container (representing an actual X11 window) and for every non-leaf container
710 which is in a stacked/tabbed container (because stacked/tabbed containers
711 display a window decoration for split containers, which consists of a representation
712 of the child container's names.
713
714 Then, parameters are collected to be able to determine whether this decoration
715 drawing is actually necessary or was already done. This saves a substantial
716 number of redraws (depending on your workload, but far over 50%).
717
718 Assuming that we need to draw this decoration, we start by filling the empty
719 space around the child window (think of MPlayer with a specific aspect ratio)
720 in the user-configured client background color.
721
722 Afterwards, we draw the appropriate border (in case of border styles "normal"
723 and "1pixel") and the top bar (in case of border style "normal").
724
725 The last step is drawing the window title on the top bar.
726
727
728 /////////////////////////////////////////////////////////////////////////////////
729
730 == Resizing containers
731
732 By clicking and dragging the border of a container, you can resize the whole
733 column (respectively row) which this container is in. This is necessary to keep
734 the table layout working and consistent.
735
736 The resizing works similarly to the resizing of floating windows or movement of
737 floating windows:
738
739 * A new, invisible window with the size of the root window is created
740   (+grabwin+)
741 * Another window, 2px width and as high as your screen (or vice versa for
742   horizontal resizing) is created. Its background color is the border color and
743   it is only there to inform the user how big the container will be (it
744   creates the impression of dragging the border out of the container).
745 * The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer
746   and enter its own event loop which will pass all events (expose events) but
747   motion notify events. This function then calls the specified callback
748   (+resize_callback+) which does some boundary checking and moves the helper
749   window. As soon as the mouse button is released, this loop will be
750   terminated.
751 * The new width_factor for each involved column (respectively row) will be
752   calculated.
753
754 /////////////////////////////////////////////////////////////////////////////////
755
756 == User commands (parser-specs/commands.spec)
757
758 In the configuration file and when using i3 interactively (with +i3-msg+, for
759 example), you use commands to make i3 do things, like focus a different window,
760 set a window to fullscreen, and so on. An example command is +floating enable+,
761 which enables floating mode for the currently focused window. See the
762 appropriate section in the link:userguide.html[User’s Guide] for a reference of
763 all commands.
764
765 In earlier versions of i3, interpreting these commands was done using lex and
766 yacc, but experience has shown that lex and yacc are not well suited for our
767 command language. Therefore, starting from version 4.2, we use a custom parser
768 for user commands and the configuration file.
769 The input specification for this parser can be found in the file
770 +parser-specs/*.spec+. Should you happen to use Vim as an editor, use
771 :source parser-specs/highlighting.vim to get syntax highlighting for this file
772 (highlighting files for other editors are welcome).
773
774 .Excerpt from commands.spec
775 -----------------------------------------------------------------------
776 state INITIAL:
777   '[' -> call cmd_criteria_init(); CRITERIA
778   'move' -> MOVE
779   'exec' -> EXEC
780   'workspace' -> WORKSPACE
781   'exit' -> call cmd_exit()
782   'restart' -> call cmd_restart()
783   'reload' -> call cmd_reload()
784 -----------------------------------------------------------------------
785
786 The input specification is written in an extremely simple format. The
787 specification is then converted into C code by the Perl script
788 generate-commands-parser.pl (the output file names begin with GENERATED and the
789 files are stored in the +include+ directory). The parser implementation
790 +src/commands_parser.c+ includes the generated C code at compile-time.
791
792 The above excerpt from commands.spec illustrates nearly all features of our
793 specification format: You describe different states and what can happen within
794 each state. State names are all-caps; the state in the above excerpt is called
795 INITIAL. A list of tokens and their actions (separated by an ASCII arrow)
796 follows. In the excerpt, all tokens are literals, that is, simple text strings
797 which will be compared with the input. An action is either the name of a state
798 in which the parser will transition into, or the keyword 'call', followed by
799 the name of a function (and optionally a state).
800
801 === Example: The WORKSPACE state
802
803 Let’s have a look at the WORKSPACE state, which is a good example of all
804 features. This is its definition:
805
806 .WORKSPACE state (commands.spec)
807 ----------------------------------------------------------------
808 # workspace next|prev|next_on_output|prev_on_output
809 # workspace back_and_forth
810 # workspace <name>
811 # workspace number <number>
812 state WORKSPACE:
813   direction = 'next_on_output', 'prev_on_output', 'next', 'prev'
814       -> call cmd_workspace($direction)
815   'back_and_forth'
816       -> call cmd_workspace_back_and_forth()
817   'number'
818       -> WORKSPACE_NUMBER
819   workspace = string
820       -> call cmd_workspace_name($workspace)
821 ----------------------------------------------------------------
822
823 As you can see from the commands, there are multiple different valid variants
824 of the workspace command:
825
826 workspace <direction>::
827         The word 'workspace' can be followed by any of the tokens 'next',
828         'prev', 'next_on_output' or 'prev_on_output'. This command will
829         switch to the next or previous workspace (optionally on the same
830         output). +
831         There is one function called +cmd_workspace+, which is defined
832         in +src/commands.c+. It will handle this kind of command. To know which
833         direction was specified, the direction token is stored on the stack
834         with the name "direction", which is what the "direction = " means in
835         the beginning. +
836
837 NOTE: Note that you can specify multiple literals in the same line. This has
838         exactly the same effect as if you specified `direction =
839         'next_on_output' -> call cmd_workspace($direction)` and so forth. +
840
841 NOTE: Also note that the order of literals is important here: If 'next' were
842         ordered before 'next_on_output', then 'next_on_output' would never
843         match.
844
845 workspace back_and_forth::
846         This is a very simple case: When the literal 'back_and_forth' is found
847         in the input, the function +cmd_workspace_back_and_forth+ will be
848         called without parameters and the parser will return to the INITIAL
849         state (since no other state was specified).
850 workspace <name>::
851         In this case, the workspace command is followed by an arbitrary string,
852         possibly in quotes, for example "workspace 3" or "workspace bleh". +
853         This is the first time that the token is actually not a literal (not in
854         single quotes), but just called string. Other possible tokens are word
855         (the same as string, but stops matching at a whitespace) and end
856         (matches the end of the input).
857 workspace number <number>::
858         The workspace command has to be followed by the keyword +number+. It
859         then transitions into the state +WORKSPACE_NUMBER+, where the actual
860         parameter will be read.
861
862 === Introducing a new command
863
864 The following steps have to be taken in order to properly introduce a new
865 command (or possibly extend an existing command):
866
867 1. Define a function beginning with +cmd_+ in the file +src/commands.c+. Copy
868    the prototype of an existing function.
869 2. After adding a comment on what the function does, copy the comment and
870    function definition to +include/commands.h+. Make the comment in the header
871    file use double asterisks to make doxygen pick it up.
872 3. Write a test case (or extend an existing test case) for your feature, see
873    link:testsuite.html[i3 testsuite]. For now, it is sufficient to simply call
874    your command in all the various possible ways.
875 4. Extend the parser specification in +parser-specs/commands.spec+. Run the
876    testsuite and see if your new function gets called with the appropriate
877    arguments for the appropriate input.
878 5. Actually implement the feature.
879 6. Document the feature in the link:userguide.html[User’s Guide].
880
881 == Moving containers
882
883 The movement code is pretty delicate. You need to consider all cases before
884 making any changes or before being able to fully understand how it works.
885
886 === Case 1: Moving inside the same container
887
888 The reference layout for this case is a single workspace in horizontal
889 orientation with two containers on it. Focus is on the left container (1).
890
891
892 [width="15%",cols="^,^"]
893 |========
894 | 1 | 2
895 |========
896
897 When moving the left window to the right (command +move right+), tree_move will
898 look for a container with horizontal orientation and finds the parent of the
899 left container, that is, the workspace. Afterwards, it runs the code branch
900 commented with "the easy case": it calls TAILQ_NEXT to get the container right
901 of the current one and swaps both containers.
902
903 === Case 2: Move a container into a split container
904
905 The reference layout for this case is a horizontal workspace with two
906 containers. The right container is a v-split with two containers. Focus is on
907 the left container (1).
908
909 [width="15%",cols="^,^"]
910 |========
911 1.2+^.^| 1 | 2
912 | 3
913 |========
914
915 When moving to the right (command +move right+), i3 will work like in case 1
916 ("the easy case"). However, as the right container is not a leaf container, but
917 a v-split, the left container (1) will be inserted at the right position (below
918 2, assuming that 2 is focused inside the v-split) by calling +insert_con_into+.
919
920 +insert_con_into+ detaches the container from its parent and inserts it
921 before/after the given target container. Afterwards, the on_remove_child
922 callback is called on the old parent container which will then be closed, if
923 empty.
924
925 Afterwards, +con_focus+ will be called to fix the focus stack and the tree will
926 be flattened.
927
928 === Case 3: Moving to non-existent top/bottom
929
930 Like in case 1, the reference layout for this case is a single workspace in
931 horizontal orientation with two containers on it. Focus is on the left
932 container:
933
934 [width="15%",cols="^,^"]
935 |========
936 | 1 | 2
937 |========
938
939 This time however, the command is +move up+ or +move down+. tree_move will look
940 for a container with vertical orientation. As it will not find any,
941 +same_orientation+ is NULL and therefore i3 will perform a forced orientation
942 change on the workspace by creating a new h-split container, moving the
943 workspace contents into it and then changing the workspace orientation to
944 vertical. Now it will again search for parent containers with vertical
945 orientation and it will find the workspace.
946
947 This time, the easy case code path will not be run as we are not moving inside
948 the same container. Instead, +insert_con_into+ will be called with the focused
949 container and the container above/below the current one (on the level of
950 +same_orientation+).
951
952 Now, +con_focus+ will be called to fix the focus stack and the tree will be
953 flattened.
954
955 === Case 4: Moving to existent top/bottom
956
957 The reference layout for this case is a vertical workspace with two containers.
958 The bottom one is a h-split containing two containers (1 and 2). Focus is on
959 the bottom left container (1).
960
961 [width="15%",cols="^,^"]
962 |========
963 2+| 3
964 | 1 | 2
965 |========
966
967 This case is very much like case 3, only this time the forced workspace
968 orientation change does not need to be performed because the workspace already
969 is in vertical orientation.
970
971 === Case 5: Moving in one-child h-split
972
973 The reference layout for this case is a horizontal workspace with two
974 containers having a v-split on the left side with a one-child h-split on the
975 bottom. Focus is on the bottom left container (2(h)):
976
977 [width="15%",cols="^,^"]
978 |========
979 | 1 1.2+^.^| 3
980 | 2(h)
981 |========
982
983 In this case, +same_orientation+ will be set to the h-split container around
984 the focused container. However, when trying the easy case, the next/previous
985 container +swap+ will be NULL. Therefore, i3 will search again for a
986 +same_orientation+ container, this time starting from the parent of the h-split
987 container.
988
989 After determining a new +same_orientation+ container (if it is NULL, the
990 orientation will be force-changed), this case is equivalent to case 2 or case
991 4.
992
993
994 === Case 6: Floating containers
995
996 The reference layout for this case is a horizontal workspace with two
997 containers plus one floating h-split container. Focus is on the floating
998 container.
999
1000 TODO: nice illustration. table not possible?
1001
1002 When moving up/down, the container needs to leave the floating container and it
1003 needs to be placed on the workspace (at workspace level). This is accomplished
1004 by calling the function +attach_to_workspace+.
1005
1006 == Click handling
1007
1008 Without much ado, here is the list of cases which need to be considered:
1009
1010 * click to focus (tiling + floating) and raise (floating)
1011 * click to focus/raise when in stacked/tabbed mode
1012 * floating_modifier + left mouse button to drag a floating con
1013 * floating_modifier + right mouse button to resize a floating con
1014 * click on decoration in a floating con to either initiate a resize (if there
1015   is more than one child in the floating con) or to drag the
1016   floating con (if it’s the one at the top).
1017 * click on border in a floating con to resize the floating con
1018 * floating_modifier + right mouse button to resize a tiling con
1019 * click on border/decoration to resize a tiling con
1020
1021 == Gotchas
1022
1023 * Forgetting to call `xcb_flush(conn);` after sending a request. This usually
1024   leads to code which looks like it works fine but which does not work under
1025   certain conditions.
1026
1027 * Forgetting to call `floating_fix_coordinates(con, old_rect, new_rect)` after
1028   moving workspaces across outputs. Coordinates for floating containers are
1029   not relative to workspace boundaries, so you must correct their coordinates
1030   or those containers will show up in the wrong workspace or not at all.
1031
1032 == Thought experiments
1033
1034 In this section, we collect thought experiments, so that we don’t forget our
1035 thoughts about specific topics. They are not necessary to get into hacking i3,
1036 but if you are interested in one of the topics they cover, you should read them
1037 before asking us why things are the way they are or why we don’t implement
1038 things.
1039
1040 === Using cgroups per workspace
1041
1042 cgroups (control groups) are a linux-only feature which provides the ability to
1043 group multiple processes. For each group, you can individually set resource
1044 limits, like allowed memory usage. Furthermore, and more importantly for our
1045 purposes, they serve as a namespace, a label which you can attach to processes
1046 and their children.
1047
1048 One interesting use for cgroups is having one cgroup per workspace (or
1049 container, doesn’t really matter). That way, you could set different priorities
1050 and have a workspace for important stuff (say, writing a LaTeX document or
1051 programming) and a workspace for unimportant background stuff (say,
1052 JDownloader). Both tasks can obviously consume a lot of I/O resources, but in
1053 this example it doesn’t really matter if JDownloader unpacks the download a
1054 minute earlier or not. However, your compiler should work as fast as possible.
1055 Having one cgroup per workspace, you would assign more resources to the
1056 programming workspace.
1057
1058 Another interesting feature is that an inherent problem of the workspace
1059 concept could be solved by using cgroups: When starting an application on
1060 workspace 1, then switching to workspace 2, you will get the application’s
1061 window(s) on workspace 2 instead of the one you started it on. This is because
1062 the window manager does not have any mapping between the process it starts (or
1063 gets started in any way) and the window(s) which appear.
1064
1065 Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu
1066 gets started with PID 3390. The user then decides to launch Firefox, which
1067 takes a long time. So they enter firefox into dmenu and press enter. Firefox
1068 gets started with PID 4001. When it finally finishes loading, it creates an X11
1069 window and uses MapWindow to make it visible. This is the first time i3
1070 actually gets in touch with Firefox. It decides to map the window, but it has
1071 no way of knowing that this window (even though it has the _NET_WM_PID property
1072 set to 4001) belongs to the dmenu the user started before.
1073
1074 How do cgroups help with this? Well, when pressing Mod+d to launch dmenu, i3
1075 would create a new cgroup, let’s call it i3-3390-1. It launches dmenu in that
1076 cgroup, which gets PID 3390. As before, the user enters firefox and Firefox
1077 gets launched with PID 4001. This time, though, the Firefox process with PID
1078 4001 is *also* member of the cgroup i3-3390-1 (because fork()ing in a cgroup
1079 retains the cgroup property). Therefore, when mapping the window, i3 can look
1080 up in which cgroup the process is and can establish a mapping between the
1081 workspace and the window.
1082
1083 There are multiple problems with this approach:
1084
1085 . Every application has to properly set +_NET_WM_PID+. This is acceptable and
1086   patches can be written for the few applications which don’t set the hint yet.
1087 . It does only work on Linux, since cgroups are a Linux-only feature. Again,
1088   this is acceptable.
1089 . The main problem is that some applications create X11 windows completely
1090   independent of UNIX processes. An example for this is Chromium (or
1091   gnome-terminal), which, when being started a second time, communicates with
1092   the first process and lets the first process open a new window. Therefore, if
1093   you have a Chromium window on workspace 2 and you are currently working on
1094   workspace 3, starting +chromium+ does not lead to the desired result (the
1095   window will open on workspace 2).
1096
1097 Therefore, my conclusion is that the only proper way of fixing the "window gets
1098 opened on the wrong workspace" problem is in the application itself. Most
1099 modern applications support freedesktop startup-notifications  which can be
1100 used for this.