From: Michael Stapelberg Date: Sun, 24 Sep 2017 17:24:09 +0000 (+0200) Subject: update docs for 4.14.1 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=34766c2a72c18bd20c3760d75d7c2aabbb2453dc;p=i3%2Fi3.github.io update docs for 4.14.1 --- diff --git a/_docs/debugging b/_docs/debugging index 925618a..8c6b2b7 100644 --- a/_docs/debugging +++ b/_docs/debugging @@ -10,7 +10,7 @@ Thank you for being interested in debugging i3. It really means something to us to get your bug fixed. If you have any questions about the process and/or need further help, do not hesitate to contact us! -== Verify you are using i3 ≥ 4.14 +== Verify you are using i3 ≥ 4.14.1 Only the latest major version of i3 is supported. To verify which version you are running, use: @@ -32,8 +32,8 @@ if you can. 4.7-85-g9c15b95 (development version):: Your version is 85 commits newer than 4.7, and the git revision of your -version is +9c15b95+. Go to http://code.i3wm.org/i3/commit/?h=next and see if -the line "commit" starts with the same revision. If so, you are using the +version is +9c15b95+. Go to https://github.com/i3/i3/commits/next and see if +the most recent commit starts with the same revision. If so, you are using the latest version. Development versions of i3 have logging enabled by default and are compiled @@ -109,9 +109,9 @@ No matter whether i3 misbehaved in some way without crashing or whether it just crashed, the logfile provides all information necessary to debug the problem. To upload a compressed version of the logfile (for a bugreport), use: ------------------------------------------------------------------------------- -DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- http://logs.i3wm.org ------------------------------------------------------------------------------- +------------------------------------------------------------------------------- +DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- https://logs.i3wm.org +------------------------------------------------------------------------------- This command does not depend on i3 (it also works while i3 displays the crash dialog), but it requires a working X11 connection. @@ -154,9 +154,9 @@ you found the section which clearly highlights the problem, additional information might be necessary to completely diagnose the problem. When debugging with us in IRC, be prepared to use a so called nopaste service -such as http://nopaste.info or http://pastebin.com because pasting large -amounts of text in IRC sometimes leads to incomplete lines (servers have line -length limitations) or flood kicks. +such as https://pastebin.com because pasting large amounts of text in IRC +sometimes leads to incomplete lines (servers have line length limitations) or +flood kicks. == Debugging i3bar diff --git a/_docs/hacking-howto b/_docs/hacking-howto index 52436da..2ca44a5 100644 --- a/_docs/hacking-howto +++ b/_docs/hacking-howto @@ -8,6 +8,84 @@ touching i3’s source code. It should contain all important information to help you understand why things are like they are. If it does not mention something you find necessary, please do not hesitate to contact me. +== Building i3 + +You can build i3 like you build any other software package which uses autotools. +Here’s a memory refresher: + + $ autoreconf -fi + $ mkdir -p build && cd build + $ ../configure + $ make -j8 + +(The autoreconf -fi step is unnecessary if you are building from a release tarball, + but shouldn’t hurt either.) + +=== Build system features + +* We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate + directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building + in a separate directory is common practice anyway. In case this causes any + trouble when packaging i3 for your distribution, please open an issue. + +* “make check” runs the i3 testsuite. See docs/testsuite for details. + +* “make distcheck” (runs testsuite on “make dist” result, tiny bit quicker + feedback cycle than waiting for the travis build to catch the issue). + +* “make uninstall” (occasionally requested by users who compile from source) + +* “make” will build manpages/docs by default if the tools are installed. + Conversely, manpages/docs are not tried to be built for users who don’t want + to install all these dependencies to get started hacking on i3. + +* non-release builds will enable address sanitizer by default. Use the + --disable-sanitizers configure option to turn off all sanitizers, and see + --help for available sanitizers. + +* Support for pre-compiled headers (PCH) has been dropped for now in the + interest of simplicity. If you need support for PCH, please open an issue. + +* Coverage reports are now generated using “make check-code-coverage”, which + requires specifying --enable-code-coverage when calling configure. + +== Using git / sending patches + +For a short introduction into using git, see +https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy +or, for more documentation, see https://git-scm.com/documentation + +Please talk to us before working on new features to see whether they will be +accepted. A good way for this is to open an issue and asking for opinions on it. +Even for accepted features, this can be a good way to refine an idea upfront. However, +we don't want to see certain features in i3, e.g., switching window focus in an +Alt+Tab like way. + +When working on bugfixes, please make sure you mention that you are working on +it in the corresponding bug report at https://github.com/i3/i3/issues. In case +there is no bug report yet, please create one. + +After you are done, please submit your work for review as a pull request at +https://github.com/i3/i3. + +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 +https://github.com/i3/i3. 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. + +=== Which branch to use? + +Work on i3 generally happens in two branches: “master” and “next” (the latter +being the default branch, the one that people get when they check out the git +repository). + +The contents of “master” are always stable. That is, it contains the source code +of the latest release, plus any bugfixes that were applied since that release. + +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”. + == Window Managers A window manager is not necessarily needed to run X, but it is usually used in @@ -78,7 +156,7 @@ workspace, the split container we are talking about is the workspace. 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#_tree_reply for documentation on that and an +https://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an example. == Files @@ -951,86 +1029,6 @@ Without much ado, here is the list of cases which need to be considered: not relative to workspace boundaries, so you must correct their coordinates or those containers will show up in the wrong workspace or not at all. -== Using git / sending patches - -=== Introduction - -For a short introduction into using git, see -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 - -Please talk to us before working on new features to see whether they will be -accepted. A good way for this is to open an issue and asking for opinions on it. -Even for accepted features, this can be a good way to refine an idea upfront. However, -we don't want to see certain features in i3, e.g., switching window focus in an -Alt+Tab like way. - -When working on bugfixes, please make sure you mention that you are working on -it in the corresponding bug report at https://github.com/i3/i3/issues. In case -there is no bug report yet, please create one. - -After you are done, please submit your work for review as a pull request at -https://github.com/i3/i3. - -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 -https://github.com/i3/i3. 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. - -=== Which branch to use? - -Work on i3 generally happens in two branches: “master” and “next” (the latter -being the default branch, the one that people get when they check out the git -repository). - -The contents of “master” are always stable. That is, it contains the source code -of the latest release, plus any bugfixes that were applied since that release. - -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”. - -=== How to build? - -You can build i3 like you build any other software package which uses autotools. -Here’s a memory refresher: - - $ autoreconf -fi - $ mkdir -p build && cd build - $ ../configure - $ make -j8 - -(The autoreconf -fi step is unnecessary if you are building from a release tarball, - but shouldn’t hurt either.) - -==== Build system features - -* We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate - directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building - in a separate directory is common practice anyway. In case this causes any - trouble when packaging i3 for your distribution, please open an issue. - -* “make check” runs the i3 testsuite. See docs/testsuite for details. - -* “make distcheck” (runs testsuite on “make dist” result, tiny bit quicker - feedback cycle than waiting for the travis build to catch the issue). - -* “make uninstall” (occasionally requested by users who compile from source) - -* “make” will build manpages/docs by default if the tools are installed. - Conversely, manpages/docs are not tried to be built for users who don’t want - to install all these dependencies to get started hacking on i3. - -* non-release builds will enable address sanitizer by default. Use the - --disable-sanitizers configure option to turn off all sanitizers, and see - --help for available sanitizers. - -* Support for pre-compiled headers (PCH) has been dropped for now in the - interest of simplicity. If you need support for PCH, please open an issue. - -* Coverage reports are now generated using “make check-code-coverage”, which - requires specifying --enable-code-coverage when calling configure. - == Thought experiments In this section, we collect thought experiments, so that we don’t forget our diff --git a/_docs/i3bar-protocol b/_docs/i3bar-protocol index ebd3b83..b8c2b5a 100644 --- a/_docs/i3bar-protocol +++ b/_docs/i3bar-protocol @@ -96,7 +96,7 @@ i3status and others will output single statuslines in one line, separated by You can find an example of a shell script which can be used as your +status_command+ in the bar configuration at -http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next +https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh === Header in detail diff --git a/_docs/ipc b/_docs/ipc index 6572357..997a305 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== Michael Stapelberg -October 2014 +September 2017 This document describes how to interface with i3 from a separate process. This is useful for example to remote-control i3 (to write test cases for example) or @@ -50,38 +50,21 @@ The magic string currently is "i3-ipc" and will only be changed when a change in the IPC API is done which breaks compatibility (we hope that we don’t need to do that). -Currently implemented message types are the following: - -COMMAND (0):: - The payload of the message is a command for i3 (like the commands you - can bind to keys in the configuration file) and will be executed - directly after receiving it. -GET_WORKSPACES (1):: - Gets the current workspaces. The reply will be a JSON-encoded list of - workspaces (see the reply section). -SUBSCRIBE (2):: - Subscribes your connection to certain events. See <> for a - description of this message and the concept of events. -GET_OUTPUTS (3):: - Gets the current outputs. The reply will be a JSON-encoded list of outputs - (see the reply section). -GET_TREE (4):: - Gets the layout tree. i3 uses a tree as data structure which includes - every container. The reply will be the JSON-encoded tree (see the reply - section). -GET_MARKS (5):: - Gets a list of marks (identifiers for containers to easily jump to them - later). The reply will be a JSON-encoded list of window marks (see - reply section). -GET_BAR_CONFIG (6):: - Gets the configuration (as JSON map) of the workspace bar with the - given ID. If no ID is provided, an array with all configured bar IDs is - returned instead. -GET_VERSION (7):: - Gets the version of i3. The reply will be a JSON-encoded dictionary - with the major, minor, patch and human-readable version. -GET_BINDING_MODES (8):: - Gets a list of currently configured binding modes. +.Currently implemented message types +[options="header",cols="^10%,^20%,^20%,^50%"] +|====================================================== +| Type (numeric) | Type (name) | Reply type | Purpose +| 0 | +RUN_COMMAND+ | <<_command_reply,COMMAND>> | Run the payload as an i3 command (like the commands you can bind to keys). +| 1 | +GET_WORKSPACES+ | <<_workspaces_reply,WORKSPACES>> | Get the list of current workspaces. +| 2 | +SUBSCRIBE+ | <<_subscribe_reply,SUBSCRIBE>> | Subscribe this IPC connection to the event types specified in the message payload. See <>. +| 3 | +GET_OUTPUTS+ | <<_outputs_reply,OUTPUTS>> | Get the list of current outputs. +| 4 | +GET_TREE+ | <<_tree_reply,TREE>> | Get the i3 layout tree. +| 5 | +GET_MARKS+ | <<_marks_reply,MARKS>> | Gets the names of all currently set marks. +| 6 | +GET_BAR_CONFIG+ | <<_bar_config_reply,BAR_CONFIG>> | Gets the specified bar configuration or the names of all bar configurations if payload is empty. +| 7 | +GET_VERSION+ | <<_version_reply,VERSION>> | Gets the i3 version. +| 8 | +GET_BINDING_MODES+ | <<_binding_modes_reply,BINDING_MODES>> | Gets the names of all currently configured binding modes. +| 9 | +GET_CONFIG+ | <<_config_reply,CONFIG>> | Returns the last loaded i3 config. +|====================================================== So, a typical message could look like this: -------------------------------------------------- @@ -124,7 +107,7 @@ payload. The following reply types are implemented: COMMAND (0):: - Confirmation/Error code for the COMMAND message. + Confirmation/Error code for the RUN_COMMAND message. WORKSPACES (1):: Reply to the GET_WORKSPACES message. SUBSCRIBE (2):: @@ -141,7 +124,10 @@ VERSION (7):: Reply to the GET_VERSION message. BINDING_MODES (8):: Reply to the GET_BINDING_MODES message. +GET_CONFIG (9):: + Reply to the GET_CONFIG message. +[[_command_reply]] === COMMAND reply The reply consists of a list of serialized maps for each command that was @@ -153,6 +139,7 @@ human-readable error message in the property +error (string)+. [{ "success": true }] ------------------- +[[_workspaces_reply]] === WORKSPACES reply The reply consists of a serialized list of workspaces. Each workspace has the @@ -212,6 +199,7 @@ output (string):: ] ------------------- +[[_subscribe_reply]] === SUBSCRIBE reply The reply consists of a single serialized map. The only property is @@ -223,6 +211,7 @@ default) or whether a JSON parse error occurred. { "success": true } ------------------- +[[_outputs_reply]] === OUTPUTS reply The reply consists of a serialized list of outputs. Each output has the @@ -269,6 +258,7 @@ rect (map):: ] ------------------- +[[_tree_reply]] === TREE reply The reply consists of a serialized tree. Each node in the tree (representing @@ -335,9 +325,22 @@ window (integer):: containers. This ID corresponds to what xwininfo(1) and other X11-related tools display (usually in hex). urgent (bool):: - Whether this container (window or workspace) has the urgency hint set. + Whether this container (window, split container, floating container or + workspace) has the urgency hint set, directly or indirectly. All parent + containers up until the workspace container will be marked urgent if they + have at least one urgent child. focused (bool):: Whether this container is currently focused. +focus (array of integer):: + List of child node IDs (see +nodes+, +floating_nodes+ and +id+) in focus + order. Traversing the tree by following the first entry in this array + will result in eventually reaching the one node with +focused+ set to + true. +nodes (array of node):: + The tiling (i.e. non-floating) child containers of this node. +floating_nodes (array of node):: + The floating child containers of this node. Only non-empty on nodes with + type +workspace+. Please note that in the following example, I have left out some keys/values which are not relevant for the type of the node. Otherwise, the example would @@ -471,6 +474,7 @@ JSON dump: } ------------------------ +[[_marks_reply]] === MARKS reply The reply consists of a single array of strings for each container that has a @@ -479,6 +483,7 @@ The order of that array is undefined. If no window has a mark the response will be the empty array []. +[[_bar_config_reply]] === BAR_CONFIG reply This can be used by third-party workspace bars (especially i3bar, but others @@ -578,6 +583,7 @@ binding_mode_text/binding_mode_bg/binding_mode_border:: } -------------- +[[_version_reply]] === VERSION reply The reply consists of a single JSON dictionary with the following keys: @@ -610,6 +616,7 @@ loaded_config_file_name (string):: } ------------------- +[[_binding_modes_reply]] === BINDING_MODES reply The reply consists of an array of all currently configured binding modes. @@ -619,6 +626,18 @@ The reply consists of an array of all currently configured binding modes. ["default", "resize"] --------------------- +[[_config_reply]] +=== CONFIG reply + +The config reply is a map which currently only contains the "config" member, +which is a string containing the config file as loaded by i3 most recently. + +*Example:* +------------------- +{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" } +------------------- + + == Events [[events]] @@ -879,3 +898,63 @@ Rust:: * https://github.com/tmerr/i3ipc-rs OCaml:: * https://github.com/Armael/ocaml-i3ipc + +== Appendix A: Detecting byte order in memory-safe languages + +Some programming languages such as Go don’t offer a way to serialize data in the +native byte order of the machine they’re running on without resorting to tricks +involving the +unsafe+ package. + +The following technique can be used (and will not be broken by changes to i3) to +detect the byte order i3 is using: + +1. The byte order dependent fields of an IPC message are message type and + payload length. + + * The message type +RUN_COMMAND+ (0) is the same in big and little endian, so + we can use it in either byte order to elicit a reply from i3. + + * The payload length 65536 + 256 (+0x00 01 01 00+) is the same in big and + little endian, and also small enough to not worry about memory allocations + of that size. We must use payloads of length 65536 + 256 in every message + we send, so that i3 will be able to read the entire message regardless of + the byte order it uses. + +2. Send a big endian encoded message of type +SUBSCRIBE+ (2) with payload `[]` + followed by 65536 + 256 - 2 +SPACE+ (ASCII 0x20) bytes. + + * If i3 is running in big endian, this message is treated as a noop, + resulting in a +SUBSCRIBE+ reply with payload `{"success":true}` + footnote:[A small payload is important: that way, we circumvent dealing + with UNIX domain socket buffer sizes, whose size depends on the + implementation/operating system. Exhausting such a buffer results in an i3 + deadlock unless you concurrently read and write, which — depending on the + programming language — makes the technique much more complicated.]. + + * If i3 is running in little endian, this message is read in its entirety due + to the byte order independent payload length, then + https://github.com/i3/i3/blob/d726d09d496577d1c337a4b97486f2c9fbc914f1/src/ipc.c#L1188[silently + discarded] due to the unknown message type. + +3. Send a byte order independent message, i.e. type +RUN_COMMAND+ (0) with + payload +nop byte order detection. padding:+, padded to 65536 + 256 bytes + with +a+ (ASCII 0x61) bytes. i3 will reply to this message with a reply of + type +COMMAND+ (0). + + * The human-readable prefix is in there to not confuse readers of the i3 log. + + * This messages serves as a synchronization primitive so that we know whether + i3 discarded the +SUBSCRIBE+ message or didn’t answer it yet. + +4. Receive a message header from i3, decoding the message type as big endian. + + * If the message’s reply type is +COMMAND+ (0), i3 is running in little + endian (because the +SUBSCRIBE+ message was discarded). Decode the message + payload length as little endian, receive the message payload. + + * If the message’s reply type is anything else, i3 is running in big endian + (because our big endian encoded +SUBSCRIBE+ message was answered). Decode + the message payload length in big endian, receive the message + payload. Then, receive the pending +COMMAND+ message reply in big endian. + +5. From here on out, send/receive all messages using the detected byte order. diff --git a/_docs/layout-saving b/_docs/layout-saving index 6ca08fa..e90ecad 100644 --- a/_docs/layout-saving +++ b/_docs/layout-saving @@ -52,7 +52,7 @@ it will be placed in the corresponding placeholder window. We say it gets Note: Swallowing windows into unsatisfied placeholder windows takes precedence over -link:http://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces[assignment +link:https://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 @@ -164,7 +164,7 @@ 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 +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 @@ -229,8 +229,8 @@ 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. +link:https://github.com/i3/i3/blob/next/.github/CONTRIBUTING.md[submit a patch] +to make +i3-save-tree(1)+ optionally output standard-conforming JSON. == Troubleshooting diff --git a/_docs/testsuite b/_docs/testsuite index 795be04..bf85cb1 100644 --- a/_docs/testsuite +++ b/_docs/testsuite @@ -41,10 +41,10 @@ Apart from this document, you should also have a look at: http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf 2. The latest Perl documentation of the "i3test" (general testcase setup) and "i3test::Test" (additional test instructions) modules: - http://build.i3wm.org/docs/lib-i3test.html respectively - http://build.i3wm.org/docs/lib-i3test-test.html + https://build.i3wm.org/docs/lib-i3test.html respectively + https://build.i3wm.org/docs/lib-i3test-test.html 3. The latest documentation on i3’s IPC interface: - http://build.i3wm.org/docs/ipc.html + https://build.i3wm.org/docs/ipc.html == Implementation @@ -75,7 +75,7 @@ used to install the testsuite. Many users prefer to use the more modern +cpanminus+ instead, though (because it asks no questions and just works): The tests additionally require +Xephyr(1)+ to run a nested X server. Install -+xserver-xephyr+ on Debian or +xorg-xserver-xephyr+ on Arch Linux. ++xserver-xephyr+ on Debian or +xorg-server-xephyr+ on Arch Linux. .Installing testsuite dependencies using cpanminus (preferred) -------------------------------------------------------------------------------- @@ -83,6 +83,7 @@ $ cd ~/i3/testcases $ sudo apt-get install cpanminus $ sudo cpanm . $ cd ~/i3/AnyEvent-I3 +$ sudo cpanm Module::Install $ sudo cpanm . -------------------------------------------------------------------------------- @@ -93,11 +94,12 @@ If you don’t want to use cpanminus for some reason, the same works with cpan: $ cd ~/i3/testcases $ sudo cpan . $ cd ~/i3/AnyEvent-I3 +$ sudo cpan Module::Install $ sudo cpan . -------------------------------------------------------------------------------- In case you don’t have root permissions, you can also install into your home -directory, see http://michael.stapelberg.de/cpan/ +directory, see https://michael.stapelberg.de/cpan/ === Mechanisms @@ -238,7 +240,7 @@ interface which i3 provides. It is used for the startup process of i3, for terminating it cleanly and (most importantly) for modifying and getting the current state (layout tree). -See [http://i3wm.org/docs/ipc.html] for documentation on the IPC interface. +See [https://i3wm.org/docs/ipc.html] for documentation on the IPC interface. ==== X11::XCB diff --git a/_docs/userguide b/_docs/userguide index 0d5de3b..ebd0a88 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -802,7 +802,7 @@ The first part of the WM_CLASS is the instance ("irssi" in this example), the second part is the class ("URxvt" in this example). Should you have any problems with assignments, make sure to check the i3 -logfile first (see http://i3wm.org/docs/debugging.html). It includes more +logfile first (see https://i3wm.org/docs/debugging.html). It includes more details about the matching process and the window’s actual class, instance and title when starting up. @@ -869,6 +869,18 @@ The 'output' is the name of the RandR output you attach your screen to. On a laptop, you might have VGA1 and LVDS1 as output names. You can see the available outputs by running +xrandr --current+. +If your X server supports RandR 1.5 or newer, i3 will use RandR monitor objects +instead of output objects. Run +xrandr --listmonitors+ to see a list. Usually, +a monitor object contains exactly one output, and has the same name as the +output; but should that not be the case, you may specify the name of either the +monitor or the output in i3's configuration. For example, the Dell UP2414Q uses +two scalers internally, so its output names might be “DP1” and “DP2”, but the +monitor name is “Dell UP2414Q”. + +(Note that even if you specify the name of an output which doesn't span the +entire monitor, i3 will still use the entire area of the containing monitor +rather than that of just the output's.) + If you use named workspaces, they must be quoted: *Examples*: @@ -1044,7 +1056,7 @@ force_focus_wrapping yes === Forcing Xinerama -As explained in-depth in , some X11 +As explained in-depth in , some X11 video drivers (especially the nVidia binary driver) only provide support for Xinerama instead of RandR. In such a situation, i3 must be told to use the inferior Xinerama API explicitly and therefore don’t provide support for @@ -1949,7 +1961,6 @@ bindsym $mod+x focus output HDMI-2 bindsym $mod+x focus output primary ------------------------------------------------- -------------------------------- Note that you might not have a primary output configured yet. To do so, run: ------------------------- xrandr --output --primary @@ -2437,7 +2448,7 @@ bindsym $mod+u border none [[shmlog]] === Enabling shared memory logging -As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared +As described in https://i3wm.org/docs/debugging.html, i3 can log to a shared memory buffer, which you can dump using +i3-dump-log+. The +shmlog+ command allows you to enable or disable the shared memory logging at runtime. diff --git a/_docs/wsbar b/_docs/wsbar index 6405880..952c200 100644 --- a/_docs/wsbar +++ b/_docs/wsbar @@ -48,7 +48,7 @@ will be adjusted properly. +i3-wsbar+ used to be the reference implementation before we had +i3bar+. Nowadays, it is not shipped with release tarballs, but you can still get it at -http://code.stapelberg.de/git/i3/tree/contrib/i3-wsbar +https://github.com/i3/i3/blob/next/contrib/i3-wsbar === The big picture diff --git a/docs/debugging.html b/docs/debugging.html index 47e90fc..a98a417 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -44,7 +44,7 @@ process and/or need further help, do not hesitate to contact us!

