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">December 2009</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="paragraph"><p>To accomplish flexible layouts, we decided to simply use a table. The table
\r
146 grows and shrinks as you need it. Each cell holds a container which then holds
\r
147 windows (see picture below). You can use different layouts for each container
\r
148 (default layout and stacking layout).</p></div>
\r
149 <div class="paragraph"><p>So, when you open a terminal and immediately open another one, they reside in
\r
150 the same container, in default layout. The layout table has exactly one column,
\r
151 one row and therefore one cell. When you move one of the terminals to the
\r
152 right, the table needs to grow. It will be expanded to two columns and one row.
\r
153 This enables you to have different layouts for each container. The table then
\r
154 looks like this:</p></div>
\r
155 <div class="tableblock">
\r
159 cellspacing="0" cellpadding="4">
\r
160 <col width="50%" />
\r
161 <col width="50%" />
\r
164 <td align="center" valign="top"><p class="table">T1</p></td>
\r
165 <td align="center" valign="top"><p class="table">T2</p></td>
\r
170 <div class="paragraph"><p>When moving terminal 2 to the bottom, the table will be expanded again.</p></div>
\r
171 <div class="tableblock">
\r
175 cellspacing="0" cellpadding="4">
\r
176 <col width="50%" />
\r
177 <col width="50%" />
\r
180 <td align="center" valign="top"><p class="table">T1</p></td>
\r
181 <td align="center" valign="top"><p class="table"></p></td>
\r
184 <td align="center" valign="top"><p class="table"></p></td>
\r
185 <td align="center" valign="top"><p class="table">T2</p></td>
\r
190 <div class="paragraph"><p>You can really think of the layout table like a traditional HTML table, if
\r
191 you’ve ever designed one. Especially col- and rowspan work similarly. Below,
\r
192 you see an example of colspan=2 for the first container (which has T1 as
\r
194 <div class="tableblock">
\r
198 cellspacing="0" cellpadding="4">
\r
199 <col width="100%" />
\r
202 <td align="center" valign="top"><div><div class="literalblock">
\r
203 <div class="content">
\r
204 <pre><tt>T1</tt></pre>
\r
205 </div></div></div></td>
\r
208 <td align="center" valign="top"><div><div class="tableblock">
\r
212 cellspacing="0" cellpadding="4">
\r
213 <col width="50%" />
\r
214 <col width="50%" />
\r
217 <td align="center" valign="top"><p class="table">T2</p></td>
\r
218 <td align="center" valign="top"><p class="table">T3</p></td>
\r
227 <div class="paragraph"><p>Furthermore, you can freely resize table cells.</p></div>
\r
231 <div class="sect1">
\r
232 <h2 id="_files">2. Files</h2>
\r
233 <div class="sectionbody">
\r
234 <div class="dlist"><dl>
\r
235 <dt class="hdlist1">
\r
240 Contains data definitions used by nearly all files. You really need to read
\r
244 <dt class="hdlist1">
\r
249 Contains forward definitions for all public functions, as well as
\r
250 doxygen-compatible comments (so if you want to get a bit more of the big
\r
251 picture, either browse all header files or use doxygen if you prefer that).
\r
254 <dt class="hdlist1">
\r
259 Contains the lexer for i3’s configuration file, written for <tt>flex(1)</tt>.
\r
262 <dt class="hdlist1">
\r
267 Contains the parser for i3’s configuration file, written for <tt>bison(1)</tt>.
\r
270 <dt class="hdlist1">
\r
275 Contains all functions which handle mouse button clicks (right mouse button
\r
276 clicks initiate resizing and thus are relatively complex).
\r
279 <dt class="hdlist1">
\r
284 Contains all functions which are specific to a certain client (make it
\r
285 fullscreen, see if its class/name matches a pattern, kill it, …).
\r
288 <dt class="hdlist1">
\r
293 Parsing commands and actually executing them (focusing, moving, …).
\r
296 <dt class="hdlist1">
\r
301 Parses the configuration file.
\r
304 <dt class="hdlist1">
\r
309 Contains debugging functions to print unhandled X events.
\r
312 <dt class="hdlist1">
\r
317 Contains functions for floating mode (mostly resizing/dragging).
\r
320 <dt class="hdlist1">
\r
325 Contains all handlers for all kinds of X events (new window title, new hints,
\r
326 unmapping, key presses, button presses, …).
\r
329 <dt class="hdlist1">
\r
334 Contains code for the IPC interface.
\r
337 <dt class="hdlist1">
\r
342 Renders your layout (screens, workspaces, containers).
\r
345 <dt class="hdlist1">
\r
350 Initializes the window manager.
\r
353 <dt class="hdlist1">
\r
358 Looks at existing or new windows and decides whether to manage them. If so, it
\r
359 reparents the window and inserts it into our data structures.
\r
362 <dt class="hdlist1">
\r
367 Contains the functions to resize columns/rows in the table.
\r
370 <dt class="hdlist1">
\r
375 Manages the most important internal data structure, the design table.
\r
378 <dt class="hdlist1">
\r
383 Contains useful functions which are not really dependant on anything.
\r
386 <dt class="hdlist1">
\r
391 Contains all functions related to workspaces (displaying, hiding, renaming…)
\r
394 <dt class="hdlist1">
\r
399 Contains wrappers to use xcb more easily.
\r
402 <dt class="hdlist1">
\r
407 (Re-)initializes the available screens and converts them to virtual screens
\r
414 <div class="sect1">
\r
415 <h2 id="_data_structures">3. Data structures</h2>
\r
416 <div class="sectionbody">
\r
417 <div class="paragraph"><p>See include/data.h for documented data structures. The most important ones are
\r
418 explained right here.</p></div>
\r
419 <div class="paragraph"><p><span class="image">
\r
420 <img src="bigpicture.png" alt="The Big Picture" />
\r
422 <div class="paragraph"><p>So, the hierarchy is:</p></div>
\r
423 <div class="olist arabic"><ol class="arabic">
\r
426 <strong>Virtual screens</strong> (Screen 0 in this example)
\r
431 <strong>Workspaces</strong> (Workspace 1 in this example)
\r
436 <strong>Table</strong> (There can only be one table per Workspace)
\r
441 <strong>Container</strong> (left and right in this example)
\r
446 <strong>Client</strong> (The two clients in the left container)
\r
450 <div class="sect2">
\r
451 <h3 id="_virtual_screens">3.1. Virtual screens</h3>
\r
452 <div class="paragraph"><p>A virtual screen (type <tt>i3Screen</tt>) is generated from the connected screens
\r
453 obtained through Xinerama. The difference to the raw Xinerama monitors as seen
\r
454 when using <tt>xrandr(1)</tt> is that it falls back to the lowest common resolution of
\r
455 the logical screens.</p></div>
\r
456 <div class="paragraph"><p>For example, if your notebook has 1280x800 and you connect a video projector
\r
457 with 1024x768, set up in clone mode (<tt>xrandr --output VGA --mode 1024x768
\r
458 --same-as LVDS</tt>), i3 will have one virtual screen.</p></div>
\r
459 <div class="paragraph"><p>However, if you configure it using <tt>xrandr --output VGA --mode 1024x768
\r
460 --right-of LVDS</tt>, i3 will generate two virtual screens. For each virtual
\r
461 screen, a new workspace will be assigned. New workspaces are created on the
\r
462 screen you are currently on.</p></div>
\r
464 <div class="sect2">
\r
465 <h3 id="_workspace">3.2. Workspace</h3>
\r
466 <div class="paragraph"><p>A workspace is identified by its number. Basically, you could think of
\r
467 workspaces as different desks in your office, if you like the desktop
\r
468 methaphor. They just contain different sets of windows and are completely
\r
469 separate of each other. Other window managers also call this “Virtual
\r
470 desktops”.</p></div>
\r
472 <div class="sect2">
\r
473 <h3 id="_the_layout_table_2">3.3. The layout table</h3>
\r
474 <div class="paragraph"><p>Each workspace has a table, which is just a two-dimensional dynamic array
\r
475 containing Containers (see below). This table grows and shrinks as you need it
\r
476 (by moving windows to the right you can create a new column in the table, by
\r
477 moving them to the bottom you create a new row).</p></div>
\r
479 <div class="sect2">
\r
480 <h3 id="_container">3.4. Container</h3>
\r
481 <div class="paragraph"><p>A container is the content of a table’s cell. It holds an arbitrary amount of
\r
482 windows and has a specific layout (default layout, stack layout or tabbed
\r
483 layout). Containers can consume multiple table cells by modifying their
\r
484 colspan/rowspan attribute.</p></div>
\r
486 <div class="sect2">
\r
487 <h3 id="_client">3.5. Client</h3>
\r
488 <div class="paragraph"><p>A client is x11-speak for a window.</p></div>
\r
492 <div class="sect1">
\r
493 <h2 id="_list_queue_macros">4. List/queue macros</h2>
\r
494 <div class="sectionbody">
\r
495 <div class="paragraph"><p>i3 makes heavy use of the list macros defined in BSD operating systems. To
\r
496 ensure that the operating system on which i3 is compiled has all the expected
\r
497 features, i3 comes with <tt>include/queue.h</tt>. On BSD systems, you can use man
\r
498 <tt>queue(3)</tt>. On Linux, you have to use google (or read the source).</p></div>
\r
499 <div class="paragraph"><p>The lists used are <tt>SLIST</tt> (single linked lists), <tt>CIRCLEQ</tt> (circular
\r
500 queues) and TAILQ (tail queues). Usually, only forward traversal is necessary,
\r
501 so an <tt>SLIST</tt> works fine. If inserting elements at arbitrary positions or at
\r
502 the end of a list is necessary, a <tt>TAILQ</tt> is used instead. However, for the
\r
503 windows inside a container, a <tt>CIRCLEQ</tt> is necessary to go from the currently
\r
504 selected window to the window above/below.</p></div>
\r
507 <div class="sect1">
\r
508 <h2 id="_naming_conventions">5. Naming conventions</h2>
\r
509 <div class="sectionbody">
\r
510 <div class="paragraph"><p>There is a row of standard variables used in many events. The following names
\r
511 should be chosen for those:</p></div>
\r
512 <div class="ulist"><ul>
\r
515 “conn” is the xcb_connection_t
\r
520 “event” is the event of the particular type
\r
525 “container” names a container
\r
530 “client” names a client, for example when using a <tt>CIRCLEQ_FOREACH</tt>
\r
536 <div class="sect1">
\r
537 <h2 id="_startup_src_mainx_c_main">6. Startup (src/mainx.c, main())</h2>
\r
538 <div class="sectionbody">
\r
539 <div class="ulist"><ul>
\r
542 Establish the xcb connection
\r
547 Check for XKB extension on the separate X connection
\r
552 Check for Xinerama screens
\r
557 Grab the keycodes for which bindings exist
\r
562 Manage all existing windows
\r
567 Enter the event loop
\r
573 <div class="sect1">
\r
574 <h2 id="_keybindings">7. Keybindings</h2>
\r
575 <div class="sectionbody">
\r
576 <div class="sect2">
\r
577 <h3 id="_grabbing_the_bindings">7.1. Grabbing the bindings</h3>
\r
578 <div class="paragraph"><p>Grabbing the bindings is quite straight-forward. You pass X your combination of
\r
579 modifiers and the keycode you want to grab and whether you want to grab them
\r
580 actively or passively. Most bindings (everything except for bindings using
\r
581 Mode_switch) are grabbed passively, that is, just the window manager gets the
\r
582 event and cannot replay it.</p></div>
\r
583 <div class="paragraph"><p>We need to grab bindings that use Mode_switch actively because of a bug in X.
\r
584 When the window manager receives the keypress/keyrelease event for an actively
\r
585 grabbed keycode, it has to decide what to do with this event: It can either
\r
586 replay it so that other applications get it or it can prevent other
\r
587 applications from receiving it.</p></div>
\r
588 <div class="paragraph"><p>So, why do we need to grab keycodes actively? Because X does not set the
\r
589 state-property of keypress/keyrelease events properly. The Mode_switch bit is
\r
590 not set and we need to get it using XkbGetState. This means we cannot pass X
\r
591 our combination of modifiers containing Mode_switch when grabbing the key and
\r
592 therefore need to grab the keycode itself without any modifiers. This means,
\r
593 if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
\r
594 check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
\r
595 will handle the event, if not, it will replay the event.</p></div>
\r
597 <div class="sect2">
\r
598 <h3 id="_handling_a_keypress">7.2. Handling a keypress</h3>
\r
599 <div class="paragraph"><p>As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
\r
600 the correct state.</p></div>
\r
601 <div class="paragraph"><p>Then, it looks through all bindings and gets the one which matches the received
\r
603 <div class="paragraph"><p>The bound command is parsed directly in command mode.</p></div>
\r
607 <div class="sect1">
\r
608 <h2 id="_manage_windows_src_mainx_c_manage_window_and_reparent_window">8. Manage windows (src/mainx.c, manage_window() and reparent_window())</h2>
\r
609 <div class="sectionbody">
\r
610 <div class="paragraph"><p><tt>manage_window()</tt> does some checks to decide whether the window should be
\r
611 managed at all:</p></div>
\r
612 <div class="ulist"><ul>
\r
615 Windows have to be mapped, that is, visible on screen
\r
620 The override_redirect must not be set. Windows with override_redirect shall
\r
621 not be managed by a window manager
\r
625 <div class="paragraph"><p>Afterwards, i3 gets the intial geometry and reparents the window (see
\r
626 <tt>reparent_window()</tt>) if it wasn’t already managed.</p></div>
\r
627 <div class="paragraph"><p>Reparenting means that for each window which is reparented, a new window,
\r
628 slightly larger than the original one, is created. The original window is then
\r
629 reparented to the bigger one (called "frame").</p></div>
\r
630 <div class="paragraph"><p>After reparenting, the window type (<tt>_NET_WM_WINDOW_TYPE</tt>) is checked to see
\r
631 whether this window is a dock (<tt>_NET_WM_WINDOW_TYPE_DOCK</tt>), like dzen2 for
\r
632 example. Docks are handled differently, they don’t have decorations and are not
\r
633 assigned to a specific container. Instead, they are positioned at the bottom
\r
634 of the screen. To get the height which needsd to be reserved for the window,
\r
635 the <tt>_NET_WM_STRUT_PARTIAL</tt> property is used.</p></div>
\r
636 <div class="paragraph"><p>Furthermore, the list of assignments (to other workspaces, which may be on
\r
637 other screens) is checked. If the window matches one of the user’s criteria,
\r
638 it may either be put in floating mode or moved to a different workspace. If the
\r
639 target workspace is not visible, the window will not be mapped.</p></div>
\r
642 <div class="sect1">
\r
643 <h2 id="_what_happens_when_an_application_is_started">9. What happens when an application is started?</h2>
\r
644 <div class="sectionbody">
\r
645 <div class="paragraph"><p>i3 does not care for applications. All it notices is when new windows are
\r
646 mapped (see <tt>src/handlers.c</tt>, <tt>handle_map_request()</tt>). The window is then
\r
647 reparented (see section "Manage windows").</p></div>
\r
648 <div class="paragraph"><p>After reparenting the window, <tt>render_layout()</tt> is called which renders the
\r
649 internal layout table. The new window has been placed in the currently focused
\r
650 container and therefore the new window and the old windows (if any) need to be
\r
651 moved/resized so that the currently active layout (default/stacking/tabbed mode)
\r
652 is rendered correctly. To move/resize windows, a window is “configured” in
\r
653 X11-speak.</p></div>
\r
654 <div class="paragraph"><p>Some applications, such as MPlayer obviously assume the window manager is
\r
655 stupid and try to configure their windows by themselves. This generates an
\r
656 event called configurerequest. i3 handles these events and tells the window the
\r
657 size it had before the configurerequest (with the exception of not yet mapped
\r
658 windows, which get configured like they want to, and floating windows, which
\r
659 can reconfigure themselves).</p></div>
\r
662 <div class="sect1">
\r
663 <h2 id="_net_wm_state">10. _NET_WM_STATE</h2>
\r
664 <div class="sectionbody">
\r
665 <div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls
\r
666 “toggle_fullscreen()” for the specific client which just configures the
\r
667 client to use the whole screen on which it currently is. Also, it is set as
\r
668 fullscreen_client for the i3Screen.</p></div>
\r
671 <div class="sect1">
\r
672 <h2 id="_wm_name">11. WM_NAME</h2>
\r
673 <div class="sectionbody">
\r
674 <div class="paragraph"><p>When the WM_NAME property of a window changes, its decoration (containing the
\r
675 title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
\r
676 totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
\r
677 if present.</p></div>
\r
680 <div class="sect1">
\r
681 <h2 id="_net_wm_name">12. _NET_WM_NAME</h2>
\r
682 <div class="sectionbody">
\r
683 <div class="paragraph"><p>Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
\r
684 is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
\r
685 to X. Using an appropriate font (ISO-10646), you can see most special
\r
686 characters (every special character contained in your font).</p></div>
\r
689 <div class="sect1">
\r
690 <h2 id="_size_hints">13. Size hints</h2>
\r
691 <div class="sectionbody">
\r
692 <div class="paragraph"><p>Size hints specify the minimum/maximum size for a given window as well as its
\r
693 aspect ratio. This is important for clients like mplayer, who only set the
\r
694 aspect ratio and resize their window to be as small as possible (but only with
\r
695 some video outputs, for example in Xv, while when using x11, mplayer does the
\r
696 necessary centering for itself).</p></div>
\r
697 <div class="paragraph"><p>So, when an aspect ratio was specified, i3 adjusts the height of the window
\r
698 until the size maintains the correct aspect ratio. For the code to do this, see
\r
699 src/layout.c, function resize_client().</p></div>
\r
702 <div class="sect1">
\r
703 <h2 id="_rendering_src_layout_c_render_layout_and_render_container">14. Rendering (src/layout.c, render_layout() and render_container())</h2>
\r
704 <div class="sectionbody">
\r
705 <div class="paragraph"><p>There are several entry points to rendering: <tt>render_layout()</tt>,
\r
706 <tt>render_workspace()</tt> and <tt>render_container()</tt>. The former one calls
\r
707 <tt>render_workspace()</tt> for every screen, which in turn will call
\r
708 <tt>render_container()</tt> for every container inside its layout table. Therefore, if
\r
709 you need to render only a single container, for example because a window was
\r
710 removed, added or changed its title, you should directly call
\r
711 render_container().</p></div>
\r
712 <div class="paragraph"><p>Rendering consists of two steps: In the first one, in <tt>render_workspace()</tt>, each
\r
713 container gets its position (screen offset + offset in the table) and size
\r
714 (container’s width times colspan/rowspan). Then, <tt>render_container()</tt> is called,
\r
715 which takes different approaches, depending on the mode the container is in:</p></div>
\r
716 <div class="sect2">
\r
717 <h3 id="_common_parts">14.1. Common parts</h3>
\r
718 <div class="paragraph"><p>On the frame (the window which was created around the client’s window for the
\r
719 decorations), a black rectangle is drawn as a background for windows like
\r
720 MPlayer, which do not completely fit into the frame.</p></div>
\r
722 <div class="sect2">
\r
723 <h3 id="_default_mode">14.2. Default mode</h3>
\r
724 <div class="paragraph"><p>Each clients gets the container’s width and an equal amount of height.</p></div>
\r
726 <div class="sect2">
\r
727 <h3 id="_stack_mode">14.3. Stack mode</h3>
\r
728 <div class="paragraph"><p>In stack mode, a window containing the decorations of all windows inside the
\r
729 container is placed at the top. The currently focused window is then given the
\r
730 whole remaining space.</p></div>
\r
732 <div class="sect2">
\r
733 <h3 id="_tabbed_mode">14.4. Tabbed mode</h3>
\r
734 <div class="paragraph"><p>Tabbed mode is like stack mode, except that the window decorations are drawn
\r
735 in one single line at the top of the container.</p></div>
\r
737 <div class="sect2">
\r
738 <h3 id="_window_decorations">14.5. Window decorations</h3>
\r
739 <div class="paragraph"><p>The window decorations consist of a rectangle in the appropriate color (depends
\r
740 on whether this window is the currently focused one, the last focused one in a
\r
741 not focused container or not focused at all) forming the background.
\r
742 Afterwards, two lighter lines are drawn and the last step is drawing the
\r
743 window’s title (see WM_NAME) onto it.</p></div>
\r
745 <div class="sect2">
\r
746 <h3 id="_fullscreen_windows">14.6. Fullscreen windows</h3>
\r
747 <div class="paragraph"><p>For fullscreen windows, the <tt>rect</tt> (x, y, width, height) is not changed to
\r
748 allow the client to easily go back to its previous position. Instead,
\r
749 fullscreen windows are skipped when rendering.</p></div>
\r
751 <div class="sect2">
\r
752 <h3 id="_resizing_containers">14.7. Resizing containers</h3>
\r
753 <div class="paragraph"><p>By clicking and dragging the border of a container, you can resize the whole
\r
754 column (respectively row) which this container is in. This is necessary to keep
\r
755 the table layout working and consistent.</p></div>
\r
756 <div class="paragraph"><p>The resizing works similarly to the resizing of floating windows or movement of
\r
757 floating windows:</p></div>
\r
758 <div class="ulist"><ul>
\r
761 A new, invisible window with the size of the root window is created
\r
767 Another window, 2px width and as high as your screen (or vice versa for
\r
768 horizontal resizing) is created. Its background color is the border color and
\r
769 it is only there to inform the user how big the container will be (it
\r
770 creates the impression of dragging the border out of the container).
\r
775 The <tt>drag_pointer</tt> function of <tt>src/floating.c</tt> is called to grab the pointer
\r
776 and enter its own event loop which will pass all events (expose events) but
\r
777 motion notify events. This function then calls the specified callback
\r
778 (<tt>resize_callback</tt>) which does some boundary checking and moves the helper
\r
779 window. As soon as the mouse button is released, this loop will be
\r
785 The new width_factor for each involved column (respectively row) will be
\r
793 <div class="sect1">
\r
794 <h2 id="_user_commands_commandmode_src_commands_c">15. User commands / commandmode (src/commands.c)</h2>
\r
795 <div class="sectionbody">
\r
796 <div class="paragraph"><p>Like in vim, you can control i3 using commands. They are intended to be a
\r
797 powerful alternative to lots of shortcuts, because they can be combined. There
\r
798 are a few special commands, which are the following:</p></div>
\r
799 <div class="dlist"><dl>
\r
800 <dt class="hdlist1">
\r
801 exec <command>
\r
805 Starts the given command by passing it to <tt>/bin/sh</tt>.
\r
808 <dt class="hdlist1">
\r
813 Restarts i3 by executing <tt>argv[0]</tt> (the path with which you started i3) without
\r
817 <dt class="hdlist1">
\r
822 "With". This is used to select a bunch of windows. Currently, only selecting
\r
823 the whole container in which the window is in, is supported by specifying "w".
\r
826 <dt class="hdlist1">
\r
831 Toggle fullscreen, stacking, default mode for the current window/container.
\r
835 <div class="paragraph"><p>The other commands are to be combined with a direction. The directions are h,
\r
836 j, k and l, like in vim (h = left, j = down, k = up, l = right). When you just
\r
837 specify the direction keys, i3 will move the focus in that direction. You can
\r
838 provide "m" or "s" before the direction to move a window respectively or snap.</p></div>
\r
841 <div class="sect1">
\r
842 <h2 id="_gotchas">16. Gotchas</h2>
\r
843 <div class="sectionbody">
\r
844 <div class="ulist"><ul>
\r
847 Forgetting to call <tt>xcb_flush(conn);</tt> after sending a request. This usually
\r
848 leads to code which looks like it works fine but which does not work under
\r
849 certain conditions.
\r
855 <div class="sect1">
\r
856 <h2 id="_using_git_sending_patches">17. Using git / sending patches</h2>
\r
857 <div class="sectionbody">
\r
858 <div class="paragraph"><p>For a short introduction into using git, see
\r
859 <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
860 <a href="http://git-scm.com/documentation">http://git-scm.com/documentation</a></p></div>
\r
861 <div class="paragraph"><p>When you want to send a patch because you fixed a bug or implemented a cool
\r
862 feature (please talk to us before working on features to see whether they are
\r
863 maybe already implemented, not possible for some some reason, or don’t fit
\r
864 into the concept), please use git to create a patchfile.</p></div>
\r
865 <div class="paragraph"><p>First of all, update your working copy to the latest version of the master
\r
867 <div class="listingblock">
\r
868 <div class="content">
\r
869 <pre><tt>git pull</tt></pre>
\r
871 <div class="paragraph"><p>Afterwards, make the necessary changes for your bugfix/feature. Then, review
\r
872 the changes using <tt>git diff</tt> (you might want to enable colors in the diff using
\r
873 <tt>git config diff.color auto</tt>). When you are definitely done, use <tt>git commit
\r
874 -a</tt> to commit all changes you’ve made.</p></div>
\r
875 <div class="paragraph"><p>Then, use the following command to generate a patchfile which we can directly
\r
876 apply to the branch, preserving your commit message and name:</p></div>
\r
877 <div class="listingblock">
\r
878 <div class="content">
\r
879 <pre><tt>git format-patch origin</tt></pre>
\r
881 <div class="paragraph"><p>Just send us the generated file via email.</p></div>
\r
885 <div id="footnotes"><hr /></div>
\r
886 <div id="footer" lang="de">
\r
887 © 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>
\r
projects / i3 / i3.github.io / blob