3.1. Anatomy of a layout file

Here is an example layout file that we’ll discuss:

{ // splitv split container with 2 children "layout": "splitv", "percent": 0.4, "type": "con", "nodes": [ { "border": "none", "name": "irssi", "percent": 0.5, "type": "con", "swallows": [ { "class": "^URxvt$", "instance": "^irssi$" } ] }, { // stacked split container with 2 children "layout": "stacked", "percent": 0.5, "type": "con", "nodes": [ { "name": "notmuch", "percent": 0.5, "type": "con", "swallows": [ { "class": "^Emacs$", "instance": "^notmuch$" } ] }, { "name": "midna: ~", "percent": 0.5, "type": "con" } ] } ] } { // stacked split container with 1 children "layout": "stacked", "percent": 0.6, "type": "con", "nodes": [ { "name": "chrome", "type": "con", "swallows": [ { "class": "^Google-chrome$" } ] } ] }

In this layout, the screen is divided into two columns. In the left column, which covers 40% of the screen, there is a terminal emulator running irssi on the top, and a stacked split container with an Emacs window and a terminal emulator on the bottom. In the right column, there is a stacked container with a Chrome window:

The structure of this JSON file looks a lot like the TREE reply, see https://build.i3wm.org/docs/ipc.html#_tree_reply for documentation on that. Some properties are excluded because they are not relevant when restoring a layout.

Most importantly, look at the "swallows" section of each window. This is where you need to be more or less specific. As an example, remember the section about the Emacs window:

"swallows": [ { "class": "^Emacs$", "instance": "^notmuch$" } ]

Here you can see that i3 will require both the class and the instance to match. Therefore, if you just start Emacs via dmenu, it will not get swallowed by that container. Only if you start Emacs with the proper instance name ( emacs24 --name notmuch ), it will get swallowed.

You can match on "class", "instance", "window_role" and "title". All values are case-sensitive regular expressions (PCRE). Use xprop(1) and click into a window to see its properties:

$ xprop WM_WINDOW_ROLE(STRING) = "gimp-toolbox-color-dialog" WM_CLASS(STRING) = "gimp-2.8", "Gimp-2.8" _NET_WM_NAME(UTF8_STRING) = "Change Foreground Color"

The first part of WM_CLASS is the "instance" (gimp-2.8 in this case), the second part is the "class" (Gimp-2.8 in this case). "title" matches against _NET_WM_NAME and "window_role" matches against WM_WINDOW_ROLE .

In general, you should try to be as specific as possible in your swallow criteria. Try to use criteria that match one window and only one window, to have a reliable startup procedure.

If you specify multiple swallow criteria, the placeholder will be replaced by the window which matches any of the criteria. As an example: