Hacking i3: How To
==================
-Michael Stapelberg <michael+i3@stapelberg.de>
-July 2011
+Michael Stapelberg <michael@i3wm.org>
+February 2013
This document is intended to be the first thing you read before looking and/or
touching i3’s source code. It should contain all important information to help
the first client of X) and manage them (reparent them, create window
decorations, etc.)
. When new windows are created, manage them
-. Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN`
+. Handle the client’s `_WM_STATE` property, but only `_WM_STATE_FULLSCREEN` and
+ `_NET_WM_STATE_DEMANDS_ATTENTION`
. Handle the client’s `WM_NAME` property
. Handle the client’s size hints to display them proportionally
. Handle the client’s urgency hint
corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this
for you? Certainly, it’s faster than you could ever do it.
-The problem with most tiling window managers is that they are too unflexible.
+The problem with most tiling window managers is that they are too inflexible.
In my opinion, a window manager is just another tool, and similar to vim which
can edit all kinds of text files (like source code, HTML, …) and is not limited
to a specific file type, a window manager should not limit itself to a certain
To get an impression of how different layouts are represented, just play around
and look at the data structures -- they are exposed as a JSON hash. See
-http://i3wm.org/docs/ipc.html#_get_tree_reply for documentation on that and an
+http://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an
example.
== Files
doxygen-compatible comments (so if you want to get a bit more of the big
picture, either browse all header files or use doxygen if you prefer that).
-src/cfgparse.l::
-Contains the lexer for i3’s configuration file, written for +flex(1)+.
-
-src/cfgparse.y::
-Contains the parser for i3’s configuration file, written for +bison(1)+.
+src/config_parser.c::
+Contains a custom configuration parser. See src/command_parser.c for rationale
+ on why we use a custom parser.
src/click.c::
Contains all functions which handle mouse button clicks (right mouse button
clicks initiate resizing and thus are relatively complex).
-src/cmdparse.l::
-Contains the lexer for i3 commands, written for +flex(1)+.
-
-src/cmdparse.y::
-Contains the parser for i3 commands, written for +bison(1)+.
+src/command_parser.c::
+Contains a hand-written parser to parse commands (commands are what
+you bind on keys and what you can send to i3 using the IPC interface, like
+'move left' or 'workspace 4').
src/con.c::
Contains all functions which deal with containers directly (creating
Contains code for loading layouts from JSON files.
src/log.c::
-Handles the setting of loglevels, contains the logging functions.
+Contains the logging functions.
src/main.c::
Initializes the window manager.
src/resize.c::
Contains the functions to resize containers.
+src/restore_layout.c::
+Everything for restored containers that is not pure state parsing (which can be
+found in load_layout.c).
+
src/sighandler.c::
Handles +SIGSEGV+, +SIGABRT+ and +SIGFPE+ by showing a dialog that i3 crashed.
You can chose to let it dump core, to restart it in-place or to restart it
* The override_redirect must not be set. Windows with override_redirect shall
not be managed by a window manager
-Afterwards, i3 gets the intial geometry and reparents the window (see
+Afterwards, i3 gets the initial geometry and reparents the window (see
`reparent_window()`) if it wasn’t already managed.
Reparenting means that for each window which is reparented, a new window,
== What happens when an application is started?
-i3 does not care for applications. All it notices is when new windows are
+i3 does not care about applications. All it notices is when new windows are
mapped (see `src/handlers.c`, `handle_map_request()`). The window is then
reparented (see section "Manage windows").
==== Dock area layout
-This is a special case. Users cannot chose the dock area layout, but it will be
+This is a special case. Users cannot choose the dock area layout, but it will be
set for the dock area containers. In the dockarea layout (at the moment!),
windows will be placed above each other.
== Using git / sending patches
+=== Introduction
+
For a short introduction into using git, see
-http://www.spheredev.org/wiki/Git_for_the_lazy or, for more documentation, see
-http://git-scm.com/documentation
+http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy
+or, for more documentation, see http://git-scm.com/documentation
-When you want to send a patch because you fixed a bug or implemented a cool
-feature (please talk to us before working on features to see whether they are
-maybe already implemented, not possible for some some reason, or don’t fit
-into the concept), please use git to create a patchfile.
+Please talk to us before working on new features to see whether they will be
+accepted. There are a few things which we don’t want to see in i3, e.g. a
+command which will focus windows in an alt+tab like way.
-First of all, update your working copy to the latest version of the master
-branch:
+When working on bugfixes, please make sure you mention that you are working on
+it in the corresponding bugreport at https://github.com/i3/i3/issues In case
+there is no bugreport yet, please create one.
---------
-git pull
---------
+After you are done, please submit your work for review at https://github.com/i3/i3
-Afterwards, make the necessary changes for your bugfix/feature. Then, review
-the changes using +git diff+ (you might want to enable colors in the diff using
-+git config diff.color auto+). When you are definitely done, use +git commit
--a+ to commit all changes you’ve made.
+Do not send emails to the mailing list or any author directly, and don’t submit
+them in the bugtracker, since all reviews should be done in public at
+http://cr.i3wm.org/. In order to make your review go as fast as possible, you
+could have a look at previous reviews and see what the common mistakes are.
-Then, use the following command to generate a patchfile which we can directly
-apply to the branch, preserving your commit message and name:
+=== Which branch to use?
------------------------
-git format-patch origin
------------------------
+Work on i3 generally happens in two branches: “master” and “next”. Since
+“master” is what people get when they check out the git repository, its
+contents are always stable. That is, it contains the source code of the latest
+release, plus any bugfixes that were applied since that release.
-Just send us the generated file via email.
+New features are only found in the “next” branch. Therefore, if you are working
+on a new feature, use the “next” branch. If you are working on a bugfix, use
+the “next” branch, too, but make sure your code also works on “master”.
== Thought experiments
Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu
gets started with PID 3390. The user then decides to launch Firefox, which
-takes a long time. So he enters firefox into dmenu and presses enter. Firefox
+takes a long time. So they enter firefox into dmenu and press enter. Firefox
gets started with PID 4001. When it finally finishes loading, it creates an X11
window and uses MapWindow to make it visible. This is the first time i3
actually gets in touch with Firefox. It decides to map the window, but it has
projects / i3 / i3 / blobdiff