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