-

1. Verify you are using i3 ≥ 4.14

+

1. Verify you are using i3 ≥ 4.14.1

Only the latest major version of i3 is supported. To verify which version you are running, use:

@@ -74,8 +74,8 @@ if you can.

Your version is 85 commits newer than 4.7, and the git revision of your -version is 9c15b95. Go to http://code.i3wm.org/i3/commit/?h=next and see if -the line "commit" starts with the same revision. If so, you are using the +version is 9c15b95. Go to https://github.com/i3/i3/commits/next and see if +the most recent commit starts with the same revision. If so, you are using the latest version.

@@ -181,7 +181,7 @@ crashed, the logfile provides all information necessary to debug the problem.

To upload a compressed version of the logfile (for a bugreport), use:

-
DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- http://logs.i3wm.org
+
DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- https://logs.i3wm.org

This command does not depend on i3 (it also works while i3 displays the crash dialog), but it requires a working X11 connection.

@@ -222,9 +222,9 @@ starting at 0.

you found the section which clearly highlights the problem, additional information might be necessary to completely diagnose the problem.

When debugging with us in IRC, be prepared to use a so called nopaste service -such as http://nopaste.info or http://pastebin.com because pasting large -amounts of text in IRC sometimes leads to incomplete lines (servers have line -length limitations) or flood kicks.

