1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <link rel="icon" type="image/png" href="/favicon.png">
\r
6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
\r
7 <meta name="generator" content="AsciiDoc 8.6.7" />
\r
8 <title>i3: Hacking i3: How To</title>
\r
9 <link rel="stylesheet" href="/css/style.css" type="text/css" />
\r
10 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />
\r
11 <script type="text/javascript">
\r
13 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
\r
16 <script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>
\r
18 <body class="article">
\r
21 <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>
\r
23 <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>
\r
24 <li><a href="/screenshots">Screens</a></li>
\r
25 <li><a href="/contact">Contact</a></li>
\r
26 <li><a href="http://bugs.i3wm.org/">Bugs</a></li>
\r
28 <br style="clear: both">
\r
31 <h1>Hacking i3: How To</h1>
\r
32 <span id="author">Michael Stapelberg</span><br />
\r
33 <span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />
\r
34 <span id="revdate">July 2011</span>
\r
36 <div id="toctitle">Table of Contents</div>
37 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
41 <div class="sectionbody">
\r
42 <div class="paragraph"><p>This document is intended to be the first thing you read before looking and/or
\r
43 touching i3’s source code. It should contain all important information to help
\r
44 you understand why things are like they are. If it does not mention something
\r
45 you find necessary, please do not hesitate to contact me.</p></div>
\r
49 <h2 id="_window_managers">1. Window Managers</h2>
\r
50 <div class="sectionbody">
\r
51 <div class="paragraph"><p>A window manager is not necessarily needed to run X, but it is usually used in
\r
52 combination with X to facilitate some things. The window manager’s job is to
\r
53 take care of the placement of windows, to provide the user with some mechanisms
\r
54 to change the position/size of windows and to communicate with clients to a
\r
55 certain extent (for example handle fullscreen requests of clients such as
\r
57 <div class="paragraph"><p>There are no different contexts in which X11 clients run, so a window manager
\r
58 is just another client, like all other X11 applications. However, it handles
\r
59 some events which normal clients usually don’t handle.</p></div>
\r
60 <div class="paragraph"><p>In the case of i3, the tasks (and order of them) are the following:</p></div>
\r
61 <div class="olist arabic"><ol class="arabic">
\r
64 Grab the key bindings (events will be sent upon keypress/keyrelease)
\r
69 Iterate through all existing windows (if the window manager is not started as
\r
70 the first client of X) and manage them (reparent them, create window
\r
76 When new windows are created, manage them
\r
81 Handle the client’s <tt>_WM_STATE</tt> property, but only the <tt>_WM_STATE_FULLSCREEN</tt>
\r
86 Handle the client’s <tt>WM_NAME</tt> property
\r
91 Handle the client’s size hints to display them proportionally
\r
96 Handle the client’s urgency hint
\r
101 Handle enter notifications (focus follows mouse)
\r
106 Handle button (as in mouse buttons) presses for focus/raise on click
\r
111 Handle expose events to re-draw own windows such as decorations
\r
116 React to the user’s commands: Change focus, Move windows, Switch workspaces,
\r
117 Change the layout mode of a container (default/stacking/tabbed), start a new
\r
118 application, restart the window manager
\r
122 <div class="paragraph"><p>In the following chapters, each of these tasks and their implementation details
\r
123 will be discussed.</p></div>
\r
124 <div class="sect2">
\r
125 <h3 id="_tiling_window_managers">1.1. Tiling window managers</h3>
\r
126 <div class="paragraph"><p>Traditionally, there are two approaches to managing windows: The most common
\r
127 one nowadays is floating, which means the user can freely move/resize the
\r
128 windows. The other approach is called tiling, which means that your window
\r
129 manager distributes windows to use as much space as possible while not
\r
130 overlapping each other.</p></div>
\r
131 <div class="paragraph"><p>The idea behind tiling is that you should not need to waste your time
\r
132 moving/resizing windows while you usually want to get some work done. After
\r
133 all, most users sooner or later tend to lay out their windows in a way which
\r
134 corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this
\r
135 for you? Certainly, it’s faster than you could ever do it.</p></div>
\r
136 <div class="paragraph"><p>The problem with most tiling window managers is that they are too unflexible.
\r
137 In my opinion, a window manager is just another tool, and similar to vim which
\r
138 can edit all kinds of text files (like source code, HTML, …) and is not limited
\r
139 to a specific file type, a window manager should not limit itself to a certain
\r
140 layout (like dwm, awesome, …) but provide mechanisms for you to easily create
\r
141 the layout you need at the moment.</p></div>
\r
143 <div class="sect2">
\r
144 <h3 id="_the_layout_tree">1.2. The layout tree</h3>
\r
145 <div class="paragraph"><p>The data structure which i3 uses to keep track of your windows is a tree. Every
\r
146 node in the tree is a container (type <tt>Con</tt>). Some containers represent actual
\r
147 windows (every container with a <tt>window != NULL</tt>), some represent split
\r
148 containers and a few have special purposes: they represent workspaces, outputs
\r
149 (like VGA1, LVDS1, …) or the X11 root window.</p></div>
\r
150 <div class="paragraph"><p>So, when you open a terminal and immediately open another one, they reside in
\r
151 the same split container, which uses the default layout. In case of an empty
\r
152 workspace, the split container we are talking about is the workspace.</p></div>
\r
153 <div class="paragraph"><p>To get an impression of how different layouts are represented, just play around
\r
154 and look at the data structures — they are exposed as a JSON hash. See
\r
155 <a href="http://i3wm.org/docs/ipc.html#_tree_reply">http://i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that and an
\r
160 <div class="sect1">
\r
161 <h2 id="_files">2. Files</h2>
\r
162 <div class="sectionbody">
\r
163 <div class="dlist"><dl>
\r
164 <dt class="hdlist1">
\r
165 include/atoms.xmacro
\r
169 A file containing all X11 atoms which i3 uses. This file will be included
\r
170 various times (for defining, requesting and receiving the atoms), each time
\r
171 with a different definition of xmacro().
\r
174 <dt class="hdlist1">
\r
179 Contains data definitions used by nearly all files. You really need to read
\r
183 <dt class="hdlist1">
\r
188 Contains forward definitions for all public functions, as well as
\r
189 doxygen-compatible comments (so if you want to get a bit more of the big
\r
190 picture, either browse all header files or use doxygen if you prefer that).
\r
193 <dt class="hdlist1">
\r
198 Contains the lexer for i3’s configuration file, written for <tt>flex(1)</tt>.
\r
201 <dt class="hdlist1">
\r
206 Contains the parser for i3’s configuration file, written for <tt>bison(1)</tt>.
\r
209 <dt class="hdlist1">
\r
214 Contains all functions which handle mouse button clicks (right mouse button
\r
215 clicks initiate resizing and thus are relatively complex).
\r
218 <dt class="hdlist1">
\r
223 Contains the lexer for i3 commands, written for <tt>flex(1)</tt>.
\r
226 <dt class="hdlist1">
\r
231 Contains the parser for i3 commands, written for <tt>bison(1)</tt>.
\r
234 <dt class="hdlist1">
\r
239 Contains all functions which deal with containers directly (creating
\r
240 containers, searching containers, getting specific properties from containers,
\r
244 <dt class="hdlist1">
\r
249 Contains all functions handling the configuration file (calling the parser
\r
250 (src/cfgparse.y) with the correct path, switching key bindings mode).
\r
253 <dt class="hdlist1">
\r
258 Contains debugging functions to print unhandled X events.
\r
261 <dt class="hdlist1">
\r
266 Functions to get/set certain EWMH properties easily.
\r
269 <dt class="hdlist1">
\r
274 Contains functions for floating mode (mostly resizing/dragging).
\r
277 <dt class="hdlist1">
\r
282 Contains all handlers for all kinds of X events (new window title, new hints,
\r
283 unmapping, key presses, button presses, …).
\r
286 <dt class="hdlist1">
\r
291 Contains code for the IPC interface.
\r
294 <dt class="hdlist1">
\r
299 Contains code for loading layouts from JSON files.
\r
302 <dt class="hdlist1">
\r
307 Contains the logging functions.
\r
310 <dt class="hdlist1">
\r
315 Initializes the window manager.
\r
318 <dt class="hdlist1">
\r
323 Looks at existing or new windows and decides whether to manage them. If so, it
\r
324 reparents the window and inserts it into our data structures.
\r
327 <dt class="hdlist1">
\r
332 A "match" is a data structure which acts like a mask or expression to match
\r
333 certain windows or not. For example, when using commands, you can specify a
\r
334 command like this: [title="<strong>Firefox</strong>"] kill. The title member of the match
\r
335 data structure will then be filled and i3 will check each window using
\r
336 match_matches_window() to find the windows affected by this command.
\r
339 <dt class="hdlist1">
\r
344 Contains code to move a container in a specific direction.
\r
347 <dt class="hdlist1">
\r
352 Functions to handle CT_OUTPUT cons.
\r
355 <dt class="hdlist1">
\r
360 The RandR API is used to get (and re-query) the configured outputs (monitors,
\r
364 <dt class="hdlist1">
\r
369 Renders the tree data structure by assigning coordinates to every node. These
\r
370 values will later be pushed to X11 in <tt>src/x.c</tt>.
\r
373 <dt class="hdlist1">
\r
378 Contains the functions to resize containers.
\r
381 <dt class="hdlist1">
\r
386 Handles <tt>SIGSEGV</tt>, <tt>SIGABRT</tt> and <tt>SIGFPE</tt> by showing a dialog that i3 crashed.
\r
387 You can chose to let it dump core, to restart it in-place or to restart it
\r
388 in-place but forget about the layout.
\r
391 <dt class="hdlist1">
\r
396 Contains functions which open or close containers in the tree, change focus or
\r
397 cleanup ("flatten") the tree. See also <tt>src/move.c</tt> for another similar
\r
398 function, which was moved into its own file because it is so long.
\r
401 <dt class="hdlist1">
\r
406 Contains useful functions which are not really dependant on anything.
\r
409 <dt class="hdlist1">
\r
414 Handlers to update X11 window properties like <tt>WM_CLASS</tt>, <tt>_NET_WM_NAME</tt>,
\r
415 <tt>CLIENT_LEADER</tt>, etc.
\r
418 <dt class="hdlist1">
\r
423 Contains all functions related to workspaces (displaying, hiding, renaming…)
\r
426 <dt class="hdlist1">
\r
431 Transfers our in-memory tree (see <tt>src/render.c</tt>) to X11.
\r
434 <dt class="hdlist1">
\r
439 Contains wrappers to use xcb more easily.
\r
442 <dt class="hdlist1">
\r
447 XCursor functions (for cursor themes).
\r
450 <dt class="hdlist1">
\r
455 Legacy support for Xinerama. See <tt>src/randr.c</tt> for the preferred API.
\r
461 <div class="sect1">
\r
462 <h2 id="_data_structures">3. Data structures</h2>
\r
463 <div class="sectionbody">
\r
464 <div class="paragraph"><p>See include/data.h for documented data structures. The most important ones are
\r
465 explained right here.</p></div>
\r
466 <div class="paragraph"><p>So, the hierarchy is:</p></div>
\r
467 <div class="olist arabic"><ol class="arabic">
\r
470 <strong>X11 root window</strong>, the root container
\r
475 <strong>Output container</strong> (LVDS1 in this example)
\r
480 <strong>Content container</strong> (there are also containers for dock windows)
\r
485 <strong>Workspaces</strong> (Workspace 1 in this example, with horizontal orientation)
\r
490 <strong>Split container</strong> (vertically split)
\r
495 <strong>X11 window containers</strong>
\r
499 <div class="paragraph"><p>The data type is <tt>Con</tt>, in all cases.</p></div>
\r
500 <div class="sect2">
\r
501 <h3 id="_x11_root_window">3.1. X11 root window</h3>
\r
502 <div class="paragraph"><p>The X11 root window is a single window per X11 display (a display is identified
\r
503 by <tt>:0</tt> or <tt>:1</tt> etc.). The root window is what you draw your background image
\r
504 on. It spans all the available outputs, e.g. <tt>VGA1</tt> is a specific part of the
\r
505 root window and <tt>LVDS1</tt> is a specific part of the root window.</p></div>
\r
507 <div class="sect2">
\r
508 <h3 id="_output_container">3.2. Output container</h3>
\r
509 <div class="paragraph"><p>Every active output obtained through RandR is represented by one output
\r
510 container. Outputs are considered active when a mode is configured (meaning
\r
511 something is actually displayed on the output) and the output is not a clone.</p></div>
\r
512 <div class="paragraph"><p>For example, if your notebook has a screen resolution of 1280x800 px and you
\r
513 connect a video projector with a resolution of 1024x768 px, set it up in clone
\r
514 mode (<tt>xrandr --output VGA1 --mode 1024x768 --same-as LVDS1</tt>), i3 will
\r
515 reduce the resolution to the lowest common resolution and disable one of the
\r
516 cloned outputs afterwards.</p></div>
\r
517 <div class="paragraph"><p>However, if you configure it using <tt>xrandr --output VGA1 --mode 1024x768
\r
518 --right-of LVDS1</tt>, i3 will set both outputs active. For each output, a new
\r
519 workspace will be assigned. New workspaces are created on the output you are
\r
520 currently on.</p></div>
\r
522 <div class="sect2">
\r
523 <h3 id="_content_container">3.3. Content container</h3>
\r
524 <div class="paragraph"><p>Each output has multiple children. Two of them are dock containers which hold
\r
525 dock clients. The other one is the content container, which holds the actual
\r
526 content (workspaces) of this output.</p></div>
\r
528 <div class="sect2">
\r
529 <h3 id="_workspace">3.4. Workspace</h3>
\r
530 <div class="paragraph"><p>A workspace is identified by its name. Basically, you could think of
\r
531 workspaces as different desks in your office, if you like the desktop
\r
532 metaphor. They just contain different sets of windows and are completely
\r
533 separate of each other. Other window managers also call this “Virtual
\r
534 desktops”.</p></div>
\r
536 <div class="sect2">
\r
537 <h3 id="_split_container">3.5. Split container</h3>
\r
538 <div class="paragraph"><p>A split container is a container which holds an arbitrary amount of split
\r
539 containers or X11 window containers. It has an orientation (horizontal or
\r
540 vertical) and a layout.</p></div>
\r
541 <div class="paragraph"><p>Split containers (and X11 window containers, which are a subtype of split
\r
542 containers) can have different border styles.</p></div>
\r
544 <div class="sect2">
\r
545 <h3 id="_x11_window_container">3.6. X11 window container</h3>
\r
546 <div class="paragraph"><p>An X11 window container holds exactly one X11 window. These are the leaf nodes
\r
547 of the layout tree, they cannot have any children.</p></div>
\r
551 <div class="sect1">
\r
552 <h2 id="_list_queue_macros">4. List/queue macros</h2>
\r
553 <div class="sectionbody">
\r
554 <div class="paragraph"><p>i3 makes heavy use of the list macros defined in BSD operating systems. To
\r
555 ensure that the operating system on which i3 is compiled has all the expected
\r
556 features, i3 comes with <tt>include/queue.h</tt>. On BSD systems, you can use man
\r
557 <tt>queue(3)</tt>. On Linux, you have to use google (or read the source).</p></div>
\r
558 <div class="paragraph"><p>The lists used are <tt>SLIST</tt> (single linked lists), <tt>CIRCLEQ</tt> (circular
\r
559 queues) and <tt>TAILQ</tt> (tail queues). Usually, only forward traversal is necessary,
\r
560 so an <tt>SLIST</tt> works fine. If inserting elements at arbitrary positions or at
\r
561 the end of a list is necessary, a <tt>TAILQ</tt> is used instead. However, for the
\r
562 windows inside a container, a <tt>CIRCLEQ</tt> is necessary to go from the currently
\r
563 selected window to the window above/below.</p></div>
\r
566 <div class="sect1">
\r
567 <h2 id="_naming_conventions">5. Naming conventions</h2>
\r
568 <div class="sectionbody">
\r
569 <div class="paragraph"><p>There is a row of standard variables used in many events. The following names
\r
570 should be chosen for those:</p></div>
\r
571 <div class="ulist"><ul>
\r
574 “conn” is the xcb_connection_t
\r
579 “event” is the event of the particular type
\r
584 “con” names a container
\r
589 “current” is a loop variable when using <tt>TAILQ_FOREACH</tt> etc.
\r
595 <div class="sect1">
\r
596 <h2 id="_startup_src_mainx_c_main">6. Startup (src/mainx.c, main())</h2>
\r
597 <div class="sectionbody">
\r
598 <div class="ulist"><ul>
\r
601 Establish the xcb connection
\r
606 Check for XKB extension on the separate X connection, load Xcursor
\r
611 Check for RandR screens (with a fall-back to Xinerama)
\r
616 Grab the keycodes for which bindings exist
\r
621 Manage all existing windows
\r
626 Enter the event loop
\r
632 <div class="sect1">
\r
633 <h2 id="_keybindings">7. Keybindings</h2>
\r
634 <div class="sectionbody">
\r
635 <div class="sect2">
\r
636 <h3 id="_grabbing_the_bindings">7.1. Grabbing the bindings</h3>
\r
637 <div class="paragraph"><p>Grabbing the bindings is quite straight-forward. You pass X your combination of
\r
638 modifiers and the keycode you want to grab and whether you want to grab them
\r
639 actively or passively. Most bindings (everything except for bindings using
\r
640 Mode_switch) are grabbed passively, that is, just the window manager gets the
\r
641 event and cannot replay it.</p></div>
\r
642 <div class="paragraph"><p>We need to grab bindings that use Mode_switch actively because of a bug in X.
\r
643 When the window manager receives the keypress/keyrelease event for an actively
\r
644 grabbed keycode, it has to decide what to do with this event: It can either
\r
645 replay it so that other applications get it or it can prevent other
\r
646 applications from receiving it.</p></div>
\r
647 <div class="paragraph"><p>So, why do we need to grab keycodes actively? Because X does not set the
\r
648 state-property of keypress/keyrelease events properly. The Mode_switch bit is
\r
649 not set and we need to get it using XkbGetState. This means we cannot pass X
\r
650 our combination of modifiers containing Mode_switch when grabbing the key and
\r
651 therefore need to grab the keycode itself without any modifiers. This means,
\r
652 if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
\r
653 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
\r
654 will handle the event, if not, it will replay the event.</p></div>
\r
656 <div class="sect2">
\r
657 <h3 id="_handling_a_keypress">7.2. Handling a keypress</h3>
\r
658 <div class="paragraph"><p>As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
\r
659 the correct state.</p></div>
\r
660 <div class="paragraph"><p>Then, it looks through all bindings and gets the one which matches the received
\r
662 <div class="paragraph"><p>The bound command is parsed by the cmdparse lexer/parser, see <tt>parse_cmd</tt> in
\r
663 <tt>src/cmdparse.y</tt>.</p></div>
\r
667 <div class="sect1">
\r
668 <h2 id="_manage_windows_src_main_c_manage_window_and_reparent_window">8. Manage windows (src/main.c, manage_window() and reparent_window())</h2>
\r
669 <div class="sectionbody">
\r
670 <div class="paragraph"><p><tt>manage_window()</tt> does some checks to decide whether the window should be
\r
671 managed at all:</p></div>
\r
672 <div class="ulist"><ul>
\r
675 Windows have to be mapped, that is, visible on screen
\r
680 The override_redirect must not be set. Windows with override_redirect shall
\r
681 not be managed by a window manager
\r
685 <div class="paragraph"><p>Afterwards, i3 gets the intial geometry and reparents the window (see
\r
686 <tt>reparent_window()</tt>) if it wasn’t already managed.</p></div>
\r
687 <div class="paragraph"><p>Reparenting means that for each window which is reparented, a new window,
\r
688 slightly larger than the original one, is created. The original window is then
\r
689 reparented to the bigger one (called "frame").</p></div>
\r
690 <div class="paragraph"><p>After reparenting, the window type (<tt>_NET_WM_WINDOW_TYPE</tt>) is checked to see
\r
691 whether this window is a dock (<tt>_NET_WM_WINDOW_TYPE_DOCK</tt>), like dzen2 for
\r
692 example. Docks are handled differently, they don’t have decorations and are not
\r
693 assigned to a specific container. Instead, they are positioned at the bottom
\r
694 or top of the screen (in the appropriate dock area containers). To get the
\r
695 height which needs to be reserved for the window, the <tt>_NET_WM_STRUT_PARTIAL</tt>
\r
696 property is used.</p></div>
\r
697 <div class="paragraph"><p>Furthermore, the list of assignments (to other workspaces, which may be on
\r
698 other screens) is checked. If the window matches one of the user’s criteria,
\r
699 it may either be put in floating mode or moved to a different workspace. If the
\r
700 target workspace is not visible, the window will not be mapped.</p></div>
\r
703 <div class="sect1">
\r
704 <h2 id="_what_happens_when_an_application_is_started">9. What happens when an application is started?</h2>
\r
705 <div class="sectionbody">
\r
706 <div class="paragraph"><p>i3 does not care for applications. All it notices is when new windows are
\r
707 mapped (see <tt>src/handlers.c</tt>, <tt>handle_map_request()</tt>). The window is then
\r
708 reparented (see section "Manage windows").</p></div>
\r
709 <div class="paragraph"><p>After reparenting the window, <tt>render_tree()</tt> is called which renders the
\r
710 internal layout table. The new window has been placed in the currently focused
\r
711 container and therefore the new window and the old windows (if any) need to be
\r
712 moved/resized so that the currently active layout (default/stacking/tabbed mode)
\r
713 is rendered correctly. To move/resize windows, a window is “configured” in
\r
714 X11-speak.</p></div>
\r
715 <div class="paragraph"><p>Some applications, such as MPlayer obviously assume the window manager is
\r
716 stupid and try to configure their windows by themselves. This generates an
\r
717 event called configurerequest. i3 handles these events and tells the window the
\r
718 size it had before the configurerequest (with the exception of not yet mapped
\r
719 windows, which get configured like they want to, and floating windows, which
\r
720 can reconfigure themselves).</p></div>
\r
723 <div class="sect1">
\r
724 <h2 id="_net_wm_state">10. _NET_WM_STATE</h2>
\r
725 <div class="sectionbody">
\r
726 <div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls
\r
727 “toggle_fullscreen()” for the specific client which just configures the
\r
728 client to use the whole screen on which it currently is. Also, it is set as
\r
729 fullscreen_client for the i3Screen.</p></div>
\r
732 <div class="sect1">
\r
733 <h2 id="_wm_name">11. WM_NAME</h2>
\r
734 <div class="sectionbody">
\r
735 <div class="paragraph"><p>When the WM_NAME property of a window changes, its decoration (containing the
\r
736 title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
\r
737 totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
\r
738 if present.</p></div>
\r
741 <div class="sect1">
\r
742 <h2 id="_net_wm_name">12. _NET_WM_NAME</h2>
\r
743 <div class="sectionbody">
\r
744 <div class="paragraph"><p>Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
\r
745 is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
\r
746 to X. Using an appropriate font (ISO-10646), you can see most special
\r
747 characters (every special character contained in your font).</p></div>
\r
750 <div class="sect1">
\r
751 <h2 id="_size_hints">13. Size hints</h2>
\r
752 <div class="sectionbody">
\r
753 <div class="paragraph"><p>Size hints specify the minimum/maximum size for a given window as well as its
\r
754 aspect ratio. This is important for clients like mplayer, who only set the
\r
755 aspect ratio and resize their window to be as small as possible (but only with
\r
756 some video outputs, for example in Xv, while when using x11, mplayer does the
\r
757 necessary centering for itself).</p></div>
\r
758 <div class="paragraph"><p>So, when an aspect ratio was specified, i3 adjusts the height of the window
\r
759 until the size maintains the correct aspect ratio. For the code to do this, see
\r
760 src/layout.c, function resize_client().</p></div>
\r
763 <div class="sect1">
\r
764 <h2 id="_rendering_src_layout_c_render_layout_and_render_container">14. Rendering (src/layout.c, render_layout() and render_container())</h2>
\r
765 <div class="sectionbody">
\r
766 <div class="paragraph"><p>Rendering in i3 version 4 is the step which assigns the correct sizes for
\r
767 borders, decoration windows, child windows and the stacking order of all
\r
768 windows. In a separate step (<tt>x_push_changes()</tt>), these changes are pushed to
\r
770 <div class="paragraph"><p>Keep in mind that all these properties (<tt>rect</tt>, <tt>window_rect</tt> and <tt>deco_rect</tt>)
\r
771 are temporary, meaning they will be overwritten by calling <tt>render_con</tt>.
\r
772 Persistent position/size information is kept in <tt>geometry</tt>.</p></div>
\r
773 <div class="paragraph"><p>The entry point for every rendering operation (except for the case of moving
\r
774 floating windows around) currently is <tt>tree_render()</tt> which will re-render
\r
775 everything that’s necessary (for every output, only the currently displayed
\r
776 workspace is rendered). This behavior is expected to change in the future,
\r
777 since for a lot of updates, re-rendering everything is not actually necessary.
\r
778 Focus was on getting it working correct, not getting it work very fast.</p></div>
\r
779 <div class="paragraph"><p>What <tt>tree_render()</tt> actually does is calling <tt>render_con()</tt> on the root
\r
780 container and then pushing the changes to X11. The following sections talk
\r
781 about the different rendering steps, in the order of "top of the tree" (root
\r
782 container) to the bottom.</p></div>
\r
783 <div class="sect2">
\r
784 <h3 id="_rendering_the_root_container">14.1. Rendering the root container</h3>
\r
785 <div class="paragraph"><p>The i3 root container (<tt>con->type == CT_ROOT</tt>) represents the X11 root window.
\r
786 It contains one child container for every output (like LVDS1, VGA1, …), which
\r
787 is available on your computer.</p></div>
\r
788 <div class="paragraph"><p>Rendering the root will first render all tiling windows and then all floating
\r
789 windows. This is necessary because a floating window can be positioned in such
\r
790 a way that it is visible on two different outputs. Therefore, by first
\r
791 rendering all the tiling windows (of all outputs), we make sure that floating
\r
792 windows can never be obscured by tiling windows.</p></div>
\r
793 <div class="paragraph"><p>Essentially, though, this code path will just call <tt>render_con()</tt> for every
\r
794 output and <tt>x_raise_con(); render_con()</tt> for every floating window.</p></div>
\r
795 <div class="paragraph"><p>In the special case of having a "global fullscreen" window (fullscreen mode
\r
796 spanning all outputs), a shortcut is taken and <tt>x_raise_con(); render_con()</tt> is
\r
797 only called for the global fullscreen window.</p></div>
\r
799 <div class="sect2">
\r
800 <h3 id="_rendering_an_output">14.2. Rendering an output</h3>
\r
801 <div class="paragraph"><p>Output containers (<tt>con->layout == L_OUTPUT</tt>) represent a hardware output like
\r
802 LVDS1, VGA1, etc. An output container has three children (at the moment): One
\r
803 content container (having workspaces as children) and the top/bottom dock area
\r
804 containers.</p></div>
\r
805 <div class="paragraph"><p>The rendering happens in the function <tt>render_l_output()</tt> in the following
\r
807 <div class="olist arabic"><ol class="arabic">
\r
810 Find the content container (<tt>con->type == CT_CON</tt>)
\r
815 Get the currently visible workspace (<tt>con_get_fullscreen_con(content,
\r
821 If there is a fullscreened window on that workspace, directly render it and
\r
822 return, thus ignoring the dock areas.
\r
827 Sum up the space used by all the dock windows (they have a variable height
\r
833 Set the workspace rects (x/y/width/height) based on the position of the
\r
834 output (stored in <tt>con->rect</tt>) and the usable space
\r
835 (<tt>con->rect.{width,height}</tt> without the space used for dock windows).
\r
840 Recursively raise and render the output’s child containers (meaning dock
\r
841 area containers and the content container).
\r
846 <div class="sect2">
\r
847 <h3 id="_rendering_a_workspace_or_split_container">14.3. Rendering a workspace or split container</h3>
\r
848 <div class="paragraph"><p>From here on, there really is no difference anymore. All containers are of
\r
849 <tt>con->type == CT_CON</tt> (whether workspace or split container) and some of them
\r
850 have a <tt>con->window</tt>, meaning they represent an actual window instead of a
\r
851 split container.</p></div>
\r
852 <div class="sect3">
\r
853 <h4 id="_default_layout">14.3.1. Default layout</h4>
\r
854 <div class="paragraph"><p>In default layout, containers are placed horizontally or vertically next to
\r
855 each other (depending on the <tt>con->orientation</tt>). If a child is a leaf node (as
\r
856 opposed to a split container) and has border style "normal", appropriate space
\r
857 will be reserved for its window decoration.</p></div>
\r
859 <div class="sect3">
\r
860 <h4 id="_stacked_layout">14.3.2. Stacked layout</h4>
\r
861 <div class="paragraph"><p>In stacked layout, only the focused window is actually shown (this is achieved
\r
862 by calling <tt>x_raise_con()</tt> in reverse focus order at the end of <tt>render_con()</tt>).</p></div>
\r
863 <div class="paragraph"><p>The available space for the focused window is the size of the container minus
\r
864 the height of the window decoration for all windows inside this stacked
\r
865 container.</p></div>
\r
866 <div class="paragraph"><p>If border style is "1pixel" or "none", no window decoration height will be
\r
867 reserved (or displayed later on), unless there is more than one window inside
\r
868 the stacked container.</p></div>
\r
870 <div class="sect3">
\r
871 <h4 id="_tabbed_layout">14.3.3. Tabbed layout</h4>
\r
872 <div class="paragraph"><p>Tabbed layout works precisely like stacked layout, but the window decoration
\r
873 position/size is different: They are placed next to each other on a single line
\r
874 (fixed height).</p></div>
\r
876 <div class="sect3">
\r
877 <h4 id="_dock_area_layout">14.3.4. Dock area layout</h4>
\r
878 <div class="paragraph"><p>This is a special case. Users cannot chose the dock area layout, but it will be
\r
879 set for the dock area containers. In the dockarea layout (at the moment!),
\r
880 windows will be placed above each other.</p></div>
\r
883 <div class="sect2">
\r
884 <h3 id="_rendering_a_window">14.4. Rendering a window</h3>
\r
885 <div class="paragraph"><p>A window’s size and position will be determined in the following way:</p></div>
\r
886 <div class="olist arabic"><ol class="arabic">
\r
889 Subtract the border if border style is not "none" (but "normal" or "1pixel").
\r
894 Subtract the X11 border, if the window has an X11 border > 0.
\r
899 Obey the aspect ratio of the window (think MPlayer).
\r
904 Obey the height- and width-increments of the window (think terminal emulator
\r
905 which can only be resized in one-line or one-character steps).
\r
912 <div class="sect1">
\r
913 <h2 id="_pushing_updates_to_x11_drawing">15. Pushing updates to X11 / Drawing</h2>
\r
914 <div class="sectionbody">
\r
915 <div class="paragraph"><p>A big problem with i3 before version 4 was that we just sent requests to X11
\r
916 anywhere in the source code. This was bad because nobody could understand the
\r
917 entirety of our interaction with X11, it lead to subtle bugs and a lot of edge
\r
918 cases which we had to consider all over again.</p></div>
\r
919 <div class="paragraph"><p>Therefore, since version 4, we have a single file, <tt>src/x.c</tt>, which is
\r
920 responsible for repeatedly transferring parts of our tree datastructure to X11.</p></div>
\r
921 <div class="paragraph"><p><tt>src/x.c</tt> consists of multiple parts:</p></div>
\r
922 <div class="olist arabic"><ol class="arabic">
\r
925 The state pushing: <tt>x_push_changes()</tt>, which calls <tt>x_push_node()</tt>.
\r
930 State modification functions: <tt>x_con_init</tt>, <tt>x_reinit</tt>,
\r
931 <tt>x_reparent_child</tt>, <tt>x_move_win</tt>, <tt>x_con_kill</tt>, <tt>x_raise_con</tt>, <tt>x_set_name</tt>
\r
932 and <tt>x_set_warp_to</tt>.
\r
937 Expose event handling (drawing decorations): <tt>x_deco_recurse()</tt> and
\r
938 <tt>x_draw_decoration()</tt>.
\r
942 <div class="sect2">
\r
943 <h3 id="_pushing_state_to_x11">15.1. Pushing state to X11</h3>
\r
944 <div class="paragraph"><p>In general, the function <tt>x_push_changes</tt> should be called to push state
\r
945 changes. Only when the scope of the state change is clearly defined (for
\r
946 example only the title of a window) and its impact is known beforehand, one can
\r
947 optimize this and call <tt>x_push_node</tt> on the appropriate con directly.</p></div>
\r
948 <div class="paragraph"><p><tt>x_push_changes</tt> works in the following steps:</p></div>
\r
949 <div class="olist arabic"><ol class="arabic">
\r
952 Clear the eventmask for all mapped windows. This leads to not getting
\r
953 useless ConfigureNotify or EnterNotify events which are caused by our
\r
954 requests. In general, we only want to handle user input.
\r
959 Stack windows above each other, in reverse stack order (starting with the
\r
960 most obscured/bottom window). This is relevant for floating windows which
\r
961 can overlap each other, but also for tiling windows in stacked or tabbed
\r
962 containers. We also update the <tt>_NET_CLIENT_LIST_STACKING</tt> hint which is
\r
963 necessary for tab drag and drop in Chromium.
\r
968 <tt>x_push_node</tt> will be called for the root container, recursively calling
\r
969 itself for the container’s children. This function actually pushes the
\r
970 state, see the next paragraph.
\r
975 If the pointer needs to be warped to a different position (for example when
\r
976 changing focus to a differnt output), it will be warped now.
\r
981 The eventmask is restored for all mapped windows.
\r
986 Window decorations will be rendered by calling <tt>x_deco_recurse</tt> on the root
\r
987 container, which then recursively calls itself for the children.
\r
992 If the input focus needs to be changed (because the user focused a different
\r
993 window), it will be updated now.
\r
998 <tt>x_push_node_unmaps</tt> will be called for the root container. This function
\r
999 only pushes UnmapWindow requests. Separating the state pushing is necessary
\r
1000 to handle fullscreen windows (and workspace switches) in a smooth fashion:
\r
1001 The newly visible windows should be visible before the old windows are
\r
1006 <div class="paragraph"><p><tt>x_push_node</tt> works in the following steps:</p></div>
\r
1007 <div class="olist arabic"><ol class="arabic">
\r
1010 Update the window’s <tt>WM_NAME</tt>, if changed (the <tt>WM_NAME</tt> is set on i3
\r
1011 containers mainly for debugging purposes).
\r
1016 Reparents a child window into the i3 container if the container was created
\r
1017 for a specific managed window.
\r
1022 If the size/position of the i3 container changed (due to opening a new
\r
1023 window or switching layouts for example), the window will be reconfigured.
\r
1024 Also, the pixmap which is used to draw the window decoration/border on is
\r
1025 reconfigured (pixmaps are size-dependent).
\r
1030 Size/position for the child window is adjusted.
\r
1035 The i3 container is mapped if it should be visible and was not yet mapped.
\r
1036 When mapping, <tt>WM_STATE</tt> is set to <tt>WM_STATE_NORMAL</tt>. Also, the eventmask of
\r
1037 the child window is updated and the i3 container’s contents are copied from
\r
1043 <tt>x_push_node</tt> is called recursively for all children of the current
\r
1048 <div class="paragraph"><p><tt>x_push_node_unmaps</tt> handles the remaining case of an i3 container being
\r
1049 unmapped if it should not be visible anymore. <tt>WM_STATE</tt> will be set to
\r
1050 <tt>WM_STATE_WITHDRAWN</tt>.</p></div>
\r
1052 <div class="sect2">
\r
1053 <h3 id="_drawing_window_decorations_borders_backgrounds">15.2. Drawing window decorations/borders/backgrounds</h3>
\r
1054 <div class="paragraph"><p><tt>x_draw_decoration</tt> draws window decorations. It is run for every leaf
\r
1055 container (representing an actual X11 window) and for every non-leaf container
\r
1056 which is in a stacked/tabbed container (because stacked/tabbed containers
\r
1057 display a window decoration for split containers, which at the moment just says
\r
1058 "another container").</p></div>
\r
1059 <div class="paragraph"><p>Then, parameters are collected to be able to determine whether this decoration
\r
1060 drawing is actually necessary or was already done. This saves a substantial
\r
1061 number of redraws (depending on your workload, but far over 50%).</p></div>
\r
1062 <div class="paragraph"><p>Assuming that we need to draw this decoration, we start by filling the empty
\r
1063 space around the child window (think of MPlayer with a specific aspect ratio)
\r
1064 in the user-configured client background color.</p></div>
\r
1065 <div class="paragraph"><p>Afterwards, we draw the appropriate border (in case of border styles "normal"
\r
1066 and "1pixel") and the top bar (in case of border style "normal").</p></div>
\r
1067 <div class="paragraph"><p>The last step is drawing the window title on the top bar.</p></div>
\r
1071 <div class="sect1">
\r
1072 <h2 id="_user_commands_parser_specs_commands_spec">16. User commands (parser-specs/commands.spec)</h2>
\r
1073 <div class="sectionbody">
\r
1074 <div class="paragraph"><p>In the configuration file and when using i3 interactively (with <tt>i3-msg</tt>, for
\r
1075 example), you use commands to make i3 do things, like focus a different window,
\r
1076 set a window to fullscreen, and so on. An example command is <tt>floating enable</tt>,
\r
1077 which enables floating mode for the currently focused window. See the
\r
1078 appropriate section in the <a href="userguide.html">User’s Guide</a> for a reference of
\r
1079 all commands.</p></div>
\r
1080 <div class="paragraph"><p>In earlier versions of i3, interpreting these commands was done using lex and
\r
1081 yacc, but experience has shown that lex and yacc are not well suited for our
\r
1082 command language. Therefore, starting from version 4.2, we use a custom parser
\r
1083 for user commands (not yet for the configuration file).
\r
1084 The input specification for this parser can be found in the file
\r
1085 <tt>parser-specs/commands.spec</tt>. Should you happen to use Vim as an editor, use
\r
1086 :source parser-specs/highlighting.vim to get syntax highlighting for this file
\r
1087 (highlighting files for other editors are welcome).</p></div>
\r
1088 <div class="listingblock">
\r
1089 <div class="title">Excerpt from commands.spec</div>
\r
1090 <div class="content">
\r
1091 <pre><tt>state INITIAL:
\r
1092 '[' -> call cmd_criteria_init(); CRITERIA
\r
1095 'workspace' -> WORKSPACE
\r
1096 'exit' -> call cmd_exit()
\r
1097 'restart' -> call cmd_restart()
\r
1098 'reload' -> call cmd_reload()</tt></pre>
\r
1100 <div class="paragraph"><p>The input specification is written in an extremely simple format. The
\r
1101 specification is then converted into C code by the Perl script
\r
1102 generate-commands-parser.pl (the output file names begin with GENERATED and the
\r
1103 files are stored in the <tt>include</tt> directory). The parser implementation
\r
1104 <tt>src/commands_parser.c</tt> includes the generated C code at compile-time.</p></div>
\r
1105 <div class="paragraph"><p>The above excerpt from commands.spec illustrates nearly all features of our
\r
1106 specification format: You describe different states and what can happen within
\r
1107 each state. State names are all-caps; the state in the above excerpt is called
\r
1108 INITIAL. A list of tokens and their actions (separated by an ASCII arrow)
\r
1109 follows. In the excerpt, all tokens are literals, that is, simple text strings
\r
1110 which will be compared with the input. An action is either the name of a state
\r
1111 in which the parser will transition into, or the keyword <em>call</em>, followed by
\r
1112 the name of a function (and optionally a state).</p></div>
\r
1113 <div class="sect2">
\r
1114 <h3 id="_example_the_workspace_state">16.1. Example: The WORKSPACE state</h3>
\r
1115 <div class="paragraph"><p>Let’s have a look at the WORKSPACE state, which is a good example of all
\r
1116 features. This is its definition:</p></div>
\r
1117 <div class="listingblock">
\r
1118 <div class="title">WORKSPACE state (commands.spec)</div>
\r
1119 <div class="content">
\r
1120 <pre><tt># workspace next|prev|next_on_output|prev_on_output
\r
1121 # workspace back_and_forth
\r
1122 # workspace <name>
\r
1124 direction = 'next_on_output', 'prev_on_output', 'next', 'prev'
\r
1125 -> call cmd_workspace($direction)
\r
1127 -> call cmd_workspace_back_and_forth()
\r
1128 workspace = string
\r
1129 -> call cmd_workspace_name($workspace)</tt></pre>
\r
1131 <div class="paragraph"><p>As you can see from the commands, there are multiple different valid variants
\r
1132 of the workspace command:</p></div>
\r
1133 <div class="dlist"><dl>
\r
1134 <dt class="hdlist1">
\r
1135 workspace <direction>
\r
1139 The word <em>workspace</em> can be followed by any of the tokens <em>next</em>,
\r
1140 <em>prev</em>, <em>next_on_output</em> or <em>prev_on_output</em>. This command will
\r
1141 switch to the next or previous workspace (optionally on the same
\r
1143 There is one function called <tt>cmd_workspace</tt>, which is defined
\r
1144 in <tt>src/commands.c</tt>. It will handle this kind of command. To know which
\r
1145 direction was specified, the direction token is stored on the stack
\r
1146 with the name "direction", which is what the "direction = " means in
\r
1147 the beginning.<br />
\r
1151 <div class="admonitionblock">
\r
1154 <div class="title">Note</div>
\r
1156 <td class="content">Note that you can specify multiple literals in the same line. This has
\r
1157 exactly the same effect as if you specified <tt>direction =
\r
1158 'next_on_output' -> call cmd_workspace($direction)</tt> and so forth.<br /></td>
\r
1161 <div class="admonitionblock">
\r
1164 <div class="title">Note</div>
\r
1166 <td class="content">Also note that the order of literals is important here: If <em>next</em> were
\r
1167 ordered before <em>next_on_output</em>, then <em>next_on_output</em> would never
\r
1171 <div class="dlist"><dl>
\r
1172 <dt class="hdlist1">
\r
1173 workspace back_and_forth
\r
1177 This is a very simple case: When the literal <em>back_and_forth</em> is found
\r
1178 in the input, the function <tt>cmd_workspace_back_and_forth</tt> will be
\r
1179 called without parameters and the parser will return to the INITIAL
\r
1180 state (since no other state was specified).
\r
1183 <dt class="hdlist1">
\r
1184 workspace <name>
\r
1188 In this case, the workspace command is followed by an arbitrary string,
\r
1189 possibly in quotes, for example "workspace 3" or "workspace bleh".<br />
\r
1190 This is the first time that the token is actually not a literal (not in
\r
1191 single quotes), but just called string. Other possible tokens are word
\r
1192 (the same as string, but stops matching at a whitespace) and end
\r
1193 (matches the end of the input).
\r
1198 <div class="sect2">
\r
1199 <h3 id="_introducing_a_new_command">16.2. Introducing a new command</h3>
\r
1200 <div class="paragraph"><p>The following steps have to be taken in order to properly introduce a new
\r
1201 command (or possibly extend an existing command):</p></div>
\r
1202 <div class="olist arabic"><ol class="arabic">
\r
1205 Define a function beginning with <tt>cmd_</tt> in the file <tt>src/commands.c</tt>. Copy
\r
1206 the prototype of an existing function.
\r
1211 After adding a comment on what the function does, copy the comment and
\r
1212 function definition to <tt>include/commands.h</tt>. Make the comment in the header
\r
1213 file use double asterisks to make doxygen pick it up.
\r
1218 Write a test case (or extend an existing test case) for your feature, see
\r
1219 <a href="testsuite.html">i3 testsuite</a>. For now, it is sufficient to simply call
\r
1220 your command in all the various possible ways.
\r
1225 Extend the parser specification in <tt>parser-specs/commands.spec</tt>. Run the
\r
1226 testsuite and see if your new function gets called with the appropriate
\r
1227 arguments for the appropriate input.
\r
1232 Actually implement the feature.
\r
1237 Document the feature in the <a href="userguide.html">User’s Guide</a>.
\r
1244 <div class="sect1">
\r
1245 <h2 id="_moving_containers">17. Moving containers</h2>
\r
1246 <div class="sectionbody">
\r
1247 <div class="paragraph"><p>The movement code is pretty delicate. You need to consider all cases before
\r
1248 making any changes or before being able to fully understand how it works.</p></div>
\r
1249 <div class="sect2">
\r
1250 <h3 id="_case_1_moving_inside_the_same_container">17.1. Case 1: Moving inside the same container</h3>
\r
1251 <div class="paragraph"><p>The reference layout for this case is a single workspace in horizontal
\r
1252 orientation with two containers on it. Focus is on the left container (1).</p></div>
\r
1253 <div class="tableblock">
\r
1254 <table rules="all"
\r
1257 cellspacing="0" cellpadding="4">
\r
1258 <col width="50%" />
\r
1259 <col width="50%" />
\r
1262 <td align="center" valign="top"><p class="table">1</p></td>
\r
1263 <td align="center" valign="top"><p class="table">2</p></td>
\r
1268 <div class="paragraph"><p>When moving the left window to the right (command <tt>move right</tt>), tree_move will
\r
1269 look for a container with horizontal orientation and finds the parent of the
\r
1270 left container, that is, the workspace. Afterwards, it runs the code branch
\r
1271 commented with "the easy case": it calls TAILQ_NEXT to get the container right
\r
1272 of the current one and swaps both containers.</p></div>
\r
1274 <div class="sect2">
\r
1275 <h3 id="_case_2_move_a_container_into_a_split_container">17.2. Case 2: Move a container into a split container</h3>
\r
1276 <div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
\r
1277 containers. The right container is a v-split with two containers. Focus is on
\r
1278 the left container (1).</p></div>
\r
1279 <div class="tableblock">
\r
1280 <table rules="all"
\r
1283 cellspacing="0" cellpadding="4">
\r
1284 <col width="50%" />
\r
1285 <col width="50%" />
\r
1288 <td rowspan="2" align="center" valign="middle"><p class="table">1</p></td>
\r
1289 <td align="center" valign="top"><p class="table">2</p></td>
\r
1292 <td align="center" valign="top"><p class="table">3</p></td>
\r
1297 <div class="paragraph"><p>When moving to the right (command <tt>move right</tt>), i3 will work like in case 1
\r
1298 ("the easy case"). However, as the right container is not a leaf container, but
\r
1299 a v-split, the left container (1) will be inserted at the right position (below
\r
1300 2, assuming that 2 is focused inside the v-split) by calling <tt>insert_con_into</tt>.</p></div>
\r
1301 <div class="paragraph"><p><tt>insert_con_into</tt> detaches the container from its parent and inserts it
\r
1302 before/after the given target container. Afterwards, the on_remove_child
\r
1303 callback is called on the old parent container which will then be closed, if
\r
1305 <div class="paragraph"><p>Afterwards, <tt>con_focus</tt> will be called to fix the focus stack and the tree will
\r
1306 be flattened.</p></div>
\r
1308 <div class="sect2">
\r
1309 <h3 id="_case_3_moving_to_non_existant_top_bottom">17.3. Case 3: Moving to non-existant top/bottom</h3>
\r
1310 <div class="paragraph"><p>Like in case 1, the reference layout for this case is a single workspace in
\r
1311 horizontal orientation with two containers on it. Focus is on the left
\r
1312 container:</p></div>
\r
1313 <div class="tableblock">
\r
1314 <table rules="all"
\r
1317 cellspacing="0" cellpadding="4">
\r
1318 <col width="50%" />
\r
1319 <col width="50%" />
\r
1322 <td align="center" valign="top"><p class="table">1</p></td>
\r
1323 <td align="center" valign="top"><p class="table">2</p></td>
\r
1328 <div class="paragraph"><p>This time however, the command is <tt>move up</tt> or <tt>move down</tt>. tree_move will look
\r
1329 for a container with vertical orientation. As it will not find any,
\r
1330 <tt>same_orientation</tt> is NULL and therefore i3 will perform a forced orientation
\r
1331 change on the workspace by creating a new h-split container, moving the
\r
1332 workspace contents into it and then changing the workspace orientation to
\r
1333 vertical. Now it will again search for parent containers with vertical
\r
1334 orientation and it will find the workspace.</p></div>
\r
1335 <div class="paragraph"><p>This time, the easy case code path will not be run as we are not moving inside
\r
1336 the same container. Instead, <tt>insert_con_into</tt> will be called with the focused
\r
1337 container and the container above/below the current one (on the level of
\r
1338 <tt>same_orientation</tt>).</p></div>
\r
1339 <div class="paragraph"><p>Now, <tt>con_focus</tt> will be called to fix the focus stack and the tree will be
\r
1340 flattened.</p></div>
\r
1342 <div class="sect2">
\r
1343 <h3 id="_case_4_moving_to_existant_top_bottom">17.4. Case 4: Moving to existant top/bottom</h3>
\r
1344 <div class="paragraph"><p>The reference layout for this case is a vertical workspace with two containers.
\r
1345 The bottom one is a h-split containing two containers (1 and 2). Focus is on
\r
1346 the bottom left container (1).</p></div>
\r
1347 <div class="tableblock">
\r
1348 <table rules="all"
\r
1351 cellspacing="0" cellpadding="4">
\r
1352 <col width="50%" />
\r
1353 <col width="50%" />
\r
1356 <td colspan="2" align="center" valign="top"><p class="table">3</p></td>
\r
1359 <td align="center" valign="top"><p class="table">1</p></td>
\r
1360 <td align="center" valign="top"><p class="table">2</p></td>
\r
1365 <div class="paragraph"><p>This case is very much like case 3, only this time the forced workspace
\r
1366 orientation change does not need to be performed because the workspace already
\r
1367 is in vertical orientation.</p></div>
\r
1369 <div class="sect2">
\r
1370 <h3 id="_case_5_moving_in_one_child_h_split">17.5. Case 5: Moving in one-child h-split</h3>
\r
1371 <div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
\r
1372 containers having a v-split on the left side with a one-child h-split on the
\r
1373 bottom. Focus is on the bottom left container (2(h)):</p></div>
\r
1374 <div class="tableblock">
\r
1375 <table rules="all"
\r
1378 cellspacing="0" cellpadding="4">
\r
1379 <col width="50%" />
\r
1380 <col width="50%" />
\r
1383 <td align="center" valign="top"><p class="table">1</p></td>
\r
1384 <td rowspan="2" align="center" valign="middle"><p class="table">3</p></td>
\r
1387 <td align="center" valign="top"><p class="table">2(h)</p></td>
\r
1392 <div class="paragraph"><p>In this case, <tt>same_orientation</tt> will be set to the h-split container around
\r
1393 the focused container. However, when trying the easy case, the next/previous
\r
1394 container <tt>swap</tt> will be NULL. Therefore, i3 will search again for a
\r
1395 <tt>same_orientation</tt> container, this time starting from the parent of the h-split
\r
1396 container.</p></div>
\r
1397 <div class="paragraph"><p>After determining a new <tt>same_orientation</tt> container (if it is NULL, the
\r
1398 orientation will be force-changed), this case is equivalent to case 2 or case
\r
1401 <div class="sect2">
\r
1402 <h3 id="_case_6_floating_containers">17.6. Case 6: Floating containers</h3>
\r
1403 <div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
\r
1404 containers plus one floating h-split container. Focus is on the floating
\r
1405 container.</p></div>
\r
1406 <div class="paragraph"><p>TODO: nice illustration. table not possible?</p></div>
\r
1407 <div class="paragraph"><p>When moving up/down, the container needs to leave the floating container and it
\r
1408 needs to be placed on the workspace (at workspace level). This is accomplished
\r
1409 by calling the function <tt>attach_to_workspace</tt>.</p></div>
\r
1413 <div class="sect1">
\r
1414 <h2 id="_click_handling">18. Click handling</h2>
\r
1415 <div class="sectionbody">
\r
1416 <div class="paragraph"><p>Without much ado, here is the list of cases which need to be considered:</p></div>
\r
1417 <div class="ulist"><ul>
\r
1420 click to focus (tiling + floating) and raise (floating)
\r
1425 click to focus/raise when in stacked/tabbed mode
\r
1430 floating_modifier + left mouse button to drag a floating con
\r
1435 floating_modifier + right mouse button to resize a floating con
\r
1440 click on decoration in a floating con to either initiate a resize (if there
\r
1441 is more than one child in the floating con) or to drag the
\r
1442 floating con (if it’s the one at the top).
\r
1447 click on border in a floating con to resize the floating con
\r
1452 floating_modifier + right mouse button to resize a tiling con
\r
1457 click on border/decoration to resize a tiling con
\r
1463 <div class="sect1">
\r
1464 <h2 id="_gotchas">19. Gotchas</h2>
\r
1465 <div class="sectionbody">
\r
1466 <div class="ulist"><ul>
\r
1469 Forgetting to call <tt>xcb_flush(conn);</tt> after sending a request. This usually
\r
1470 leads to code which looks like it works fine but which does not work under
\r
1471 certain conditions.
\r
1476 Forgetting to call <tt>floating_fix_coordinates(con, old_rect, new_rect)</tt> after
\r
1477 moving workspaces across outputs. Coordinates for floating containers are
\r
1478 not relative to workspace boundaries, so you must correct their coordinates
\r
1479 or those containers will show up in the wrong workspace or not at all.
\r
1485 <div class="sect1">
\r
1486 <h2 id="_using_git_sending_patches">20. Using git / sending patches</h2>
\r
1487 <div class="sectionbody">
\r
1488 <div class="paragraph"><p>For a short introduction into using git, see
\r
1489 <a href="http://www.spheredev.org/wiki/Git_for_the_lazy">http://www.spheredev.org/wiki/Git_for_the_lazy</a> or, for more documentation, see
\r
1490 <a href="http://git-scm.com/documentation">http://git-scm.com/documentation</a></p></div>
\r
1491 <div class="paragraph"><p>When you want to send a patch because you fixed a bug or implemented a cool
\r
1492 feature (please talk to us before working on features to see whether they are
\r
1493 maybe already implemented, not possible for some some reason, or don’t fit
\r
1494 into the concept), please use git to create a patchfile.</p></div>
\r
1495 <div class="paragraph"><p>First of all, update your working copy to the latest version of the master
\r
1497 <div class="listingblock">
\r
1498 <div class="content">
\r
1499 <pre><tt>git pull</tt></pre>
\r
1501 <div class="paragraph"><p>Afterwards, make the necessary changes for your bugfix/feature. Then, review
\r
1502 the changes using <tt>git diff</tt> (you might want to enable colors in the diff using
\r
1503 <tt>git config diff.color auto</tt>). When you are definitely done, use <tt>git commit
\r
1504 -a</tt> to commit all changes you’ve made.</p></div>
\r
1505 <div class="paragraph"><p>Then, use the following command to generate a patchfile which we can directly
\r
1506 apply to the branch, preserving your commit message and name:</p></div>
\r
1507 <div class="listingblock">
\r
1508 <div class="content">
\r
1509 <pre><tt>git format-patch origin</tt></pre>
\r
1511 <div class="paragraph"><p>Just send us the generated file via email.</p></div>
\r
1514 <div class="sect1">
\r
1515 <h2 id="_thought_experiments">21. Thought experiments</h2>
\r
1516 <div class="sectionbody">
\r
1517 <div class="paragraph"><p>In this section, we collect thought experiments, so that we don’t forget our
\r
1518 thoughts about specific topics. They are not necessary to get into hacking i3,
\r
1519 but if you are interested in one of the topics they cover, you should read them
\r
1520 before asking us why things are the way they are or why we don’t implement
\r
1522 <div class="sect2">
\r
1523 <h3 id="_using_cgroups_per_workspace">21.1. Using cgroups per workspace</h3>
\r
1524 <div class="paragraph"><p>cgroups (control groups) are a linux-only feature which provides the ability to
\r
1525 group multiple processes. For each group, you can individually set resource
\r
1526 limits, like allowed memory usage. Furthermore, and more importantly for our
\r
1527 purposes, they serve as a namespace, a label which you can attach to processes
\r
1528 and their children.</p></div>
\r
1529 <div class="paragraph"><p>One interesting use for cgroups is having one cgroup per workspace (or
\r
1530 container, doesn’t really matter). That way, you could set different priorities
\r
1531 and have a workspace for important stuff (say, writing a LaTeX document or
\r
1532 programming) and a workspace for unimportant background stuff (say,
\r
1533 JDownloader). Both tasks can obviously consume a lot of I/O resources, but in
\r
1534 this example it doesn’t really matter if JDownloader unpacks the download a
\r
1535 minute earlier or not. However, your compiler should work as fast as possible.
\r
1536 Having one cgroup per workspace, you would assign more resources to the
\r
1537 programming workspace.</p></div>
\r
1538 <div class="paragraph"><p>Another interesting feature is that an inherent problem of the workspace
\r
1539 concept could be solved by using cgroups: When starting an application on
\r
1540 workspace 1, then switching to workspace 2, you will get the application’s
\r
1541 window(s) on workspace 2 instead of the one you started it on. This is because
\r
1542 the window manager does not have any mapping between the process it starts (or
\r
1543 gets started in any way) and the window(s) which appear.</p></div>
\r
1544 <div class="paragraph"><p>Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu
\r
1545 gets started with PID 3390. The user then decides to launch Firefox, which
\r
1546 takes a long time. So he enters firefox into dmenu and presses enter. Firefox
\r
1547 gets started with PID 4001. When it finally finishes loading, it creates an X11
\r
1548 window and uses MapWindow to make it visible. This is the first time i3
\r
1549 actually gets in touch with Firefox. It decides to map the window, but it has
\r
1550 no way of knowing that this window (even though it has the _NET_WM_PID property
\r
1551 set to 4001) belongs to the dmenu the user started before.</p></div>
\r
1552 <div class="paragraph"><p>How do cgroups help with this? Well, when pressing Mod+d to launch dmenu, i3
\r
1553 would create a new cgroup, let’s call it i3-3390-1. It launches dmenu in that
\r
1554 cgroup, which gets PID 3390. As before, the user enters firefox and Firefox
\r
1555 gets launched with PID 4001. This time, though, the Firefox process with PID
\r
1556 4001 is <strong>also</strong> member of the cgroup i3-3390-1 (because fork()ing in a cgroup
\r
1557 retains the cgroup property). Therefore, when mapping the window, i3 can look
\r
1558 up in which cgroup the process is and can establish a mapping between the
\r
1559 workspace and the window.</p></div>
\r
1560 <div class="paragraph"><p>There are multiple problems with this approach:</p></div>
\r
1561 <div class="olist arabic"><ol class="arabic">
\r
1564 Every application has to properly set <tt>_NET_WM_PID</tt>. This is acceptable and
\r
1565 patches can be written for the few applications which don’t set the hint yet.
\r
1570 It does only work on Linux, since cgroups are a Linux-only feature. Again,
\r
1571 this is acceptable.
\r
1576 The main problem is that some applications create X11 windows completely
\r
1577 independent of UNIX processes. An example for this is Chromium (or
\r
1578 gnome-terminal), which, when being started a second time, communicates with
\r
1579 the first process and lets the first process open a new window. Therefore, if
\r
1580 you have a Chromium window on workspace 2 and you are currently working on
\r
1581 workspace 3, starting <tt>chromium</tt> does not lead to the desired result (the
\r
1582 window will open on workspace 2).
\r
1586 <div class="paragraph"><p>Therefore, my conclusion is that the only proper way of fixing the "window gets
\r
1587 opened on the wrong workspace" problem is in the application itself. Most
\r
1588 modern applications support freedesktop startup-notifications which can be
\r
1589 used for this.</p></div>
\r
1594 <div id="footnotes"><hr /></div>
\r
1595 <div id="footer" lang="de">
\r
1596 © 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>
\r
projects / i3 / i3.github.io / blob