Hacking i3: How To ================== Michael Stapelberg February 2013 This document is intended to be the first thing you read before looking and/or touching i3’s source code. It should contain all important information to help you understand why things are like they are. If it does not mention something you find necessary, please do not hesitate to contact me. ++++
WARNING!

++++ This document is not 100% up to date. Specifically, everything up to and including <> has been updated recently. The rest might contain outdated information. ++++

++++ == Building i3 You can build i3 like you build any other software package which uses autotools. Here’s a memory refresher: $ autoreconf -fi $ mkdir -p build && cd build $ ../configure $ make -j8 The autoreconf -fi step is unnecessary if you are building from a release tarball, but shouldn’t hurt either. === Build system features * We use the +AX_ENABLE_BUILDDIR+ macro to enforce builds happening in a separate directory. This is a prerequisite for the +AX_EXTEND_SRCDIR+ macro and building in a separate directory is common practice anyway. In case this causes any trouble when packaging i3 for your distribution, please open an issue. * +make check+ runs the i3 testsuite. See docs/testsuite for details. * +make distcheck+ (runs testsuite on +make dist+ result, tiny bit quicker feedback cycle than waiting for the travis build to catch the issue). * +make uninstall+ (occasionally requested by users who compile from source) * +make+ will build manpages/docs by default if the tools are installed. Conversely, manpages/docs are not tried to be built for users who don’t want to install all these dependencies to get started hacking on i3. Manpages and docs can be disabled with the +--disable-mans++ and ++--disable-docs++ configure options respectively. * non-release builds will enable address sanitizer by default. Use the +--disable-sanitizers+ configure option to turn off all sanitizers, and see +--help+ for available sanitizers. * Coverage reports are now generated using +make check-code-coverage+, which requires specifying +--enable-code-coverage+ when calling configure. == Pull requests Please talk to us before working on new features to see whether they will be accepted. A good way for this is to open an issue and asking for opinions on it. Even for accepted features, this can be a good way to refine an idea upfront. However, we don't want to see certain features in i3, e.g., switching window focus in an Alt+Tab like way. When working on bugfixes, please make sure you mention that you are working on it in the corresponding bug report at https://github.com/i3/i3/issues. In case there is no bug report yet, please create one. After you are done, please submit your work for review as a pull request at https://github.com/i3/i3. In order to make your review go as fast as possible, you could have a look at previous reviews and see what the common mistakes are. === Which branch to use? Work on i3 generally happens in two branches: “master” and “next” (the latter being the default branch, the one that people get when they check out the git repository). The contents of “master” are always stable. That is, it contains the source code of the latest release, plus any bugfixes that were applied since that release. New features are only found in the “next” branch. Always use this branch when writing new code (both bugfixes and features). == Window Managers A window manager is not necessarily needed to run X, but it is usually used in combination with X to facilitate some things. The window manager's job is to take care of the placement of windows, to provide the user with some mechanisms to change the position/size of windows and to communicate with clients to a certain extent (for example handle fullscreen requests of clients such as MPlayer). There are no different contexts in which X11 clients run, so a window manager is just another client, like all other X11 applications. However, it handles some events which normal clients usually don’t handle. In the case of i3, the tasks (and order of them) are the following: . Grab the key bindings (events will be sent upon keypress/keyrelease) . Iterate through all existing windows (if the window manager is not started as the first client of X) and manage them (reparent them, create window decorations, etc.) . When new windows are created, manage them . Handle the client’s +_WM_STATE+ property, but only +_WM_STATE_FULLSCREEN+ and +_NET_WM_STATE_DEMANDS_ATTENTION+ . Handle the client’s +WM_NAME+ property . Handle the client’s size hints to display them proportionally . Handle the client’s urgency hint . Handle enter notifications (focus follows mouse) . Handle button (as in mouse buttons) presses for focus/raise on click . Handle expose events to re-draw own windows such as decorations . React to the user’s commands: Change focus, Move windows, Switch workspaces, Change the layout mode of a container (default/stacking/tabbed), start a new application, restart the window manager In the following chapters, each of these tasks and their implementation details will be discussed. === Tiling window managers Traditionally, there are two approaches to managing windows: The most common one nowadays is stacking (or floating, using i3's terminology), which means the user can freely move/resize the windows, potentially overlapping them. The other approach is called tiling, which means that the window manager distributes windows to use as much space as possible while not overlapping each other. The idea behind tiling is that you should not need to waste your time moving/resizing windows while you usually want to get some work done. After all, most users sooner or later tend to lay out their windows in a way which corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this for you? Certainly, it’s faster than you could ever do it. The problem with most tiling window managers is that they are too inflexible. In my opinion, a window manager is just another tool, and similar to vim which can edit all kinds of text files (like source code, HTML, …) and is not limited to a specific file type, a window manager should not limit itself to a certain layout (like dwm, awesome, …) but provide mechanisms for you to easily create the layout you need at the moment. === The layout tree The data structure which i3 uses to keep track of your windows is a tree. Every node in the tree is a container (type +Con+). Some containers represent actual windows (every container with a +window != NULL+), some represent split containers and a few have special purposes: they represent workspaces, outputs (like VGA1, LVDS1, …) or the X11 root window. So, when you open a terminal and immediately open another one, they reside in the same split container, which uses the default layout. In case of an empty workspace, the split container we are talking about is the workspace. To get an impression of how different layouts are represented, just play around and look at the data structures -- they are exposed as a JSON hash. See https://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an example. == Files i3's source code is in the +src+ folder while header files reside in +include+. Other tools such as i3bar and i3-nagbar have their own folders. i3 and its tools share an internal library called ``libi3'' which also has its own folder. The following list gives an overview of the codebase, explaining the functionality of the most important, core source code files. Other files in the tree that are not mentioned here implement specific functionalities: for example, +src/scratchpad.c+ is obviously about the scratchpad functionality. include/data.h:: Contains data definitions used by nearly all files. include/*.h:: Contains forward definitions for all public functions, as well as doxygen-compatible comments (so if you want to get a bit more of the big picture, either browse all header files or use doxygen if you prefer that). src/config_directives.c:: src/commands.c:: Contain the definitions for all high-level config and command directives. These are excellent places to start with a top-to-bottom approach to understand specific i3 behavior. For example, if you want to investigate a bug that happens for the +move to mark+ command, you can use gdb to pause in +cmd_move_con_to_mark+ and then work your way from there, stepping into lower-level functions. src/con.c:: Contains all functions which deal with containers directly (creating containers, searching containers, getting specific properties from containers, …). Contains abstractions and auxiliary functions necessary to work with the container structure which is used in almost all parts of the codebase. src/tree.c:: Contains functions which deal with the tree abstraction. However, be aware that +src/con.c+ also contains functions that heavily interact with the tree structure. Some functions that are included in +str/tree.c+ are those that handle opening and closing containers in the tree, finding the container that should be focused next and flattening the tree. See also +src/move.c+ for other move-specific functions that interact with the tree, which were moved into their own file because they are so long. src/workspace.c:: Contains functions which deal with workspaces. Includes code that creates new workspaces, shows existing ones and deals with workspace assignments. src/handlers.c:: Contains all handlers for all kinds of X events (new window title, new hints, unmapping, key presses, button presses, …). This is a very important file to understand how i3 interacts with changes to its environment. src/command_parser.c:: src/config_parser.c:: Contain a hand-written parser to parse commands and configuration (commands are what you bind on keys and what you can send to i3 using the IPC interface, like +move left+ or +workspace 4+). +src/config.c+ is responsible for calling the configuration parser. src/click.c:: src/resize.c:: Contain functions which handle mouse button clicks (right mouse button clicks initiate resizing and thus are relatively complex). src/manage.c:: Looks at existing or new windows and decides whether to manage them. If so, it reparents the window and inserts it into our data structures. src/match.c:: A "match" is a data structure which acts like a mask or expression to match certain windows or not. For example, when using commands, you can specify a command like this: +[title="*Firefox*"] kill+. The title member of the match data structure will then be filled and i3 will check each window using +match_matches_window()+ to find the windows affected by this command. src/randr.c:: The RandR API is used to get (and re-query) the configured outputs (monitors, …). Legacy Xinerama support resides in +src/xinerama.c+. src/render.c:: Renders the tree data structure by assigning coordinates to every node. These values will later be pushed to X11 in +src/x.c+. src/sighandler.c:: Handles +SIGSEGV+, +SIGABRT+ and +SIGFPE+ by showing a dialog that i3 crashed. You can choose to let it dump core and restart i3 in-place (either trying to preserve layout or forget about it). src/window.c:: Handlers to update X11 window properties like +WM_CLASS+, +_NET_WM_NAME+, +CLIENT_LEADER+, etc. include/atoms.xmacro:: A file containing all X11 atoms which i3 uses. This file will be included various times (for defining, requesting and receiving the atoms), each time with a different definition of xmacro(). [[data_structures]] == Data structures See +include/data.h+ for documented data structures. The most important ones are explained here. The following picture is generated by the +contrib/dump-asy.pl+ script. image:bigpicture.png["The Big Picture",width=1000,link="bigpicture.png"] The hierarchy is: . *Root container* . *Output containers*: +eDP-1+ in this example and the internal +__i3++ output . *Content and 2 dockarea containers* . *Workspaces*: Numbered workspace ``1'' and a ``Named workspace'' . *Split containers*: One horizontal in the first workspace and a tabbed one in the named one. . *Leaf containers*: Windows like vim and an i3bar dock. The data type is +Con+, in all cases. === Root container The root container (global variable +croot+) is the up-most ascendant of every i3 container. It can be used to iterate over the whole tree structure. E.g., it is used to reply to the +GET_WORKSPACES+ request, iterating over it's children to find all workspaces. This is different from the X11 root window. The X11 root window (global variable +root+) is a single window per X11 display (a display is identified by +:0+ or +:1+ etc.). The root window is what you draw your background image on. It spans all the available outputs, e.g. +VGA1+ is a specific part of the root window and +LVDS1+ is a specific part of the root window. === Output container Every active output obtained through RandR is represented by one output container. Outputs are considered active when a mode is configured (meaning something is actually displayed on the output) and the output is not a clone. For example, if your notebook has a screen resolution of 1280x800 px and you connect a video projector with a resolution of 1024x768 px, set it up in clone mode (+xrandr \--output VGA1 \--mode 1024x768 \--same-as LVDS1+), i3 will reduce the resolution to the lowest common resolution and disable one of the cloned outputs afterwards. However, if you configure it using +xrandr \--output VGA1 \--mode 1024x768 \--right-of LVDS1+, i3 will set both outputs active. For each output, a new workspace will be assigned. New workspaces are created on the output you are currently on. === Content container Each output has multiple children. Two of them are dock containers which hold the top and bottom dock clients. The other one is the content container, which holds the actual content (workspaces) of this output. === Workspace A workspace is identified by its name. Basically, you could think of workspaces as different desks in your office, if you like the desktop metaphor. They just contain different sets of windows and are completely separate of each other. Other window managers also call this ``Virtual desktops''. === Split container A split container is a container which holds an arbitrary amount of split containers or X11 window containers. It has an orientation (horizontal or vertical) and a layout. Split containers (and X11 window containers, which are a subtype of split containers) can have different border styles. === Leaf containers A leaf container holds exactly one X11 window. They can't have any children. == List/queue macros i3 makes heavy use of the list macros defined in BSD operating systems. To ensure that the operating system on which i3 is compiled has all the expected features, i3 comes with +include/queue.h+. On BSD systems, you can use +man queue(3)+. On Linux, you have to use google (or read the source). The lists used are +SLIST+ (single linked lists), +CIRCLEQ+ (circular queues) and +TAILQ+ (tail queues). Usually, only forward traversal is necessary, so an +SLIST+ works fine. If inserting elements at arbitrary positions or at the end of a list is necessary, a +TAILQ+ is used instead. However, for the windows inside a container, a +CIRCLEQ+ is necessary to go from the currently selected window to the window above/below. == Naming conventions There is a row of standard variables used in many events. The following names should be chosen for those: * +conn+ is the xcb_connection_t * +event+ is the event of the particular type * +con+ names a container * +current+ is a loop variable when using +TAILQ_FOREACH+ etc. == Startup (src/mainx.c, main()) * Establish the xcb connection * Check for XKB extension on the separate X connection, load Xcursor * Check for RandR screens (with a fall-back to Xinerama) * Grab the keycodes for which bindings exist * Manage all existing windows * Enter the event loop == Keybindings === Grabbing the bindings Grabbing the bindings is quite straight-forward. You pass X your combination of modifiers and the keycode you want to grab and whether you want to grab them actively or passively. Most bindings (everything except for bindings using Mode_switch) are grabbed passively, that is, just the window manager gets the event and cannot replay it. We need to grab bindings that use Mode_switch actively because of a bug in X. When the window manager receives the keypress/keyrelease event for an actively grabbed keycode, it has to decide what to do with this event: It can either replay it so that other applications get it or it can prevent other applications from receiving it. So, why do we need to grab keycodes actively? Because X does not set the state-property of keypress/keyrelease events properly. The Mode_switch bit is not set and we need to get it using XkbGetState. This means we cannot pass X our combination of modifiers containing Mode_switch when grabbing the key and therefore need to grab the keycode itself without any modifiers. This means, if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it will handle the event, if not, it will replay the event. === Handling a keypress As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets the correct state. Then, it looks through all bindings and gets the one which matches the received event. The bound command is parsed by the cmdparse lexer/parser, see +parse_cmd+ in +src/cmdparse.y+. == Manage windows (src/main.c, manage_window() and reparent_window()) +manage_window()+ does some checks to decide whether the window should be managed at all: * Windows have to be mapped, that is, visible on screen * The override_redirect must not be set. Windows with override_redirect shall not be managed by a window manager Afterwards, i3 gets the initial geometry and reparents the window (see +reparent_window()+) if it wasn’t already managed. Reparenting means that for each window which is reparented, a new window, slightly larger than the original one, is created. The original window is then reparented to the bigger one (called "frame"). After reparenting, the window type (+_NET_WM_WINDOW_TYPE+) is checked to see whether this window is a dock (+_NET_WM_WINDOW_TYPE_DOCK+), like dzen2 for example. Docks are handled differently, they don’t have decorations and are not assigned to a specific container. Instead, they are positioned at the bottom or top of the screen (in the appropriate dock area containers). To get the height which needs to be reserved for the window, the +_NET_WM_STRUT_PARTIAL+ property is used. Furthermore, the list of assignments (to other workspaces, which may be on other screens) is checked. If the window matches one of the user’s criteria, it may either be put in floating mode or moved to a different workspace. If the target workspace is not visible, the window will not be mapped. == What happens when an application is started? i3 does not care about applications. All it notices is when new windows are mapped (see +src/handlers.c+, +handle_map_request()+). The window is then reparented (see section "Manage windows"). After reparenting the window, +render_tree()+ is called which renders the internal layout table. The new window has been placed in the currently focused container and therefore the new window and the old windows (if any) need to be moved/resized so that the currently active layout (default/stacking/tabbed mode) is rendered correctly. To move/resize windows, a window is ``configured'' in X11-speak. Some applications, such as MPlayer obviously assume the window manager is stupid and try to configure their windows by themselves. This generates an event called configurerequest. i3 handles these events and tells the window the size it had before the configurerequest (with the exception of not yet mapped windows, which get configured like they want to, and floating windows, which can reconfigure themselves). == _NET_WM_STATE Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms are handled. The former calls +toggle_fullscreen()+ for the specific client which just configures the client to use the whole screen on which it currently is. Also, it is set as fullscreen_client for the i3Screen. The latter is used to set, read and display urgency hints. == WM_NAME When the WM_NAME property of a window changes, its decoration (containing the title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used if present. == _NET_WM_NAME Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it to X. Using an appropriate font (ISO-10646), you can see most special characters (every special character contained in your font). == Size hints Size hints specify the minimum/maximum size for a given window as well as its aspect ratio. This is important for clients like mplayer, who only set the aspect ratio and resize their window to be as small as possible (but only with some video outputs, for example in Xv, while when using x11, mplayer does the necessary centering for itself). So, when an aspect ratio was specified, i3 adjusts the height of the window until the size maintains the correct aspect ratio. For the code to do this, see src/layout.c, function resize_client(). == Rendering (src/layout.c, render_layout() and render_container()) Rendering in i3 version 4 is the step which assigns the correct sizes for borders, decoration windows, child windows and the stacking order of all windows. In a separate step (+x_push_changes()+), these changes are pushed to X11. Keep in mind that all these properties (+rect+, +window_rect+ and +deco_rect+) are temporary, meaning they will be overwritten by calling +render_con+. Persistent position/size information is kept in +geometry+. The entry point for every rendering operation (except for the case of moving floating windows around) currently is +tree_render()+ which will re-render everything that’s necessary (for every output, only the currently displayed workspace is rendered). This behavior is expected to change in the future, since for a lot of updates, re-rendering everything is not actually necessary. Focus was on getting it working correct, not getting it work very fast. What +tree_render()+ actually does is calling +render_con()+ on the root container and then pushing the changes to X11. The following sections talk about the different rendering steps, in the order of "top of the tree" (root container) to the bottom. === Rendering the root container The i3 root container (+con->type == CT_ROOT+) represents the X11 root window. It contains one child container for every output (like LVDS1, VGA1, …), which is available on your computer. Rendering the root will first render all tiling windows and then all floating windows. This is necessary because a floating window can be positioned in such a way that it is visible on two different outputs. Therefore, by first rendering all the tiling windows (of all outputs), we make sure that floating windows can never be obscured by tiling windows. Essentially, though, this code path will just call +render_con()+ for every output and +x_raise_con(); render_con()+ for every floating window. In the special case of having a "global fullscreen" window (fullscreen mode spanning all outputs), a shortcut is taken and +x_raise_con(); render_con()+ is only called for the global fullscreen window. === Rendering an output Output containers (+con->layout == L_OUTPUT+) represent a hardware output like LVDS1, VGA1, etc. An output container has three children (at the moment): One content container (having workspaces as children) and the top/bottom dock area containers. The rendering happens in the function +render_l_output()+ in the following steps: 1. Find the content container (+con->type == CT_CON+) 2. Get the currently visible workspace (+con_get_fullscreen_con(content, CF_OUTPUT)+). 3. If there is a fullscreened window on that workspace, directly render it and return, thus ignoring the dock areas. 4. Sum up the space used by all the dock windows (they have a variable height only). 5. Set the workspace rects (x/y/width/height) based on the position of the output (stored in +con->rect+) and the usable space (+con->rect.{width,height}+ without the space used for dock windows). 6. Recursively raise and render the output’s child containers (meaning dock area containers and the content container). === Rendering a workspace or split container From here on, there really is no difference anymore. All containers are of +con->type == CT_CON+ (whether workspace or split container) and some of them have a +con->window+, meaning they represent an actual window instead of a split container. ==== Default layout In default layout, containers are placed horizontally or vertically next to each other (depending on the +con->orientation+). If a child is a leaf node (as opposed to a split container) and has border style "normal", appropriate space will be reserved for its window decoration. ==== Stacked layout In stacked layout, only the focused window is actually shown (this is achieved by calling +x_raise_con()+ in reverse focus order at the end of +render_con()+). The available space for the focused window is the size of the container minus the height of the window decoration for all windows inside this stacked container. If border style is "1pixel" or "none", no window decoration height will be reserved (or displayed later on), unless there is more than one window inside the stacked container. ==== Tabbed layout Tabbed layout works precisely like stacked layout, but the window decoration position/size is different: They are placed next to each other on a single line (fixed height). ==== Dock area layout This is a special case. Users cannot choose the dock area layout, but it will be set for the dock area containers. In the dockarea layout (at the moment!), windows will be placed above each other. === Rendering a window A window’s size and position will be determined in the following way: 1. Subtract the border if border style is not "none" (but "normal" or "1pixel"). 2. Subtract the X11 border, if the window has an X11 border > 0. 3. Obey the aspect ratio of the window (think MPlayer). 4. Obey the height- and width-increments of the window (think terminal emulator which can only be resized in one-line or one-character steps). == Pushing updates to X11 / Drawing A big problem with i3 before version 4 was that we just sent requests to X11 anywhere in the source code. This was bad because nobody could understand the entirety of our interaction with X11, it lead to subtle bugs and a lot of edge cases which we had to consider all over again. Therefore, since version 4, we have a single file, +src/x.c+, which is responsible for repeatedly transferring parts of our tree datastructure to X11. +src/x.c+ consists of multiple parts: 1. The state pushing: +x_push_changes()+, which calls +x_push_node()+. 2. State modification functions: +x_con_init+, +x_reinit+, +x_reparent_child+, +x_move_win+, +x_con_kill+, +x_raise_con+, +x_set_name+ and +x_set_warp_to+. 3. Expose event handling (drawing decorations): +x_deco_recurse()+ and +x_draw_decoration()+. === Pushing state to X11 In general, the function +x_push_changes+ should be called to push state changes. Only when the scope of the state change is clearly defined (for example only the title of a window) and its impact is known beforehand, one can optimize this and call +x_push_node+ on the appropriate con directly. +x_push_changes+ works in the following steps: 1. Clear the eventmask for all mapped windows. This leads to not getting useless ConfigureNotify or EnterNotify events which are caused by our requests. In general, we only want to handle user input. 2. Stack windows above each other, in reverse stack order (starting with the most obscured/bottom window). This is relevant for floating windows which can overlap each other, but also for tiling windows in stacked or tabbed containers. We also update the +_NET_CLIENT_LIST_STACKING+ hint which is necessary for tab drag and drop in Chromium. 3. +x_push_node+ will be called for the root container, recursively calling itself for the container’s children. This function actually pushes the state, see the next paragraph. 4. If the pointer needs to be warped to a different position (for example when changing focus to a different output), it will be warped now. 5. The eventmask is restored for all mapped windows. 6. Window decorations will be rendered by calling +x_deco_recurse+ on the root container, which then recursively calls itself for the children. 7. If the input focus needs to be changed (because the user focused a different window), it will be updated now. 8. +x_push_node_unmaps+ will be called for the root container. This function only pushes UnmapWindow requests. Separating the state pushing is necessary to handle fullscreen windows (and workspace switches) in a smooth fashion: The newly visible windows should be visible before the old windows are unmapped. +x_push_node+ works in the following steps: 1. Update the window’s +WM_NAME+, if changed (the +WM_NAME+ is set on i3 containers mainly for debugging purposes). 2. Reparents a child window into the i3 container if the container was created for a specific managed window. 3. If the size/position of the i3 container changed (due to opening a new window or switching layouts for example), the window will be reconfigured. Also, the pixmap which is used to draw the window decoration/border on is reconfigured (pixmaps are size-dependent). 4. Size/position for the child window is adjusted. 5. The i3 container is mapped if it should be visible and was not yet mapped. When mapping, +WM_STATE+ is set to +WM_STATE_NORMAL+. Also, the eventmask of the child window is updated and the i3 container’s contents are copied from the pixmap. 6. +x_push_node+ is called recursively for all children of the current container. +x_push_node_unmaps+ handles the remaining case of an i3 container being unmapped if it should not be visible anymore. +WM_STATE+ will be set to +WM_STATE_WITHDRAWN+. === Drawing window decorations/borders/backgrounds +x_draw_decoration+ draws window decorations. It is run for every leaf container (representing an actual X11 window) and for every non-leaf container which is in a stacked/tabbed container (because stacked/tabbed containers display a window decoration for split containers, which consists of a representation of the child container's names. Then, parameters are collected to be able to determine whether this decoration drawing is actually necessary or was already done. This saves a substantial number of redraws (depending on your workload, but far over 50%). Assuming that we need to draw this decoration, we start by filling the empty space around the child window (think of MPlayer with a specific aspect ratio) in the user-configured client background color. Afterwards, we draw the appropriate border (in case of border styles "normal" and "1pixel") and the top bar (in case of border style "normal"). The last step is drawing the window title on the top bar. ///////////////////////////////////////////////////////////////////////////////// == Resizing containers By clicking and dragging the border of a container, you can resize the whole column (respectively row) which this container is in. This is necessary to keep the table layout working and consistent. The resizing works similarly to the resizing of floating windows or movement of floating windows: * A new, invisible window with the size of the root window is created (+grabwin+) * Another window, 2px width and as high as your screen (or vice versa for horizontal resizing) is created. Its background color is the border color and it is only there to inform the user how big the container will be (it creates the impression of dragging the border out of the container). * The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer and enter its own event loop which will pass all events (expose events) but motion notify events. This function then calls the specified callback (+resize_callback+) which does some boundary checking and moves the helper window. As soon as the mouse button is released, this loop will be terminated. * The new width_factor for each involved column (respectively row) will be calculated. ///////////////////////////////////////////////////////////////////////////////// == User commands (parser-specs/commands.spec) In the configuration file and when using i3 interactively (with +i3-msg+, for example), you use commands to make i3 do things, like focus a different window, set a window to fullscreen, and so on. An example command is +floating enable+, which enables floating mode for the currently focused window. See the appropriate section in the link:userguide.html[User’s Guide] for a reference of all commands. In earlier versions of i3, interpreting these commands was done using lex and yacc, but experience has shown that lex and yacc are not well suited for our command language. Therefore, starting from version 4.2, we use a custom parser for user commands and the configuration file. The input specification for this parser can be found in the file +parser-specs/*.spec+. Should you happen to use Vim as an editor, use :source parser-specs/highlighting.vim to get syntax highlighting for this file (highlighting files for other editors are welcome). .Excerpt from commands.spec ----------------------------------------------------------------------- state INITIAL: '[' -> call cmd_criteria_init(); CRITERIA 'move' -> MOVE 'exec' -> EXEC 'workspace' -> WORKSPACE 'exit' -> call cmd_exit() 'restart' -> call cmd_restart() 'reload' -> call cmd_reload() ----------------------------------------------------------------------- The input specification is written in an extremely simple format. The specification is then converted into C code by the Perl script generate-commands-parser.pl (the output file names begin with GENERATED and the files are stored in the +include+ directory). The parser implementation +src/commands_parser.c+ includes the generated C code at compile-time. The above excerpt from commands.spec illustrates nearly all features of our specification format: You describe different states and what can happen within each state. State names are all-caps; the state in the above excerpt is called INITIAL. A list of tokens and their actions (separated by an ASCII arrow) follows. In the excerpt, all tokens are literals, that is, simple text strings which will be compared with the input. An action is either the name of a state in which the parser will transition into, or the keyword 'call', followed by the name of a function (and optionally a state). === Example: The WORKSPACE state Let’s have a look at the WORKSPACE state, which is a good example of all features. This is its definition: .WORKSPACE state (commands.spec) ---------------------------------------------------------------- # workspace next|prev|next_on_output|prev_on_output # workspace back_and_forth # workspace # workspace number state WORKSPACE: direction = 'next_on_output', 'prev_on_output', 'next', 'prev' -> call cmd_workspace($direction) 'back_and_forth' -> call cmd_workspace_back_and_forth() 'number' -> WORKSPACE_NUMBER workspace = string -> call cmd_workspace_name($workspace) ---------------------------------------------------------------- As you can see from the commands, there are multiple different valid variants of the workspace command: workspace :: The word 'workspace' can be followed by any of the tokens 'next', 'prev', 'next_on_output' or 'prev_on_output'. This command will switch to the next or previous workspace (optionally on the same output). + There is one function called +cmd_workspace+, which is defined in +src/commands.c+. It will handle this kind of command. To know which direction was specified, the direction token is stored on the stack with the name "direction", which is what the "direction = " means in the beginning. + NOTE: Note that you can specify multiple literals in the same line. This has exactly the same effect as if you specified +direction = 'next_on_output' -> call cmd_workspace($direction)+ and so forth. + NOTE: Also note that the order of literals is important here: If 'next' were ordered before 'next_on_output', then 'next_on_output' would never match. workspace back_and_forth:: This is a very simple case: When the literal 'back_and_forth' is found in the input, the function +cmd_workspace_back_and_forth+ will be called without parameters and the parser will return to the INITIAL state (since no other state was specified). workspace :: In this case, the workspace command is followed by an arbitrary string, possibly in quotes, for example "workspace 3" or "workspace bleh". + This is the first time that the token is actually not a literal (not in single quotes), but just called string. Other possible tokens are word (the same as string, but stops matching at a whitespace) and end (matches the end of the input). workspace number :: The workspace command has to be followed by the keyword +number+. It then transitions into the state +WORKSPACE_NUMBER+, where the actual parameter will be read. === Introducing a new command The following steps have to be taken in order to properly introduce a new command (or possibly extend an existing command): 1. Define a function beginning with +cmd_+ in the file +src/commands.c+. Copy the prototype of an existing function. 2. After adding a comment on what the function does, copy the comment and function definition to +include/commands.h+. Make the comment in the header file use double asterisks to make doxygen pick it up. 3. Write a test case (or extend an existing test case) for your feature, see link:testsuite.html[i3 testsuite]. For now, it is sufficient to simply call your command in all the various possible ways. 4. Extend the parser specification in +parser-specs/commands.spec+. Run the testsuite and see if your new function gets called with the appropriate arguments for the appropriate input. 5. Actually implement the feature. 6. Document the feature in the link:userguide.html[User’s Guide]. == Moving containers The movement code is pretty delicate. You need to consider all cases before making any changes or before being able to fully understand how it works. === Case 1: Moving inside the same container The reference layout for this case is a single workspace in horizontal orientation with two containers on it. Focus is on the left container (1). [width="15%",cols="^,^"] |======== | 1 | 2 |======== When moving the left window to the right (command +move right+), tree_move will look for a container with horizontal orientation and finds the parent of the left container, that is, the workspace. Afterwards, it runs the code branch commented with "the easy case": it calls TAILQ_NEXT to get the container right of the current one and swaps both containers. === Case 2: Move a container into a split container The reference layout for this case is a horizontal workspace with two containers. The right container is a v-split with two containers. Focus is on the left container (1). [width="15%",cols="^,^"] |======== 1.2+^.^| 1 | 2 | 3 |======== When moving to the right (command +move right+), i3 will work like in case 1 ("the easy case"). However, as the right container is not a leaf container, but a v-split, the left container (1) will be inserted at the right position (below 2, assuming that 2 is focused inside the v-split) by calling +insert_con_into+. +insert_con_into+ detaches the container from its parent and inserts it before/after the given target container. Afterwards, the on_remove_child callback is called on the old parent container which will then be closed, if empty. Afterwards, +con_focus+ will be called to fix the focus stack and the tree will be flattened. === Case 3: Moving to non-existent top/bottom Like in case 1, the reference layout for this case is a single workspace in horizontal orientation with two containers on it. Focus is on the left container: [width="15%",cols="^,^"] |======== | 1 | 2 |======== This time however, the command is +move up+ or +move down+. tree_move will look for a container with vertical orientation. As it will not find any, +same_orientation+ is NULL and therefore i3 will perform a forced orientation change on the workspace by creating a new h-split container, moving the workspace contents into it and then changing the workspace orientation to vertical. Now it will again search for parent containers with vertical orientation and it will find the workspace. This time, the easy case code path will not be run as we are not moving inside the same container. Instead, +insert_con_into+ will be called with the focused container and the container above/below the current one (on the level of +same_orientation+). Now, +con_focus+ will be called to fix the focus stack and the tree will be flattened. === Case 4: Moving to existent top/bottom The reference layout for this case is a vertical workspace with two containers. The bottom one is a h-split containing two containers (1 and 2). Focus is on the bottom left container (1). [width="15%",cols="^,^"] |======== 2+| 3 | 1 | 2 |======== This case is very much like case 3, only this time the forced workspace orientation change does not need to be performed because the workspace already is in vertical orientation. === Case 5: Moving in one-child h-split The reference layout for this case is a horizontal workspace with two containers having a v-split on the left side with a one-child h-split on the bottom. Focus is on the bottom left container (2(h)): [width="15%",cols="^,^"] |======== | 1 1.2+^.^| 3 | 2(h) |======== In this case, +same_orientation+ will be set to the h-split container around the focused container. However, when trying the easy case, the next/previous container +swap+ will be NULL. Therefore, i3 will search again for a +same_orientation+ container, this time starting from the parent of the h-split container. After determining a new +same_orientation+ container (if it is NULL, the orientation will be force-changed), this case is equivalent to case 2 or case 4. === Case 6: Floating containers The reference layout for this case is a horizontal workspace with two containers plus one floating h-split container. Focus is on the floating container. TODO: nice illustration. table not possible? When moving up/down, the container needs to leave the floating container and it needs to be placed on the workspace (at workspace level). This is accomplished by calling the function +attach_to_workspace+. == Click handling Without much ado, here is the list of cases which need to be considered: * click to focus (tiling + floating) and raise (floating) * click to focus/raise when in stacked/tabbed mode * floating_modifier + left mouse button to drag a floating con * floating_modifier + right mouse button to resize a floating con * click on decoration in a floating con to either initiate a resize (if there is more than one child in the floating con) or to drag the floating con (if it’s the one at the top). * click on border in a floating con to resize the floating con * floating_modifier + right mouse button to resize a tiling con * click on border/decoration to resize a tiling con == Gotchas * Forgetting to call +xcb_flush(conn);+ after sending a request. This usually leads to code which looks like it works fine but which does not work under certain conditions. * Forgetting to call +floating_fix_coordinates(con, old_rect, new_rect)+ after moving workspaces across outputs. Coordinates for floating containers are not relative to workspace boundaries, so you must correct their coordinates or those containers will show up in the wrong workspace or not at all. == Thought experiments In this section, we collect thought experiments, so that we don’t forget our thoughts about specific topics. They are not necessary to get into hacking i3, but if you are interested in one of the topics they cover, you should read them before asking us why things are the way they are or why we don’t implement things. === Using cgroups per workspace cgroups (control groups) are a linux-only feature which provides the ability to group multiple processes. For each group, you can individually set resource limits, like allowed memory usage. Furthermore, and more importantly for our purposes, they serve as a namespace, a label which you can attach to processes and their children. One interesting use for cgroups is having one cgroup per workspace (or container, doesn’t really matter). That way, you could set different priorities and have a workspace for important stuff (say, writing a LaTeX document or programming) and a workspace for unimportant background stuff (say, JDownloader). Both tasks can obviously consume a lot of I/O resources, but in this example it doesn’t really matter if JDownloader unpacks the download a minute earlier or not. However, your compiler should work as fast as possible. Having one cgroup per workspace, you would assign more resources to the programming workspace. Another interesting feature is that an inherent problem of the workspace concept could be solved by using cgroups: When starting an application on workspace 1, then switching to workspace 2, you will get the application’s window(s) on workspace 2 instead of the one you started it on. This is because the window manager does not have any mapping between the process it starts (or gets started in any way) and the window(s) which appear. Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu gets started with PID 3390. The user then decides to launch Firefox, which takes a long time. So they enter firefox into dmenu and press enter. Firefox gets started with PID 4001. When it finally finishes loading, it creates an X11 window and uses MapWindow to make it visible. This is the first time i3 actually gets in touch with Firefox. It decides to map the window, but it has no way of knowing that this window (even though it has the _NET_WM_PID property set to 4001) belongs to the dmenu the user started before. How do cgroups help with this? Well, when pressing Mod+d to launch dmenu, i3 would create a new cgroup, let’s call it i3-3390-1. It launches dmenu in that cgroup, which gets PID 3390. As before, the user enters firefox and Firefox gets launched with PID 4001. This time, though, the Firefox process with PID 4001 is *also* member of the cgroup i3-3390-1 (because fork()ing in a cgroup retains the cgroup property). Therefore, when mapping the window, i3 can look up in which cgroup the process is and can establish a mapping between the workspace and the window. There are multiple problems with this approach: . Every application has to properly set +_NET_WM_PID+. This is acceptable and patches can be written for the few applications which don’t set the hint yet. . It does only work on Linux, since cgroups are a Linux-only feature. Again, this is acceptable. . The main problem is that some applications create X11 windows completely independent of UNIX processes. An example for this is Chromium (or gnome-terminal), which, when being started a second time, communicates with the first process and lets the first process open a new window. Therefore, if you have a Chromium window on workspace 2 and you are currently working on workspace 3, starting +chromium+ does not lead to the desired result (the window will open on workspace 2). Therefore, my conclusion is that the only proper way of fixing the "window gets opened on the wrong workspace" problem is in the application itself. Most modern applications support freedesktop startup-notifications which can be used for this.