+such as https://pastebin.com because pasting large amounts of text in IRC +sometimes leads to incomplete lines (servers have line length limitations) or +flood kicks.

diff --git a/docs/hacking-howto.html b/docs/hacking-howto.html index 606fad6..a55a82d 100644 --- a/docs/hacking-howto.html +++ b/docs/hacking-howto.html @@ -47,7 +47,111 @@ you find necessary, please do not hesitate to contact me.

-

1. Window Managers

+

1. Building i3

+
+

You can build i3 like you build any other software package which uses autotools. +Here’s a memory refresher:

+
+
+
$ autoreconf -fi
+$ mkdir -p build && cd build
+$ ../configure
+$ make -j8
+
+

(The autoreconf -fi step is unnecessary if you are building from a release tarball, + but shouldn’t hurt either.)

+
+

1.1. Build system features

+
    +
  • +

    +We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate + directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building + in a separate directory is common practice anyway. In case this causes any + trouble when packaging i3 for your distribution, please open an issue. +

    +
    • +
  • +

    +“make check” runs the i3 testsuite. See docs/testsuite for details. +

    +
    • +
  • +

    +“make distcheck” (runs testsuite on “make dist” result, tiny bit quicker + feedback cycle than waiting for the travis build to catch the issue). +

    +
    • +
  • +

    +“make uninstall” (occasionally requested by users who compile from source) +

    +
    • +
  • +

    +“make” will build manpages/docs by default if the tools are installed. + Conversely, manpages/docs are not tried to be built for users who don’t want + to install all these dependencies to get started hacking on i3. +

    +
    • +
  • +

    +non-release builds will enable address sanitizer by default. Use the + --disable-sanitizers configure option to turn off all sanitizers, and see + --help for available sanitizers. +

    +
    • +
  • +

    +Support for pre-compiled headers (PCH) has been dropped for now in the + interest of simplicity. If you need support for PCH, please open an issue. +

    +
    • +
  • +

    +Coverage reports are now generated using “make check-code-coverage”, which + requires specifying --enable-code-coverage when calling configure. +

    +
    • +
