add docs/layout-saving
Feedback on this new document is very much appreciated, please don’t hesitate to state anything that is hard to understand/could be improved.
This commit is contained in:
Michael Stapelberg
parent
254e4d6f05
commit
7deb23c727
|
|
@ -14,7 +14,8 @@ ASCIIDOC_TOC_TARGETS = \
|
||||||
docs/multi-monitor.html \
|
docs/multi-monitor.html \
|
||||||
docs/wsbar.html \
|
docs/wsbar.html \
|
||||||
docs/testsuite.html \
|
docs/testsuite.html \
|
||||||
docs/i3bar-protocol.html
|
docs/i3bar-protocol.html \
|
||||||
|
docs/layout-saving.html
|
||||||
|
|
||||||
ASCIIDOC_TARGETS = \
|
ASCIIDOC_TARGETS = \
|
||||||
$(ASCIIDOC_TOC_TARGETS) \
|
$(ASCIIDOC_TOC_TARGETS) \
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,233 @@
|
||||||
|
Layout saving in i3
|
||||||
|
===================
|
||||||
|
Michael Stapelberg <michael@i3wm.org>
|
||||||
|
April 2014
|
||||||
|
|
||||||
|
Layout saving/restoring is a feature that was introduced in i3 v4.8.
|
||||||
|
|
||||||
|
Layout saving/restoring allows you to load a JSON layout file so that you can
|
||||||
|
have a base layout to start working with after powering on your computer.
|
||||||
|
Dynamic use-cases also come to mind: if you frequently (but not always!) need a
|
||||||
|
grid layout of terminals with ping/traceroute commands to diagnose network
|
||||||
|
issues, you can easily automate opening these windows in just the right layout.
|
||||||
|
|
||||||
|
== Saving the layout
|
||||||
|
|
||||||
|
You can save the layout of either a single workspace or an entire output (e.g.
|
||||||
|
LVDS1). Of course, you can repeat this step multiple times if you want to
|
||||||
|
save/restore multiple workspaces/outputs.
|
||||||
|
|
||||||
|
+i3-save-tree(1)+ is a tool to save the layout. It will print a JSON
|
||||||
|
representation of i3’s internal layout data structures to stdout. Typically,
|
||||||
|
you may want to take a quick look at the output, then save it to a file and
|
||||||
|
tweak it a little bit:
|
||||||
|
|
||||||
|
---------------------------------------------------
|
||||||
|
i3-save-tree --workspace 1 > ~/.i3/workspace-1.json
|
||||||
|
---------------------------------------------------
|
||||||
|
|
||||||
|
Please note that the output of +i3-save-tree(1)+ is *NOT useful* until you
|
||||||
|
manually modify it — you need to tell i3 how to match/distinguish windows (for
|
||||||
|
example based on their WM_CLASS, title, etc.). By default, all the different
|
||||||
|
window properties are included in the output, but commented out. This is partly
|
||||||
|
to avoid relying on heuristics and partly to make you aware how i3 works so
|
||||||
|
that you can easily solve layout restoring problems.
|
||||||
|
|
||||||
|
How to modify the file manually is described in <<EditingLayoutFiles>>.
|
||||||
|
|
||||||
|
== Restoring the layout
|
||||||
|
|
||||||
|
After restoring the example layout from <<EditingLayoutFiles>>, i3 will open
|
||||||
|
placeholder windows for all the windows that were specified in the layout file.
|
||||||
|
You can recognize the placeholder windows by the watch symbol
|
||||||
|
footnote:[Depending on the font you are using, a placeholder symbol may show up
|
||||||
|
instead of the watch symbol.] in the center of the window, and by the swallow
|
||||||
|
criteria specification at the top of the window:
|
||||||
|
|
||||||
|
image:layout-saving-1.png["Restored layout",width=400,link="layout-saving-1.png"]
|
||||||
|
|
||||||
|
When an application opens a window that matches the specified swallow criteria,
|
||||||
|
it will be placed in the corresponding placeholder window. We say it gets
|
||||||
|
*swallowed* by the placeholder container, hence the term.
|
||||||
|
|
||||||
|
Note: Swallowing windows into unsatisfied placeholder windows takes precedence
|
||||||
|
over
|
||||||
|
link:http://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces[assignment
|
||||||
|
rules]. For example, if you assign all Emacs windows to workspace 1 in your i3
|
||||||
|
configuration file, but there is a placeholder window on workspace 2 which
|
||||||
|
matches Emacs as well, your newly started Emacs window will end up in the
|
||||||
|
placeholder window on workspace 2.
|
||||||
|
|
||||||
|
The placeholder windows are just regular windows, so feel free to move them
|
||||||
|
around or close them, for example.
|
||||||
|
|
||||||
|
=== append_layout command
|
||||||
|
|
||||||
|
The +append_layout+ command is used to load a layout file into i3. It accepts a
|
||||||
|
path (relative to i3’s current working directory or absolute) to a JSON file.
|
||||||
|
|
||||||
|
*Syntax*:
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
append_layout <path>
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
*Examples*:
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
# From a terminal or script:
|
||||||
|
i3-msg "workspace 1; append_layout /home/michael/.i3/workspace-1.json"
|
||||||
|
|
||||||
|
# In your i3 configuration file, you can autostart i3-msg like this:
|
||||||
|
# (Note that those lines will quickly become long, so typically you would store
|
||||||
|
# them in a script with proper indentation.)
|
||||||
|
exec --no-startup-id "i3-msg 'workspace 1; append_layout /home/michael/.i3/workspace-1.json'"
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
== Editing layout files
|
||||||
|
|
||||||
|
[[EditingLayoutFiles]]
|
||||||
|
|
||||||
|
=== 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:
|
||||||
|
|
||||||
|
image:layout-saving-1.png["Restored layout",width=400,link="layout-saving-1.png"]
|
||||||
|
|
||||||
|
The structure of this JSON file looks a lot like the +TREE+ reply, see
|
||||||
|
http://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:
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
// Matches either Emacs or Gvim, whichever one is started first.
|
||||||
|
"swallows": [
|
||||||
|
{"class": "^Emacs$"},
|
||||||
|
{"class": "^Gvim$"}
|
||||||
|
]
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
=== JSON standard non-compliance
|
||||||
|
|
||||||
|
A layout file as generated by +i3-save-tree(1)+ is not strictly valid JSON:
|
||||||
|
|
||||||
|
1. Layout files contain multiple “JSON documents” on the top level, whereas the
|
||||||
|
JSON standard only allows precisely one “document” (array or hash).
|
||||||
|
|
||||||
|
2. Layout files contain comments which are not standardized, but understood by
|
||||||
|
many parsers.
|
||||||
|
|
||||||
|
Both deviations from the JSON standard are to make manual editing by humans
|
||||||
|
easier. In case you are writing a more elaborate tool for manipulating these
|
||||||
|
layouts, you can either use a JSON parser that supports these deviations (for
|
||||||
|
example libyajl), transform the layout file to a JSON-conforming file, or
|
||||||
|
link:http://cr.i3wm.org/[submit a patch] to make +i3-save-tree(1)+ optionally
|
||||||
|
output standard-conforming JSON.
|
||||||
Loading…
Reference in New Issue