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.4" />
\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_table">1.2. The layout table</h3>
\r
145 <div class="sidebarblock">
\r
146 <div class="content">
\r
147 <div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on
\r
148 time, but we will update this soon. Please talk to us on IRC if you need to
\r
149 know stuff <strong>NOW</strong> :).</p></div>
\r
154 <div class="sect1">
\r
155 <h2 id="_files">2. Files</h2>
\r
156 <div class="sectionbody">
\r
157 <div class="dlist"><dl>
\r
158 <dt class="hdlist1">
\r
159 include/atoms.xmacro
\r
163 A file containing all X11 atoms which i3 uses. This file will be included
\r
164 various times (for defining, requesting and receiving the atoms), each time
\r
165 with a different definition of xmacro().
\r
168 <dt class="hdlist1">
\r
173 Contains data definitions used by nearly all files. You really need to read
\r
177 <dt class="hdlist1">
\r
182 Contains forward definitions for all public functions, as well as
\r
183 doxygen-compatible comments (so if you want to get a bit more of the big
\r
184 picture, either browse all header files or use doxygen if you prefer that).
\r
187 <dt class="hdlist1">
\r
192 Contains the lexer for i3’s configuration file, written for <tt>flex(1)</tt>.
\r
195 <dt class="hdlist1">
\r
200 Contains the parser for i3’s configuration file, written for <tt>bison(1)</tt>.
\r
203 <dt class="hdlist1">
\r
208 Contains all functions which handle mouse button clicks (right mouse button
\r
209 clicks initiate resizing and thus are relatively complex).
\r
212 <dt class="hdlist1">
\r
217 Contains the lexer for i3 commands, written for <tt>flex(1)</tt>.
\r
220 <dt class="hdlist1">
\r
225 Contains the parser for i3 commands, written for <tt>bison(1)</tt>.
\r
228 <dt class="hdlist1">
\r
233 Contains all functions which deal with containers directly (creating
\r
234 containers, searching containers, getting specific properties from containers,
\r
238 <dt class="hdlist1">
\r
243 Contains all functions handling the configuration file (calling the parser
\r
244 (src/cfgparse.y) with the correct path, switching key bindings mode).
\r
247 <dt class="hdlist1">
\r
252 Contains debugging functions to print unhandled X events.
\r
255 <dt class="hdlist1">
\r
260 iFunctions to get/set certain EWMH properties easily.
\r
263 <dt class="hdlist1">
\r
268 Contains functions for floating mode (mostly resizing/dragging).
\r
271 <dt class="hdlist1">
\r
276 Contains all handlers for all kinds of X events (new window title, new hints,
\r
277 unmapping, key presses, button presses, …).
\r
280 <dt class="hdlist1">
\r
285 Contains code for the IPC interface.
\r
288 <dt class="hdlist1">
\r
293 Contains code for loading layouts from JSON files.
\r
296 <dt class="hdlist1">
\r
301 Handles the setting of loglevels, contains the logging functions.
\r
304 <dt class="hdlist1">
\r
309 Initializes the window manager.
\r
312 <dt class="hdlist1">
\r
317 Looks at existing or new windows and decides whether to manage them. If so, it
\r
318 reparents the window and inserts it into our data structures.
\r
321 <dt class="hdlist1">
\r
326 A "match" is a data structure which acts like a mask or expression to match
\r
327 certain windows or not. For example, when using commands, you can specify a
\r
328 command like this: [title="<strong>Firefox</strong>"] kill. The title member of the match
\r
329 data structure will then be filled and i3 will check each window using
\r
330 match_matches_window() to find the windows affected by this command.
\r
333 <dt class="hdlist1">
\r
338 Contains code to move a container in a specific direction.
\r
341 <dt class="hdlist1">
\r
346 Functions to handle CT_OUTPUT cons.
\r
349 <dt class="hdlist1">
\r
354 The RandR API is used to get (and re-query) the configured outputs (monitors,
\r
358 <dt class="hdlist1">
\r
363 Renders the tree data structure by assigning coordinates to every node. These
\r
364 values will later be pushed to X11 in <tt>src/x.c</tt>.
\r
367 <dt class="hdlist1">
\r
372 Contains the functions to resize containers.
\r
375 <dt class="hdlist1">
\r
380 Handles <tt>SIGSEGV</tt>, <tt>SIGABRT</tt> and <tt>SIGFPE</tt> by showing a dialog that i3 crashed.
\r
381 You can chose to let it dump core, to restart it in-place or to restart it
\r
382 in-place but forget about the layout.
\r
385 <dt class="hdlist1">
\r
390 Contains functions which open or close containers in the tree, change focus or
\r
391 cleanup ("flatten") the tree. See also <tt>src/move.c</tt> for another similar
\r
392 function, which was moved into its own file because it is so long.
\r
395 <dt class="hdlist1">
\r
400 Contains useful functions which are not really dependant on anything.
\r
403 <dt class="hdlist1">
\r
408 Handlers to update X11 window properties like <tt>WM_CLASS</tt>, <tt>_NET_WM_NAME</tt>,
\r
409 <tt>CLIENT_LEADER</tt>, etc.
\r
412 <dt class="hdlist1">
\r
417 Contains all functions related to workspaces (displaying, hiding, renaming…)
\r
420 <dt class="hdlist1">
\r
425 Transfers our in-memory tree (see <tt>src/render.c</tt>) to X11.
\r
428 <dt class="hdlist1">
\r
433 Contains wrappers to use xcb more easily.
\r
436 <dt class="hdlist1">
\r
441 XCursor functions (for cursor themes).
\r
444 <dt class="hdlist1">
\r
449 Legacy support for Xinerama. See <tt>src/randr.c</tt> for the preferred API.
\r
455 <div class="sect1">
\r
456 <h2 id="_data_structures">3. Data structures</h2>
\r
457 <div class="sectionbody">
\r
458 <div class="sidebarblock">
\r
459 <div class="content">
\r
460 <div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on
\r
461 time, but we will update this soon. Please talk to us on IRC if you need to
\r
462 know stuff <strong>NOW</strong> :).</p></div>
\r
464 <div class="paragraph"><p>So, the hierarchy is:</p></div>
\r
465 <div class="olist arabic"><ol class="arabic">
\r
468 <strong>X11 root window</strong>, the root container
\r
473 <strong>Virtual screens</strong> (Screen 0 in this example)
\r
478 <strong>Content container</strong> (there are also containers for dock windows)
\r
483 <strong>Workspaces</strong> (Workspace 1 in this example, with horizontal orientation)
\r
488 <strong>Split container</strong> (vertically split)
\r
493 <strong>X11 window containers</strong>
\r
497 <div class="paragraph"><p>The data type is <tt>Con</tt>, in all cases.</p></div>
\r
498 <div class="sect2">
\r
499 <h3 id="_virtual_screens">3.1. Virtual screens</h3>
\r
500 <div class="paragraph"><p>A virtual screen (type <tt>i3Screen</tt>) is generated from the connected outputs
\r
501 obtained through RandR. The difference to the raw RandR outputs as seen
\r
502 when using <tt>xrandr(1)</tt> is that it falls back to the lowest common resolution of
\r
503 the actual enabled outputs.</p></div>
\r
504 <div class="paragraph"><p>For example, if your notebook has a screen resolution of 1280x800 px and you
\r
505 connect a video projector with a resolution of 1024x768 px, set it up in clone
\r
506 mode (<tt>xrandr --output VGA1 --mode 1024x768 --same-as LVDS1</tt>), i3 will have
\r
507 one virtual screen.</p></div>
\r
508 <div class="paragraph"><p>However, if you configure it using <tt>xrandr --output VGA1 --mode 1024x768
\r
509 --right-of LVDS1</tt>, i3 will generate two virtual screens. For each virtual
\r
510 screen, a new workspace will be assigned. New workspaces are created on the
\r
511 screen you are currently on.</p></div>
\r
513 <div class="sect2">
\r
514 <h3 id="_workspace">3.2. Workspace</h3>
\r
515 <div class="paragraph"><p>A workspace is identified by its name. Basically, you could think of
\r
516 workspaces as different desks in your office, if you like the desktop
\r
517 methaphor. They just contain different sets of windows and are completely
\r
518 separate of each other. Other window managers also call this “Virtual
\r
519 desktops”.</p></div>
\r
521 <div class="sect2">
\r
522 <h3 id="_the_layout_table_2">3.3. The layout table</h3>
\r
523 <div class="sidebarblock">
\r
524 <div class="content">
\r
525 <div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on
\r
526 time, but we will update this soon. Please talk to us on IRC if you need to
\r
527 know stuff <strong>NOW</strong> :).</p></div>
\r
530 <div class="sect2">
\r
531 <h3 id="_container">3.4. Container</h3>
\r
532 <div class="sidebarblock">
\r
533 <div class="content">
\r
534 <div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on
\r
535 time, but we will update this soon. Please talk to us on IRC if you need to
\r
536 know stuff <strong>NOW</strong> :).</p></div>
\r
539 <div class="sect2">
\r
540 <h3 id="_client">3.5. Client</h3>
\r
541 <div class="paragraph"><p>A client is x11-speak for a window.</p></div>
\r
545 <div class="sect1">
\r
546 <h2 id="_list_queue_macros">4. List/queue macros</h2>
\r
547 <div class="sectionbody">
\r
548 <div class="paragraph"><p>i3 makes heavy use of the list macros defined in BSD operating systems. To
\r
549 ensure that the operating system on which i3 is compiled has all the expected
\r
550 features, i3 comes with <tt>include/queue.h</tt>. On BSD systems, you can use man
\r
551 <tt>queue(3)</tt>. On Linux, you have to use google (or read the source).</p></div>
\r
552 <div class="paragraph"><p>The lists used are <tt>SLIST</tt> (single linked lists), <tt>CIRCLEQ</tt> (circular
\r
553 queues) and <tt>TAILQ</tt> (tail queues). Usually, only forward traversal is necessary,
\r
554 so an <tt>SLIST</tt> works fine. If inserting elements at arbitrary positions or at
\r
555 the end of a list is necessary, a <tt>TAILQ</tt> is used instead. However, for the
\r
556 windows inside a container, a <tt>CIRCLEQ</tt> is necessary to go from the currently
\r
557 selected window to the window above/below.</p></div>
\r
560 <div class="sect1">
\r
561 <h2 id="_naming_conventions">5. Naming conventions</h2>
\r
562 <div class="sectionbody">
\r
563 <div class="paragraph"><p>There is a row of standard variables used in many events. The following names
\r
564 should be chosen for those:</p></div>
\r
565 <div class="ulist"><ul>
\r
568 “conn” is the xcb_connection_t
\r
573 “event” is the event of the particular type
\r
578 “con” names a container
\r
583 “current” is a loop variable when using <tt>TAILQ_FOREACH</tt> etc.
\r
589 <div class="sect1">
\r
590 <h2 id="_startup_src_mainx_c_main">6. Startup (src/mainx.c, main())</h2>
\r
591 <div class="sectionbody">
\r
592 <div class="ulist"><ul>
\r
595 Establish the xcb connection
\r
600 Check for XKB extension on the separate X connection, load Xcursor
\r
605 Check for RandR screens (with a fall-back to Xinerama)
\r
610 Grab the keycodes for which bindings exist
\r
615 Manage all existing windows
\r
620 Enter the event loop
\r
626 <div class="sect1">
\r
627 <h2 id="_keybindings">7. Keybindings</h2>
\r
628 <div class="sectionbody">
\r
629 <div class="sect2">
\r
630 <h3 id="_grabbing_the_bindings">7.1. Grabbing the bindings</h3>
\r
631 <div class="paragraph"><p>Grabbing the bindings is quite straight-forward. You pass X your combination of
\r
632 modifiers and the keycode you want to grab and whether you want to grab them
\r
633 actively or passively. Most bindings (everything except for bindings using
\r
634 Mode_switch) are grabbed passively, that is, just the window manager gets the
\r
635 event and cannot replay it.</p></div>
\r
636 <div class="paragraph"><p>We need to grab bindings that use Mode_switch actively because of a bug in X.
\r
637 When the window manager receives the keypress/keyrelease event for an actively
\r
638 grabbed keycode, it has to decide what to do with this event: It can either
\r
639 replay it so that other applications get it or it can prevent other
\r
640 applications from receiving it.</p></div>
\r
641 <div class="paragraph"><p>So, why do we need to grab keycodes actively? Because X does not set the
\r
642 state-property of keypress/keyrelease events properly. The Mode_switch bit is
\r
643 not set and we need to get it using XkbGetState. This means we cannot pass X
\r
644 our combination of modifiers containing Mode_switch when grabbing the key and
\r
645 therefore need to grab the keycode itself without any modifiers. This means,
\r
646 if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
\r
647 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
\r
648 will handle the event, if not, it will replay the event.</p></div>
\r
650 <div class="sect2">
\r
651 <h3 id="_handling_a_keypress">7.2. Handling a keypress</h3>
\r
652 <div class="paragraph"><p>As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
\r
653 the correct state.</p></div>
\r
654 <div class="paragraph"><p>Then, it looks through all bindings and gets the one which matches the received
\r
656 <div class="paragraph"><p>The bound command is parsed by the cmdparse lexer/parser, see <tt>parse_cmd</tt> in
\r
657 <tt>src/cmdparse.y</tt>.</p></div>
\r
661 <div class="sect1">
\r
662 <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
663 <div class="sectionbody">
\r
664 <div class="paragraph"><p><tt>manage_window()</tt> does some checks to decide whether the window should be
\r
665 managed at all:</p></div>
\r
666 <div class="ulist"><ul>
\r
669 Windows have to be mapped, that is, visible on screen
\r
674 The override_redirect must not be set. Windows with override_redirect shall
\r
675 not be managed by a window manager
\r
679 <div class="paragraph"><p>Afterwards, i3 gets the intial geometry and reparents the window (see
\r
680 <tt>reparent_window()</tt>) if it wasn’t already managed.</p></div>
\r
681 <div class="paragraph"><p>Reparenting means that for each window which is reparented, a new window,
\r
682 slightly larger than the original one, is created. The original window is then
\r
683 reparented to the bigger one (called "frame").</p></div>
\r
684 <div class="paragraph"><p>After reparenting, the window type (<tt>_NET_WM_WINDOW_TYPE</tt>) is checked to see
\r
685 whether this window is a dock (<tt>_NET_WM_WINDOW_TYPE_DOCK</tt>), like dzen2 for
\r
686 example. Docks are handled differently, they don’t have decorations and are not
\r
687 assigned to a specific container. Instead, they are positioned at the bottom
\r
688 of the screen. To get the height which needs to be reserved for the window,
\r
689 the <tt>_NET_WM_STRUT_PARTIAL</tt> property is used.</p></div>
\r
690 <div class="paragraph"><p>Furthermore, the list of assignments (to other workspaces, which may be on
\r
691 other screens) is checked. If the window matches one of the user’s criteria,
\r
692 it may either be put in floating mode or moved to a different workspace. If the
\r
693 target workspace is not visible, the window will not be mapped.</p></div>
\r
696 <div class="sect1">
\r
697 <h2 id="_what_happens_when_an_application_is_started">9. What happens when an application is started?</h2>
\r
698 <div class="sectionbody">
\r
699 <div class="paragraph"><p>i3 does not care for applications. All it notices is when new windows are
\r
700 mapped (see <tt>src/handlers.c</tt>, <tt>handle_map_request()</tt>). The window is then
\r
701 reparented (see section "Manage windows").</p></div>
\r
702 <div class="paragraph"><p>After reparenting the window, <tt>render_tree()</tt> is called which renders the
\r
703 internal layout table. The new window has been placed in the currently focused
\r
704 container and therefore the new window and the old windows (if any) need to be
\r
705 moved/resized so that the currently active layout (default/stacking/tabbed mode)
\r
706 is rendered correctly. To move/resize windows, a window is “configured” in
\r
707 X11-speak.</p></div>
\r
708 <div class="paragraph"><p>Some applications, such as MPlayer obviously assume the window manager is
\r
709 stupid and try to configure their windows by themselves. This generates an
\r
710 event called configurerequest. i3 handles these events and tells the window the
\r
711 size it had before the configurerequest (with the exception of not yet mapped
\r
712 windows, which get configured like they want to, and floating windows, which
\r
713 can reconfigure themselves).</p></div>
\r
716 <div class="sect1">
\r
717 <h2 id="_net_wm_state">10. _NET_WM_STATE</h2>
\r
718 <div class="sectionbody">
\r
719 <div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls
\r
720 “toggle_fullscreen()” for the specific client which just configures the
\r
721 client to use the whole screen on which it currently is. Also, it is set as
\r
722 fullscreen_client for the i3Screen.</p></div>
\r
725 <div class="sect1">
\r
726 <h2 id="_wm_name">11. WM_NAME</h2>
\r
727 <div class="sectionbody">
\r
728 <div class="paragraph"><p>When the WM_NAME property of a window changes, its decoration (containing the
\r
729 title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
\r
730 totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
\r
731 if present.</p></div>
\r
734 <div class="sect1">
\r
735 <h2 id="_net_wm_name">12. _NET_WM_NAME</h2>
\r
736 <div class="sectionbody">
\r
737 <div class="paragraph"><p>Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
\r
738 is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
\r
739 to X. Using an appropriate font (ISO-10646), you can see most special
\r
740 characters (every special character contained in your font).</p></div>
\r
743 <div class="sect1">
\r
744 <h2 id="_size_hints">13. Size hints</h2>
\r
745 <div class="sectionbody">
\r
746 <div class="paragraph"><p>Size hints specify the minimum/maximum size for a given window as well as its
\r
747 aspect ratio. This is important for clients like mplayer, who only set the
\r
748 aspect ratio and resize their window to be as small as possible (but only with
\r
749 some video outputs, for example in Xv, while when using x11, mplayer does the
\r
750 necessary centering for itself).</p></div>
\r
751 <div class="paragraph"><p>So, when an aspect ratio was specified, i3 adjusts the height of the window
\r
752 until the size maintains the correct aspect ratio. For the code to do this, see
\r
753 src/layout.c, function resize_client().</p></div>
\r
756 <div class="sect1">
\r
757 <h2 id="_rendering_src_layout_c_render_layout_and_render_container">14. Rendering (src/layout.c, render_layout() and render_container())</h2>
\r
758 <div class="sectionbody">
\r
759 <div class="sidebarblock">
\r
760 <div class="content">
\r
761 <div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on
\r
762 time, but we will update this soon. Please talk to us on IRC if you need to
\r
763 know stuff <strong>NOW</strong> :).</p></div>
\r
767 <div class="sect1">
\r
768 <h2 id="_user_commands_commandmode_src_cmdparse_l_y">15. User commands / commandmode (src/cmdparse.{l,y})</h2>
\r
769 <div class="sectionbody">
\r
770 <div class="sidebarblock">
\r
771 <div class="content">
\r
772 <div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on
\r
773 time, but we will update this soon. Please talk to us on IRC if you need to
\r
774 know stuff <strong>NOW</strong> :).</p></div>
\r
778 <div class="sect1">
\r
779 <h2 id="_moving_containers">16. Moving containers</h2>
\r
780 <div class="sectionbody">
\r
781 <div class="paragraph"><p>The movement code is pretty delicate. You need to consider all cases before
\r
782 making any changes or before being able to fully understand how it works.</p></div>
\r
783 <div class="sect2">
\r
784 <h3 id="_case_1_moving_inside_the_same_container">16.1. Case 1: Moving inside the same container</h3>
\r
785 <div class="paragraph"><p>The reference layout for this case is a single workspace in horizontal
\r
786 orientation with two containers on it. Focus is on the left container (1).</p></div>
\r
787 <div class="tableblock">
\r
791 cellspacing="0" cellpadding="4">
\r
792 <col width="50%" />
\r
793 <col width="50%" />
\r
796 <td align="center" valign="top"><p class="table">1</p></td>
\r
797 <td align="center" valign="top"><p class="table">2</p></td>
\r
802 <div class="paragraph"><p>When moving the left window to the right (command <tt>move right</tt>), tree_move will
\r
803 look for a container with horizontal orientation and finds the parent of the
\r
804 left container, that is, the workspace. Afterwards, it runs the code branch
\r
805 commented with "the easy case": it calls TAILQ_NEXT to get the container right
\r
806 of the current one and swaps both containers.</p></div>
\r
808 <div class="sect2">
\r
809 <h3 id="_case_2_move_a_container_into_a_split_container">16.2. Case 2: Move a container into a split container</h3>
\r
810 <div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
\r
811 containers. The right container is a v-split with two containers. Focus is on
\r
812 the left container (1).</p></div>
\r
813 <div class="tableblock">
\r
817 cellspacing="0" cellpadding="4">
\r
818 <col width="50%" />
\r
819 <col width="50%" />
\r
822 <td rowspan="2" align="center" valign="middle"><p class="table">1</p></td>
\r
823 <td align="center" valign="top"><p class="table">2</p></td>
\r
826 <td align="center" valign="top"><p class="table">3</p></td>
\r
831 <div class="paragraph"><p>When moving to the right (command <tt>move right</tt>), i3 will work like in case 1
\r
832 ("the easy case"). However, as the right container is not a leaf container, but
\r
833 a v-split, the left container (1) will be inserted at the right position (below
\r
834 2, assuming that 2 is focused inside the v-split) by calling <tt>insert_con_into</tt>.</p></div>
\r
835 <div class="paragraph"><p><tt>insert_con_into</tt> detaches the container from its parent and inserts it
\r
836 before/after the given target container. Afterwards, the on_remove_child
\r
837 callback is called on the old parent container which will then be closed, if
\r
839 <div class="paragraph"><p>Afterwards, <tt>con_focus</tt> will be called to fix the focus stack and the tree will
\r
840 be flattened.</p></div>
\r
842 <div class="sect2">
\r
843 <h3 id="_case_3_moving_to_non_existant_top_bottom">16.3. Case 3: Moving to non-existant top/bottom</h3>
\r
844 <div class="paragraph"><p>Like in case 1, the reference layout for this case is a single workspace in
\r
845 horizontal orientation with two containers on it. Focus is on the left
\r
846 container:</p></div>
\r
847 <div class="tableblock">
\r
851 cellspacing="0" cellpadding="4">
\r
852 <col width="50%" />
\r
853 <col width="50%" />
\r
856 <td align="center" valign="top"><p class="table">1</p></td>
\r
857 <td align="center" valign="top"><p class="table">2</p></td>
\r
862 <div class="paragraph"><p>This time however, the command is <tt>move up</tt> or <tt>move down</tt>. tree_move will look
\r
863 for a container with vertical orientation. As it will not find any,
\r
864 <tt>same_orientation</tt> is NULL and therefore i3 will perform a forced orientation
\r
865 change on the workspace by creating a new h-split container, moving the
\r
866 workspace contents into it and then changing the workspace orientation to
\r
867 vertical. Now it will again search for parent containers with vertical
\r
868 orientation and it will find the workspace.</p></div>
\r
869 <div class="paragraph"><p>This time, the easy case code path will not be run as we are not moving inside
\r
870 the same container. Instead, <tt>insert_con_into</tt> will be called with the focused
\r
871 container and the container above/below the current one (on the level of
\r
872 <tt>same_orientation</tt>).</p></div>
\r
873 <div class="paragraph"><p>Now, <tt>con_focus</tt> will be called to fix the focus stack and the tree will be
\r
874 flattened.</p></div>
\r
876 <div class="sect2">
\r
877 <h3 id="_case_4_moving_to_existant_top_bottom">16.4. Case 4: Moving to existant top/bottom</h3>
\r
878 <div class="paragraph"><p>The reference layout for this case is a vertical workspace with two containers.
\r
879 The bottom one is a h-split containing two containers (1 and 2). Focus is on
\r
880 the bottom left container (1).</p></div>
\r
881 <div class="tableblock">
\r
885 cellspacing="0" cellpadding="4">
\r
886 <col width="50%" />
\r
887 <col width="50%" />
\r
890 <td colspan="2" align="center" valign="top"><p class="table">3</p></td>
\r
893 <td align="center" valign="top"><p class="table">1</p></td>
\r
894 <td align="center" valign="top"><p class="table">2</p></td>
\r
899 <div class="paragraph"><p>This case is very much like case 3, only this time the forced workspace
\r
900 orientation change does not need to be performed because the workspace already
\r
901 is in vertical orientation.</p></div>
\r
903 <div class="sect2">
\r
904 <h3 id="_case_5_moving_in_one_child_h_split">16.5. Case 5: Moving in one-child h-split</h3>
\r
905 <div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
\r
906 containers having a v-split on the left side with a one-child h-split on the
\r
907 bottom. Focus is on the bottom left container (2(h)):</p></div>
\r
908 <div class="tableblock">
\r
912 cellspacing="0" cellpadding="4">
\r
913 <col width="50%" />
\r
914 <col width="50%" />
\r
917 <td align="center" valign="top"><p class="table">1</p></td>
\r
918 <td rowspan="2" align="center" valign="middle"><p class="table">3</p></td>
\r
921 <td align="center" valign="top"><p class="table">2(h)</p></td>
\r
926 <div class="paragraph"><p>In this case, <tt>same_orientation</tt> will be set to the h-split container around
\r
927 the focused container. However, when trying the easy case, the next/previous
\r
928 container <tt>swap</tt> will be NULL. Therefore, i3 will search again for a
\r
929 <tt>same_orientation</tt> container, this time starting from the parent of the h-split
\r
930 container.</p></div>
\r
931 <div class="paragraph"><p>After determining a new <tt>same_orientation</tt> container (if it is NULL, the
\r
932 orientation will be force-changed), this case is equivalent to case 2 or case
\r
935 <div class="sect2">
\r
936 <h3 id="_case_6_floating_containers">16.6. Case 6: Floating containers</h3>
\r
937 <div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
\r
938 containers plus one floating h-split container. Focus is on the floating
\r
939 container.</p></div>
\r
940 <div class="paragraph"><p>TODO: nice illustration. table not possible?</p></div>
\r
941 <div class="paragraph"><p>When moving up/down, the container needs to leave the floating container and it
\r
942 needs to be placed on the workspace (at workspace level). This is accomplished
\r
943 by calling the function <tt>attach_to_workspace</tt>.</p></div>
\r
947 <div class="sect1">
\r
948 <h2 id="_click_handling">17. Click handling</h2>
\r
949 <div class="sectionbody">
\r
950 <div class="paragraph"><p>Without much ado, here is the list of cases which need to be considered:</p></div>
\r
951 <div class="ulist"><ul>
\r
954 click to focus (tiling + floating) and raise (floating)
\r
959 click to focus/raise when in stacked/tabbed mode
\r
964 floating_modifier + left mouse button to drag a floating con
\r
969 floating_modifier + right mouse button to resize a floating con
\r
974 click on decoration in a floating con to either initiate a resize (if there
\r
975 is more than one child in the floating con) or to drag the
\r
976 floating con (if it’s the one at the top).
\r
981 click on border in a floating con to resize the floating con
\r
986 floating_modifier + right mouse button to resize a tiling con
\r
991 click on border/decoration to resize a tiling con
\r
997 <div class="sect1">
\r
998 <h2 id="_gotchas">18. Gotchas</h2>
\r
999 <div class="sectionbody">
\r
1000 <div class="ulist"><ul>
\r
1003 Forgetting to call <tt>xcb_flush(conn);</tt> after sending a request. This usually
\r
1004 leads to code which looks like it works fine but which does not work under
\r
1005 certain conditions.
\r
1011 <div class="sect1">
\r
1012 <h2 id="_using_git_sending_patches">19. Using git / sending patches</h2>
\r
1013 <div class="sectionbody">
\r
1014 <div class="paragraph"><p>For a short introduction into using git, see
\r
1015 <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
1016 <a href="http://git-scm.com/documentation">http://git-scm.com/documentation</a></p></div>
\r
1017 <div class="paragraph"><p>When you want to send a patch because you fixed a bug or implemented a cool
\r
1018 feature (please talk to us before working on features to see whether they are
\r
1019 maybe already implemented, not possible for some some reason, or don’t fit
\r
1020 into the concept), please use git to create a patchfile.</p></div>
\r
1021 <div class="paragraph"><p>First of all, update your working copy to the latest version of the master
\r
1023 <div class="listingblock">
\r
1024 <div class="content">
\r
1025 <pre><tt>git pull</tt></pre>
\r
1027 <div class="paragraph"><p>Afterwards, make the necessary changes for your bugfix/feature. Then, review
\r
1028 the changes using <tt>git diff</tt> (you might want to enable colors in the diff using
\r
1029 <tt>git config diff.color auto</tt>). When you are definitely done, use <tt>git commit
\r
1030 -a</tt> to commit all changes you’ve made.</p></div>
\r
1031 <div class="paragraph"><p>Then, use the following command to generate a patchfile which we can directly
\r
1032 apply to the branch, preserving your commit message and name:</p></div>
\r
1033 <div class="listingblock">
\r
1034 <div class="content">
\r
1035 <pre><tt>git format-patch origin</tt></pre>
\r
1037 <div class="paragraph"><p>Just send us the generated file via email.</p></div>
\r
1041 <div id="footnotes"><hr /></div>
\r
1042 <div id="footer" lang="de">
\r
1043 © 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>
\r
projects / i3 / i3.github.io / blob