+
+
+
+
+

2. Using git / sending patches

+
+

For a short introduction into using git, see +https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy +or, for more documentation, see https://git-scm.com/documentation

+

Please talk to us before working on new features to see whether they will be +accepted. A good way for this is to open an issue and asking for opinions on it. +Even for accepted features, this can be a good way to refine an idea upfront. However, +we don’t want to see certain features in i3, e.g., switching window focus in an +Alt+Tab like way.

+

When working on bugfixes, please make sure you mention that you are working on +it in the corresponding bug report at https://github.com/i3/i3/issues. In case +there is no bug report yet, please create one.

+

After you are done, please submit your work for review as a pull request at +https://github.com/i3/i3.

+

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 +https://github.com/i3/i3. 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.

+
+

2.1. Which branch to use?

+

Work on i3 generally happens in two branches: “master” and “next” (the latter +being the default branch, the one that people get when they check out the git +repository).

+

The contents of “master” are always stable. That is, it contains the source code +of the latest release, plus any bugfixes that were applied since that release.

+

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”.

+
+
+
+
+

3. Window Managers

A window manager is not necessarily needed to run X, but it is usually used in combination with X to facilitate some things. The window manager’s job is to @@ -124,7 +228,7 @@ React to the user’s commands: Change focus, Move windows, Switch workspaces,

In the following chapters, each of these tasks and their implementation details will be discussed.

-

1.1. Tiling window managers

+

3.1. Tiling window managers

Traditionally, there are two approaches to managing windows: The most common one nowadays is floating, which means the user can freely move/resize the windows. The other approach is called tiling, which means that your window @@ -143,7 +247,7 @@ layout (like dwm, awesome, …) but provide mechanisms for you to easily create the layout you need at the moment.

-

1.2. The layout tree

+

3.2. The layout tree

The data structure which i3 uses to keep track of your windows is a tree. Every node in the tree is a container (type Con). Some containers represent actual windows (every container with a window != NULL), some represent split @@ -154,13 +258,13 @@ the same split container, which uses the default layout. In case of an empty workspace, the split container we are talking about is the workspace.

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#_tree_reply for documentation on that and an +https://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an example.

-

2. Files

+

4. Files

@@ -449,7 +553,7 @@ Legacy support for Xinerama. See src/randr.c for the preferred API.
-

3. Data structures

+

5. Data structures

See include/data.h for documented data structures. The most important ones are explained right here.

@@ -488,14 +592,14 @@ explained right here.

The data type is Con, in all cases.

-

3.1. X11 root window

+

5.1. X11 root window

The X11 root window is a single window per X11 display (a display is identified by :0 or :1 etc.). The root window is what you draw your background image on. It spans all the available outputs, e.g. VGA1 is a specific part of the root window and LVDS1 is a specific part of the root window.

-

3.2. Output container

+

5.2. Output container

Every active output obtained through RandR is represented by one output container. Outputs are considered active when a mode is configured (meaning something is actually displayed on the output) and the output is not a clone.

@@ -510,13 +614,13 @@ workspace will be assigned. New workspaces are created on the output you are currently on.

-

3.3. Content container

+

5.3. Content container

Each output has multiple children. Two of them are dock containers which hold dock clients. The other one is the content container, which holds the actual content (workspaces) of this output.

-

3.4. Workspace

+

5.4. Workspace

A workspace is identified by its name. Basically, you could think of workspaces as different desks in your office, if you like the desktop metaphor. They just contain different sets of windows and are completely @@ -524,7 +628,7 @@ separate of each other. Other window managers also call this “Virtual desktops”.

-

3.5. Split container

+

5.5. Split container

A split container is a container which holds an arbitrary amount of split containers or X11 window containers. It has an orientation (horizontal or vertical) and a layout.

@@ -532,14 +636,14 @@ vertical) and a layout.

containers) can have different border styles.

-

3.6. X11 window container

+

5.6. X11 window container

An X11 window container holds exactly one X11 window. These are the leaf nodes of the layout tree, they cannot have any children.

-

4. List/queue macros

+

6. List/queue macros

i3 makes heavy use of the list macros defined in BSD operating systems. To ensure that the operating system on which i3 is compiled has all the expected @@ -554,7 +658,7 @@ selected window to the window above/below.

-

5. Naming conventions

+

7. Naming conventions

There is a row of standard variables used in many events. The following names should be chosen for those:

@@ -583,7 +687,7 @@ should be chosen for those:

-

6. Startup (src/mainx.c, main())

+

8. Startup (src/mainx.c, main())

  • @@ -620,10 +724,10 @@ Enter the event loop
-

7. Keybindings

+

9. Keybindings

-

7.1. Grabbing the bindings

+

9.1. Grabbing the bindings

Grabbing the bindings is quite straight-forward. You pass X your combination of modifiers and the keycode you want to grab and whether you want to grab them actively or passively. Most bindings (everything except for bindings using @@ -644,7 +748,7 @@ check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it will handle the event, if not, it will replay the event.

-

7.2. Handling a keypress

+

9.2. Handling a keypress

As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets the correct state.

Then, it looks through all bindings and gets the one which matches the received @@ -655,7 +759,7 @@ event.

-

8. Manage windows (src/main.c, manage_window() and reparent_window())

+

10. Manage windows (src/main.c, manage_window() and reparent_window())

manage_window() does some checks to decide whether the window should be managed at all:

@@ -691,7 +795,7 @@ target workspace is not visible, the window will not be mapped.

-

9. What happens when an application is started?

+

11. What happens when an application is started?

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 @@ -711,7 +815,7 @@ can reconfigure themselves).

-

10. _NET_WM_STATE

+

12. _NET_WM_STATE

Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms are handled.

@@ -722,7 +826,7 @@ Also, it is set as fullscreen_client for the i3Screen.

-

11. WM_NAME

+

13. WM_NAME

When the WM_NAME property of a window changes, its decoration (containing the title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is @@ -731,7 +835,7 @@ if present.

-

12. _NET_WM_NAME

+

14. _NET_WM_NAME

Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it @@ -740,7 +844,7 @@ characters (every special character contained in your font).

-

13. Size hints

+

15. Size hints

Size hints specify the minimum/maximum size for a given window as well as its aspect ratio. This is important for clients like mplayer, who only set the @@ -753,7 +857,7 @@ src/layout.c, function resize_client().

-

14. Rendering (src/layout.c, render_layout() and render_container())

+

16. Rendering (src/layout.c, render_layout() and render_container())

Rendering in i3 version 4 is the step which assigns the correct sizes for borders, decoration windows, child windows and the stacking order of all @@ -773,7 +877,7 @@ container and then pushing the changes to X11. The following sections talk about the different rendering steps, in the order of "top of the tree" (root container) to the bottom.

-

14.1. Rendering the root container

+

16.1. Rendering the root container

The i3 root container (con->type == CT_ROOT) represents the X11 root window. It contains one child container for every output (like LVDS1, VGA1, …), which is available on your computer.

@@ -789,7 +893,7 @@ spanning all outputs), a shortcut is taken and x_raise_con(); render_con()
-

14.2. Rendering an output

+

16.2. Rendering an output

Output containers (con->layout == L_OUTPUT) represent a hardware output like LVDS1, VGA1, etc. An output container has three children (at the moment): One content container (having workspaces as children) and the top/bottom dock area @@ -836,20 +940,20 @@ Recursively raise and render the output’s child containers (meaning dock

-

14.3. Rendering a workspace or split container

+

16.3. Rendering a workspace or split container

From here on, there really is no difference anymore. All containers are of con->type == CT_CON (whether workspace or split container) and some of them have a con->window, meaning they represent an actual window instead of a split container.

-

14.3.1. Default layout

+

16.3.1. Default layout

In default layout, containers are placed horizontally or vertically next to each other (depending on the con->orientation). If a child is a leaf node (as opposed to a split container) and has border style "normal", appropriate space will be reserved for its window decoration.

-

14.3.2. Stacked layout

+

16.3.2. Stacked layout

In stacked layout, only the focused window is actually shown (this is achieved by calling x_raise_con() in reverse focus order at the end of render_con()).

The available space for the focused window is the size of the container minus @@ -860,20 +964,20 @@ reserved (or displayed later on), unless there is more than one window inside the stacked container.

-

14.3.3. Tabbed layout

+

16.3.3. Tabbed layout

Tabbed layout works precisely like stacked layout, but the window decoration position/size is different: They are placed next to each other on a single line (fixed height).

-

14.3.4. Dock area layout

+

16.3.4. Dock area layout

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.

-

14.4. Rendering a window

+

16.4. Rendering a window

A window’s size and position will be determined in the following way:

  1. @@ -902,7 +1006,7 @@ Obey the height- and width-increments of the window (think terminal emulator
-

15. Pushing updates to X11 / Drawing

+

17. Pushing updates to X11 / Drawing

A big problem with i3 before version 4 was that we just sent requests to X11 anywhere in the source code. This was bad because nobody could understand the @@ -932,7 +1036,7 @@ Expose event handling (drawing decorations): x_deco_recurse() and

-

15.1. Pushing state to X11

+

17.1. Pushing state to X11

In general, the function x_push_changes should be called to push state changes. Only when the scope of the state change is clearly defined (for example only the title of a window) and its impact is known beforehand, one can @@ -1042,7 +1146,7 @@ unmapped if it should not be visible anymore. WM_STATE will be set to WM_STATE_WITHDRAWN.

-

15.2. Drawing window decorations/borders/backgrounds

+

17.2. Drawing window decorations/borders/backgrounds

x_draw_decoration draws window decorations. It is run for every leaf container (representing an actual X11 window) and for every non-leaf container which is in a stacked/tabbed container (because stacked/tabbed containers @@ -1061,7 +1165,7 @@ and "1pixel") and the top bar (in case of border style "normal").

-

16. User commands (parser-specs/commands.spec)

+

18. User commands (parser-specs/commands.spec)

In the configuration file and when using i3 interactively (with i3-msg, for example), you use commands to make i3 do things, like focus a different window, @@ -1103,7 +1207,7 @@ which will be compared with the input. An action is either the name of a state in which the parser will transition into, or the keyword call, followed by the name of a function (and optionally a state).

-

16.1. Example: The WORKSPACE state

+

18.1. Example: The WORKSPACE state

Let’s have a look at the WORKSPACE state, which is a good example of all features. This is its definition:

@@ -1201,7 +1305,7 @@ workspace number <number>
-

16.2. Introducing a new command

+

18.2. Introducing a new command

The following steps have to be taken in order to properly introduce a new command (or possibly extend an existing command):

    @@ -1247,12 +1351,12 @@ Document the feature in the User’s Guide.
-

17. Moving containers

+

19. Moving containers

The movement code is pretty delicate. You need to consider all cases before making any changes or before being able to fully understand how it works.

-

17.1. Case 1: Moving inside the same container

+

19.1. Case 1: Moving inside the same container

The reference layout for this case is a single workspace in horizontal orientation with two containers on it. Focus is on the left container (1).

@@ -1277,7 +1381,7 @@ commented with "the easy case": it calls TAILQ_NEXT to get the container right of the current one and swaps both containers.

-

17.2. Case 2: Move a container into a split container

+

19.2. Case 2: Move a container into a split container

The reference layout for this case is a horizontal workspace with two containers. The right container is a v-split with two containers. Focus is on the left container (1).

@@ -1311,7 +1415,7 @@ empty.

be flattened.

-

17.3. Case 3: Moving to non-existent top/bottom

+

19.3. Case 3: Moving to non-existent top/bottom

Like in case 1, the reference layout for this case is a single workspace in horizontal orientation with two containers on it. Focus is on the left container:

@@ -1345,7 +1449,7 @@ container and the container above/below the current one (on the level of flattened.

-

17.4. Case 4: Moving to existent top/bottom

+

19.4. Case 4: Moving to existent top/bottom

The reference layout for this case is a vertical workspace with two containers. The bottom one is a h-split containing two containers (1 and 2). Focus is on the bottom left container (1).

@@ -1372,7 +1476,7 @@ orientation change does not need to be performed because the workspace already is in vertical orientation.

-

17.5. Case 5: Moving in one-child h-split

+

19.5. Case 5: Moving in one-child h-split

The reference layout for this case is a horizontal workspace with two containers having a v-split on the left side with a one-child h-split on the bottom. Focus is on the bottom left container (2(h)):

@@ -1404,7 +1508,7 @@ orientation will be force-changed), this case is equivalent to case 2 or case 4.

-

17.6. Case 6: Floating containers

+

19.6. Case 6: Floating containers

The reference layout for this case is a horizontal workspace with two containers plus one floating h-split container. Focus is on the floating container.

@@ -1416,7 +1520,7 @@ by calling the function attach_to_workspace.

-

18. Click handling

+

20. Click handling

Without much ado, here is the list of cases which need to be considered:

    @@ -1466,7 +1570,7 @@ click on border/decoration to resize a tiling con
-

19. Gotchas

+

21. Gotchas

  • @@ -1488,112 +1592,7 @@ Forgetting to call floating_fix_coordinates(con, old_rect, new_rect) af
-

20. Using git / sending patches

-
-
-

20.1. Introduction

-

For a short introduction into using git, see -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

-

Please talk to us before working on new features to see whether they will be -accepted. A good way for this is to open an issue and asking for opinions on it. -Even for accepted features, this can be a good way to refine an idea upfront. However, -we don’t want to see certain features in i3, e.g., switching window focus in an -Alt+Tab like way.

-

When working on bugfixes, please make sure you mention that you are working on -it in the corresponding bug report at https://github.com/i3/i3/issues. In case -there is no bug report yet, please create one.

-

After you are done, please submit your work for review as a pull request at -https://github.com/i3/i3.

-

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 -https://github.com/i3/i3. 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.

-
-
-

20.2. Which branch to use?

-

Work on i3 generally happens in two branches: “master” and “next” (the latter -being the default branch, the one that people get when they check out the git -repository).

-

The contents of “master” are always stable. That is, it contains the source code -of the latest release, plus any bugfixes that were applied since that release.

-

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”.

-
-
-

20.3. How to build?

-

You can build i3 like you build any other software package which uses autotools. -Here’s a memory refresher:

-
-
-
$ autoreconf -fi
-$ mkdir -p build && cd build
-$ ../configure
-$ make -j8
-
-

(The autoreconf -fi step is unnecessary if you are building from a release tarball, - but shouldn’t hurt either.)

-
-

20.3.1. Build system features

-
    -
  • -

    -We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate - directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building - in a separate directory is common practice anyway. In case this causes any - trouble when packaging i3 for your distribution, please open an issue. -

    -
    • -
  • -

    -“make check” runs the i3 testsuite. See docs/testsuite for details. -

    -
    • -
  • -

    -“make distcheck” (runs testsuite on “make dist” result, tiny bit quicker - feedback cycle than waiting for the travis build to catch the issue). -

    -
    • -
  • -

    -“make uninstall” (occasionally requested by users who compile from source) -

    -
    • -
  • -

    -“make” will build manpages/docs by default if the tools are installed. - Conversely, manpages/docs are not tried to be built for users who don’t want - to install all these dependencies to get started hacking on i3. -

    -
    • -
  • -

    -non-release builds will enable address sanitizer by default. Use the - --disable-sanitizers configure option to turn off all sanitizers, and see - --help for available sanitizers. -

    -
    • -
  • -

    -Support for pre-compiled headers (PCH) has been dropped for now in the - interest of simplicity. If you need support for PCH, please open an issue. -

    -
    • -
  • -

    -Coverage reports are now generated using “make check-code-coverage”, which - requires specifying --enable-code-coverage when calling configure. -

    -
    • -
-
-
-
-
-
-

21. Thought experiments

+

22. Thought experiments

In this section, we collect thought experiments, so that we don’t forget our thoughts about specific topics. They are not necessary to get into hacking i3, @@ -1601,7 +1600,7 @@ but if you are interested in one of the topics they cover, you should read them before asking us why things are the way they are or why we don’t implement things.

-

21.1. Using cgroups per workspace

+

22.1. Using cgroups per workspace

cgroups (control groups) are a linux-only feature which provides the ability to group multiple processes. For each group, you can individually set resource limits, like allowed memory usage. Furthermore, and more importantly for our diff --git a/docs/i3bar-protocol.html b/docs/i3bar-protocol.html index a9478fc..4955b89 100644 --- a/docs/i3bar-protocol.html +++ b/docs/i3bar-protocol.html @@ -145,7 +145,7 @@ i3status and others will output single statuslines in one line, separated by \n.

You can find an example of a shell script which can be used as your status_command in the bar configuration at -http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next

+https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh

2.1. Header in detail

diff --git a/docs/ipc.html b/docs/ipc.html index 8780aed..deb1e0f 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -32,7 +32,7 @@ document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); a

IPC interface (interprocess communication)

Michael Stapelberg
<michael@i3wm.org>
-October 2014 +September 2017
Table of Contents
@@ -92,93 +92,88 @@ they are in native byte order).

The magic string currently is "i3-ipc" and will only be changed when a change in the IPC API is done which breaks compatibility (we hope that we don’t need to do that).

-

Currently implemented message types are the following:

-
-
-COMMAND (0) -
-
-

- The payload of the message is a command for i3 (like the commands you - can bind to keys in the configuration file) and will be executed - directly after receiving it. -

-
-
-GET_WORKSPACES (1) -
-
-

- Gets the current workspaces. The reply will be a JSON-encoded list of - workspaces (see the reply section). -

-
-
-SUBSCRIBE (2) -
-
-

- Subscribes your connection to certain events. See [events] for a - description of this message and the concept of events. -

-
-
-GET_OUTPUTS (3) -
-
-

- Gets the current outputs. The reply will be a JSON-encoded list of outputs - (see the reply section). -

-
-
-GET_TREE (4) -
-
-

- Gets the layout tree. i3 uses a tree as data structure which includes - every container. The reply will be the JSON-encoded tree (see the reply - section). -

-
-
-GET_MARKS (5) -
-
-

- Gets a list of marks (identifiers for containers to easily jump to them - later). The reply will be a JSON-encoded list of window marks (see - reply section). -

-
-
-GET_BAR_CONFIG (6) -
-
-

- Gets the configuration (as JSON map) of the workspace bar with the - given ID. If no ID is provided, an array with all configured bar IDs is - returned instead. -

-
-
-GET_VERSION (7) -
-
-

- Gets the version of i3. The reply will be a JSON-encoded dictionary - with the major, minor, patch and human-readable version. -

-
-
-GET_BINDING_MODES (8) -
-
-

- Gets a list of currently configured binding modes. -

-
-
+
+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Currently implemented message types
Type (numeric) Type (name) Reply type Purpose

0

RUN_COMMAND

COMMAND

Run the payload as an i3 command (like the commands you can bind to keys).

1

GET_WORKSPACES

WORKSPACES

Get the list of current workspaces.

2

SUBSCRIBE

SUBSCRIBE

Subscribe this IPC connection to the event types specified in the message payload. See [events].

3

GET_OUTPUTS

OUTPUTS

Get the list of current outputs.

4

GET_TREE

TREE

Get the i3 layout tree.

5

GET_MARKS

MARKS

Gets the names of all currently set marks.

6

GET_BAR_CONFIG

BAR_CONFIG

Gets the specified bar configuration or the names of all bar configurations if payload is empty.

7

GET_VERSION

VERSION

Gets the i3 version.

8

GET_BINDING_MODES

BINDING_MODES

Gets the names of all currently configured binding modes.

9

GET_CONFIG

CONFIG

Returns the last loaded i3 config.

+

So, a typical message could look like this:

@@ -225,7 +220,7 @@ COMMAND (0)

- Confirmation/Error code for the COMMAND message. + Confirmation/Error code for the RUN_COMMAND message.

@@ -292,6 +287,14 @@ BINDING_MODES (8) Reply to the GET_BINDING_MODES message.

+
+GET_CONFIG (9) +
+
+

+ Reply to the GET_CONFIG message. +

+
@@ -643,7 +646,10 @@ urgent (bool)

- Whether this container (window or workspace) has the urgency hint set. + Whether this container (window, split container, floating container or + workspace) has the urgency hint set, directly or indirectly. All parent + containers up until the workspace container will be marked urgent if they + have at least one urgent child.

@@ -654,6 +660,34 @@ focused (bool) Whether this container is currently focused.

+
+focus (array of integer) +
+
+

+ List of child node IDs (see nodes, floating_nodes and id) in focus + order. Traversing the tree by following the first entry in this array + will result in eventually reaching the one node with focused set to + true. +

+
+
+nodes (array of node) +
+
+

+ The tiling (i.e. non-floating) child containers of this node. +

+
+
+floating_nodes (array of node) +
+
+

+ The floating child containers of this node. Only non-empty on nodes with + type workspace. +

+

Please note that in the following example, I have left out some keys/values which are not relevant for the type of the node. Otherwise, the example would @@ -1142,6 +1176,16 @@ loaded_config_file_name (string) 

["default", "resize"]
+
+

3.11. CONFIG reply

+

The config reply is a map which currently only contains the "config" member, +which is a string containing the config file as loaded by i3 most recently.

+

Example:

+
+
+
{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }
+
+
@@ -1628,6 +1672,116 @@ OCaml
+
+

6. Appendix A: Detecting byte order in memory-safe languages

+
+

Some programming languages such as Go don’t offer a way to serialize data in the +native byte order of the machine they’re running on without resorting to tricks +involving the unsafe package.

+

The following technique can be used (and will not be broken by changes to i3) to +detect the byte order i3 is using:

+
    +
  1. +

    +The byte order dependent fields of an IPC message are message type and + payload length. +

    +
      +
    • +

      +The message type RUN_COMMAND (0) is the same in big and little endian, so + we can use it in either byte order to elicit a reply from i3. +

      +
      • +
    • +

      +The payload length 65536 + 256 (0x00 01 01 00) is the same in big and + little endian, and also small enough to not worry about memory allocations + of that size. We must use payloads of length 65536 + 256 in every message + we send, so that i3 will be able to read the entire message regardless of + the byte order it uses. +

      +
      • +
    +
    2. +
  2. +

    +Send a big endian encoded message of type SUBSCRIBE (2) with payload [] + followed by 65536 + 256 - 2 SPACE (ASCII 0x20) bytes. +

    +
      +
    • +

      +If i3 is running in big endian, this message is treated as a noop, + resulting in a SUBSCRIBE reply with payload {"success":true} +
      [A small payload is important: that way, we circumvent dealing + with UNIX domain socket buffer sizes, whose size depends on the + implementation/operating system. Exhausting such a buffer results in an i3 + deadlock unless you concurrently read and write, which — depending on the + programming language — makes the technique much more complicated.]
      . +

      +
      • +
    • +

      +If i3 is running in little endian, this message is read in its entirety due + to the byte order independent payload length, then + silently + discarded due to the unknown message type. +

      +
      • +
    +
    3. +
  3. +

    +Send a byte order independent message, i.e. type RUN_COMMAND (0) with + payload nop byte order detection. padding:, padded to 65536 + 256 bytes + with a (ASCII 0x61) bytes. i3 will reply to this message with a reply of + type COMMAND (0). +

    +
      +
    • +

      +The human-readable prefix is in there to not confuse readers of the i3 log. +

      +
      • +
    • +

      +This messages serves as a synchronization primitive so that we know whether + i3 discarded the SUBSCRIBE message or didn’t answer it yet. +

      +
      • +
    +
    4. +
  4. +

    +Receive a message header from i3, decoding the message type as big endian. +

    +
      +
    • +

      +If the message’s reply type is COMMAND (0), i3 is running in little + endian (because the SUBSCRIBE message was discarded). Decode the message + payload length as little endian, receive the message payload. +

      +
      • +
    • +

      +If the message’s reply type is anything else, i3 is running in big endian + (because our big endian encoded SUBSCRIBE message was answered). Decode + the message payload length in big endian, receive the message + payload. Then, receive the pending COMMAND message reply in big endian. +

      +
      • +
    +
    5. +
  5. +

    +From here on out, send/receive all messages using the detected byte order. +

    +
    6. +
+
+

Note: Swallowing windows into unsatisfied placeholder windows takes precedence over -assignment +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 @@ -202,7 +202,7 @@ a Chrome window:

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 +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 @@ -268,8 +268,8 @@ Layout files contain comments which are not standardized, but understood by 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 -submit a patch to make i3-save-tree(1) optionally -output standard-conforming JSON.

+submit a patch +to make i3-save-tree(1) optionally output standard-conforming JSON.

diff --git a/docs/testsuite.html b/docs/testsuite.html index 3563125..8946765 100644 --- a/docs/testsuite.html +++ b/docs/testsuite.html @@ -85,14 +85,14 @@ The "Modern Perl" book, which can be found at

The latest Perl documentation of the "i3test" (general testcase setup) and "i3test::Test" (additional test instructions) modules: - http://build.i3wm.org/docs/lib-i3test.html respectively - http://build.i3wm.org/docs/lib-i3test-test.html + https://build.i3wm.org/docs/lib-i3test.html respectively + https://build.i3wm.org/docs/lib-i3test-test.html

  • The latest documentation on i3’s IPC interface: - http://build.i3wm.org/docs/ipc.html + https://build.i3wm.org/docs/ipc.html

    • @@ -140,7 +140,7 @@ client, simply called cpan. It comes with every Perl installation and c used to install the testsuite. Many users prefer to use the more modern cpanminus instead, though (because it asks no questions and just works):

    The tests additionally require Xephyr(1) to run a nested X server. Install -xserver-xephyr on Debian or xorg-xserver-xephyr on Arch Linux.

    +xserver-xephyr on Debian or xorg-server-xephyr on Arch Linux.

    Installing testsuite dependencies using cpanminus (preferred)
    @@ -148,6 +148,7 @@ used to install the testsuite. Many users prefer to use the more modern $ sudo apt-get install cpanminus $ sudo cpanm . $ cd ~/i3/AnyEvent-I3 +$ sudo cpanm Module::Install $ sudo cpanm .

    If you don’t want to use cpanminus for some reason, the same works with cpan:

    @@ -157,10 +158,11 @@ $ sudo cpanm . 
    $ cd ~/i3/testcases
 $ sudo cpan .
 $ cd ~/i3/AnyEvent-I3
+$ sudo cpan Module::Install
 $ sudo cpan .

    In case you don’t have root permissions, you can also install into your home -directory, see http://michael.stapelberg.de/cpan/

    +directory, see https://michael.stapelberg.de/cpan/

    3.2. Mechanisms

    @@ -295,7 +297,7 @@ use this tool to judge how effective your tests are.

    interface which i3 provides. It is used for the startup process of i3, for terminating it cleanly and (most importantly) for modifying and getting the current state (layout tree).

    -

    See [http://i3wm.org/docs/ipc.html] for documentation on the IPC interface.

    +

    See [https://i3wm.org/docs/ipc.html] for documentation on the IPC interface.

    3.2.4. X11::XCB

    diff --git a/docs/userguide.html b/docs/userguide.html index 7362e00..6f70c73 100644 --- a/docs/userguide.html +++ b/docs/userguide.html @@ -848,7 +848,7 @@ window, you will see the following output:

    The first part of the WM_CLASS is the instance ("irssi" in this example), the second part is the class ("URxvt" in this example).

    Should you have any problems with assignments, make sure to check the i3 -logfile first (see http://i3wm.org/docs/debugging.html). It includes more +logfile first (see https://i3wm.org/docs/debugging.html). It includes more details about the matching process and the window’s actual class, instance and title when starting up.

    Note that if you want to start an application just once on a specific @@ -909,6 +909,16 @@ the second screen and so on).

    The output is the name of the RandR output you attach your screen to. On a laptop, you might have VGA1 and LVDS1 as output names. You can see the available outputs by running xrandr --current.

    +

    If your X server supports RandR 1.5 or newer, i3 will use RandR monitor objects +instead of output objects. Run xrandr --listmonitors to see a list. Usually, +a monitor object contains exactly one output, and has the same name as the +output; but should that not be the case, you may specify the name of either the +monitor or the output in i3’s configuration. For example, the Dell UP2414Q uses +two scalers internally, so its output names might be “DP1” and “DP2”, but the +monitor name is “Dell UP2414Q”.

    +

    (Note that even if you specify the name of an output which doesn’t span the +entire monitor, i3 will still use the entire area of the containing monitor +rather than that of just the output’s.)

    If you use named workspaces, they must be quoted:

    Examples:

    @@ -1125,7 +1135,7 @@ will always wrap.

    4.25. Forcing Xinerama

    -

    As explained in-depth in http://i3wm.org/docs/multi-monitor.html, some X11 +

    As explained in-depth in https://i3wm.org/docs/multi-monitor.html, some X11 video drivers (especially the nVidia binary driver) only provide support for Xinerama instead of RandR. In such a situation, i3 must be told to use the inferior Xinerama API explicitly and therefore don’t provide support for @@ -2230,77 +2240,97 @@ bindsym $mod+x focus output HDMI-2 # Focus the primary output bindsym $mod+x focus output primary

    +

    Note that you might not have a primary output configured yet. To do so, run:

    -
    Note that you might not have a primary output configured yet. To do so, run:
    +
    xrandr --output <output> --primary
    -

    xrandr --output <output> --primary

    +
    +
    +

    6.5. Moving containers

    +

    Use the move command to move a container.

    +

    Syntax:

    -
    === Moving containers
-
-Use the +move+ command to move a container.
-
-*Syntax*:
    -
    -

    # Moves the container into the given direction. +

    # Moves the container into the given direction.
 # The optional pixel argument specifies how far the
 # container should be moved if it is floating and
 # defaults to 10 pixels.
-move <left|right|down|up> [<px> px]
    -

    # Moves the container either to a specific location -# or to the center of the screen. If absolute is +move <left|right|down|up> [<px> px] + +# Moves the container either to a specific location +# or to the center of the screen. If 'absolute' is # used, it is moved to the center of all outputs. move [absolute] position <pos_x> [px] <pos_y> [px] -move [absolute] position center

    -

    # Moves the container to the current position of the +move [absolute] position center + +# Moves the container to the current position of the # mouse cursor. Only affects floating containers. -move position mouse

    +move position mouse     +
    +

    Examples:

    -
    *Examples*:
    -
    -

    # Move container to the left, bottom, top, right +

    # Move container to the left, bottom, top, right
 bindsym $mod+j move left
 bindsym $mod+k move down
 bindsym $mod+l move up
-bindsym $mod+semicolon move right
    -

    # Move container, but make floating containers +bindsym $mod+semicolon move right + +# Move container, but make floating containers # move more than the default -bindsym $mod+j move left 20 px

    -

    # Move floating container to the center of all outputs -bindsym $mod+c move absolute position center

    -

    # Move container to the current position of the cursor -bindsym $mod+m move position mouse

    -
    -
    -
    === Swapping containers
+bindsym $mod+j move left 20 px
 
-Two containers can be swapped (i.e., move to each other's position) by using
-the +swap+ command. They will assume the position and geometry of the container
-they are swapped with.
+# Move floating container to the center of all outputs
+bindsym $mod+c move absolute position center
 
-The first container to participate in the swapping can be selected through the
+# Move container to the current position of the cursor
+bindsym $mod+m move position mouse
    +
    + +
    +

    6.6. Swapping containers

    +

    Two containers can be swapped (i.e., move to each other’s position) by using +the swap command. They will assume the position and geometry of the container +they are swapped with.

    +

    The first container to participate in the swapping can be selected through the normal command criteria process with the focused window being the usual fallback if no criteria are specified. The second container can be selected -using one of the following methods: - -+id+:: The X11 window ID of a client window. -+con_id+:: The i3 container ID of a container. -+mark+:: A container with the specified mark, see <<vim_like_marks>>. - -Note that swapping does not work with all containers. Most notably, swapping +using one of the following methods:

    +
    +
    +id +
    +
    +

    +The X11 window ID of a client window. +

    +
    +
    +con_id +
    +
    +

    +The i3 container ID of a container. +

    +
    +
    +mark +
    +
    +

    +A container with the specified mark, see [vim_like_marks]. +

    +
    +
    +

    Note that swapping does not work with all containers. Most notably, swapping floating containers or containers that have a parent-child relationship to one -another does not work. - -*Syntax*: +another does not work.

    +

    Syntax:

    +
    +
    +
    swap container with id|con_id|mark <arg>
    -
    - - -
    -

    7. swap container with id|con_id|mark <arg>

    -

    Examples:

    @@ -2310,8 +2340,9 @@ swap container with mark swapee # Swaps container marked »A« and »B« [con_mark="^A$"] swap container with mark B
    +
    -

    7.1. Sticky floating windows

    +

    6.7. Sticky floating windows

    If you want a window to stick to the glass, i.e., have it stay on screen even if you switch to another workspace, you can use the sticky command. For example, this can be useful for notepads, a media player or a video chat @@ -2331,7 +2362,7 @@ for_window [instance=notepad] sticky enable

    -

    7.2. Changing (named) workspaces/moving to workspaces

    +

    6.8. Changing (named) workspaces/moving to workspaces

    To change to a specific workspace, use the workspace command, followed by the number or name of the workspace. Pass the optional flag --no-auto-back-and-forth to disable [back_and_forth] for this specific call @@ -2391,7 +2422,7 @@ bindsym $mod+x move workspace to output right bindsym $mod+F1 [class="Firefox"] move workspace current

    -

    7.2.1. Named workspaces

    +

    6.8.1. Named workspaces

    Workspaces are identified by their name. So, instead of using numbers in the workspace command, you can use an arbitrary name:

    Example:

    @@ -2419,7 +2450,7 @@ dynamically. To combine both commands you can use workspace number 1: mail
    -

    7.2.2. Renaming workspaces

    +

    6.8.2. Renaming workspaces

    You can rename workspaces. This might be useful to start with the default numbered workspaces, do your work, and rename the workspaces afterwards to reflect what’s actually on them. You can also omit the old name to rename @@ -2457,12 +2488,12 @@ to "1: web", the above command will still switch to it.

    -

    7.3. Moving workspaces to a different screen

    +

    6.9. Moving workspaces to a different screen

    See [move_to_outputs] for how to move a container/workspace to a different RandR output.

    -

    7.4. Moving containers/workspaces to RandR outputs

    +

    6.10. Moving containers/workspaces to RandR outputs

    To move a container to another RandR output (addressed by names like LVDS1 or VGA1) or to a RandR output identified by a specific direction (like left, right, up or down), there are two commands:

    @@ -2508,7 +2539,7 @@ after the currently focused child within that container.
    -

    8. move window|container to mark <mark>

    +

    7. move window|container to mark <mark>

    Example:

    @@ -2516,7 +2547,7 @@ after the currently focused child within that container. 
    for_window [instance="tabme"] move window to mark target
    -

    8.1. Resizing containers/windows

    +

    7.1. Resizing containers/windows

    If you want to resize containers/windows using your keyboard, you can use the resize command:

    Syntax:

    @@ -2544,7 +2575,7 @@ context.

    -

    8.2. Jumping to specific windows

    +

    7.2. Jumping to specific windows

    Often when in a multi-monitor environment, you want to quickly jump to a specific window. For example, while working on workspace 3 you may want to jump to your mail client to email your boss that you’ve achieved some @@ -2565,7 +2596,7 @@ bindsym $mod+a [class="urxvt" title="VIM"] focus

    -

    8.3. VIM-like marks (mark/goto)

    +

    7.3. VIM-like marks (mark/goto)

    This feature is like the jump feature: It allows you to directly jump to a specific window (this means switching to the appropriate workspace and setting focus to the windows). However, you can directly mark a specific window with @@ -2608,7 +2639,7 @@ unmark irssi

    -

    8.4. Window title format

    +

    7.4. Window title format

    By default, i3 will simply print the X11 window title. Using title_format, this can be customized by setting the format to the desired output. This directive supports @@ -2666,7 +2697,7 @@ for_window [class="(?i)firefox"] title_format "<span foreground='red'>%tit

    -

    8.5. Changing border style

    +

    7.5. Changing border style

    To change the border of the current client, you can use border normal to use the normal border (including window title), border pixel 1 to use a 1-pixel border (no window title) and border none to make the client borderless.

    @@ -2695,8 +2726,8 @@ bindsym $mod+u border none
    -

    8.6. Enabling shared memory logging

    -

    As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared +

    7.6. Enabling shared memory logging

    +

    As described in https://i3wm.org/docs/debugging.html, i3 can log to a shared memory buffer, which you can dump using i3-dump-log. The shmlog command allows you to enable or disable the shared memory logging at runtime.

    Note that when using shmlog <size_in_bytes>, the current log will be @@ -2719,7 +2750,7 @@ i3-msg shmlog $((50*1024*1024))

    -

    8.7. Enabling debug logging

    +

    7.7. Enabling debug logging

    The debuglog command allows you to enable or disable debug logging at runtime. Debug logging is much more verbose than non-debug logging. This command does not activate shared memory logging (shmlog), and as such is most @@ -2737,7 +2768,7 @@ bindsym $mod+x debuglog toggle

    -

    8.8. Reloading/Restarting/Exiting

    +

    7.8. Reloading/Restarting/Exiting

    You can make i3 reload its configuration file with reload. You can also restart i3 inplace with the restart command to get it out of some weird state (if that should ever happen) or to perform an upgrade without having to restart @@ -2752,7 +2783,7 @@ bindsym $mod+Shift+e exit

    -

    8.9. Scratchpad

    +

    7.9. Scratchpad

    There are two commands to use any existing window as scratchpad window. move scratchpad will move a window to the scratchpad workspace. This will make it invisible until you show it again. There is no way to open that workspace. @@ -2787,7 +2818,7 @@ bindsym mod4+s [title="^Sup ::"] scratchpad show

    -

    8.10. Nop

    +

    7.10. Nop

    There is a no operation command nop which allows you to override default behavior. This can be useful for, e.g., disabling a focus change on clicks with the middle mouse button.

    @@ -2807,7 +2838,7 @@ bindsym button2 nop
    -

    8.11. i3bar control

    +

    7.11. i3bar control

    There are two options in the configuration of each i3bar instance that can be changed during runtime by invoking a command through i3. The commands bar hidden_state and bar mode allow setting the current hidden_state @@ -2841,7 +2872,7 @@ bindsym $mod+Shift+b bar mode invisible bar-1

    -

    9. Multiple monitors

    +

    8. Multiple monitors

    As you can see in the goal list on the website, i3 was specifically developed with support for multiple monitors in mind. This section will explain how to @@ -2864,7 +2895,7 @@ create an unlimited number of workspaces in i3 and tie them to specific screens, you can have the "traditional" approach of having X workspaces per screen by changing your configuration (using modes, for example).

    -

    9.1. Configuring your monitors

    +

    8.1. Configuring your monitors

    To help you get going if you have never used multiple monitors before, here is a short overview of the xrandr options which will probably be of interest to you. It is always useful to get an overview of the current screen configuration. @@ -2927,7 +2958,7 @@ only what you can see in xrandr.

    See also [presentations] for more examples of multi-monitor setups.

    -

    9.2. Interesting configuration for multi-monitor environments

    +

    8.2. Interesting configuration for multi-monitor environments

    There are several things to configure in i3 which may be interesting if you have more than one monitor:

      @@ -2964,10 +2995,10 @@ For information on how to move existing workspaces between monitors,
    -

    10. i3 and the rest of your software world

    +

    9. i3 and the rest of your software world

    -

    10.1. Displaying a status line

    +

    9.1. Displaying a status line

    A very common thing amongst users of exotic window managers is a status line at some corner of the screen. It is an often superior replacement to the widget approach you have in the task bar of a traditional desktop environment.

    @@ -2984,14 +3015,14 @@ on which hint the application sets. With i3bar, you can configure its position, see [i3bar_position].

    -

    10.2. Giving presentations (multi-monitor)

    +

    9.2. Giving presentations (multi-monitor)

    When giving a presentation, you typically want the audience to see what you see on your screen and then go through a series of slides (if the presentation is simple). For more complex presentations, you might want to have some notes which only you can see on your screen, while the audience can only see the slides.

    -

    10.2.1. Case 1: everybody gets the same output

    +

    9.2.1. Case 1: everybody gets the same output

    This is the simple case. You connect your computer to the video projector, turn on both (computer and video projector) and configure your X server to clone the internal flat panel of your computer to the video output:

    @@ -3004,7 +3035,7 @@ your screen will be left untouched (it will show the X background). So, in our example, this would be 1024x768 (my notebook has 1280x800).

    -

    10.2.2. Case 2: you can see more than your audience

    +

    9.2.2. Case 2: you can see more than your audience

    This case is a bit harder. First of all, you should configure the VGA output somewhere near your internal flat panel, say right of it:

    diff --git a/docs/wsbar.html b/docs/wsbar.html index 04dd6cd..b598f77 100644 --- a/docs/wsbar.html +++ b/docs/wsbar.html @@ -93,7 +93,7 @@ will be adjusted properly.

    i3-wsbar used to be the reference implementation before we had i3bar. Nowadays, it is not shipped with release tarballs, but you can still get it at -http://code.stapelberg.de/git/i3/tree/contrib/i3-wsbar

    +https://github.com/i3/i3/blob/next/contrib/i3-wsbar

    5.1. The big picture

    The most common reason to use an external workspace bar is to integrate system